Saltar al contenido principal

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

  1. Estados de Orden: Las órdenes pueden estar en diferentes estados (PENDING, CONFIRMED, DELIVERED, CANCELLED)
  2. Flujo de Estados: El flujo normal es PENDING → CONFIRMED → DELIVERED
  3. Entregas Parciales: Las órdenes pueden entregarse parcialmente con productos específicos
  4. Devoluciones: Los productos pueden devolverse después de la entrega
  5. Cancelaciones: Una orden puede ser cancelada con códigos de motivo específicos
  6. Operaciones por Lotes: Soporte para actualizar múltiples órdenes eficientemente

Operaciones Individuales

Obtener Orden por ID

GET/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ámetroTipoRequeridoDescripción
idstringCódigo de identificación de la orden (el mismo informado en el webhook)

Códigos de Respuesta

CódigoDescripción
200Operación exitosa
404Orden no encontrada

Ejemplo de Uso

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));

Listar Todas las Órdenes

GET/order

Obtiene 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ámetroTipoRequeridoDescripción
takenumberNoNúmero de items por página (máximo 50, mínimo 1, default 50)
pagestringNoNúmero de página (default 1)
cursorstringNoCursor para paginación. La primera llamada debe pasar 0, las siguientes deben usar el cursor del último item
statusstringNoEstado de la orden (DELIVERED, PENDING, CONFIRMED, CANCELLED)
fromstringNoFecha inicial para filtrar (formato YYYY-MM-DD, requerido si se especifica 'to')
tostringNoFecha final para filtrar (formato YYYY-MM-DD, requerido si se especifica 'from')

Ejemplo de Uso

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));

Confirmar Orden

PUT/order/{id}/confirm

Confirma 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ámetroTipoRequeridoDescripción
idintegerCódigo de identificación de la orden (el mismo informado en el webhook)

Parámetros del Cuerpo de la Solicitud

ParámetroTipoRequeridoDescripción
deliveryDatestringNoFecha estimada de entrega (formato YYYY-MM-DD)

Ejemplo del Cuerpo de la Solicitud

{
"deliveryDate": "2025-12-03"
}

Códigos de Respuesta

CódigoDescripción
200Operación exitosa
404Orden no encontrada

Ejemplo de Uso

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));

Marcar Orden como Entregada

PUT/order/{id}/deliver

Actualiza el estado de una orden a entregada. Este endpoint soporta entregas completas y parciales.

Parámetros de Ruta

ParámetroTipoRequeridoDescripción
idintegerCódigo de identificación de la orden (el mismo informado en el webhook)

Parámetros del Cuerpo de la Solicitud

ParámetroTipoRequeridoDescripción
completebooleanNoSi la orden fue entregada completamente
partialDeliveryobjectNoInformación de entrega parcial (si es entrega parcial)

Objeto partialDelivery:

ParámetroTipoRequeridoDescripción
datestringFecha de entrega (formato YYYY-MM-DD)
productsarrayLista de productos que fueron entregados

Items del array products:

ParámetroTipoRequeridoDescripción
productCodestringCódigo interno del producto
unitsintegerUnidades por paquete
quantitynumberCantidad 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ódigoDescripción
200Operación exitosa
404Orden no encontrada

Devolver Productos de Orden

PUT/order/{id}/return

Devuelve productos de una orden entregada. Usa este endpoint para registrar devoluciones de productos.

Parámetros de Ruta

ParámetroTipoRequeridoDescripción
idintegerCódigo de identificación de la orden (el mismo informado en el webhook)

Parámetros del Cuerpo de la Solicitud

ParámetroTipoRequeridoDescripción
datestringFecha de devolución (formato YYYY-MM-DD)
productsarrayLista de productos a devolver

Items del array products:

ParámetroTipoRequeridoDescripción
productCodestringCódigo interno del producto
unitsintegerUnidades por paquete
quantitynumberCantidad a devolver

Ejemplo del Cuerpo de la Solicitud

{
"date": "2025-12-03",
"products": [
{
"productCode": "12345",
"units": 1,
"quantity": 2
}
]
}

Códigos de Respuesta

CódigoDescripción
200Operación exitosa
404Orden no encontrada

Ejemplo de Uso

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));

