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ámetro	Tipo	Requerido	Descripción
code	string	Sí	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

Javascript

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));

Python

import requests

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

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

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

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á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
from	string	No	Filtro de fecha inicio (YYYY-MM-DD)
to	string	No	Filtro 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ámetro	Tipo	Requerido	Descripción
title	string	Sí	Título del desafío
internalCode	string	Sí	Identificador único para el desafío
description	string	No	Descripción del desafío
image	string	No	URL de la imagen del desafío
pointsGiven	number	Sí	Puntos otorgados al completar el desafío
requiredAmount	number	Sí	Monto mínimo de compra para completar el desafío
start	string	Sí	Fecha de inicio (YYYY-MM-DD)
end	string	Sí	Fecha de fin (YYYY-MM-DD)
enabled	boolean	Sí	Si el desafío está activo
products	array	Sí	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

Javascript

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));

Python

import requests

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

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

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"}
    ]
}

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

Cambiar Estado del Desafío

PUT/loyaltychallenge/{code}/status

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

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	Código interno del desafío de lealtad

Parámetros del Body

Parámetro	Tipo	Requerido	Descripción
enabled	boolean	Sí	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