Guía de Integración

Este documento describe el proceso recomendado para la integración de tus sistemas con la API REST de Nilo. El objetivo es proporcionar una guía clara sobre las fases de integración, el orden de las operaciones y las mejores prácticas para garantizar una implementación exitosa y eficiente.

Fases de Integración

La integración se divide en cuatro fases principales:

🔐

Fase 1: Configuración

Obtención de credenciales y token de acceso para comunicarse con la API

→📦

Fase 2: Datos Maestros

Carga inicial de información del catálogo: marcas, categorías, productos, tiendas y precios

→🎯

Fase 3: Promociones

Configuración de dinámicas comerciales y carga de órdenes históricas

→🛒

Fase 4: Transacciones

Ciclo de vida de pedidos desde recepción por webhook hasta entrega o cancelación

→

---

Conceptos Clave de la API

Antes de iniciar la integración, es importante comprender algunos conceptos fundamentales que aplican a varias operaciones dentro de la API de Nilo.

El Identificador Único: "internalCode"

A lo largo de toda la API, encontrarás el campo internalCode para entidades como productos, tiendas, marcas, categorías, etc.

Aspecto	Descripción
¿Qué es?	El internalCode es el código o identificador único con el que esa entidad es conocida en tus sistemas (como tu ERP). Por ejemplo, el SKU de un producto, el código de cliente de una tienda, o el ID de una marca.
¿Por qué es importante?	Utilizar el internalCode es una práctica fundamental de esta API. Permite que la comunicación entre tus sistemas y Nilo sea directa, utilizando los mismos identificadores que ya manejas internamente. Esto elimina la necesidad de crear y mantener tablas de mapeo entre los IDs de Nilo y los IDs del ERP, simplificando la lógica de integración y la gestión posterior.

Excepción Importante: Las Órdenes

Las órdenes se originan en la plataforma de Nilo. Por lo tanto, no tienen un internalCode proveniente de tu sistema. Para gestionar el ciclo de vida de una orden (confirmar, entregar, cancelar, etc.), se debe utilizar siempre el identificador numérico id que Nilo envía en el webhook de creación de la orden.

Operaciones Asíncronas (Batch)

Varios endpoints de la API, especialmente los diseñados para la carga masiva de datos (como /batch/brand o /batch/store), operan de forma asíncrona. Es fundamental comprender este flujo para una correcta implementación.

Cómo funciona:

1. Envío de Solicitud: Envía una petición POST al endpoint batch con un arreglo de entidades
2. Validación y Encolado: Nilo valida la estructura del payload y encola las tareas para procesamiento en segundo plano
3. Respuesta Inmediata: Si el encolado es exitoso, la API responde con 202 Accepted (no 200 OK), conteniendo uno o más batchId (formato UUID)
4. Procesamiento en Segundo Plano: Los servidores de Nilo procesan las tareas de forma asíncrona

Consulta del Estado de los Procesos Batch:

GET/batch/{uuid}/status

Devuelve un resumen: estado general (processing, processed, failed) y conteo de ítems (total, procesados, fallidos, completados).

GET/batch/{uuid}/detail

Proporciona un detalle ítem por ítem de todo el lote. Esencial para la depuración e identificar por qué un registro específico no pudo ser procesado.

Gestión de Imágenes

Para todas las entidades que soporten imágenes (Marcas, Categorías, Productos, etc.), el campo image espera una URL pública y accesible.

Durante el procesamiento, Nilo:

1. Descargará la imagen desde esa URL
2. La almacenará en sus propios servidores
3. La distribuirá a través de una CDN para optimizar su carga

Recomendación

Utiliza imágenes de buena calidad. La plataforma se encargará de generar automáticamente las versiones optimizadas para los diferentes dispositivos (móvil, tablet, web).

---

Fase 1: Configuración y Autenticación

El primer paso para interactuar con la API de Nilo es obtener un token de autenticación.

Obtención de Credenciales

El equipo de Nilo te proporcionará un clientId y un clientSecret. Estas credenciales son confidenciales y deben ser almacenadas de forma segura.

Generación del Token de Acceso

POST/login

Este servicio autentica tus credenciales y devuelve un access_token.

Consideraciones importantes:

