API de Gestión de Órdenes
La API de Gestión de Órdenes permite administrar y dar seguimiento a los pedidos en la plataforma Nilo. Estos endpoints te ayudan a obtener, confirmar, entregar, devolver y cancelar órdenes, así como realizar operaciones masivas e importar historial de pedidos.
Entendiendo las Órdenes
Las órdenes en Nilo representan los pedidos realizados por los clientes:
-
Estructura de Orden
- Identificador único de orden
- Información del cliente y entrega
- Lista de productos y cantidades
- Estado de la orden (PENDING, CONFIRMED, DELIVERED, CANCELLED)
- Fechas de creación, confirmación y entrega
- Detalles de facturación y envío
-
Jerarquía de Orden
- Las órdenes contienen múltiples items
- Cada item está asociado a un producto
- Las órdenes pasan por diferentes estados
- Soporte para entregas parciales y devoluciones
- Mantienen un historial de cambios
Consideraciones Importantes
- Estados de Orden: Las órdenes pueden estar en diferentes estados (PENDING, CONFIRMED, DELIVERED, CANCELLED)
- Flujo de Estados: El flujo normal es PENDING → CONFIRMED → DELIVERED
- Entregas Parciales: Las órdenes pueden entregarse parcialmente con productos específicos
- Devoluciones: Los productos pueden devolverse después de la entrega
- Cancelaciones: Una orden puede ser cancelada con códigos de motivo específicos
- Operaciones por Lotes: Soporte para actualizar múltiples órdenes eficientemente
Operaciones Individuales
Obtener Orden por ID
/order/{id}Obtiene los detalles de una orden específica. Este endpoint es útil para:
- Verificar el estado actual de una orden
- Obtener detalles completos de los productos ordenados
- Consultar información de entrega y facturación
Parámetros de Ruta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| id | string | Sí | Código de identificación de la orden (el mismo informado en el webhook) |
Códigos de Respuesta
| Código | Descripción |
|---|---|
| 200 | Operación exitosa |
| 404 | Orden no encontrada |
Ejemplo de Uso
- Javascript
- Python
const headers = {
Authorization: "TU_TOKEN_DE_AUTH",
"x-api-key": "TU_API_KEY",
};
fetch(
"https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/order/1234567890",
{
method: "GET",
headers: headers,
}
)
.then((response) => response.json())
.then((result) => console.log(result))
.catch((error) => console.log("error", error));
import requests
url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/order/1234567890"
headers = {
'Authorization': 'TU_TOKEN_DE_AUTH',
'x-api-key': 'TU_API_KEY'
}
response = requests.get(url, headers=headers)
print(response.text)
Listar Todas las Órdenes
/orderObtiene una lista paginada de órdenes con opciones de filtrado. Este endpoint permite:
- Consultar órdenes por estado
- Filtrar por rango de fechas
- Implementar paginación basada en cursor
- Monitorear órdenes pendientes
Parámetros de Consulta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| take | number | No | Número de items por página (máximo 50, mínimo 1, default 50) |
| page | string | No | Número de página (default 1) |
| cursor | string | No | Cursor para paginación. La primera llamada debe pasar 0, las siguientes deben usar el cursor del último item |
| status | string | No | Estado de la orden (DELIVERED, PENDING, CONFIRMED, CANCELLED) |
| from | string | No | Fecha inicial para filtrar (formato YYYY-MM-DD, requerido si se especifica 'to') |
| to | string | No | Fecha final para filtrar (formato YYYY-MM-DD, requerido si se especifica 'from') |
Ejemplo de Uso
- Javascript
- Python
const headers = {
Authorization: "TU_TOKEN_DE_AUTH",
"x-api-key": "TU_API_KEY",
};
// Primera solicitud
fetch(
"https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/order?status=PENDING&take=50&cursor=0",
{
method: "GET",
headers: headers,
}
)
.then((response) => response.json())
.then((result) => console.log(result))
.catch((error) => console.log("error", error));
import requests
url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/order"
headers = {
'Authorization': 'TU_TOKEN_DE_AUTH',
'x-api-key': 'TU_API_KEY'
}
params = {
'status': 'PENDING',
'take': 50,
'cursor': 0
}
response = requests.get(url, headers=headers, params=params)
print(response.text)
Confirmar Orden
/order/{id}/confirmConfirma una orden y establece la fecha estimada de entrega. Este endpoint permite:
- Aceptar una orden para procesamiento
- Establecer fecha estimada de entrega
- Actualizar la fecha de entrega en confirmaciones subsecuentes
Si la orden ya ha sido confirmada, las solicitudes posteriores actualizarán la fecha de entrega con la última fecha proporcionada.
Parámetros de Ruta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| id | integer | Sí | Código de identificación de la orden (el mismo informado en el webhook) |
Parámetros del Cuerpo de la Solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| deliveryDate | string | No | Fecha estimada de entrega (formato YYYY-MM-DD) |
Ejemplo del Cuerpo de la Solicitud
{
"deliveryDate": "2025-12-03"
}
Códigos de Respuesta
| Código | Descripción |
|---|---|
| 200 | Operación exitosa |
| 404 | Orden no encontrada |
Ejemplo de Uso
- Javascript
- Python
const headers = {
Authorization: "TU_TOKEN_DE_AUTH",
"x-api-key": "TU_API_KEY",
"Content-Type": "application/json",
};
const data = {
deliveryDate: "2025-12-03",
};
fetch(
"https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/order/22/confirm",
{
method: "PUT",
headers: headers,
body: JSON.stringify(data),
}
)
.then((response) => response.json())
.then((result) => console.log(result))
.catch((error) => console.log("error", error));
import requests
url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/order/22/confirm"
headers = {
'Authorization': 'TU_TOKEN_DE_AUTH',
'x-api-key': 'TU_API_KEY',
'Content-Type': 'application/json'
}
data = {
"deliveryDate": "2025-12-03"
}
response = requests.put(url, headers=headers, json=data)
print(response.text)
Marcar Orden como Entregada
/order/{id}/deliverActualiza el estado de una orden a entregada. Este endpoint soporta entregas completas y parciales.
Parámetros de Ruta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| id | integer | Sí | Código de identificación de la orden (el mismo informado en el webhook) |
Parámetros del Cuerpo de la Solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| complete | boolean | No | Si la orden fue entregada completamente |
| partialDelivery | object | No | Información de entrega parcial (si es entrega parcial) |
Objeto partialDelivery:
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| date | string | Sí | Fecha de entrega (formato YYYY-MM-DD) |
| products | array | Sí | Lista de productos que fueron entregados |
Items del array products:
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| productCode | string | Sí | Código interno del producto |
| units | integer | Sí | Unidades por paquete |
| quantity | number | Sí | Cantidad entregada |
Ejemplo del Cuerpo - Entrega Completa
{
"complete": true
}
Ejemplo del Cuerpo - Entrega Parcial
{
"complete": false,
"partialDelivery": {
"date": "2025-12-03",
"products": [
{
"productCode": "12345",
"units": 1,
"quantity": 5
},
{
"productCode": "67890",
"units": 6,
"quantity": 2
}
]
}
}
Códigos de Respuesta
| Código | Descripción |
|---|---|
| 200 | Operación exitosa |
| 404 | Orden no encontrada |
Devolver Productos de Orden
/order/{id}/returnDevuelve productos de una orden entregada. Usa este endpoint para registrar devoluciones de productos.
Parámetros de Ruta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| id | integer | Sí | Código de identificación de la orden (el mismo informado en el webhook) |
Parámetros del Cuerpo de la Solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| date | string | Sí | Fecha de devolución (formato YYYY-MM-DD) |
| products | array | Sí | Lista de productos a devolver |
Items del array products:
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| productCode | string | Sí | Código interno del producto |
| units | integer | Sí | Unidades por paquete |
| quantity | number | Sí | Cantidad a devolver |
Ejemplo del Cuerpo de la Solicitud
{
"date": "2025-12-03",
"products": [
{
"productCode": "12345",
"units": 1,
"quantity": 2
}
]
}
Códigos de Respuesta
| Código | Descripción |
|---|---|
| 200 | Operación exitosa |
| 404 | Orden no encontrada |
Ejemplo de Uso
- Javascript
- Python
const headers = {
Authorization: "TU_TOKEN_DE_AUTH",
"x-api-key": "TU_API_KEY",
"Content-Type": "application/json",
};
const data = {
date: "2025-12-03",
products: [
{
productCode: "12345",
units: 1,
quantity: 2,
},
],
};
fetch(
"https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/order/22/return",
{
method: "PUT",
headers: headers,
body: JSON.stringify(data),
}
)
.then((response) => response.json())
.then((result) => console.log(result))
.catch((error) => console.log("error", error));
import requests
url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/order/22/return"
headers = {
'Authorization': 'TU_TOKEN_DE_AUTH',
'x-api-key': 'TU_API_KEY',
'Content-Type': 'application/json'
}
data = {
"date": "2025-12-03",
"products": [
{
"productCode": "12345",
"units": 1,
"quantity": 2
}
]
}
response = requests.put(url, headers=headers, json=data)
print(response.text)
Cancelar Orden
/order/{id}/cancelCancela una orden existente. Debes proporcionar un código de motivo de cancelación.
Parámetros de Ruta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| id | integer | Sí | Código de identificación de la orden (el mismo informado en el webhook) |
Parámetros del Cuerpo de la Solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| code | string | No | Código de motivo de cancelación |
Códigos de Motivo de Cancelación
| Código | Descripción |
|---|---|
| IMPRECISE_DELIVERY_ADDRESS | Dirección de entrega imprecisa |
| OUT_DELIVERY_HOURS | Fuera de horario de entrega |
| OUT_TIME_CONFIRM | Tiempo de confirmación expirado |
| OUTSTANDING_BALANCE | Cliente tiene saldo pendiente |
| OUT_OF_STOCK | Productos sin stock |
| OTHER | Otro motivo |
Ejemplo del Cuerpo de la Solicitud
{
"code": "OUT_OF_STOCK"
}
Códigos de Respuesta
| Código | Descripción |
|---|---|
| 200 | Operación exitosa |
| 404 | Orden no encontrada |
Ejemplo de Uso
- Javascript
- Python
const headers = {
Authorization: "TU_TOKEN_DE_AUTH",
"x-api-key": "TU_API_KEY",
"Content-Type": "application/json",
};
const data = {
code: "OUT_OF_STOCK",
};
fetch(
"https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/order/22/cancel",
{
method: "PUT",
headers: headers,
body: JSON.stringify(data),
}
)
.then((response) => response.json())
.then((result) => console.log(result))
.catch((error) => console.log("error", error));
import requests
url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/order/22/cancel"
headers = {
'Authorization': 'TU_TOKEN_DE_AUTH',
'x-api-key': 'TU_API_KEY',
'Content-Type': 'application/json'
}
data = {
"code": "OUT_OF_STOCK"
}
response = requests.put(url, headers=headers, json=data)
print(response.text)
Operaciones por Lotes
Actualización Masiva de Órdenes
/batch/orderRealiza actualizaciones en múltiples órdenes simultáneamente. Este endpoint permite confirmar, entregar, devolver o cancelar múltiples órdenes en una sola solicitud.
Estructura del Cuerpo de la Solicitud
El cuerpo contiene un objeto status con arrays para cada tipo de operación:
{
"status": {
"confirm": [...],
"deliver": [...],
"return": [...],
"cancel": [...]
}
}
Items del Array confirm
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| id | integer | Sí | Identificación de la orden |
| deliveryDate | string | No | Fecha estimada de entrega (YYYY-MM-DD) |
Items del Array deliver
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| id | integer | Sí | Identificación de la orden |
| complete | boolean | No | Si la orden fue entregada completamente |
| partialDelivery | object | No | Info de entrega parcial (date + array de products) |
Items del Array return
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| id | integer | Sí | Identificación de la orden |
| date | string | Sí | Fecha de devolución (YYYY-MM-DD) |
| products | array | Sí | Lista de productos a devolver |
Items del Array cancel
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| id | integer | Sí | Identificación de la orden |
| code | string | No | Código de motivo: IMPRECISE_DELIVERY_ADDRESS, OUT_DELIVERY_HOURS, OUT_TIME_CONFIRM, OUTSTANDING_BALANCE, OUT_OF_STOCK, OTHER |
Ejemplo del Cuerpo de la Solicitud
{
"status": {
"confirm": [
{
"id": 10,
"deliveryDate": "2025-12-03"
},
{
"id": 11,
"deliveryDate": "2025-12-04"
}
],
"deliver": [
{
"id": 5,
"complete": true
}
],
"cancel": [
{
"id": 7,
"code": "OUT_OF_STOCK"
}
]
}
}
Códigos de Respuesta
| Código | Descripción |
|---|---|
| 202 | Solicitud aceptada, procesamiento iniciado |
| 402 | Solicitud incorrecta |
Operaciones de Importación
Importación Masiva de Órdenes
/order/bulk-importPermite importar historial de órdenes desde otros sistemas (ej. tu ERP). Esto es útil para:
- Migrar órdenes históricas a Nilo
- Sincronizar órdenes creadas en otros sistemas
- Mantener un historial completo de órdenes
Parámetros del Cuerpo de la Solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| orders | array | Sí | Array de órdenes a importar |
Objeto order:
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| id | integer | Sí | Identificación de la orden |
| source | string | Sí | Identificador del sistema origen (ej. "ERP") |
| buyer | object | Sí | Información del comprador (storeCode, routeCode) |
| address | object | Sí | Dirección de entrega (addressLine, zipCode, etc.) |
| status | string | Sí | Estado: PENDING, CONFIRMED, CANCELLED, DELIVERED |
| createdAt | string | Sí | Fecha de creación (YYYY-MM-DD) |
| products | array | No | Lista de productos en la orden |
| invoices | array | No | Lista de facturas generadas de la orden |
Ejemplo del Cuerpo de la Solicitud
{
"orders": [
{
"id": 10,
"source": "ERP",
"buyer": {
"storeCode": "10",
"routeCode": "10"
},
"address": {
"addressLine": "25 de mayo 1200, Buenos Aires, Argentina",
"zipCode": "2400"
},
"status": "DELIVERED",
"createdAt": "2025-12-03",
"products": [
{
"productCode": "12345",
"units": 1,
"quantity": 5
}
]
}
]
}
Códigos de Respuesta
| Código | Descripción |
|---|---|
| 200 | Órdenes recibidas exitosamente |
| 400 | Error en validación de solicitud |
| 500 | Error interno del servidor |
Quick Order
/order/quick-orderPermite a otros sistemas enviar sugerencias de pedidos rápidos a usuarios. Este endpoint es útil para:
- Sugerir productos a usuarios basándose en su historial de compras
- Crear listas de compras pre-pobladas
- Habilitar funcionalidad de re-ordenar con un click
Parámetros del Cuerpo de la Solicitud
El cuerpo es un array de sugerencias de productos:
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| productInternalCode | string | Sí | Código de identificación del producto (igual que en ERP) |
| units | integer | No | Unidades para buscar display específico |
| quantity | integer | No | Cantidad de productos a sugerir |
| rank | integer | No | Ranking/orden del producto en la lista de sugerencias |
| displayInGroup | array | No | Displays alternativos a mostrar al usuario |
Ejemplo del Cuerpo de la Solicitud
[
{
"productInternalCode": "529",
"units": 1,
"quantity": 4,
"rank": 1
},
{
"productInternalCode": "530",
"units": 6,
"quantity": 2,
"rank": 2
}
]
Códigos de Respuesta
| Código | Descripción |
|---|---|
| 200 | Órdenes recibidas exitosamente |
| 400 | Error en validación de solicitud |
| 500 | Error interno del servidor |
Tipos de Respuesta
Respuesta Exitosa
{
"code": 200,
"message": "Operación exitosa",
"data": {
"id": "22",
"status": "CONFIRMED",
"estimatedDeliveryDate": "2024-02-20",
"items": [
{
"productCode": "123",
"quantity": 2
}
]
}
}
Ejemplos de Respuesta de Error
Orden No Encontrada
{
"code": 404,
"message": "Orden no encontrada"
}
Error de Validación
{
"code": 400,
"message": "Datos inválidos",
"errors": [
{
"field": "estimatedDeliveryDate",
"message": "La fecha de entrega es requerida"
}
]
}
Mejores Prácticas
-
Gestión de Estados
- Respetar el flujo de estados: PENDING → CONFIRMED → DELIVERED
- Usar códigos de cancelación apropiados al cancelar órdenes
- Rastrear entregas parciales y devoluciones con precisión
- Mantener consistencia en fechas a través de las operaciones
-
Manejo de Fechas
- Usar formato YYYY-MM-DD para todas las fechas
- Validar fechas de entrega realistas
- Considerar zonas horarias
- Mantener histórico de cambios
-
Procesamiento de Órdenes
- Implementar validaciones de inventario antes de confirmar
- Usar entrega parcial cuando no todos los productos se entregan
- Rastrear devoluciones correctamente para gestión de inventario
- Documentar motivos de cancelación con códigos apropiados
-
Optimización de Rendimiento
- Usar operaciones por lotes para actualizaciones masivas
- Usar paginación basada en cursor para listar órdenes
- Implementar caché cuando sea apropiado
- Monitorear tiempos de respuesta
Casos de Uso Comunes
-
Gestión de Pedidos Nuevos
- Monitorear órdenes pendientes usando el endpoint de listado con filtro de estado
- Confirmar órdenes rápidamente con fechas estimadas de entrega
- Validar disponibilidad de productos antes de confirmar
- Usar webhooks para recibir notificaciones de nuevas órdenes
-
Gestión de Entregas
- Marcar órdenes como entregadas (completa o parcialmente)
- Rastrear entregas parciales con productos específicos
- Gestionar devoluciones cuando se regresan productos
- Documentar problemas de entrega
-
Operaciones por Lotes
- Confirmar múltiples órdenes a la vez
- Procesar entregas por lotes al final del día
- Gestionar cancelaciones en lote
- Sincronizar estados de órdenes con tu ERP
-
Importación de Órdenes
- Importar órdenes históricas desde tu ERP
- Sincronizar órdenes creadas en otros sistemas
- Usar quick-order para compras sugeridas
- Mantener historial completo de órdenes en Nilo
Guías de Implementación
-
Procesamiento de Órdenes
- Validar datos requeridos antes de operaciones
- Verificar que el estado actual permite la transición
- Usar endpoint por lotes para múltiples actualizaciones
- Gestionar errores de forma elegante
-
Gestión de Estados
- Implementar lógica de máquina de estados
- Validar que las transiciones están permitidas
- Registrar cambios con timestamps
- Notificar sistemas relevantes de las actualizaciones
-
Operaciones Parciales
- Usar entrega parcial cuando no todos los productos se entregan
- Rastrear productos devueltos con fecha y cantidades
- Mantener inventario preciso basado en entregas/devoluciones
- Gestionar excepciones apropiadamente
-
Procesamiento por Lotes
- Validar datos del lote antes de enviar
- Gestionar fallos parciales de forma elegante
- Verificar estado del lote para resultados
- Implementar lógica de reintento para items fallidos
Seguridad
Todos los endpoints de la API requieren dos tipos de autenticación:
- API Key en el encabezado:
x-api-key - Token de autorización en el encabezado:
Authorization
Permisos Requeridos
Para los endpoints de órdenes, se requieren los siguientes permisos:
- Para operaciones de lectura:
supplier/order.read - Para operaciones de escritura:
supplier/order.write - Para operaciones de lote e importación:
supplier/order.bulkwrite
Manejo de Errores
-
Validación de Entrada
- Validar IDs de orden
- Verificar estados válidos
- Validar fechas de entrega
- Verificar datos de items
-
Respuestas de Error
- Usar códigos HTTP apropiados
- Proporcionar mensajes claros
- Incluir detalles específicos
- Mantener consistencia
-
Procedimientos de Recuperación
- Manejar fallos de red
- Implementar reintentos
- Mantener consistencia de datos
- Registrar errores críticos
-
Monitoreo
- Rastrear errores frecuentes
- Monitorear tiempos de proceso
- Alertar sobre fallos críticos
- Analizar patrones de error