API de Gestión de Productos

La API de Gestión de Productos permite administrar la información de productos en la plataforma Nilo. Estos endpoints ayudan a crear, actualizar y recuperar datos de productos, incluyendo detalles del producto, imágenes y configuraciones de visualización.

Entendiendo los Productos

Los productos en Nilo representan artículos disponibles para la venta en diferentes tiendas:

Estructura del Producto
- Código interno único para identificación (coincide con ERP)
- Nombre y descripción para visualización
- Asociaciones con marcas y categorías
- Configuraciones de visualización para diferentes presentaciones de unidades
- Imágenes (principal y adicionales)
- Estado para habilitar/deshabilitar visibilidad
Jerarquía del Producto
- Los productos pertenecen a marcas y categorías
- Soportan múltiples configuraciones de visualización
- Mantienen su propio estado y visibilidad
- Pueden gestionarse individualmente o por lotes

Consideraciones Importantes

Códigos Únicos: Cada producto requiere un código interno único que coincida con su sistema ERP
Configuraciones de Visualización: Los productos pueden tener múltiples presentaciones de unidades (ej., unidad individual, paquete de 6)
Gestión de Imágenes: Los productos admiten una imagen principal y imágenes adicionales
Marca y Categoría: Los productos deben estar asociados con marcas y categorías válidas
Control de Estado: Los productos pueden ser habilitados o deshabilitados sin eliminación

Operaciones de Producto Individual

Crear Producto

POST/product

Crea un nuevo producto en la plataforma Nilo. Este endpoint se utiliza para registrar todos los detalles del producto, incluyendo:

Información del producto (nombre, descripción, códigos)
Asociaciones de marca y categoría
Configuraciones de visualización (unidades, visualización predeterminada)
Imágenes del producto

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
name	string	Sí	Nombre del producto
internalCode	string	Sí	Código del producto (igual que en ERP)
description	string	Sí	Descripción del producto
brandInternalCode	string	Sí	Código de marca (igual que en ERP)
categoryInternalCode	string	Sí	Código de categoría (igual que en ERP)
displayProducts	array	Sí	Array de configuraciones de visualización (ver abajo)
mainImage	string	No	URL pública de la imagen principal del producto
images	array	No	Array de URLs públicas de imágenes adicionales
codeDUN	string	No	Código DUN (igual que en ERP)
codeUPC	string	No	Código UPC (igual que en ERP)
weight	integer	No	Posición en la lista de ordenación

Gestión de Imágenes

Los campos mainImage e images esperan URLs públicas y accesibles. Durante el procesamiento, Nilo descargará las imágenes, las almacenará en servidores de Nilo y las distribuirá a través de una CDN para carga optimizada. Usa imágenes de alta calidad - la plataforma generará automáticamente versiones optimizadas para diferentes dispositivos.

Configuración de Visualización del Producto

Parámetro	Tipo	Requerido	Descripción
default	boolean	Sí	Si esta es la visualización predeterminada
units	integer	Sí	Número de unidades en esta configuración de visualización
internalCode	string	No	Código específico de la visualización
codeDUN	string	No	Código DUN para esta visualización (igual que en ERP)
codeUPC	string	No	Código UPC para esta visualización (igual que en ERP)

Actualizar o Crear Producto (Upsert)

PUT/product

Crea o actualiza un producto en la plataforma Nilo. Este endpoint es útil cuando necesitas:

Crear un nuevo producto si no existe
Actualizar un producto existente con nueva información
Mantener la consistencia de productos entre múltiples sistemas

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
internalCode	string	Sí	Código del producto (igual que en ERP)
name	string	Sí	Nombre del producto
description	string	Sí	Descripción del producto
brandInternalCode	string	Sí	Código de marca (igual que en ERP)
categoryInternalCode	string	Sí	Código de categoría (igual que en ERP)
displayProducts	array	Sí	Array de configuraciones de visualización
enabled	boolean	Sí	Indica si el producto está activo
mainImage	string	No	URL pública de la imagen principal del producto
images	array	No	Array de URLs públicas de imágenes adicionales
codeDUN	string	No	Código DUN (igual que en ERP)
codeUPC	string	No	Código UPC (igual que en ERP)
weight	integer	No	Posición en la lista de ordenación

