API de Gestión de Stock

La API de Gestión de Stock permite administrar la disponibilidad de productos usando agrupadores de stock. Estos endpoints ayudan a mantener información precisa del stock en la plataforma Nilo.

Entendiendo la Gestión de Stock

La gestión de stock en Nilo está organizada alrededor de agrupadores - grupos lógicos de tiendas que comparten la misma disponibilidad de productos:

Estructura del Stock
- La disponibilidad de productos se gestiona por agrupador (no por tienda individual)
- Seguimiento de disponibilidad específica por unidad para configuraciones de display
- La gestión basada en agrupadores permite actualizaciones eficientes en múltiples tiendas
- Seguimiento de estado para disponibilidad de productos
Jerarquía del Stock
- Las tiendas se asignan a agrupadores de stock
- Los productos se marcan como disponibles/no disponibles para un agrupador
- Todas las tiendas en un agrupador comparten la misma disponibilidad de productos
- Soporte para operaciones por lotes en múltiples productos

Consideraciones Importantes

Gestión Basada en Agrupadores: El stock se gestiona a nivel de agrupador, no de tiendas individuales
Gestión de Unidades: El stock puede gestionarse a nivel de presentación de unidades (configuraciones de display)
Sistema de Agrupadores: Crea agrupadores para representar almacenes, regiones o centros de distribución
Operaciones por Lotes: Soporte para actualizaciones masivas en múltiples productos
Actualizaciones en Tiempo Real: Los cambios de stock afectan la visibilidad inmediata del producto en todas las tiendas del agrupador

Operaciones de Producto Individual

Actualizar Stock de Producto

POST/product/{code}/stock

Este endpoint permite actualizar el estado de disponibilidad de un producto específico para un agrupador de stock en particular. Úsalo cuando necesites:

Marcar un producto como disponible/no disponible para un agrupador específico
Actualizar las unidades disponibles para una presentación específica del producto
Gestionar la visibilidad individual de productos en todas las tiendas del agrupador

Cuando un producto se marca como no disponible, no se mostrará en los catálogos de ninguna tienda que pertenezca a ese agrupador, evitando que los clientes ordenen productos sin stock.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	Código interno del producto (igual que en ERP)

Parámetros del Cuerpo de la Petición

Parámetro	Tipo	Requerido	Descripción
grouperCode	string	Sí	Código del agrupador de stock donde se actualizará la disponibilidad (igual que en ERP)
available	boolean	Sí	Si el producto está disponible (true) o no disponible (false) para el agrupador
units	integer	No	Número de unidades. Cuando se especifica, solo actualiza la presentación con esta configuración específica

Ejemplo del Cuerpo de la Petición

{
  "grouperCode": "123456",
  "available": true,
  "units": 1
}

Códigos de Respuesta

Código	Descripción
200	Operación exitosa
404	Código de Producto no encontrado o Agrupador no encontrado

Ejemplo de Uso

Javascript
Python

