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

Procesamiento Asíncrono: Las operaciones por lotes se ejecutan en segundo plano y pueden tardar en completarse
Seguimiento de Estado: Se recomienda verificar regularmente el estado para monitorear el progreso
Manejo de Errores: Las operaciones fallidas dentro de un lote se rastrean individualmente
Estados de Finalización: Los procesos pueden terminar en estados completado, fallido o completado parcialmente
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
Python

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

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
Python

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

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)

Mejores Prácticas para el Procesamiento por Lotes

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

Entendiendo los Procesos por Lotes​

Consideraciones Importantes​

Operaciones por Lotes​

Obtener Detalles del Proceso por Lotes​

Parámetros de Ruta​

Parámetros de Respuesta​

Ejemplo de Respuesta​

Ejemplo de Uso​

Obtener Estado del Proceso por Lotes​

Parámetros de Ruta​

Parámetros de Respuesta​

Ejemplo de Respuesta​

Ejemplo de Uso​

Mejores Prácticas para el Procesamiento por Lotes​

Seguridad​

Autenticación​

Permisos Requeridos​

Entendiendo los Procesos por Lotes

Consideraciones Importantes

Operaciones por Lotes

Obtener Detalles del Proceso por Lotes

Parámetros de Ruta

Parámetros de Respuesta

Ejemplo de Respuesta

Ejemplo de Uso

Obtener Estado del Proceso por Lotes

Parámetros de Ruta

Parámetros de Respuesta

Ejemplo de Respuesta

Ejemplo de Uso

Mejores Prácticas para el Procesamiento por Lotes

Seguridad

Autenticación

Permisos Requeridos