Gestión de Imágenes

Ejemplo del Cuerpo de la Solicitud

{
  "internalCode": "12345",
  "name": "Bebida 1L",
  "description": "Bebida refrescante 1L",
  "brandInternalCode": "brand1",
  "categoryInternalCode": "category1",
  "displayProducts": [
    {
      "default": true,
      "units": 1,
      "internalCode": "12345.1"
    }
  ],
  "enabled": true,
  "mainImage": "https://image.jpg",
  "images": ["https://image1.jpg"]
}

Códigos de Respuesta

Código	Descripción
200	Producto actualizado correctamente
400	Parámetros inválidos
401	Acceso no autorizado

Ejemplo de Uso

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

const data = {
  internalCode: "12345",
  name: "Bebida 1L",
  description: "Bebida refrescante 1L",
  brandInternalCode: "brand1",
  categoryInternalCode: "category1",
  displayProducts: [
    {
      default: true,
      units: 1,
      internalCode: "12345.1",
    },
  ],
  enabled: true,
  mainImage: "https://image.jpg",
  images: ["https://image1.jpg"],
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/product", {
  method: "PUT",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Obtener Todos los Productos

GET/product

Recupera una lista paginada de todos los productos. Útil para:

Navegar por el catálogo de productos
Implementar paginación en tu aplicación
Filtrar productos por estado activo/inactivo

Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
take	number	No	Items por página (default: 50, máximo: 50)
page	string	No	Número de página (default: 1)
enabled	boolean	No	Filtrar por estado activo/inactivo
cursor	string	No	Cursor para paginación. Primer llamado usar 0, luego usar el cursor de la respuesta anterior

Ejemplo de Respuesta

{
  "data": [
    {
      "name": "Bebida 1L",
      "internalCode": "12345",
      "description": "Bebida refrescante 1L",
      "mainImage": "https://image.jpg",
      "images": ["https://image1.jpg"],
      "brand": {
        "name": "Marca 1",
        "internalCode": "brand1"
      },
      "category": {
        "name": "Bebidas",
        "internalCode": "category1"
      },
      "displayProducts": [
        {
          "default": true,
          "units": 1,
          "internalCode": "12345.1"
        }
      ]
    }
  ],
  "page": {
    "pageBased": {
      "count": 100
    },
    "cursorBased": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "firstCursor": "0",
      "lastCursor": "49"
    }
  }
}

Ejemplo de Uso

Javascript
Python

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

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/product?take=10&page=1&enabled=true",
  {
    method: "GET",
    headers: headers,
  }
)
  .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"
params = {
    "take": 10,
    "page": 1,
    "enabled": True
}

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

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

Obtener Detalles de Producto

GET/product/{code}

Obtiene información detallada de un producto específico. Incluye:

Metadatos del producto
Información de marca y categoría
Todas las configuraciones de visualización
Imágenes del producto

Parámetros de Ruta

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

Ejemplo de Respuesta

{
  "name": "Bebida 1L",
  "internalCode": "12345",
  "description": "Bebida refrescante 1L",
  "mainImage": "https://image.jpg",
  "images": ["https://image1.jpg"],
  "brand": {
    "name": "Marca 1",
    "internalCode": "brand1"
  },
  "category": {
    "name": "Bebidas",
    "internalCode": "category1"
  },
  "displayProducts": [
    {
      "default": true,
      "units": 1,
      "internalCode": "12345.1"
    }
  ]
}

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/product/12345",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Cambiar Estado de Producto

PUT/product/{code}/status

Actualiza el estado de un producto o visualización específica. Permite:

Activar/desactivar un producto
Actualizar estado de configuraciones de visualización específicas
Gestionar visibilidad del producto en catálogos

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 Solicitud

Parámetro	Tipo	Requerido	Descripción
enabled	boolean	Sí	Estado activo/inactivo del producto
units	integer	No	Unidades específicas a actualizar

Ejemplo del Cuerpo de la Solicitud

{
  "enabled": true,
  "units": 1
}

