Saltar al contenido principal

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ónTipo en API NiloEndpoint
Bonificación Directa (mismo producto)BONUS_INDIVIDUALPUT /promotion/bonus/individual
Bonificación Cruzada (producto diferente)BONUS_CROSSEDPUT /promotion/bonus/crossed
Descuento Grupal (combinación de productos)DISCOUNT_MULTIPLEPUT /promotion/discount/multiple
Descuento Simple EscalonadoDISCOUNT_SIMPLEPUT /promotion/discount/simple
Combos con descuentoDISCOUNT_MULTIPLEPUT /promotion/discount/multiple
Combos con bonificaciónBONUS_CROSSEDPUT /promotion/bonus/crossed

Consideraciones Importantes

Campos Mutuamente Excluyentes

La API define ciertos campos como mutuamente excluyentes:

  • Condición por Cantidad vs Monto: No envíes discountTiersData/bonusTierData y discountTiersDataCash/bonusTierDataCash simultáneamente
  • Tipo de descuento: Especifica discountPercentage O discountAmount, no ambos

Enviar ambos campos resultará en un error.

  1. 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)
  2. 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
  3. 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

GET/promotion/{code}

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

Parámetros de Ruta

ParámetroTipoRequeridoDescripción
codestringCó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

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

Listar Todas las Promociones

GET/promotion

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

Parámetros de Consulta

ParámetroTipoRequeridoDescripción
takenumberNoNúmero de items por página (default: 50, max: 50)
pagestringNoNúmero de página (default: 1)
enabledbooleanNoFiltrar por estado habilitado
fromstringNoFecha inicial para filtrar (YYYY-MM-DD)
tostringNoFecha final para filtrar (YYYY-MM-DD)

Crear/Actualizar Promoción de Descuento Simple

PUT/promotion/discount/simple

Crea o actualiza una promoción de descuento simple.

Parámetros del Cuerpo de la Solicitud

ParámetroTipoRequeridoDescripción
namestringNombre de la promoción
internalCodestringIdentificador único de la promoción
startstringFecha de inicio (YYYY-MM-DD)
endstringFecha de fin (YYYY-MM-DD)
productsobjectProductos incluidos en la promoción
discountTiersDataarrayConfiguración de niveles de descuento
enabledbooleanSi 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

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

Crear/Actualizar Promoción de Descuento Múltiple

PUT/promotion/discount/multiple

Crea o actualiza una promoción con múltiples niveles de descuento.

Parámetros del Cuerpo de la Solicitud

ParámetroTipoRequeridoDescripción
namestringNombre de la promoción
internalCodestringIdentificador único de la promoción
titlestringNoTítulo para mostrar de la promoción
descriptionstringNoDescripción detallada
imagestringNoURL de la imagen de la promoción
startstringFecha de inicio (YYYY-MM-DD)
endstringFecha de fin (YYYY-MM-DD)
productsarrayArray de productos en la promoción
discountTiersDataarrayConfiguración de niveles de descuento
enabledbooleanSi 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

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

Crear/Actualizar Promoción de Bonificación Individual

PUT/promotion/bonus/individual

Crea o actualiza una promoción de tipo "compra X lleva Y" para el mismo producto.

Parámetros del Cuerpo de la Solicitud

ParámetroTipoRequeridoDescripción
namestringNombre de la promoción
internalCodestringIdentificador único de la promoción
startstringFecha de inicio (YYYY-MM-DD)
endstringFecha de fin (YYYY-MM-DD)
productsobjectConfiguración del producto
bonusTierDataobjectConfiguración de la bonificación
enabledbooleanSi 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

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

Crear/Actualizar Promoción de Bonificación Cruzada

PUT/promotion/bonus/crossed

Crea 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ámetroTipoRequeridoDescripción
namestringNombre de la promoción
internalCodestringIdentificador único de la promoción
titlestringNoTítulo para mostrar de la promoción
descriptionstringNoDescripción detallada
imagestringNoURL de la imagen de la promoción
startstringFecha de inicio (YYYY-MM-DD)
endstringFecha de fin (YYYY-MM-DD)
productsarrayProductos que activan la bonificación
bonusTierDataobjectConfiguración del producto de regalo
enabledbooleanSi 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

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

Cambiar Estado de Promoción

PUT/promotion/{code}/status

Habilita o deshabilita una promoción específica.

Parámetros de Ruta

ParámetroTipoRequeridoDescripción
codestringCódigo interno de la promoción

Parámetros del Cuerpo de la Solicitud

ParámetroTipoRequeridoDescripción
enabledbooleanNuevo estado de la promoción

Ejemplo del Cuerpo de la Solicitud

{
"enabled": true
}

Ejemplo de Uso

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

Operaciones por Lotes

Actualización por Lotes de Promociones

POST/batch/promotion

Actualiza múltiples promociones en una sola operación.

Parámetros del Cuerpo de la Solicitud

ParámetroTipoRequeridoDescripción
upsertobjectNoContiene promociones para crear o actualizar
removeobjectNoContiene 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

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

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