API de Rutas Comerciales

La API de Rutas Comerciales permite gestionar rutas comerciales en la plataforma Nilo. Las rutas comerciales representan caminos de venta o distribución que organizan cómo las tiendas son visitadas y atendidas por los equipos de venta.

Entendiendo las Rutas Comerciales

Las Rutas Comerciales en Nilo definen los caminos de venta o distribución utilizados por tu fuerza de ventas:

• Estructura de la Ruta
  • Código interno único para identificación (igual al código de ruta en tu ERP)
  • Nombre para visualización y organización
  • Estado (habilitado/deshabilitado)

Consideraciones Importantes

1. Códigos Únicos: Cada ruta requiere un código interno único (típicamente el código de ruta de tu ERP)
2. Solo por Lotes: Las rutas comerciales se gestionan exclusivamente a través de operaciones por lotes
3. Lógica de Upsert: El endpoint crea nuevas rutas o actualiza las existentes basándose en el internalCode
4. Gestión de Estado: Las rutas pueden ser habilitadas o deshabilitadas mediante el campo enabled

Operaciones por Lotes

Upsert Masivo de Rutas Comerciales

POST/batch/commercial-route

Crea o actualiza múltiples rutas comerciales en una sola operación. Las rutas se buscan por su internalCode — si una ruta con ese código existe, se actualiza; de lo contrario, se crea una nueva.

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
upsert	array	Sí	Array de rutas comerciales a crear/actualizar

Cada elemento en el array upsert:

Campo	Tipo	Requerido	Descripción
internalCode	string	Sí	Identificador único de la ruta
name	string	No	Nombre de visualización de la ruta
enabled	boolean	Sí	Si la ruta está activa o no

Ejemplo del Cuerpo de la Solicitud

{
  "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
    }
  ]
}

Respuesta

Retorna un 202 Accepted con IDs de proceso por lotes para rastrear la operación.

Campo	Tipo	Descripción
code	number	Código de estado HTTP (202)
batchIds	object	Objeto con UUIDs de seguimiento del lote
message	string	Mensaje de estado

Objeto batchIds:

Campo	Tipo	Descripción
upsert	array	Array de UUIDs para rastrear el proceso de upsert

Ejemplo de Respuesta

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

Códigos de Respuesta

Código	Descripción
202	Solicitud aceptada, procesamiento iniciado
400	Solicitud incorrecta - error de validación
401	No autorizado - token inválido

Ejemplo de Uso

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)

Seguimiento del Progreso del Lote

Después de enviar un upsert por lotes, usa el UUID del proceso retornado en la respuesta para rastrear el progreso mediante los endpoints de Operaciones por Lotes:

• GET /batch/{uuid}/status — progreso general
• GET /batch/{uuid}/detail — resultados individuales de cada operación

Seguridad

Autenticación

Todos los endpoints requieren dos tipos de autenticación:

• API Key en el header: x-api-key
• Token de autorización en el header: Authorization

Permisos Requeridos

Para los endpoints de rutas comerciales, se requieren los siguientes permisos:

• Para operaciones de upsert por lotes: supplier/grouper.bulkwrite