Integration Guide

This document describes the recommended process for integrating your systems with the Nilo REST API. The goal is to provide a clear guide on integration phases, operation order, and best practices to ensure a successful and efficient implementation.

Integration Phases

The integration is divided into four main phases:

🔐

Phase 1: Configuration

Obtain credentials and access token to communicate with the API

→📦

Phase 2: Master Data

Initial load of catalog information: brands, categories, products, stores, and prices

→🎯

Phase 3: Promotions

Configure commercial dynamics and load historical orders

→🛒

Phase 4: Transactions

Order lifecycle from webhook reception to delivery or cancellation

→

---

Key API Concepts

Before starting the integration, it's important to understand some fundamental concepts that apply to various operations within the Nilo API.

The Unique Identifier: "internalCode"

Throughout the API, you'll find the internalCode field for entities such as products, stores, brands, categories, etc.

Aspect	Description
What is it?	The internalCode is the unique code or identifier by which that entity is known in your systems (like your ERP). For example, a product's SKU, a store's customer code, or a brand's ID.
Why is it important?	Using internalCode is a fundamental practice of this API. It allows direct communication between your systems and Nilo using the same identifiers you already manage internally. This eliminates the need to create and maintain mapping tables between Nilo IDs and ERP IDs, simplifying integration logic and subsequent management.

Important Exception: Orders

Orders originate on the Nilo platform. Therefore, they don't have an internalCode from your system. To manage an order's lifecycle (confirm, deliver, cancel, etc.), you must always use the numeric id that Nilo sends in the order creation webhook.

Asynchronous (Batch) Operations

Several API endpoints, especially those designed for bulk data loading (like /batch/brand or /batch/store), operate asynchronously. Understanding this flow is essential for correct implementation.

How it works:

1. Send Request: Send a POST request to the batch endpoint with an array of entities
2. Validation & Queuing: Nilo validates the payload structure and queues tasks for background processing
3. Immediate Response: If queuing is successful, the API responds with 202 Accepted (not 200 OK), containing one or more batchId (UUID format)
4. Background Processing: Nilo servers process tasks asynchronously

Checking Batch Status:

GET/batch/{uuid}/status

Returns a summary: general status (processing, processed, failed) and item counts (total, processed, failed, completed).

GET/batch/{uuid}/detail

Provides item-by-item detail of the entire batch. Essential for debugging and identifying why a specific record couldn't be processed.

Image Management

For all entities that support images (Brands, Categories, Products, etc.), the image field expects a public and accessible URL.

During processing, Nilo will:

1. Download the image from that URL
2. Store it on Nilo servers
3. Distribute it through a CDN for optimized loading

Recommendation

Use high-quality images. The platform will automatically generate optimized versions for different devices (mobile, tablet, web).

---

Phase 1: Configuration and Authentication

The first step to interact with the Nilo API is obtaining an authentication token.

Obtaining Credentials

The Nilo team will provide you with a clientId and clientSecret. These credentials are confidential and must be stored securely.

Generating the Access Token

POST/login

This service authenticates your credentials and returns an access_token.

Important considerations:

Requirement	Description
Token Duration	The access_token has a limited duration and must be sent in the Authorization header of all subsequent API requests
API Key	Additionally, include the x-api-key header with the value provided by Nilo. This header is required in all API endpoints
Best Practice	Implement logic to cache the token and automatically renew it before expiration to avoid service interruptions

Example headers for all requests:

Authorization: Bearer <your_token>
x-api-key: <your_api_key>

---

Phase 2: Master Data Synchronization

Once authenticated, the next step is to load the fundamental information that makes up the product catalog and commercial structure.

Recommended Sync Order

Follow this exact order to avoid dependency issues:

2.1 Create Stock Groupers

POST/grouper/stock

Create one grouper per warehouse or depot. The internalCode should be the warehouse code in your ERP.

2.2 Create Promotion Groupers

POST/grouper/promotion

These should represent your commercial segmentations. The internalCode should correspond to the segment code in your ERP.

2.3 Sync Brands

POST/batch/brand

Use the upsert operation. The internalCode should be the brand code from your ERP.

2.4 Sync Categories and Subcategories

Categories (Level 1):

PUT/category

Use upsertCategory operation. The internalCode should be the unique category code in your ERP.

Subcategories (Level 2):

PUT/subcategory

Use upsertSubcategory operation. The parentCategoryInternalCode field is mandatory and must contain the internalCode of a parent category.

2.5 Sync Products

POST/batch/product

Use the upsert operation to create or update products in bulk. The internalCode should be the product SKU from your ERP. Products must have valid brandInternalCode and categoryInternalCode associations (created in previous steps).

See Product documentation for complete field details and examples.

2.6 Stock and Availability Management

Stock management in Nilo is done in two steps:

