API de Operaciones por Lotes

La API de Operaciones por Lotes permite monitorear y rastrear el estado de los procesos por lotes asíncronos en la plataforma Nilo. Cuando realizas operaciones masivas (como actualizar múltiples productos, precios o promociones), estos procesos se ejecutan de manera asíncrona, y puedes usar estos endpoints para rastrear su progreso y resultados.

Entendiendo los Procesos por Lotes

Los procesos por lotes en Nilo representan operaciones a gran escala que se procesan de manera asíncrona:

• Estructura del Proceso
  • Cada proceso por lotes tiene un identificador UUID único
  • Los procesos contienen múltiples operaciones individuales
  • Las operaciones se rastrean con estado y resultados detallados
  • El progreso puede monitorearse en tiempo real

Consideraciones Importantes

1. Procesamiento Asíncrono: Las operaciones por lotes se ejecutan en segundo plano y pueden tardar en completarse
2. Seguimiento de Estado: Se recomienda verificar regularmente el estado para monitorear el progreso
3. Manejo de Errores: Las operaciones fallidas dentro de un lote se rastrean individualmente
4. Estados de Finalización: Los procesos pueden terminar en estados completado, fallido o completado parcialmente
5. Registro Detallado: Cada operación dentro de un lote mantiene su propio estado y mensajes de error

Operaciones por Lotes

Obtener Detalles del Proceso por Lotes

GET/batch/{uuid}/detail

Recupera información detallada sobre un proceso por lotes específico, incluyendo el estado de las operaciones individuales dentro del lote.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
uuid	string	Sí	Código de identificación del proceso

Parámetros de Respuesta

Parámetro	Tipo	Descripción
uuid	string	Identificador único del proceso por lotes
detail	array	Array de operaciones individuales en el lote

Cada elemento del detalle contiene:

Campo	Tipo	Descripción
code	string	Identificador único de la operación
endpoint	string	Endpoint de API utilizado para la operación
action	string	Tipo de acción realizada
batchItem	string	Datos JSON del elemento procesado
status	string	Estado actual (processing/completed/failed)
message	string	Mensaje del sistema o descripción del error
finishedAt	string	Marca de tiempo de finalización (formato ISO 8601)
createdAt	string	Marca de tiempo de creación (formato ISO 8601)

Ejemplo de Respuesta

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "detail": [
    {
      "code": "550e8400-e29b-41d4-a716-446655440000",
      "endpoint": "batch/product/22222.1",
      "action": "availability",
      "batchItem": "{\"product\": \"22222.1\", \"store\": 2134, \"available\": true, \"units\": 1}",
      "status": "completed",
      "message": "Producto procesado exitosamente",
      "finishedAt": "2025-12-03T10:15:30Z",
      "createdAt": "2025-12-03T10:15:30Z"
    }
  ]
}

Ejemplo de Uso

Javascript

const headers = {
  Authorization: "TU_TOKEN_DE_AUTORIZACION",
  "x-api-key": "TU_API_KEY",
};

fetch(
  "https://api.nilo.com/batch/550e8400-e29b-41d4-a716-446655440000/detail",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://api.nilo.com/batch/550e8400-e29b-41d4-a716-446655440000/detail"

headers = {
    'Authorization': 'TU_TOKEN_DE_AUTORIZACION',
    'x-api-key': 'TU_API_KEY'
}

response = requests.get(url, headers=headers)
print(response.text)

Obtener Estado del Proceso por Lotes

GET/batch/{uuid}/status

Recupera un resumen del estado del proceso por lotes, incluyendo estadísticas de progreso y estado de finalización.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
uuid	string	Sí	Código de identificación del proceso

Parámetros de Respuesta

Parámetro	Tipo	Descripción
uuid	string	Identificador único del proceso por lotes
status	string	Estado general (processing/completed/failed)
createdAt	string	Marca de tiempo de creación (formato ISO 8601)
finishedAt	string	Marca de tiempo de finalización (formato ISO 8601)
summary	object	Resumen estadístico del proceso por lotes

El objeto summary contiene:

Campo	Tipo	Descripción
total	integer	Número total de operaciones en el lote
processed	integer	Número de operaciones procesadas
failed	integer	Número de operaciones fallidas
completed	integer	Número de operaciones completadas exitosamente

Ejemplo de Respuesta

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "createdAt": "2025-12-03T10:15:30Z",
  "finishedAt": "2025-12-03T10:15:30Z",
  "summary": {
    "total": 100,
    "processed": 50,
    "failed": 10,
    "completed": 40
  }
}

Ejemplo de Uso

Javascript

const headers = {
  Authorization: "TU_TOKEN_DE_AUTORIZACION",
  "x-api-key": "TU_API_KEY",
};

fetch(
  "https://api.nilo.com/batch/550e8400-e29b-41d4-a716-446655440000/status",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://api.nilo.com/batch/550e8400-e29b-41d4-a716-446655440000/status"

headers = {
    'Authorization': 'TU_TOKEN_DE_AUTORIZACION',
    'x-api-key': 'TU_API_KEY'
}

response = requests.get(url, headers=headers)
print(response.text)

Obtener Ítems Fallidos por Fecha

GET/batch/failed-items

Devuelve los ítems fallidos del proveedor autenticado para una fecha determinada. Usá los filtros opcionales para acotar la cola de reintentos.

Parámetro de consulta	Tipo	Requerido	Descripción
date	string	Sí	Fecha con formato YYYY-MM-DD.
entity	string	No	Entidad por la que se filtra. Ver los valores permitidos abajo.
page	integer	No	Número de página.
pageSize	integer	No	Cantidad de ítems por página.

Valores permitidos para entity: STOCK, PRODUCT, STORE, PROMOTION, GROUPERS, PRICELIST, ORDER, BRAND, CATEGORY, SALES_REP, COMMERCIAL_ROUTE y LOYALTY.

curl -G "https://api.nilo.com/batch/failed-items" \
  -H "Authorization: TU_TOKEN_DE_AUTORIZACION" \
  -H "x-api-key: TU_API_KEY" \
  --data-urlencode "date=2026-05-19" \
  --data-urlencode "entity=PRODUCT" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=50"

Mejores Prácticas para el Procesamiento por Lotes

1. Monitoreo de Estado

   • Verificar regularmente el estado de los procesos de larga duración
   • Implementar retroceso exponencial para las verificaciones de estado
   • Monitorear tanto el estado general como los detalles de operaciones individuales
   • Mantener un registro de las operaciones fallidas para estrategias de reintento

2. Manejo de Errores

   • Revisar mensajes de error detallados para operaciones fallidas
   • Implementar lógica de reintentos para elementos fallidos
   • Mantener registro de lotes completados parcialmente
   • Registrar todas las respuestas de error para solución de problemas

3. Optimización de Rendimiento

   • Agrupar operaciones relacionadas en lotes únicos
   • Monitorear tamaños de lote para un rendimiento óptimo
   • Programar lotes grandes durante horas de baja demanda
   • Implementar procesamiento paralelo cuando sea posible

4. Gestión de Datos

   • Mantener registros de IDs de procesos por lotes
   • Archivar detalles de lotes completados para auditoría
   • Rastrear tasas de éxito en diferentes tipos de operaciones
   • Monitorear patrones en operaciones fallidas

Seguridad

Autenticación

Todos los endpoints 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 operaciones por lotes, se requieren los siguientes permisos:

• Para leer detalles de lotes: supplier/batch.read
• Para leer estado de lotes: supplier/bulk.read
• Para leer ítems fallidos: supplier/batch.read