Saltar al contenido principal

API de Desafíos de Lealtad

La API de Desafíos de Lealtad permite gestionar programas de lealtad y desafíos en la plataforma Nilo. Los desafíos de lealtad recompensan a los clientes con puntos cuando compran productos específicos y alcanzan un monto requerido.

Entendiendo los Desafíos de Lealtad​

Los Desafíos de Lealtad en Nilo son promociones gamificadas que recompensan a los clientes:

  • Estructura del Desafío
    • Código interno único para identificación
    • Título y descripción para visualización
    • Puntos otorgados como recompensa
    • Monto de compra requerido para completar el desafío
    • Período de validez (fechas de inicio y fin)
    • Lista de productos que califican para el desafío

Consideraciones Importantes​

  1. Códigos Únicos: Cada desafío requiere un código interno único (igual que en tu ERP)
  2. Sistema de Puntos: Define cuántos puntos ganan los clientes al completar el desafío
  3. Monto Requerido: Establece el monto mínimo de compra necesario para completar el desafío
  4. Alcance de Productos: Especifica qué productos cuentan para el desafío
  5. Validez por Fechas: Los desafíos solo están activos dentro de las fechas de inicio y fin

Operaciones Individuales​

Obtener Detalles del Desafío​

GET/loyaltychallenge/{code}

Obtiene información detallada sobre un desafío de lealtad específico.

Parámetros de Ruta​

ParámetroTipoRequeridoDescripción
codestringSíCódigo interno del desafío de lealtad

Ejemplo de Respuesta​

{
  "id": 1,
  "title": "Desafío de Puntos de Verano",
  "description": "Gana puntos en productos de verano",
  "image": "https://example.com/challenge.jpg",
  "internalCode": "CHALLENGE-001",
  "pointsGiven": 100,
  "requiredMoney": 500,
  "enabled": true,
  "startDate": "2025-06-01",
  "endDate": "2025-08-31",
  "products": [
    {
      "internalCode": "PROD-001"
    },
    {
      "internalCode": "PROD-002"
    }
  ]
}

Ejemplo de Uso​

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

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

Listar Todos los Desafíos de Lealtad​

GET/loyaltychallenge

Obtiene una lista de todos los desafíos de lealtad con soporte de paginación y filtrado.

Parámetros de Query​

ParámetroTipoRequeridoDescripción
takenumberNoNúmero de items por página (default: 50, max: 50)
pagestringNoNúmero de página (default: 1)
cursorstringNoCursor para paginación. Primera llamada debe pasar 0, llamadas siguientes usan el cursor de la respuesta anterior
enabledbooleanNoFiltrar por estado habilitado
fromstringNoFiltro de fecha inicio (YYYY-MM-DD)
tostringNoFiltro de fecha fin (YYYY-MM-DD)

Crear o Actualizar Desafío de Lealtad​

PUT/loyaltychallenge

Crea un nuevo desafío de lealtad o actualiza uno existente.

Parámetros del Body​

ParámetroTipoRequeridoDescripción
titlestringSíTítulo del desafío
internalCodestringSíIdentificador único para el desafío
descriptionstringNoDescripción del desafío
imagestringNoURL de la imagen del desafío
pointsGivennumberSíPuntos otorgados al completar el desafío
requiredAmountnumberSíMonto mínimo de compra para completar el desafío
startstringSíFecha de inicio (YYYY-MM-DD)
endstringSíFecha de fin (YYYY-MM-DD)
enabledbooleanSíSi el desafío está activo
productsarraySíArray de productos que califican para el desafío

Ejemplo del Body​

{
  "title": "Desafío de Puntos de Verano",
  "internalCode": "CHALLENGE-001",
  "description": "Gana 100 puntos cuando gastes $500 en productos de verano",
  "image": "https://example.com/challenge.jpg",
  "pointsGiven": 100,
  "requiredAmount": 500,
  "start": "2025-06-01",
  "end": "2025-08-31",
  "enabled": true,
  "products": [
    {
      "internalCode": "PROD-001"
    },
    {
      "internalCode": "PROD-002"
    }
  ]
}

Ejemplo de Uso​

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

const data = {
  title: "Desafío de Puntos de Verano",
  internalCode: "CHALLENGE-001",
  description: "Gana 100 puntos cuando gastes $500 en productos de verano",
  image: "https://example.com/challenge.jpg",
  pointsGiven: 100,
  requiredAmount: 500,
  start: "2025-06-01",
  end: "2025-08-31",
  enabled: true,
  products: [
    { internalCode: "PROD-001" },
    { internalCode: "PROD-002" },
  ],
};

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

Cambiar Estado del Desafío​

PUT/loyaltychallenge/{code}/status

Habilita o deshabilita un desafío de lealtad específico.

Parámetros de Ruta​

ParámetroTipoRequeridoDescripción
codestringSíCódigo interno del desafío de lealtad

Parámetros del Body​

ParámetroTipoRequeridoDescripción
enabledbooleanSíNuevo estado del desafío

Ejemplo del Body​

{
  "enabled": true
}

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/loyaltychallenge.read
  • Para operaciones de escritura: supplier/loyaltychallenge.write