API de Recomendaciones

La API de Recomendaciones permite gestionar recomendaciones de productos en la plataforma Nilo. Las recomendaciones son listas curadas de productos que pueden mostrarse a tiendas específicas durante un período definido.

Entendiendo las Recomendaciones

Las Recomendaciones en Nilo ayudan a destacar productos específicos para tiendas seleccionadas:

• Estructura de Recomendación
  • Código interno único para identificación
  • Título y descripción para visualización
  • Peso para ordenamiento (valores menores aparecen primero)
  • Período de validez (fechas de inicio y fin)
  • Lista de productos a recomendar
  • Segmentación de tiendas mediante operaciones batch

Consideraciones Importantes

1. Códigos Únicos: Cada recomendación requiere un código interno único
2. Ordenamiento por Peso: Valores de peso menores posicionan la recomendación primero en la lista
3. Validez por Fechas: Las recomendaciones solo están activas dentro de las fechas de inicio y fin
4. Asignación de Tiendas: Usa operaciones batch para asignar recomendaciones a tiendas específicas

Operaciones Individuales

Obtener Detalles de Recomendación

GET/recommendations/{code}

Obtiene información detallada sobre una recomendación específica.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	Código interno de la recomendación

Ejemplo de Respuesta

{
  "title": "Recomendaciones de Verano",
  "internalCode": "REC-001",
  "description": "Los mejores productos para el verano",
  "weight": 1,
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "enabled": true,
  "products": [
    {
      "internalCode": "PROD-001"
    },
    {
      "internalCode": "PROD-002"
    }
  ]
}

Ejemplo de Uso

Javascript

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/recommendations/REC-001",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/recommendations/REC-001"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY'
}

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

Listar Todas las Recomendaciones

GET/recommendations

Obtiene una lista de todas las recomendaciones con soporte de paginación y filtrado.

Parámetros de Query

Parámetro	Tipo	Requerido	Descripción
take	number	No	Número de items por página (default: 50, max: 50)
page	string	No	Número de página (default: 1)
cursor	string	No	Cursor para paginación. Primera llamada debe pasar 0, llamadas siguientes usan el cursor de la respuesta anterior
enabled	boolean	No	Filtrar por estado habilitado

Crear o Actualizar Recomendación

PUT/recommendations

Crea una nueva recomendación o actualiza una existente. Si el internalCode existe, actualiza; de lo contrario, crea una nueva recomendación.

Parámetros del Body

Parámetro	Tipo	Requerido	Descripción
title	string	Sí	Título de la recomendación
internalCode	string	Sí	Identificador único para la recomendación
description	string	Sí	Descripción de la recomendación
startDate	string	Sí	Fecha de inicio (YYYY-MM-DD)
endDate	string	Sí	Fecha de fin (YYYY-MM-DD)
weight	integer	No	Peso para ordenamiento (valores menores aparecen primero)
products	array	No	Array de productos a incluir en la recomendación

Ejemplo del Body

{
  "title": "Recomendaciones de Verano",
  "internalCode": "REC-001",
  "description": "Los mejores productos para el verano",
  "weight": 1,
  "startDate": "2025-06-01",
  "endDate": "2025-08-31",
  "products": [
    {
      "internalCode": "PROD-001"
    },
    {
      "internalCode": "PROD-002"
    }
  ]
}

Cambiar Estado de Recomendación

PUT/recommendations/{code}/status

Habilita o deshabilita una recomendación específica.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	Código interno de la recomendación

Parámetros del Body

Parámetro	Tipo	Requerido	Descripción
enabled	boolean	Sí	Nuevo estado de la recomendación

Ejemplo del Body

{
  "enabled": true
}

Operaciones Batch

Actualización Batch de Asignación de Tiendas

POST/batch/recommendations

Agrega o elimina tiendas de recomendaciones en batch. Define qué tiendas verán recomendaciones específicas.

Parámetros del Body

Parámetro	Tipo	Requerido	Descripción
add	object	No	Tiendas a agregar a recomendaciones
remove	object	No	Tiendas a eliminar de recomendaciones

Items del array stores:

Campo	Tipo	Requerido	Descripción
recommendationInternalCode	string	Sí	Código interno de la recomendación
storeInternalCode	string	Sí	Código interno de la tienda

Ejemplo del Body

{
  "add": {
    "stores": [
      {
        "recommendationInternalCode": "REC-001",
        "storeInternalCode": "STORE-001"
      },
      {
        "recommendationInternalCode": "REC-001",
        "storeInternalCode": "STORE-002"
      }
    ]
  },
  "remove": {
    "stores": [
      {
        "recommendationInternalCode": "REC-002",
        "storeInternalCode": "STORE-003"
      }
    ]
  }
}

Códigos de Respuesta

Código	Descripción
202	Solicitud aceptada, procesamiento iniciado
400	Solicitud incorrecta

Seguridad

Autenticación

Todos los endpoints requieren dos tipos de autenticación:

• API Key en header: x-api-key
• Token de autorización en header: Authorization

Permisos Requeridos

• Para operaciones de lectura: supplier/recommendation.read
• Para operaciones de escritura: supplier/recommendation.write
• Para operaciones batch: supplier/recommendation.bulkwrite