Commercial Routes API

The Commercial Routes API allows you to manage commercial routes in the Nilo platform. Commercial routes represent sales routes or distribution paths that organize how stores are visited and served by sales teams.

Understanding Commercial Routes

Commercial Routes in Nilo define the sales or distribution paths used by your sales force:

• Route Structure
  • Unique internal code for identification (same as route code in your ERP)
  • Name for display and organization
  • Status (enabled/disabled)

Important Considerations

1. Unique Codes: Each route requires a unique internal code (typically your route code from ERP)
2. Batch Only: Commercial routes are managed exclusively through batch operations
3. Upsert Logic: The batch endpoint creates new routes or updates existing ones based on the internalCode
4. Status Management: Routes can be enabled or disabled via the enabled field

Batch Operations

Batch Upsert Commercial Routes

POST/batch/commercial-route

Create or update multiple commercial routes in a single operation. Routes are matched by their internalCode — if a route with that code exists, it will be updated; otherwise, a new route is created.

Request Body Parameters

Parameter	Type	Required	Description
upsert	array	Yes	Array of commercial routes to upsert

Each item in the upsert array:

Field	Type	Required	Description
internalCode	string	Yes	Unique identifier for the route
name	string	No	Display name of the route
enabled	boolean	Yes	Whether the route is active or not

Request Body Example

{
  "upsert": [
    {
      "internalCode": "RUTA-001",
      "name": "Ruta Norte",
      "enabled": true
    },
    {
      "internalCode": "RUTA-002",
      "name": "Ruta Sur",
      "enabled": true
    },
    {
      "internalCode": "RUTA-003",
      "name": "Ruta Oeste (desactivada)",
      "enabled": false
    }
  ]
}

Response

Returns a 202 Accepted with batch process IDs to track the operation.

Field	Type	Description
code	number	HTTP status code (202)
batchIds	object	Object containing batch tracking UUIDs
message	string	Status message

batchIds object:

Field	Type	Description
upsert	array	Array of UUIDs for tracking the upsert process

Response Example

{
  "code": 202,
  "batchIds": {
    "upsert": ["550e8400-e29b-41d4-a716-446655440000"]
  },
  "message": "Operation in processing"
}

Response Codes

Code	Description
202	Request accepted, processing initiated
400	Bad request - validation error
401	Unauthorized - invalid token

Example Usage

Javascript

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  upsert: [
    {
      internalCode: "RUTA-001",
      name: "Ruta Norte",
      enabled: true,
    },
    {
      internalCode: "RUTA-002",
      name: "Ruta Sur",
      enabled: true,
    },
  ],
};

fetch("https://api.nilo.com/batch/commercial-route", {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://api.nilo.com/batch/commercial-route"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "upsert": [
        {
            "internalCode": "RUTA-001",
            "name": "Ruta Norte",
            "enabled": True
        },
        {
            "internalCode": "RUTA-002",
            "name": "Ruta Sur",
            "enabled": True
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Tracking Batch Progress

After submitting a batch upsert, use the batch process UUID returned in the response to track progress via the Batch Operations endpoints:

• GET /batch/{uuid}/status — overall progress
• GET /batch/{uuid}/detail — individual operation results

Security

Authentication

All endpoints require two types of authentication:

• API Key in header: x-api-key
• Authorization token in header: Authorization

Required Permissions

For commercial route endpoints, the following permissions are required:

• For batch upsert operations: supplier/grouper.bulkwrite