Códigos de Respuesta

Código	Descripción
200	Estado actualizado correctamente
400	Parámetros inválidos
404	Producto 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 = {
  enabled: true,
  units: 1,
};

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

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

data = {
    "enabled": True,
    "units": 1
}

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

Operaciones por Lotes

Operaciones Masivas de Productos

POST/batch/product

Realiza operaciones masivas en productos. Permite:

Crear múltiples productos nuevos
Actualizar productos existentes
Actualizar o crear productos (upsert)

La operación se procesa de forma asíncrona. Recibirás confirmación inmediata y las actualizaciones se procesarán en segundo plano.

Gestión de Imágenes

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Descripción
create	array	Array de productos a crear
update	array	Array de productos a actualizar
upsert	array	Array de productos a actualizar o crear

Cada producto en los arrays soporta los siguientes campos: internalCode, name, description, brandInternalCode, categoryInternalCode, displayProducts, enabled, mainImage, images, codeDUN, codeUPC, weight.

Ejemplo del Cuerpo de la Solicitud

{
  "create": [
    {
      "name": "Nuevo Producto",
      "internalCode": "67890",
      "description": "Descripción del nuevo producto",
      "brandInternalCode": "brand2",
      "categoryInternalCode": "category2",
      "enabled": true,
      "mainImage": "https://image.jpg",
      "images": ["https://image1.jpg"],
      "displayProducts": [
        {
          "default": true,
          "units": 1,
          "internalCode": "67890.1"
        }
      ]
    }
  ],
  "update": [
    {
      "internalCode": "12345",
      "name": "Nombre Actualizado",
      "description": "Descripción actualizada",
      "brandInternalCode": "brand2",
      "categoryInternalCode": "category2",
      "enabled": true,
      "mainImage": "https://image.jpg",
      "images": ["https://image1.jpg"],
      "displayProducts": [
        {
          "default": true,
          "units": 1,
          "internalCode": "12345.1"
        }
      ]
    }
  ],
  "upsert": [
    {
      "internalCode": "12345",
      "name": "Nombre Actualizado",
      "description": "Descripción actualizada",
      "brandInternalCode": "brand2",
      "categoryInternalCode": "category2",
      "enabled": true,
      "mainImage": "https://image.jpg",
      "images": ["https://image1.jpg"],
      "displayProducts": [
        {
          "default": true,
          "units": 1,
          "internalCode": "12345.1"
        }
      ]
    }
  ]
}

Códigos de Respuesta

Código	Descripción
202	Solicitud aceptada para procesar
400	Parámetros inválidos
401	Acceso no autorizado

Ejemplo de Uso

Javascript
Python

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

const data = {
  upsert: [
    {
      internalCode: "12345",
      name: "Nombre Actualizado",
      description: "Descripción actualizada",
      brandInternalCode: "brand2",
      categoryInternalCode: "category2",
      enabled: true,
      mainImage: "https://image.jpg",
      images: ["https://image1.jpg"],
      displayProducts: [
        {
          default: true,
          units: 1,
          internalCode: "12345.1",
        },
      ],
    },
  ],
};

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

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

data = {
    "upsert": [
        {
            "internalCode": "12345",
            "name": "Nombre Actualizado",
            "description": "Descripción actualizada",
            "brandInternalCode": "brand2",
            "categoryInternalCode": "category2",
            "enabled": True,
            "mainImage": "https://image.jpg",
            "images": ["https://image1.jpg"],
            "displayProducts": [
                {
                    "default": True,
                    "units": 1,
                    "internalCode": "12345.1"
                }
            ]
        }
    ]
}

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": 202,
  "batchIds": {
    "create": ["550e8400-e29b-41d4-a716-446655440000"],
    "update": [],
    "upsert": []
  },
  "message": "Procesamiento por lotes iniciado"
}

Respuesta de Error

{
  "code": 400,
  "message": "Parámetros inválidos"
}

Mejores Prácticas