Step 1: Assign Stores to Stock Grouper

POST/batch/grouper/stock

Associate or disassociate stores to a specific stock grouper. This defines which group of stores will be affected by availability updates.

Step 2: Update Product Availability

POST/batch/stock/grouper

Indicate availability (available: true or available: false) of products for a specific grouperCode. This is the main operation for daily stock management.

2.7 Create Price Lists

POST/pricelist

Create one list per price segmentation. The internalCode should be the list code in your ERP.

2.8 Sync Stores (Clients)

POST/batch/store

Use exclusively the upsert node. In this call, assign priceListCode, stockGrouperCode, and promotionGrouperCodes.

Minimum Order Amount

The settings.dropSize field allows defining a minimum purchase amount per store. If the amount is global, it's not necessary to send it.

2.9 Assign Users to Stores

PUT/store/{code}/add/user

PUT/store/{code}/remove/user

Multiple users can be assigned to a store, and the same user can be assigned to multiple stores.

2.10 Assign Prices and Stores to Lists

POST/batch/pricelist

Add, update, or delete both product prices and associated stores in bulk.

Payload flexibility:

Action	How to do it
Update only prices	Send info in upsert.products, leave upsert.stores as []
Assign only stores	Send info in upsert.stores, leave upsert.products as []
Remove products	Send products in remove.products
Remove stores	Send stores in remove.stores

---

Phase 3: Promotions and Historical Data

3.1 Promotion Types Mapping

Important Configuration Note

The API defines certain fields as mutually exclusive:

• Quantity vs Amount condition: Don't send bonusTierData and bonusTierDataCash simultaneously
• Discount type: Specify discountPercentage OR discountAmount, not both

Sending both fields will result in an error.

Promotion Type	Nilo API Type	Endpoint
Direct Bonus (same product)	BONUS_INDIVIDUAL	PUT /promotion/bonus/individual
Crossed Bonus (different product)	BONUS_CROSSED	PUT /promotion/bonus/crossed
Group Discount (product combination)	DISCOUNT_MULTIPLE	PUT /promotion/discount/multiple
Group Bonus (product combination)	BONUS_CROSSED	PUT /promotion/bonus/crossed
Tiered Simple Discount	DISCOUNT_SIMPLE	PUT /promotion/discount/simple
Combos with discount	DISCOUNT_MULTIPLE	PUT /promotion/discount/multiple
Combos with bonus	BONUS_CROSSED	PUT /promotion/bonus/crossed
Volume Group Discount	DISCOUNT_MULTIPLE	PUT /promotion/discount/multiple
Bonus by Minimum Amount	BONUS_CROSSED	PUT /promotion/bonus/crossed
Simple Discount	DISCOUNT_SIMPLE	PUT /promotion/discount/simple

For bulk management, use:

POST/batch/promotion

3.2 Historical Orders Load

POST/order/bulk-import

Send a batch of historical orders to enrich Nilo's data models and improve user experience (e.g., purchase suggestions). This service is designed for initial data load, not real-time order management.

---

Phase 4: Transactional Flow (Order Management)

This phase describes an order's lifecycle, from Nilo's creation notification to management in your systems.

4.1 Receiving Orders and Cancellations (Webhooks)

Your system must expose an endpoint (URL) that Nilo can invoke to notify real-time events.

Order Creation Webhook:

POST/webhooks/order

Nilo sends a request to your URL each time a new order is created. The request body contains all order information, including Nilo's id, products, quantities, and buyer data.

Required action: Process this information, create the order in your ERP, and respond to Nilo with 200 OK to confirm receipt.

Order Cancellation Webhook:

PUT/webhooks/order

If a store cancels an order from the Nilo platform (while the order is in PENDING status), Nilo sends a notification to this endpoint.

4.2 Order Lifecycle Management (API)

Once an order has been received and created in your ERP, it's your responsibility to update its status on the Nilo platform. Use the id received in the webhook.

PUT/order/{id}/confirm

Confirm that the order has been accepted and is being prepared. You can specify an estimated delivery date (deliveryDate).

PUT/order/{id}/deliver

Notify that the order has been delivered. Allows complete deliveries ("complete": true) or partial, specifying which products and quantities were actually delivered.

PUT/order/{id}/return

Register total or partial product returns from an already delivered order.

PUT/order/{id}/cancel

For cases where you need to cancel an order you had already confirmed (e.g., unexpected stock shortage). Specify a cancellation reason code.

Bulk Order Updates (Recommended)

POST/batch/order

Update the status of multiple orders in a single call. Send batches to confirm, deliver, return, or cancel, each in its corresponding payload node. This significantly reduces API calls and is the most efficient method for daily order management.

---

Next Steps

🔑

Authentication Details

Complete authentication API reference

→🔔

Webhooks Setup

Configure real-time notifications

→