Requisito	Descripción
Duración del Token	El access_token tiene una duración limitada y debe ser enviado en la cabecera Authorization de todas las peticiones posteriores a la API
API Key	Adicionalmente, incluye la cabecera x-api-key con el valor proporcionado por Nilo. Esta cabecera es requerida en todos los endpoints de la API
Mejor Práctica	Implementa una lógica para cachear el token y renovarlo automáticamente antes de que expire para evitar interrupciones en el servicio

Ejemplo de cabeceras para todas las peticiones:

Authorization: Bearer <tu_token>
x-api-key: <tu_api_key>

---

Fase 2: Sincronización de Datos Maestros

Una vez autenticados, el siguiente paso es cargar la información fundamental que compone el catálogo de productos y la estructura comercial.

Orden de Sincronización Recomendado

Sigue este orden exacto para evitar problemas de dependencias:

2.1 Crear Agrupadores de Stock

POST/grouper/stock

Crea un agrupador por cada almacén o depósito. El internalCode debe ser el código del almacén en tu ERP.

2.2 Crear Agrupadores de Promociones

POST/grouper/promotion

Deben representar las segmentaciones comerciales de tu negocio. El internalCode debe corresponder al código de segmento en tu ERP.

2.3 Sincronizar Marcas

POST/batch/brand

Utiliza la operación upsert. El internalCode debe ser el código de marca de tu ERP.

2.4 Sincronizar Categorías y Subcategorías

Categorías (Nivel 1):

PUT/category

Usa la operación upsertCategory. El internalCode debe ser el código único de la categoría en tu ERP.

Subcategorías (Nivel 2):

PUT/subcategory

Usa la operación upsertSubcategory. El campo parentCategoryInternalCode es obligatorio y debe contener el internalCode de una categoría padre.

2.5 Sincronizar Productos

POST/batch/product

Usa la operación upsert para crear o actualizar productos de forma masiva. El internalCode debe ser el SKU del producto en tu ERP. Los productos deben tener asociaciones válidas de brandInternalCode y categoryInternalCode (creadas en pasos anteriores).

Consulta la documentación de Productos para detalles completos de campos y ejemplos.

2.6 Gestión de Stock y Disponibilidad

La gestión de stock en Nilo se realiza en dos pasos:

Paso 1: Asignar Tiendas al Agrupador de Stock

POST/batch/grouper/stock

Asocia o desasocia masivamente tiendas a un agrupador de stock específico. Esto define qué grupo de tiendas se verá afectado por las actualizaciones de disponibilidad.

Paso 2: Actualizar Disponibilidad de Productos

POST/batch/stock/grouper

Indica la disponibilidad (available: true o available: false) de productos para un grouperCode determinado. Es la operación principal para el manejo diario del stock.

2.7 Crear Listas de Precios

POST/pricelist

Crea una lista por cada segmentación de precios. El internalCode debe ser el código de la lista en tu ERP.

2.8 Sincronizar Tiendas (Clientes)

POST/batch/store

Usa exclusivamente el nodo upsert. En esta llamada se asignan priceListCode, stockGrouperCode y promotionGrouperCodes.

Monto Mínimo de Compra

El campo settings.dropSize permite definir un monto mínimo de compra por tienda. Si el monto es global, no es necesario enviarlo.

2.9 Asignar Usuarios a Tiendas

PUT/store/{code}/add/user

PUT/store/{code}/remove/user

Se pueden asignar múltiples usuarios a una tienda y un mismo usuario a múltiples tiendas.

2.10 Asignar Precios y Tiendas a las Listas

POST/batch/pricelist

Añade, actualiza o elimina de forma masiva tanto los precios de los productos como las tiendas asociadas a las listas de precios.

Flexibilidad del payload:

Acción	Cómo hacerlo
Actualizar solo precios	Envía info en upsert.products, deja upsert.stores como []
Asignar solo tiendas	Envía info en upsert.stores, deja upsert.products como []
Eliminar productos	Envía productos en remove.products
Quitar tiendas	Envía tiendas en remove.stores

---

Fase 3: Promociones y Datos Históricos

3.1 Mapeo de Tipos de Promociones

Nota Importante sobre Configuración

La API define ciertos campos como mutuamente excluyentes:

