API de Gestión de Promociones
Descripción General
La API de Gestión de Promociones proporciona un conjunto completo de endpoints para administrar promociones en la plataforma Nilo. Esta API permite crear, actualizar y gestionar diferentes tipos de promociones, incluyendo descuentos simples, descuentos múltiples, bonificaciones individuales y bonificaciones cruzadas.
Entendiendo las Promociones
Estructura de Promoción
- Código Interno: Identificador único para la promoción (igual que en tu ERP)
- Nombre: Nombre descriptivo para la promoción
- Tipo: Tipo de promoción (DISCOUNT_SIMPLE, DISCOUNT_MULTIPLE, BONUS_INDIVIDUAL, BONUS_CROSSED)
- Estado: Estado habilitado/deshabilitado de la promoción
- Período de Validez: Fechas de inicio y fin de la promoción
- Niveles (Tiers): Condiciones para descuentos o bonificaciones (basados en cantidad o monto)
- Productos: Productos incluidos en la promoción
- Agrupadores: Agrupadores de promoción que determinan qué tiendas ven la promoción
Mapeo de Tipos de Promoción
| Tipo de Promoción | Tipo en API Nilo | Endpoint |
|---|---|---|
| Bonificación Directa (mismo producto) | BONUS_INDIVIDUAL | PUT /promotion/bonus/individual |
| Bonificación Cruzada (producto diferente) | BONUS_CROSSED | PUT /promotion/bonus/crossed |
| Descuento Grupal (combinación de productos) | DISCOUNT_MULTIPLE | PUT /promotion/discount/multiple |
| 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 |
Consideraciones Importantes
La API define ciertos campos como mutuamente excluyentes:
- Condición por Cantidad vs Monto: No envíes
discountTiersData/bonusTierDataydiscountTiersDataCash/bonusTierDataCashsimultáneamente - Tipo de descuento: Especifica
discountPercentageOdiscountAmount, no ambos
Enviar ambos campos resultará en un error.
-
Tipos de Niveles (Tiers):
- Basados en Cantidad (
discountTiersData/bonusTierData): El descuento aplica según cantidad comprada (ej. compra 5+ unidades obtén 10% de descuento) - Basados en Monto (
discountTiersDataCash/bonusTierDataCash): El descuento aplica según monto de compra (ej. gasta $100+ obtén 10% de descuento)
- Basados en Cantidad (
-
Configuración de Descuentos:
- Puede ser basado en porcentaje o monto fijo
- No se pueden mezclar porcentaje y monto fijo en el mismo nivel
- Se pueden configurar múltiples niveles basados en cantidad
-
Manejo de Fechas:
- Todas las fechas deben estar en formato YYYY-MM-DD
- Las fechas de inicio y fin son obligatorias
- La fecha de fin debe ser posterior a la fecha de inicio
Operaciones Individuales de Promoción
Obtener Detalles de Promoción
/promotion/{code}Obtiene información detallada sobre una promoción específica.
Parámetros de Ruta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| code | string | Sí | Código interno de la promoción |
Ejemplo de Respuesta
{
"name": "Oferta de Verano",
"internalCode": "VERANO2023",
"title": "Oferta de Verano",
"enabled": true,
"description": "Oferta de Verano 20%",
"image": "https://imagen.jpg",
"start": "2023-06-01",
"end": "2023-08-31",
"type": "DISCOUNT_SIMPLE",
"products": [
{
"internalCode": "PROD123",
"boxRatio": 1
}
],
"discountTiersData": [
{
"min": 1,
"max": 2,
"discountPercentage": 20
}
]
}
Ejemplo de Uso
- Javascript
- Python
const headers = {
Authorization: "TU_TOKEN_DE_AUTORIZACION",
"x-api-key": "TU_API_KEY",
};
fetch("https://api.nilo.com/promotion/VERANO2023", {
method: "GET",
headers: headers,
})
.then((response) => response.json())
.then((result) => console.log(result))
.catch((error) => console.log("error", error));
import requests
url = "https://api.nilo.com/promotion/VERANO2023"
headers = {
'Authorization': 'TU_TOKEN_DE_AUTORIZACION',
'x-api-key': 'TU_API_KEY'
}
response = requests.get(url, headers=headers)
print(response.text)
Listar Todas las Promociones
/promotionObtiene una lista de todas las promociones con soporte para paginación y filtrado.
Parámetros de Consulta
| 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) |
| enabled | boolean | No | Filtrar por estado habilitado |
| from | string | No | Fecha inicial para filtrar (YYYY-MM-DD) |
| to | string | No | Fecha final para filtrar (YYYY-MM-DD) |
Crear/Actualizar Promoción de Descuento Simple
/promotion/discount/simpleCrea o actualiza una promoción de descuento simple.
Parámetros del Cuerpo de la Solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| name | string | Sí | Nombre de la promoción |
| internalCode | string | Sí | Identificador único de la promoción |
| start | string | Sí | Fecha de inicio (YYYY-MM-DD) |
| end | string | Sí | Fecha de fin (YYYY-MM-DD) |
| products | object | Sí | Productos incluidos en la promoción |
| discountTiersData | array | Sí | Configuración de niveles de descuento |
| enabled | boolean | Sí | Si la promoción está activa |
Ejemplo del Cuerpo de la Solicitud
{
"name": "Oferta de Verano",
"internalCode": "VERANO2023",
"start": "2023-06-01",
"end": "2023-08-31",
"products": {
"internalCode": "PROD123",
"boxRatio": 1
},
"discountTiersData": [
{
"min": 1,
"max": 2,
"discountPercentage": 10.5
}
],
"enabled": true,
"promotionGrouperCodes": ["GRUPO1", "GRUPO2"]
}
Ejemplo de Uso
- Javascript
- Python
const headers = {
Authorization: "TU_TOKEN_DE_AUTORIZACION",
"x-api-key": "TU_API_KEY",
"Content-Type": "application/json",
};
const data = {
name: "Oferta de Verano",
internalCode: "VERANO2023",
start: "2023-06-01",
end: "2023-08-31",
products: {
internalCode: "PROD123",
boxRatio: 1,
},
discountTiersData: [
{
min: 1,
max: 2,
discountPercentage: 10.5,
},
],
enabled: true,
promotionGrouperCodes: ["GRUPO1", "GRUPO2"],
};
fetch("https://api.nilo.com/promotion/discount/simple", {
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://api.nilo.com/promotion/discount/simple"
headers = {
'Authorization': 'TU_TOKEN_DE_AUTORIZACION',
'x-api-key': 'TU_API_KEY',
'Content-Type': 'application/json'
}
data = {
"name": "Oferta de Verano",
"internalCode": "VERANO2023",
"start": "2023-06-01",
"end": "2023-08-31",
"products": {
"internalCode": "PROD123",
"boxRatio": 1
},
"discountTiersData": [
{
"min": 1,
"max": 2,
"discountPercentage": 10.5
}
],
"enabled": True,
"promotionGrouperCodes": ["GRUPO1", "GRUPO2"]
}
response = requests.put(url, headers=headers, json=data)
print(response.text)
Crear/Actualizar Promoción de Descuento Múltiple
/promotion/discount/multipleCrea o actualiza una promoción con múltiples niveles de descuento.
Parámetros del Cuerpo de la Solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| name | string | Sí | Nombre de la promoción |
| internalCode | string | Sí | Identificador único de la promoción |
| title | string | No | Título para mostrar de la promoción |
| description | string | No | Descripción detallada |
| image | string | No | URL de la imagen de la promoción |
| start | string | Sí | Fecha de inicio (YYYY-MM-DD) |
| end | string | Sí | Fecha de fin (YYYY-MM-DD) |
| products | array | Sí | Array de productos en la promoción |
| discountTiersData | array | Sí | Configuración de niveles de descuento |
| enabled | boolean | Sí | Si la promoción está activa |
Ejemplo del Cuerpo de la Solicitud
{
"name": "Descuento por Volumen",
"internalCode": "VOLUMEN2023",
"title": "Compra Más, Ahorra Más",
"description": "Descuentos progresivos en compras por volumen",
"image": "https://ejemplo.com/promo.jpg",
"start": "2023-06-01",
"end": "2023-08-31",
"products": [
{
"internalCode": "PROD123",
"boxRatio": 1
},
{
"internalCode": "PROD124",
"boxRatio": 1
}
],
"discountTiersData": [
{
"min": 1,
"max": 5,
"discountPercentage": 10
},
{
"min": 6,
"max": 10,
"discountPercentage": 15
}
],
"enabled": true
}
Ejemplo de Uso
- Javascript
- Python
const headers = {
Authorization: "TU_TOKEN_DE_AUTORIZACION",
"x-api-key": "TU_API_KEY",
"Content-Type": "application/json",
};
const data = {
name: "Descuento por Volumen",
internalCode: "VOLUMEN2023",
title: "Compra Más, Ahorra Más",
description: "Descuentos progresivos en compras por volumen",
image: "https://ejemplo.com/promo.jpg",
start: "2023-06-01",
end: "2023-08-31",
products: [
{
internalCode: "PROD123",
boxRatio: 1,
},
{
internalCode: "PROD124",
boxRatio: 1,
},
],
discountTiersData: [
{
min: 1,
max: 5,
discountPercentage: 10,
},
{
min: 6,
max: 10,
discountPercentage: 15,
},
],
enabled: true,
};
fetch("https://api.nilo.com/promotion/discount/multiple", {
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://api.nilo.com/promotion/discount/multiple"
headers = {
'Authorization': 'TU_TOKEN_DE_AUTORIZACION',
'x-api-key': 'TU_API_KEY',
'Content-Type': 'application/json'
}
data = {
"name": "Descuento por Volumen",
"internalCode": "VOLUMEN2023",
"title": "Compra Más, Ahorra Más",
"description": "Descuentos progresivos en compras por volumen",
"image": "https://ejemplo.com/promo.jpg",
"start": "2023-06-01",
"end": "2023-08-31",
"products": [
{
"internalCode": "PROD123",
"boxRatio": 1
},
{
"internalCode": "PROD124",
"boxRatio": 1
}
],
"discountTiersData": [
{
"min": 1,
"max": 5,
"discountPercentage": 10
},
{
"min": 6,
"max": 10,
"discountPercentage": 15
}
],
"enabled": True
}
response = requests.put(url, headers=headers, json=data)
print(response.text)
Crear/Actualizar Promoción de Bonificación Individual
/promotion/bonus/individualCrea o actualiza una promoción de tipo "compra X lleva Y" para el mismo producto.
Parámetros del Cuerpo de la Solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| name | string | Sí | Nombre de la promoción |
| internalCode | string | Sí | Identificador único de la promoción |
| start | string | Sí | Fecha de inicio (YYYY-MM-DD) |
| end | string | Sí | Fecha de fin (YYYY-MM-DD) |
| products | object | Sí | Configuración del producto |
| bonusTierData | object | Sí | Configuración de la bonificación |
| enabled | boolean | Sí | Si la promoción está activa |
Ejemplo del Cuerpo de la Solicitud
{
"name": "Lleva 2 Paga 1",
"internalCode": "2X1PROMO",
"start": "2023-06-01",
"end": "2023-08-31",
"products": {
"internalCode": "PROD123",
"boxRatio": 1
},
"bonusTierData": {
"quantityRequired": 2,
"quantityGiven": 1,
"units": 1
},
"enabled": true
}
Ejemplo de Uso
- Javascript
- Python
const headers = {
Authorization: "TU_TOKEN_DE_AUTORIZACION",
"x-api-key": "TU_API_KEY",
"Content-Type": "application/json",
};
const data = {
name: "Lleva 2 Paga 1",
internalCode: "2X1PROMO",
start: "2023-06-01",
end: "2023-08-31",
products: {
internalCode: "PROD123",
boxRatio: 1,
},
bonusTierData: {
quantityRequired: 2,
quantityGiven: 1,
units: 1,
},
enabled: true,
};
fetch("https://api.nilo.com/promotion/bonus/individual", {
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://api.nilo.com/promotion/bonus/individual"
headers = {
'Authorization': 'TU_TOKEN_DE_AUTORIZACION',
'x-api-key': 'TU_API_KEY',
'Content-Type': 'application/json'
}
data = {
"name": "Lleva 2 Paga 1",
"internalCode": "2X1PROMO",
"start": "2023-06-01",
"end": "2023-08-31",
"products": {
"internalCode": "PROD123",
"boxRatio": 1
},
"bonusTierData": {
"quantityRequired": 2,
"quantityGiven": 1,
"units": 1
},
"enabled": True
}
response = requests.put(url, headers=headers, json=data)
print(response.text)
Crear/Actualizar Promoción de Bonificación Cruzada
/promotion/bonus/crossedCrea o actualiza una promoción donde la compra de un producto otorga una bonificación de un producto diferente.
Parámetros del Cuerpo de la Solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| name | string | Sí | Nombre de la promoción |
| internalCode | string | Sí | Identificador único de la promoción |
| title | string | No | Título para mostrar de la promoción |
| description | string | No | Descripción detallada |
| image | string | No | URL de la imagen de la promoción |
| start | string | Sí | Fecha de inicio (YYYY-MM-DD) |
| end | string | Sí | Fecha de fin (YYYY-MM-DD) |
| products | array | Sí | Productos que activan la bonificación |
| bonusTierData | object | Sí | Configuración del producto de regalo |
| enabled | boolean | Sí | Si la promoción está activa |
Ejemplo del Cuerpo de la Solicitud
{
"name": "Compra X Lleva Y Gratis",
"internalCode": "PROMOCRUZADA",
"title": "Promoción Especial Cruzada",
"description": "Compra Producto A, Lleva Producto B Gratis",
"image": "https://ejemplo.com/promo-cruzada.jpg",
"start": "2023-06-01",
"end": "2023-08-31",
"products": [
{
"internalCode": "PRODA",
"boxRatio": 1
}
],
"bonusTierData": {
"quantityRequired": 2,
"quantityGiven": 1,
"productInternalCode": "PRODB",
"units": 1
},
"enabled": true
}
Ejemplo de Uso
- Javascript
- Python
const headers = {
Authorization: "TU_TOKEN_DE_AUTORIZACION",
"x-api-key": "TU_API_KEY",
"Content-Type": "application/json",
};
const data = {
name: "Compra X Lleva Y Gratis",
internalCode: "PROMOCRUZADA",
title: "Promoción Especial Cruzada",
description: "Compra Producto A, Lleva Producto B Gratis",
image: "https://ejemplo.com/promo-cruzada.jpg",
start: "2023-06-01",
end: "2023-08-31",
products: [
{
internalCode: "PRODA",
boxRatio: 1,
},
],
bonusTierData: {
quantityRequired: 2,
quantityGiven: 1,
productInternalCode: "PRODB",
units: 1,
},
enabled: true,
};
fetch("https://api.nilo.com/promotion/bonus/crossed", {
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://api.nilo.com/promotion/bonus/crossed"
headers = {
'Authorization': 'TU_TOKEN_DE_AUTORIZACION',
'x-api-key': 'TU_API_KEY',
'Content-Type': 'application/json'
}
data = {
"name": "Compra X Lleva Y Gratis",
"internalCode": "PROMOCRUZADA",
"title": "Promoción Especial Cruzada",
"description": "Compra Producto A, Lleva Producto B Gratis",
"image": "https://ejemplo.com/promo-cruzada.jpg",
"start": "2023-06-01",
"end": "2023-08-31",
"products": [
{
"internalCode": "PRODA",
"boxRatio": 1
}
],
"bonusTierData": {
"quantityRequired": 2,
"quantityGiven": 1,
"productInternalCode": "PRODB",
"units": 1
},
"enabled": True
}
response = requests.put(url, headers=headers, json=data)
print(response.text)
Cambiar Estado de Promoción
/promotion/{code}/statusHabilita o deshabilita una promoción específica.
Parámetros de Ruta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| code | string | Sí | Código interno de la promoción |
Parámetros del Cuerpo de la Solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| enabled | boolean | Sí | Nuevo estado de la promoción |
Ejemplo del Cuerpo de la Solicitud
{
"enabled": true
}
Ejemplo de Uso
- Javascript
- Python
const headers = {
Authorization: "TU_TOKEN_DE_AUTORIZACION",
"x-api-key": "TU_API_KEY",
"Content-Type": "application/json",
};
const data = {
enabled: true,
};
fetch("https://api.nilo.com/promotion/VERANO2023/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://api.nilo.com/promotion/VERANO2023/status"
headers = {
'Authorization': 'TU_TOKEN_DE_AUTORIZACION',
'x-api-key': 'TU_API_KEY',
'Content-Type': 'application/json'
}
data = {
"enabled": True
}
response = requests.put(url, headers=headers, json=data)
print(response.text)
Operaciones por Lotes
Actualización por Lotes de Promociones
/batch/promotionActualiza múltiples promociones en una sola operación.
Parámetros del Cuerpo de la Solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| upsert | object | No | Contiene promociones para crear o actualizar |
| remove | object | No | Contiene promociones para eliminar |
Ejemplo del Cuerpo de la Solicitud
{
"upsert": {
"discount": {
"simple": [
{
"name": "Descuento Simple 1",
"internalCode": "DS1",
"start": "2023-06-01",
"end": "2023-08-31",
"products": {
"internalCode": "PROD1",
"boxRatio": 1
},
"discountTiersData": [
{
"min": 1,
"discountPercentage": 10
}
],
"enabled": true
}
],
"multiple": []
},
"bonus": {
"individual": [],
"crossed": []
}
}
}
Ejemplo de Uso
- Javascript
- Python
const headers = {
Authorization: "TU_TOKEN_DE_AUTORIZACION",
"x-api-key": "TU_API_KEY",
"Content-Type": "application/json",
};
const data = {
upsert: {
discount: {
simple: [
{
name: "Descuento Simple 1",
internalCode: "DS1",
start: "2023-06-01",
end: "2023-08-31",
products: {
internalCode: "PROD1",
boxRatio: 1,
},
discountTiersData: [
{
min: 1,
discountPercentage: 10,
},
],
enabled: true,
},
],
multiple: [],
},
bonus: {
individual: [],
crossed: [],
},
},
};
fetch("https://api.nilo.com/batch/promotion", {
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://api.nilo.com/batch/promotion"
headers = {
'Authorization': 'TU_TOKEN_DE_AUTORIZACION',
'x-api-key': 'TU_API_KEY',
'Content-Type': 'application/json'
}
data = {
"upsert": {
"discount": {
"simple": [
{
"name": "Descuento Simple 1",
"internalCode": "DS1",
"start": "2023-06-01",
"end": "2023-08-31",
"products": {
"internalCode": "PROD1",
"boxRatio": 1
},
"discountTiersData": [
{
"min": 1,
"discountPercentage": 10
}
],
"enabled": True
}
],
"multiple": []
},
"bonus": {
"individual": [],
"crossed": []
}
}
}
response = requests.post(url, headers=headers, json=data)
print(response.text)
Seguridad
Autenticación
Todos los endpoints 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 operaciones de lectura:
supplier/promotion.read - Para operaciones de escritura:
supplier/promotion.write - Para operaciones por lotes:
supplier/promotion.bulkwrite