Cancelar Orden

PUT/order/{id}/cancel

Cancela una orden existente. Debes proporcionar un código de motivo de cancelación.

Parámetros de Ruta

ParámetroTipoRequeridoDescripción
idintegerCódigo de identificación de la orden (el mismo informado en el webhook)

Parámetros del Cuerpo de la Solicitud

ParámetroTipoRequeridoDescripción
codestringNoCódigo de motivo de cancelación

Códigos de Motivo de Cancelación

CódigoDescripción
IMPRECISE_DELIVERY_ADDRESSDirección de entrega imprecisa
OUT_DELIVERY_HOURSFuera de horario de entrega
OUT_TIME_CONFIRMTiempo de confirmación expirado
OUTSTANDING_BALANCECliente tiene saldo pendiente
OUT_OF_STOCKProductos sin stock
OTHEROtro motivo

Ejemplo del Cuerpo de la Solicitud

{
"code": "OUT_OF_STOCK"
}

Códigos de Respuesta

CódigoDescripción
200Operación exitosa
404Orden no encontrada

Ejemplo de Uso

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));

Operaciones por Lotes

Actualización Masiva de Órdenes

POST/batch/order

Realiza 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ámetroTipoRequeridoDescripción
idintegerIdentificación de la orden
deliveryDatestringNoFecha estimada de entrega (YYYY-MM-DD)

Items del Array deliver

ParámetroTipoRequeridoDescripción
idintegerIdentificación de la orden
completebooleanNoSi la orden fue entregada completamente
partialDeliveryobjectNoInfo de entrega parcial (date + array de products)

Items del Array return

ParámetroTipoRequeridoDescripción
idintegerIdentificación de la orden
datestringFecha de devolución (YYYY-MM-DD)
productsarrayLista de productos a devolver

Items del Array cancel

ParámetroTipoRequeridoDescripción
idintegerIdentificación de la orden
codestringNoCó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ódigoDescripción
202Solicitud aceptada, procesamiento iniciado
402Solicitud incorrecta

Operaciones de Importación

Importación Masiva de Órdenes

POST/order/bulk-import

Permite 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ámetroTipoRequeridoDescripción
ordersarrayArray de órdenes a importar

Objeto order:

ParámetroTipoRequeridoDescripción
idintegerIdentificación de la orden
sourcestringIdentificador del sistema origen (ej. "ERP")
buyerobjectInformación del comprador (storeCode, routeCode)
addressobjectDirección de entrega (addressLine, zipCode, etc.)
statusstringEstado: PENDING, CONFIRMED, CANCELLED, DELIVERED
createdAtstringFecha de creación (YYYY-MM-DD)
productsarrayNoLista de productos en la orden
invoicesarrayNoLista 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ódigoDescripción
200Órdenes recibidas exitosamente
400Error en validación de solicitud
500Error interno del servidor

Quick Order

POST/order/quick-order

Permite 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ámetroTipoRequeridoDescripción
productInternalCodestringCódigo de identificación del producto (igual que en ERP)
unitsintegerNoUnidades para buscar display específico
quantityintegerNoCantidad de productos a sugerir
rankintegerNoRanking/orden del producto en la lista de sugerencias
displayInGrouparrayNoDisplays 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ódigoDescripción
200Órdenes recibidas exitosamente
400Error en validación de solicitud
500Error 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

  1. 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
  2. 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
  3. 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
  4. 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

  1. 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
  2. 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
  3. 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
  4. 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

  1. 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
  2. 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
  3. 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
  4. 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:

  1. API Key en el encabezado: x-api-key
  2. 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

  1. Validación de Entrada

    • Validar IDs de orden
    • Verificar estados válidos
    • Validar fechas de entrega
    • Verificar datos de items
  2. Respuestas de Error

    • Usar códigos HTTP apropiados
    • Proporcionar mensajes claros
    • Incluir detalles específicos
    • Mantener consistencia
  3. Procedimientos de Recuperación

    • Manejar fallos de red
    • Implementar reintentos
    • Mantener consistencia de datos
    • Registrar errores críticos
  4. Monitoreo

    • Rastrear errores frecuentes
    • Monitorear tiempos de proceso
    • Alertar sobre fallos críticos
    • Analizar patrones de error