• Condición por Cantidad vs Monto: No envíes bonusTierData y bonusTierDataCash simultáneamente
• Tipo de Descuento: Especifica discountPercentage O discountAmount, no ambos

Enviar ambos campos resultará en un error.

Tipo de Promoción	Tipo API Nilo	Endpoint
Bonificación Directa (mismo producto)	BONUS_INDIVIDUAL	PUT /promotion/bonus/individual
Bonificación Cruzada (producto distinto)	BONUS_CROSSED	PUT /promotion/bonus/crossed
Descuento Grupal (combinación de productos)	DISCOUNT_MULTIPLE	PUT /promotion/discount/multiple
Bonificación Grupal (combinación de productos)	BONUS_CROSSED	PUT /promotion/bonus/crossed
Descuento Simple Escalonado	DISCOUNT_SIMPLE	PUT /promotion/discount/simple
Combos con descuento	DISCOUNT_MULTIPLE	PUT /promotion/discount/multiple
Combos con bonificación	BONUS_CROSSED	PUT /promotion/bonus/crossed
Descuento Grupal por Volumen	DISCOUNT_MULTIPLE	PUT /promotion/discount/multiple
Bonificación por Monto Mínimo	BONUS_CROSSED	PUT /promotion/bonus/crossed
Descuento Simple	DISCOUNT_SIMPLE	PUT /promotion/discount/simple

Para gestión masiva, usa:

POST/batch/promotion

3.2 Carga de Histórico de Órdenes

POST/order/bulk-import

Envía un lote de órdenes históricas para enriquecer los modelos de datos de Nilo y mejorar la experiencia del usuario (ej: sugerencias de compra). Este servicio está diseñado para una carga inicial de datos, no para la gestión de pedidos en tiempo real.

---

Fase 4: Flujo Transaccional (Gestión de Pedidos)

Esta fase describe el ciclo de vida de un pedido, desde que Nilo notifica su creación hasta que lo gestionas en tus sistemas.

4.1 Recepción de Pedidos y Cancelaciones (Webhooks)

Tu sistema debe exponer un endpoint (URL) que Nilo pueda invocar para notificar eventos en tiempo real.

Webhook de Creación de Orden:

POST/webhooks/order

Nilo enviará una petición a tu URL cada vez que se cree una nueva orden. El cuerpo de la petición contendrá toda la información de la orden, incluyendo el id de Nilo, los productos, las cantidades y los datos del comprador.

Acción requerida: Procesa esta información, crea el pedido en tu ERP y responde a Nilo con 200 OK para confirmar la recepción.

Webhook de Cancelación de Orden:

PUT/webhooks/order

Si una tienda cancela una orden desde la plataforma de Nilo (mientras la orden está en estado PENDING), Nilo enviará una notificación a este endpoint.

4.2 Gestión del Ciclo de Vida de los Pedidos (API)

Una vez que un pedido ha sido recibido y creado en tu ERP, es tu responsabilidad actualizar su estado en la plataforma de Nilo. Usa el id recibido en el webhook.

PUT/order/{id}/confirm

Confirma que el pedido ha sido aceptado y está siendo preparado. Puedes especificar una fecha de entrega estimada (deliveryDate).

PUT/order/{id}/deliver

Notifica que el pedido ha sido entregado. Permite entregas completas ("complete": true) o parciales, especificando qué productos y cantidades fueron efectivamente entregados.

PUT/order/{id}/return

Registra la devolución total o parcial de productos de una orden ya entregada.

PUT/order/{id}/cancel

Para los casos en que necesites cancelar un pedido que ya habías confirmado (ej: por falta de stock imprevista). Especifica un código de motivo de cancelación.

Actualización Masiva de Pedidos (Recomendado)

POST/batch/order

Actualiza el estado de múltiples pedidos en una sola llamada. Envía lotes para confirmar, entregar, devolver o cancelar, cada uno en su nodo correspondiente dentro del payload. Esto reduce significativamente el número de llamadas a la API y es el método más eficiente para la gestión diaria de órdenes.

---

Próximos Pasos

🔑

Detalles de Autenticación

Referencia completa de la API de autenticación

→🔔

Configurar Webhooks

Configura notificaciones en tiempo real

→