const headers = {
  Authorization: "TU_TOKEN_DE_AUTH",
  "x-api-key": "TU_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  grouperCode: "123456",
  available: true,
  units: 1,
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/product/22222/stock",
  {
    method: "POST",
    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/product/22222/stock"

headers = {
    'Authorization': 'TU_TOKEN_DE_AUTH',
    'x-api-key': 'TU_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "grouperCode": "123456",
    "available": True,
    "units": 1
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Operaciones por Lotes

Actualización por Lotes de Stock por Agrupador

POST/batch/stock/grouper

Este endpoint te permite actualizar la disponibilidad de múltiples productos a la vez usando códigos de agrupador. Este es el endpoint principal para la gestión diaria de stock.

Úsalo cuando necesites:

Actualizar el estado del stock de múltiples productos simultáneamente
Sincronizar datos de inventario desde tu sistema ERP
Realizar actualizaciones masivas de disponibilidad para un agrupador específico
Gestionar eficientemente la visibilidad de productos en todas las tiendas de un agrupador

La operación por lotes se procesa de forma asíncrona, lo que significa que recibirás una confirmación inmediata de la solicitud, y las actualizaciones se procesarán en segundo plano.

Recomendado para Operaciones Diarias

Este es el método más eficiente para la gestión diaria de stock. En lugar de actualizar productos uno por uno, envía lotes de actualizaciones de disponibilidad para un agrupador específico.

Parámetros del Cuerpo de la Petición

Parámetro	Tipo	Requerido	Descripción
productCode	string	Sí	Código interno del producto (igual que en ERP)
grouperCode	string	Sí	Código del agrupador de stock - todas las tiendas de este agrupador se verán afectadas
available	boolean	Sí	Si el producto está disponible (true) o no disponible (false)

Ejemplo del Cuerpo de la Petición

{
  "availability": [
    {
      "productCode": "22222",
      "grouperCode": "123456",
      "available": true
    },
    {
      "productCode": "33333",
      "grouperCode": "123456",
      "available": false
    },
    {
      "productCode": "44444",
      "grouperCode": "789012",
      "available": true
    }
  ]
}

Códigos de Respuesta

Código	Descripción
200	Solicitud aceptada, procesamiento iniciado
404	Código de Agrupador no encontrado

Ejemplo de Uso

Javascript
Python

const headers = {
  Authorization: "TU_TOKEN_DE_AUTH",
  "x-api-key": "TU_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  availability: [
    {
      productCode: "22222",
      grouperCode: "123456",
      available: true,
    },
    {
      productCode: "33333",
      grouperCode: "123456",
      available: false,
    },
  ],
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/stock/grouper",
  {
    method: "POST",
    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/batch/stock/grouper"

headers = {
    'Authorization': 'TU_TOKEN_DE_AUTH',
    'x-api-key': 'TU_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "availability": [
        {
            "productCode": "22222",
            "grouperCode": "123456",
            "available": True
        },
        {
            "productCode": "33333",
            "grouperCode": "123456",
            "available": False
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Tipos de Respuesta

Respuesta Exitosa

{
  "code": 200,
  "message": "Operación exitosa"
}

Respuesta de Operación por Lotes

{
  "code": 201,
  "batchIds": [
    {
      "code": "12356",
      "uuid": ["550e8400-e29b-41d4-a716-446655440000"]
    }
  ],
  "message": "Operación en procesamiento"
}

Respuesta de Error

{
  "code": 404,
  "message": "Código de Producto no encontrado"
}

Mejores Prácticas

Gestión Basada en Agrupadores
- Crear agrupadores que representen tus almacenes o centros de distribución
- Asignar tiendas a agrupadores según qué almacén las abastece
- Usar operaciones por lotes para actualizaciones diarias de stock eficientes
- Mantener las asignaciones de agrupadores actualizadas
Actualizaciones de Stock
- Usar /batch/stock/grouper para actualizaciones diarias masivas
- Usar /product/{code}/stock para actualizaciones individuales de productos
- Enviar available: true o available: false basándose en el inventario real
- Actualizar solo cuando cambie el estado del stock para minimizar llamadas a la API
Procesamiento por Lotes
- Agrupar actualizaciones por grouperCode para eficiencia
- Enviar múltiples productos en una sola solicitud por lotes
- Monitorear el estado del procesamiento por lotes usando los endpoints de estado
- Manejar fallos parciales de forma elegante
Optimización de Rendimiento
- Usar operaciones por lotes en lugar de actualizaciones individuales cuando sea posible
- Programar actualizaciones masivas durante horas de bajo tráfico
- Monitorear patrones de uso de API
- Implementar lógica de reintento para solicitudes fallidas

Casos de Uso Comunes

Configuración Inicial de Stock
- Crear agrupadores de stock para cada almacén/depósito
- Asignar tiendas a sus agrupadores correspondientes
- Inicializar disponibilidad de productos para cada agrupador
- Configurar presentaciones de unidades si es necesario
Sincronización Diaria de Stock
- Exportar datos de disponibilidad desde tu ERP
- Enviar actualizaciones por lotes usando /batch/stock/grouper
- Actualizar productos que cambiaron de estado
- Monitorear resultados del procesamiento por lotes
Actualizaciones Individuales de Productos
- Usar /product/{code}/stock para actualizaciones en tiempo real
- Actualizar unidades de display específicas si es necesario
- Reaccionar a cambios inmediatos de stock
- Manejar situaciones de productos agotados rápidamente
Escenarios de Integración
- Conectar con sistemas ERP/WMS
- Implementar sincronización programada de inventario
- Configurar webhooks para alertas de stock
- Establecer reglas automatizadas de disponibilidad

Guías de Implementación

Gestión de Disponibilidad
- Validar que el grouperCode exista antes de actualizar
- Verificar existencia de productos
- Manejar configuraciones de unidades para displays específicos
- Usar endpoints de estado de lotes para monitorear actualizaciones
Configuración de Agrupadores
- Crear agrupadores de stock usando el endpoint /grouper/stock
- Asignar tiendas a agrupadores al crear/actualizar tiendas
- Usar grouperCodes significativos que coincidan con tu ERP
- Documentar relaciones agrupador-almacén
Sincronización de Stock
- Programar sincronización regular desde tu sistema de inventario
- Usar endpoint por lotes para actualizaciones masivas
- Rastrear qué productos cambiaron desde la última sincronización
- Manejar errores y reintentar actualizaciones fallidas
Procesamiento por Lotes
- Validar datos por lotes
- Manejar fallos parciales
- Implementar rollback
- Reportar resultados por lotes

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 gestión de stock, se requieren los siguientes permisos:

Para operaciones de lectura: supplier/product.read
Para operaciones de escritura: supplier/product.write
Para operaciones masivas: supplier/product.bulkwrite

Manejo de Errores

Validación de Entrada
- Validar códigos de tienda
- Verificar códigos de producto
- Verificar valores de unidades
- Validar códigos de agrupadores
Respuestas de Error
- Usar códigos de estado HTTP apropiados
- Proporcionar mensajes de error detallados
- Incluir errores a nivel de campo
- Agregar códigos de seguimiento de error
Procedimientos de Recuperación
- Manejar fallos de red
- Implementar lógica de reintentos
- Mantener consistencia de datos
- Registrar detalles de error
Monitoreo
- Rastrear tasas de error
- Monitorear rendimiento de API
- Alertar sobre errores críticos
- Analizar patrones de error

Entendiendo la Gestión de Stock​

Consideraciones Importantes​

Operaciones de Producto Individual​

Actualizar Stock de Producto​

Parámetros de Ruta​

Parámetros del Cuerpo de la Petición​

Ejemplo del Cuerpo de la Petición​

Códigos de Respuesta​

Ejemplo de Uso​

Operaciones por Lotes​

Actualización por Lotes de Stock por Agrupador​

Parámetros del Cuerpo de la Petición​

Ejemplo del Cuerpo de la Petición​

Códigos de Respuesta​

Ejemplo de Uso​

Tipos de Respuesta​

Respuesta Exitosa​

Respuesta de Operación por Lotes​

Respuesta de Error​

Mejores Prácticas​

Casos de Uso Comunes​

Guías de Implementación​

Seguridad​

Permisos Requeridos​

Manejo de Errores​

Entendiendo la Gestión de Stock

Consideraciones Importantes

Operaciones de Producto Individual

Actualizar Stock de Producto

Parámetros de Ruta

Parámetros del Cuerpo de la Petición

Ejemplo del Cuerpo de la Petición

Códigos de Respuesta

Ejemplo de Uso

Operaciones por Lotes

Actualización por Lotes de Stock por Agrupador

Parámetros del Cuerpo de la Petición

Ejemplo del Cuerpo de la Petición

Códigos de Respuesta

Ejemplo de Uso

Tipos de Respuesta

Respuesta Exitosa

Respuesta de Operación por Lotes

Respuesta de Error

Mejores Prácticas

Casos de Uso Comunes

Guías de Implementación

Seguridad

Permisos Requeridos

Manejo de Errores