Gestión de Productos
- Usar convenciones de nombres consistentes
- Mantener descripciones precisas de productos
- Mantener actualizadas las asociaciones de marca y categoría
- Implementar gestión adecuada de estados
Configuración de Visualización
- Definir presentaciones claras de unidades
- Establecer visualizaciones predeterminadas apropiadas
- Mantener códigos internos consistentes
- Documentar configuraciones de unidades
Manejo de Imágenes
- Usar imágenes de producto de alta calidad
- Mantener dimensiones de imagen consistentes
- Implementar optimización de imágenes
- Mantener actualizadas todas las vistas del producto
Optimización de Rendimiento
- Usar operaciones por lotes para múltiples actualizaciones
- Implementar estrategias de caché adecuadas
- Optimizar entrega de imágenes
- Monitorear patrones de uso de API

Casos de Uso Comunes

Configuración Inicial de Producto
- Crear información básica del producto
- Configurar unidades de visualización
- Subir imágenes del producto
- Establecer asociaciones de marca y categoría
Mantenimiento de Producto
- Actualizar información del producto
- Gestionar visibilidad del producto
- Actualizar configuraciones de visualización
- Actualizar imágenes del producto
Operaciones Masivas
- Importar múltiples productos
- Actualizar estados de productos
- Modificar configuraciones de visualización
- Sincronizar datos de productos
Integración de Producto
- Conectar con sistemas de inventario
- Implementar búsqueda de productos
- Configurar visualizaciones de productos
- Configurar filtrado de productos

Guías de Implementación

Creación de Producto
- Validar todos los campos requeridos
- Verificar códigos duplicados
- Procesar imágenes del producto
- Establecer configuraciones predeterminadas
Actualizaciones de Producto
- Verificar existencia del producto
- Manejar actualizaciones parciales
- Gestionar cambios de imagen
- Actualizar entidades relacionadas
Gestión de Visualización
- Manejar configuraciones de unidades
- Actualizar visualizaciones predeterminadas
- Mantener códigos de visualización
- Validar valores de unidades
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 productos, 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 todos los campos requeridos
- Verificar tipos y formatos de datos
- Verificar especificaciones de imagen
- Validar códigos internos
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 los Productos​

Consideraciones Importantes​

Operaciones de Producto Individual​

Crear Producto​

Parámetros del Cuerpo de la Solicitud​

Configuración de Visualización del Producto​

Actualizar o Crear Producto (Upsert)​

Parámetros del Cuerpo de la Solicitud​

Ejemplo del Cuerpo de la Solicitud​

Códigos de Respuesta​

Ejemplo de Uso​

Obtener Todos los Productos​

Parámetros de Consulta​

Ejemplo de Respuesta​

Ejemplo de Uso​

Obtener Detalles de Producto​

Parámetros de Ruta​

Ejemplo de Respuesta​

Ejemplo de Uso​

Cambiar Estado de Producto​

Parámetros de Ruta​

Parámetros del Cuerpo de la Solicitud​

Ejemplo del Cuerpo de la Solicitud​

Códigos de Respuesta​

Ejemplo de Uso​

Operaciones por Lotes​

Operaciones Masivas de Productos​

Parámetros del Cuerpo de la Solicitud​

Ejemplo del Cuerpo de la Solicitud​

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

Consideraciones Importantes

Operaciones de Producto Individual

Crear Producto

Parámetros del Cuerpo de la Solicitud

Configuración de Visualización del Producto

Actualizar o Crear Producto (Upsert)

Parámetros del Cuerpo de la Solicitud

Ejemplo del Cuerpo de la Solicitud

Códigos de Respuesta

Ejemplo de Uso

Obtener Todos los Productos

Parámetros de Consulta

Ejemplo de Respuesta

Ejemplo de Uso

Obtener Detalles de Producto

Parámetros de Ruta

Ejemplo de Respuesta

Ejemplo de Uso

Cambiar Estado de Producto

Parámetros de Ruta

Parámetros del Cuerpo de la Solicitud

Ejemplo del Cuerpo de la Solicitud

Códigos de Respuesta

Ejemplo de Uso

Operaciones por Lotes

Operaciones Masivas de Productos

Parámetros del Cuerpo de la Solicitud

Ejemplo del Cuerpo de la Solicitud

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