Manual integración modulo de promociones.
Introducción
Los conceptos involucrados en el módulo promocional, son las promociones, las ofertas, los cupones, los códigos promocionales, y los regalos.
Las promociones contienen las definiciones de los descuentos, los productos a que se aplican etc.; las ofertas, códigos promocionales y los cupones, son las aplicaciones reales y siempre se refieren a una promoción.
Definición de la promoción
Las promociones permiten ofrecer al usuario una ventaja sobre el surtido estándar, para ello se definen tanto los productos donde se pueden aplicar, así como el efecto de la promoción misma: por ejemplo el efecto puede ser cierto tipo de descuento o un regalo.
Una promoción puede tener vinculadas las siguientes entidades:
- Ofertas
Cuando una promoción está vinculada a una oferta, esta será disponible para cualquier usuario.
- Códigos promocionales
Cuando una promoción está vinculada a un código promocional será disponible solo para los usuarios que posean e introduzcan dicho código.
- Cupones.
Siempre están vinculados a una promoción. La promoción sólo será disponible para quien disponga de dicho cupón.
Los cupones, códigos promocionales y ofertas, tienen siempre una vigencia (que eventualmente puede no expirar nunca).
De esta manera, una vez definida y cargada una promoción, esta será reusable siempre que se desee vincular algo (oferta, cupón, código promocional) a ella misma.
Por ejemplo podríamos cargar una promoción 3X2 sobre el agua, y en un segundo momento vincularle una oferta con cierta vigencia. Más adelante, una vez caducada la oferta, el cliente podría decidir reusar la misma promoción para una nueva oferta, o unos cupones para algunos clientes, sin necesidad de reenviar la definición de la promoción. Esto proporciona agilidad, sobre todo para promociones muy complejas de definir.
Una promoción que no tiene vinculado nada vigente, por sí sola no sirve de nada. Pero queda a disposición para ser lanzada en cualquier momento.
En seguida vamos a introducir los conceptos, o parámetros, en base a los cuales el sistema define una promoción. Las definiciones presentadas en las siguientes tablas tienen solo carácter orientativo, para introducir el lector a los conceptos que se detallarán en las especificaciones formales del formato Json.
Conceptos genéricos de una promoción
| Conceptos promoción | Descripción/Ejemplo |
|---|---|
| Donde Aplica | Expresa cuál es el concepto que dispara la promoción. Pueden ser productos o totales. |
| Tipo Descuento | Expresa la manera en la cual los productos o conceptos de Donde Aplica son involucrados en la promoción. Por ejemplo 3X2 o pack. |
| Como Aplica | Expresa la acción concreta que desencadena la aplicación de la promoción. Por ejemplo descuento neto o porcentual. |
| Alcance de un uso | Expresa si se tiene que aplicar el descuento sobre una sola unidad, sobre la linia, sobre el total del ticket o sobre portes (entrega o recogida). |
| Condiciones de la promoción | Se trata de condiciones mínimas para poder aplicar la promoción. Por ejemplo hay que comprar un número mínimo de unidades, o gastar cierto importe. |
| Rango Aplicación | Expresa los límites de aplicación de la promoción. Por ejemplo la promoción se aplica hasta un límite de 50 euros. |
| Variables de control de la promoción | Expresa valores que condicionan y/o limitan el comportamiento de la promoción. Ej. Máximos usos por compra, u otro ejemplo, en el caso M x N, define M y N |
A continuación se detallan los conceptos arriba expuestos.
Donde Aplica
Donde aplica especifica dónde se va a calcular el descuento. La promoción puede aplicar a un conjunto de productos, o a otros conceptos del ticket como el total o los portes. Donde aplica puede asumir los siguientes valores:
| ID | Nombre | Descripcion |
|---|---|---|
| 1 | Producto | Promoción que aplica a un producto. Se debe especificar el código del producto. |
| 2 | Categoría | Promoción que aplica a una categoría. |
| 3 | Jerarquía | Promoción que aplica a una o varias jerarquías. |
| 4 | Total | Promoción que aplica al total del ticket (suma de importes a precio normal). |
| 5 | Lote | Promoción que aplica a un lote. |
| 6 | Agrupación | Promoción que aplica a una agrupación. |
| 9 | Importe neto | Promoción que aplica al importe final del pedido (importe a pagar). |
| 10 | Informativa | Promoción informativa que no modifica importes. |
| 11 | Bundle | Promoción que aplica a un Bundle. |
Tipo descuento
Se soportan promociones con los siguientes tipos de descuento.
- MxN
Por ejemplo promoción 3 x 2 en productos de limpieza.
3 x 2 significa que se aplicará un descuento a 1 unidad en función del campo Como aplica, que podrá ser
- Porcentaje
Ejemplo: Si descuento = 70% será interpretado como que por la compra de tres unidades la 3ª unidad vale el 70% menos
- precio neto.
Ejemplo: Si importe promoción = 0 será interpretado como que por la compra de 3 unidades una es gratuita, siendo así un 3x2 clásico.
Ejemplo: Si importe promoción = 0,5 será interpretado como que por la compra de tres unidades una vale 0,5.
- Descuento neto
En el caso que en las variables de control se especifique la oferta como cruzada, el descuento se aplicará a los artículos más baratos.
- Tramo Importe
El descuento se aplicará a un tramo de importe en función del campo Como aplica
Por ejemplo cada 10 euros gastados, se descuenta el 10%
El descuento se aplicaría por tramos de 10 euros. Es decir si se gastan 12 euros, no hay descuento alguno sobre los 2 euros que sobran. Si se gastan 25 euros, el descuento se aplica a 20 euros, y no a los cinco que sobran.
El importe se deduce por el campo Donde aplica. Si aplica a la categoría charcutería, entonces el importe será el gastado en esta categoría.
- Tramo Unidades
Es el mismo concepto del tramo importe, pero por unidades.
Como se calcula el número de unidades depende del campo donde aplica.
Por ejemplo descuento de un euro cada 5 unidades. Si Donde aplica es categoría limpieza, el descuento se aplica cada cinco unidades de productos de limpieza. Si Donde aplica es total, entonces las unidades son las del carrito entero.
- Pack
El descuento pack solo se permite cuando donde aplica tiene valor = lote.
La promoción sólo aplica cuando se cumple por completo los productos definidos en el lote (con sus cantidades)
Se define por ejemplo un lote con código ‘zumos-varios’: (2 zumos naranja pascual de 1litro, 1 zumo manzana pascual de 1 litros, y un zumo de piña marca pascual 1l)
Se puede definir una promoción con donde aplica = lote, tipo descuento = pack, como aplica = precio neto = 3 euro. En este caso el cliente se lleva todo el pack por 3 euro.
- Unitario
Descuento que se aplica cuando se cumplen las condiciones
Ejemplo: Descuento de 25% en chocolate Nestle postres. Donde aplica = producto (código chocolate nestle postres), Como aplica = porcentaje (25).
Como aplica
Expresa la acción concreta de la promoción. Puede tener los siguientes valores:
- descuento neto
Se especifica en el campo importePromocion, y debe informarse en la divisa corresponidente.
- precio neto
Es el precio que se aplicará a las unidades que aplica la promoción. Se especifica en el campo importePromocion, y debe informarse en la divisa corresponidente.
- descuento porcentaje
El porcentaje se especifica en el campo descuento.
- regalo.
En este caso se deberá especificar el código de regalo en el campo oportuno
41 – Regalo Tipo 1
46 – Regalo Tipo 6
47 – Regalo Tipo 7
- % próxima compra.
Se utilizar para la generación de vales para compras futuras. Esta promoción no genera ningún importe
Alcance de un uso de la promoción
En el caso de cupones y códigos promocionales, se pueden dar casos de usos limitados; por ejemplo un cupón se puede usar solo diez veces. Puede ser también que muchos usos puedan ser consumidos en la misma compra. Para estos casos se tiene que definir el alcance de un uso, es decir cuántos productos se pueden descontar con un uso.
| Alcance de un uso | Descripción/Ejemplo |
|---|---|
| Unidad | Un uso aplica el descuento a una unidad. Puede ser un artículo, un pack, un MxN (por ejemplo a un 3X2) o un tramo. |
| Línea Ticket | Un uso aplica el descuento a todos las unidades de una sola línea del ticket |
| Ticket | Un uso aplica el descuento a todo lo que se puede en el ticket. |
| Gastos entrega | Un uso aplica el descuento al importe de los gastos de entrega. |
| Gastos recogida | Un uso aplica el descuento al importe de los gastos de recogida. |
Condiciones de la promoción
Las condiciones mínimas para que la promoción sea aplicable se expresan como número de unidades mínimas, como mínimo número de productos distintos, o importe mínimo.
- Nº unidades mínimas
Con número de unidades mínimas nos referimos a la cantidad de unidades independientemente de si son el mismo producto.
- Mínimo número de productos distintos
Con mínimo número de productos distintos nos referimos al número de productos diferentes, pero dentro de la promoción, sin considerar los productos fuera de la promoción, a menos que la promoción aplique al total
Ejemplo:
Descuento comprando un mínimo de 3 productos diferentes en charcutería. Se expresaría:
- Donde Aplica = categoría; categoría = charcutería
-
mínimo número de productos distintos = 3.
-
Importe mínimo.
La condición de importe mínimo para aplicar una promoción tiene las siguientes interpretaciones posible en función del paramentro donde aplica:
- Para “donde aplica” portes, recogida, total (7,8,4) se considera el importe del total de la compra (suma de importes de los productos menos los descuentos por promociones a total y producto)
- Para “donde aplica” importe neto (9) se considera el importe del total del tiquet considerando la suma de todos los productos menos los descuentos y mas los gastos de envio/recogida y menos sus promociones.
- Para “donde aplica” categoría, jerarquía, lote, agrupación (2,3,5,6) se considera el importe de lo comprado en el ticket para esa selección. En este caso es obligatorio informar el campo “cruzada” con el valor 1.
Rango de aplicación de una promoción
La aplicación de una promoción puede limitarse desde un mínimo o hasta un máximo y tanto por importe como por unidades.
Ejemplo:
50% de descuento a partir de la décima botella de Coca cola. Si se compran 15 coca colas, el descuento aplicará solo a cinco unidades.
5% de descuento a partir de la 1ª unidad y hasta un máximo de 20 unidades.
| Rango aplicación de la promoción | Descripción/Ejemplo |
|---|---|
| Desde importe | El descuento se aplica al rango de importe después del valor especificado por este campo. El importe es él gastado en donde aplica (puede ser una categoría, el total, los portes etc.). |
| Hasta importe | El descuento se aplica al rango de importe hasta el valor especificado por este campo. El importe es él gastado en donde aplica (puede ser una categoría, el total, los portes etc.). |
| Desde nº unidades | El descuento se aplica a las unidades después del valor especificado por este campo. Se trata de las unidades de productos de donde aplica la promoción. En el caso la promoción aplique al total serían las unidades de todo el carrito |
| Hasta nº unidades | El descuento se aplica a las unidades después del valor especificado por este campo. Se trata de las unidades de productos de donde aplica la promoción. En el caso la promoción aplique al total serían las unidades de todo el carrito |
Variables de control de la promoción
Se trata de variables que definen de una manera más concreta la promoción. Por ejemplo si es un tipo de descuento M x N, habrá que especificar los valores de M y N. Análogamente para los tramos habrá que especificar su anchura.
En este juego de variables también se especifica el concepto de promoción cruzada. Una promoción se define cruzada cuando involucra diferentes productos en el mismo descuento concreto. Se piensa por ejemplo en los yogures de distintos sabores. Un ejemplo de promoción cruzada es un 3X2 sobre los yogures Danone, aunque sean de diferentes tipos. Se piense también en un descuento desde la unidad 20 en la sección envasado sin importar que productos sean. Si una promoción es cruzada hay que especificarlo.
Otro comportamiento que se puede definir es relativo al máximo número de usos por compra. Los cupones y los códigos promocionales pueden tener usos limitados, pero por ejemplo se puede no querer que se usen más de una vez en la misma compra. O limitar como se quiera su uso en la misma compra.
| Variable | Descripción/Ejemplo |
|---|---|
| Unidades M | Valor M para la promoción (M x N) |
| Unidades N | Valor N para la promoción (M x N) |
| Cruzada | Específica si para el cálculo del descuento hay que considerar diferentes productos o no. Hay que tener en cuenta que el tipo descuento pack siempre es cruzado, y el tipo descuento unitario (estándar) nunca lo es. Si Donde Aplica no representa un conjunto, la promoción no puede ser cruzada |
| Tramo importe | Anchura del tramo expresado en importe para las promociones con Tipo Descuento tramo importe |
| Tramo unidades | Anchura del tramo expresado en unidades para las promociones con Tipo Descuento tramo unidades |
| Máximo de usos por compra | Máximos de usos por compra |
| Inmediato | Descuento inmediato o diferido |
| Acumula | Para las promociones de fidelización define si genera un vale o acumula a la cuenta de fidelización |
| Uso Exlusivo Importe mínimo | Define si el importe mínimo de esta promoción puede compartirse con otra promoción o si lo consume la promoción ya no esta disponible para otras promociones. |
| Precio Oferta | Define si la promoción es el precio oferta. Este tipo de promociones son las que aparecen en el grid de producto con precio tachado. En este caso la promoción solo es valida para los siguientes valores de la variable “Donde Aplica” 1 – Producto Adicionalmente se controla |
| Origen Precio Descuento | Define el precio a partir del cual se calcula el descuento de la promoción en el caso de no aplicar a total. 1 → Precio articulo. El descuento se calcula a partir del precio del artículo. 2 → Precio oferta artículo El descuento se calcula a partir del precio oferta del artículo. 3 → Ultimo precio calculado. El descuento se calcula a partir del último precio calculado después de aplicar todas las ofertas para ese articulo Solo soportado para promociones diferidas (“inmediato” = 0) |
Variables de visualización de la promoción
Se trata de variables que permiten definir la visualización de la promoción en las pantallas de la TOL.
| Variable | Descripción/Ejemplo |
|---|---|
| Visible | Define si la promoción es visible en el widget de producto |
| Visible widget | Define si la promoción es visible en el widget de promociones |
| Visible Validar | Define si la promoción es visible cuando no esta aplicada en la pantalla de validar carrito |
| Grupo Agrupación promoción | Permite ver el total de varias promociones en una única línea en la pantalla validar carrito. |
| Tipo creatividad promoción | Este código se utiliza para poder definir diferentes creatividades. |
Ilustraciones de las promociones
Existen 2 tipos de integración de ilustraciones de promociones en la TOL:
INTEGRACIÓN BÁSICA
En esta integración básica donde se pueden configura un icono en una promoción. Para ello se utiliza la combinación de dos campos:
- imagen: identifica el nombre de la imagen que se asocia a la promoción en los diferentes lugares de la TOL.
- descripcionMinima: es la descripción más reducida de la promoción.
Con la combinación de estos dos campos obtenemos las siguientes casuísticas:
| Se informa descripción mínima | No se informa descripción mínima | |
|---|---|---|
| Se informa imagen | AZUCARERA Se muestra la imagen. La descripción mínima se oculta | KELLOGS Se muestra la imagen. La descripción mínima se oculta |
| No se informa imagen | CERVEZA MAHOU Ocultar imagen Background color Mostrar la descripción mínima (2x1) | LECHE CELTA Ocultar imagen Background color por defecto Ocultar texto (esta configuración no sería correcta, debería tener por lo menos una de las dos) |
Este es el comportamiento por defecto, al tratarse de comportamientos frontales se podrían configurar en cada una de las instalaciones.
Atributos adicionales de la promoción
La siguiente tabla define los atributos adicionales que pueden aplicar a una promoción:
| Id de atributo | Descripción |
|---|---|
| max_usos_globales | Determina cuántas veces puede aplicarse una promoción. |
| max_usos_usuario | Determina cuántas veces puede aplicarse una promoción por un usuario concreto. |
| numero_maximo_pedidos_usuario | Define cuántos pedidos máximos debe tener un usuario para que aplique la promoción. |
Definición de cupones
Las cupones son ofertas personalizadas a un usuario en concreto.
En un cupón se puede informar las siguientes variables :
- Fecha de validez
Periodo durante el que el cupón será aplicable al usuario.
- Usos
Número de usos que puede realizar el usuario de ese cupon.
- Usos automáticos
Permite definir si el cupón se aplica automáticamente en el caso que se cumplan las condiciones de disparo o es el usuario que tiene que aplicarlo manualmente.
- Zonas
Permite informar las tiendas donde el usuario podrá utilizar el cupon, en caso de no informarse el cupón será valido para todas las tiendas.
- Codigo de validación
Opcionalmente puede informarse un código de validación de manera que el usuario solo podrá utilizar el cupon si tiene el código de validación..
Cupones tipo ALL
Es posible cargar cupones genéricos para todos los clientes, denominados tipo ALL, en la carga se utiliza el usuario #ALL# (valor a definir en la implantación)
Cuando existe un cupón de este tipo (puede ser para una tienda o para todas) y el usuario hace login, entonces se genera una copia del cupón ALL y se le asigna al usuario. Este cupón tendrá las mismas condiciones que el cupon cargado para el usuario ALL.
De esta forma, con un cupón ALL podemos controlar los usos del cupon por parte de cada usuario en concreto.
Cupones tipo INPUT
Para los cupones tipo ALL es posible informar un código de validación de forma que el usuario tenga que introducir un código para poder utilizar dicho cupón.
Detalle del formato JSON
Datos de la promoción
En la siguiente tabla se detalla de manera completa el listado de campos a informar para definir una promoción.
| Campo “Nombre campo” | Descripción/Ejemplo | Formato | Oblig. |
|---|---|---|---|
| Código “codigo” | Código que identifica la promoción de forma distintiva para intercambio con la TOL No se puede repetir | Literal (50 caracteres max.) | Sí |
| Canal “canal” | Canal en el que se hace efectiva la promoción. | Numérico entero | Sí |
| Dónde aplica promoción “dondeAplicaPromocion” | Posible valores: 1 → Producto 2 → Categoría 3 → Jerarquía 4 → Total compra 5 → Lote 6 → Agrupación 9 → Importe neto 10 → Informativas 11 → Bundle | Numérico entero | Sí |
| Tipo descuento promoción “tipoDescuentoPromocion” | Posibles valores: 1 → MxN: Especifica que el descuento se aplica a las ‘M-N’ unidades de productos. En el caso que la promoción sea cruzada, los productos descontados serán los más baratos. 2 → Tramo Importe: Por tramo de importe gastado en Donde Aplica. 3 → Tramo Unidades: Por tramos de unidades de productos de Donde Aplica. 4 → Pack: Para obtener el descuento hay que llevarse todos los artículos especificados en Donde Aplica. 5 → Unitario: Descuento estándar unidad por unidad. | Numérico entero | Sí |
| Alcance del uso de la promoción “alcanceUsoPromocion” | Expresa el alcance de la aplicación de una promoción una vez. Posibles valores: 1 → Unitario: Un uso aplica el descuento a la unidad del tipo descuento. Por ejemplo a una unidad de un producto, a una unidad de pack, a una unidad de M x N o a una unidad de tramo. 2 → Linea de ticket: Un uso aplica el descuento a todos las unidades de una sola línea del ticket. 3 → Ticket: Un uso aplica el descuento a todo lo que se puede en el ticket. 41 → Gastos envío: Un uso aplica el descuento a los gastos de envío. 42 → Gastos recogida: Un uso aplica el descuento a los gastos de recogida. | Numérico entero | Sí |
| Como aplica la promoción “comoAplica” | Expresa la acción concreta que desencadena la aplicación de la promoción Posibles valores: 1 → Descuento neto 2 → Precio neto 3 → Porcentaje 4 → Regalo 5 → Porcentaje descuento en próxima compra 111 → Descuento neto de grupo Bundle 112 → Precio neto de grupo Bundle 113 → Porcentaje de grupo Bundle Los valores 111, 112 y 113 solo son válidos con “dondeAplicaPromocion” = 11, y en ellos el importe o el porcentaje lo define cada grupo del Bundle y no la promoción | Numérico entero | Sí |
| Máximo de usos por compra “maxUsosCompra” | Cuantas veces puede ser utilizada una promoción en una compra (-1 para ilimitado). Actualmente está disponible para promociones como: producto, bundles y conjunto de productos(lote, jerarquia, agrupación, etc). Ejemplos: 2x1, 10%, 2ud al 50%, 2x20€ MXN, 2x20€ Tramo (Cruzadas y no cruzadas). En promociones de descuento porcentual, se limita las unidades como hace "HastaUnidades". En el caso de descuento porcentual cruzada, cogen las unidades con el menor importe. Si es cruzada indica N usos por compra, si es no cruzada indica N usos por linea. Si se desea limitar los usos de una promoción no cruzada a N usos por compra (Aplicar en N lineas, por ejemplo promoción a productos de un lote, pero que solo aplique en los N más baratos), dicha promo tiene que tener idScopeUsoPromocion=ALCANCE_USO_UNITARIO. | Numérico entero | Sí |
| Inmediato “inmediato” | Si el descuento se aplica en la compra actual o en otro momento 1 → Oferta aplica a la compra actual 0 → Oferta genera descuento para futuras compras (fidelización, vales) | Booleano (1,0) | Sí |
| Acumula “acumula” | Para el caso de ofertas diferidas (fidelización) define si se suma al total o individualmete. 0 → La promoción suma el importe al total diferido (fidelización) 1 →La promoción genera un importe por si mismo (ej. Vale) Si la promoción es “inmediato” = 0 y acumula no viene informado se informa 0 | Numérico entero | No |
| Grupo promoción “grupoPromocion” | Codigo de agrupación de la promoción. Este código se utiliza para poder totalizar varias promociones en una única línea en la pantalla validar carrito. | Literal (50 caracteres máx.) | No |
| Tipo creatividad promoción “tipoCreatividadPromocion” | Codigo de creatividad de la promoción. Este código se utiliza para poder definir diferentes creatividades. | Literal (10 caracteres) | No |
| Uso exclusivo importe mínimo "usoExclusivoImporteMinimo” | Define si el importe mínimo de esta promoción puede compartirse con otra: 0 → No exclusivo (el importe se comparte con otras promociones). 1+ → Cualquier valor superior a 0 indica con que otras promociones se calcula el importe minimo exlusivo. Por ejemplo si se usa valor 1 →Exclusivo (el importe es “quemado” y no esta disponible para otras promociones de valor 1). Si se usa valor N, el importe es “quemado” y no esta disponible para otras promociones de con valor N. | ||
| Si no aplica se informa 0. | Numérico entero | No | |
| Precio Oferta “esPrecioOferta” | Define si la promoción es el precio oferta 0 → No es precio oferta 1 → Precio oferta Si no aplica se informa 0 | Booleano (1,0) | Sí |
| Origen Precio Descuento “origenPrecioDescuento” | Define el precio a partir del cual se calcula el descuento de la promoción. 1 → Precio articulo Valor obligatorio si “esPrecioOferta” = 1 2 → Precio oferta artículo 3 → Ultimo precio calculado. Solo soportado para promociones diferidas (“inmediato” = 0) Si el precio definido no existe para el artículo se utiliza el precio anterior. Ejemplo promoción con origenPrecioDescuento = 2 pero artículo no tiene Precio Oferta. La promoción aplica sobre precio articulo. | Numérico entero | Si |
| Destacado “destacado” | Visualización destacada del producto con promoción | Booleano (1,0) | Sí |
| Unidades mínimas “unidadesMinimas” | Unidades mínimas para hacer efectiva la promoción Sin no hay mínimo poner 0. Sólo compatible con el Tipo Descuento = Unidades | Numérico decimal (formato: 0.00) | Sí |
| Mínimo producto distinto “mininimoProductosDistintos” | Número de productos distintos para hacer efectiva la promoción. Si no aplica es informa 1 | Numérico entero | Sí |
| Importes “importes” | Importes que aplican en la promoción | Tipo Moneda | No |
| Desde número unidades “desdeNumUnidades” | El descuento se aplica a las unidades después del valor especificado por este campo. Sólo compatible con el Tipo Descuento de Unidaes | Numérico decimal (formato: 0.00) | No |
| Hasta número unidades “hastaNumUnidades” | El descuento se aplica a las unidades hasta el valor especificado por este campo. | Numérico decimal (formato: 0.00) | No |
| Unidades M “unidadesM” | Valor M para la promoción (M x N) | Numérico entero | No |
| Unidades N “unidadesN” | Valor N para la promoción (M x N) | Numérico entero | No |
| Tramo unidades “tramoUnidades” | Valor del tramo en unidades donde se aplica promoción si el Tipo Descuento es tramo unidades; nulo si es otro Tipo Descuento. | Numérico decimal (formato: 0.00) | No |
| Descuento “descuento” | Descuento que se aplica a la promoción del tipo porcentaje. Este campo es obligatorio si Como Aplica 3: descuento porcentaje; 5: % próxima compra. En esta caso es un valor informativo para pintar el vale nulo si es otro Como Aplica. | Numérico decimal (formato: 0.00) | No |
| Producto “producto” | Código del producto al que se aplica la promoción. Este campo es obligatorio si Donde Aplica es producto;nulo si es otro Tipo Descuento. | Literal (10 caracteres máx.) | No |
| Lote “lote” | Código del Lote donde se aplica la promoción. . Este campo es obligatorio si Donde Aplica es lote;nulo si es otro Tipo Descuento. | Literal (30 caracteres máx.) | No |
| Categoría “categoria” | Identificador de la categoría donde se aplica la promoción. Este campo es obligatorio si Donde Aplica es categoría;nulo si es otro Tipo Descuento. | Numérico entero | No |
| Agrupación “agrupación” | Agrupación donde se aplica la promoción. Este campo es obligatorio si Donde Aplica es agrupación;nulo si es otro Tipo Descuento. | Literal (15 caracteres máx.) | No |
| Código Jerarquía “jerarquiaCodigo” | Código de la Jerarquía donde se aplica la promoción dentro del árbol de jerarquías propio de la tienda física. | Literal (30 caracteres máx.) | No |
| Nivel Jerarquía “jerarquiaNivel” | Nivel de la Jerarquía donde se aplica la promoción dentro del árbol de jerarquías propio de la tienda física. | Numérico entero | No |
| Lista de jerarquías “jerarquias” | En caso de promociones a múltiples jerarquías: Lista de jerarquías donde se aplica la promoción. | Tipo Lista jerarquias | No |
| Tipo Lista Regalos “regalos” | Nodo tipo lista para regalar productos a los usuarios en función de la compra realizada, ya sea dependiendo de los productos añadidos al carrito | Tipo Lista regalos | No |
| Tipo Bundle “bundle” | Definición de la promoción de tipo Bundle. Donde aplica = 11 | Tipo Bundle | No |
| Cruzada “cruzada” | Especifica si para el cálculo del descuento hay que considerar diferentes productos o no. Hay que tener en cuenta que el tipo descuento pack siempre es cruzado, y el tipo descuento unitario (estándar) nunca lo es. Si Donde Aplica no representa un conjunto, la promoción no puede ser cruzada Si no aplica se informa 0 | Booleano (1,0) | No |
| Descripciones “descripciones” | Descripción de la promoción. | Tipo Literal Multi-idioma | Si |
| Fecha Vigencia Vale desde “fechaValeDesde” | Fecha de inicio de vigencia del vale que genera la oferta. Se añade 00:00:00 en el caso de informar dd/mm/aaaa | Fecha (dd/mm/aaaa hh:mm:ss) | No |
| Fecha Vigencia Vale hasta “fechaValeHasta” | Fecha fin de vigencia del vale que genera la oferta. Se añade 23:59:59 en el caso de informar dd/mm/aaaa | Fecha (dd/mm/aaaa hh:mm:ss) | No |
| Codigo promoción origen “codigoOrigenPromocion” | Codigo de la promoción origen que generó el vale o cupon | Literal (50 caracteres max.) | No |
| Codigo promoción cliente “codigoPromocionCliente” | Codigo de la promoción/oferta en los sistemas del cliente | Literal (50 caracteres max.) | No |
| Codigo segmentacion “codigoSegmentacion” | Codigo de segmentación para los usuarios que tengan dicha promoción. | Literal (100 caracteres max.) | No |
| Imagen “imagen” | Nombre de la imagen que se asocia a la promoción. Si no se informa se asociará la imagen: “codigoPromocion.png” | Literal (30 caracteres máx.) | No |
| Acción “accion” | Alta, baja o modificación | Literal (1 carácter ) “A”, “B” | Sí |
Importes
El campo importes definido en el json depende de la divisa y se informa con un campo Tipo Moneda. Para cada uno de ellos se tiene que especificar un valor para cada divisa que se quiere soportar.
| Campo “Nombre campo” | Descripción/Ejemplo | Formato | Oblig. |
|---|---|---|---|
| Divisa “divisa” | Código que identifica la divisa (ISO-4217) | Literal (3 caracteres máx.) | Sí |
| Desde importe “desdeImporte” | El descuento se aplica al rango de importe después del valor especificado por este campo. El importe es el de los productos involucrados en el descuento. | Decimal (10,5) | No |
| Hasta importe “hastaImporte” | El descuento se aplica al rango de importe hasta el valor especificado por este campo. El importe es el de los productos involucrados en el descuento. | Decimal (10,5) | No |
| Importe promoción “importePromocion” | Se aplica la promoción con un determinado valor. Este campo es obligatorio si Como Aplica es precio neto o descuento neto;nulo si es otro Como Aplica. | Decimal (10,5) | No |
| Importe mínimo “importeMinimo” | Importe mínimo para efectuar la promoción | Decimal (10,5) | No |
| Tramo importe “tramoImporte” | Valor del tramo en importe donde se aplica promoción si el Tipo Descuento es tramo importe; nulo si es otro Tipo Descuento. | Decimal (10,5) | No |
Descripciones
Las descripciones se deben informar en fución de cada idioma soportado para ello se utiliza un campo de Tipo Literal Multi-idioma:
| Campo “Nombre campo” | Descripción/Ejemplo | Formato | Oblig. |
|---|---|---|---|
| Idioma “idioma” | Identificador del idioma (ISO 639-1) | Literal (2 caracteres máx.) | Sí |
| Descripción Mínima “descripcionMinima” | Descripción Mínima de la promoción, se utiliza para pintar sobre los iconos. | Literal (10 caracteres) | Si |
| Descripción Breve “descripcionBreve” | Descripción breve de la promoción | Literal (50 caracteres) | Si |
| Descripción Larga “descripcionLarga” | Descripción larga | Literal (150 caracteres.) | No |
| Descripción Vale “descripcionVale” | Descripción detallada del vale que genera la promoción Permite código html que se visualizara en la TOL. | Literal (200 caracteres.) | No |
| Descripción Vale Extendida “descripcionValeExtendida” | Descripción detallada del vale que genera la promoción Permite código html que se visualizara en la TOL. | Literal (600 caracteres.) | No |
| Atributos de la promocion “atributos” | Atributos de la promocion | Tipo Mapa clave/valor | No |
| Zonas de Envío “zonasEnvio” | Zonas de envío donde aplica la promoción. | Lista Tipo Código Zona Envío | No |
Jerarquías
En el caso de que un promoción aplique a varias jerarquias se utilizara un lista informada en el campo Tipo Lista jerarquias:
| Campo “Nombre campo” | Descripción/Ejemplo | Formato | Oblig. |
|---|---|---|---|
| Código Jerarquía “jerarquiaCodigo” | Código de la Jerarquía donde se aplica la promoción dentro del árbol de jerarquías propio de la tienda física. | Literal (30 caracteres máx.) | No |
| Nivel Jerarquía “jerarquiaNivel” | Nivel de la Jerarquía donde se aplica la promoción dentro del árbol de jerarquías propio de la tienda física. | Numérico entero | No |
Regalos
Este nodo tiene el objetivo de poder regalar productos a los usuarios en función de la compra realizada, ya sea dependiendo de los productos añadidos al carrito, o del importe total alcanzado en el mismo.
Dichos productos se informarán en el JSON siguiendo el siguiente formato:
Tipo Lista Regalos:
| Campo “Nombre campo” | Descripción/Ejemplo | Formato | Oblig. |
|---|---|---|---|
| Código de producto “codigo” | Código del producto / regalo / obsequio | Literal (50 caracteres máx.) | Si |
| Cantidad “cantidad” | Cantidad a regalar en formato decimal | Decimal (10,2) | Si |
Bundles
El objetivo del nodo bundles es que los clientes pueden vender un conjunto de productos distintos (mínimo 2) aplicando un descuento en caso de que el usuario compre todo este conjunto de productos. Es decir, el precio de estos artículos resultará más bajo si se compran todos ellos, que en caso de adquirirlos de forma separada.
Existen dos tipologías de Bundle, que se distinguen por el campo “comoAplica” de la promoción:
| Tipología | “comoAplica” | Dónde se define el descuento |
|---|---|---|
| Bundle cerrado | 1, 2 o 3 | En la promoción. Cada grupo indica en “repartoDescuentoPorcentaje” qué parte de ese descuento le corresponde. |
| Bundle abierto | 111, 112 o 113 | En cada grupo del Bundle. La promoción no lleva importe ni porcentaje propios. |
En el Bundle abierto, el campo en el que se informa la cifra de cada grupo depende del “comoAplica” elegido:
| “comoAplica” | Campo del grupo | Significado |
|---|---|---|
| 111 → Descuento neto de grupo | “repartoDescuentoImporte”, por divisa | Importe que descuenta el grupo. |
| 112 → Precio neto de grupo | “repartoImporteNeto”, por divisa | Importe final al que queda el grupo. |
| 113 → Porcentaje de grupo | “repartoDescuentoPorcentaje” | Porcentaje de descuento sobre el precio del propio grupo. |
Con las tres tipologías de grupo se aplican las siguientes reglas:
- La promoción no puede informar “descuento” ni “importePromocion”, porque la cifra la define cada grupo.
- Todos los grupos deben informar el campo que corresponde al “comoAplica” elegido.
- El nombre del grupo en español es obligatorio.
Dichos productos se informarán en el JSON siguiendo el siguiente formato:
Tipo Bundle:
| Campo “Nombre campo” | Descripción/Ejemplo | Formato | Oblig. |
|---|---|---|---|
| Definición del Bundle “grupoDefiniciones” | Lista de grupos que componen el Bundle. | Lista Tipo Bundle Grupo | Si |
Tipo Bundle Grupo:
| Campo “Nombre campo” | Descripción/Ejemplo | Formato | Oblig. |
|---|---|---|---|
| Orden “orden” | Orden de los grupos del Bundle. | Numérico | No |
| Unidades minimas “unidadesMinimas” | Productos del grupo pueden ser AND o OR, se controla mediante mínimo de de productos distintos (cuantos productos distintos) y mínimo de unidades por grupo. Unidades mínimas (mínimo de unidades totales) por grupo, en formato decimal. | Decimal (10,2) | Si |
| Mínimo productos distintos “minProDistinto” | Productos del grupo pueden ser AND o OR, se controla mediante mínimo de de productos distintos (cuantos productos distintos) y mínimo de unidades por grupo. Mínimo de productos distintos en formato decimal. | Decimal (10,2) | Si |
| Reparto del descuento porcentaje “repartoDescuentoPorcentaje” | Con “comoAplica” 1, 2 o 3, reparto porcentual del descuento de la promoción en cada grupo. Con “comoAplica” = 113, porcentaje de descuento sobre el precio del propio grupo. Formato decimal. | Decimal (10,2) | Si |
| Idiomas “descripciones” | Lista con los valores por idioma del grupo del Bundle. | Lista Tipo Bundle Grupo Idioma | No |
| Divisas “importes” | Lista con los valores por divisa del grupo del Bundle. | Lista Tipo Bundle Grupo Divisa | No |
| Productos “infoProducto” | Lista de los productos que conforman el Bundle | Lista Tipo Bundle Grupo Producto | Si |
Lista Bundle Grupo Idioma:
| Campo “Nombre campo” | Descripción/Ejemplo | Formato | Oblig. |
|---|---|---|---|
| Idioma “idioma” | Identificador del idioma (ISO 639-1). | Literal (2 caracteres máx.) | Sí |
| Nombre grupo “nombre” | Nombre del grupo del Bundle. | Literal (250 caracteres) | Si |
Lista Bundle Grupo Divisa:
| Campo “Nombre campo” | Descripción/Ejemplo | Formato | Oblig. |
|---|---|---|---|
| Divisa “divisa” | Código que identifica la divisa (ISO-4217). | Literal (3 caracteres máx.) | Sí |
| Reparto importe neto “repartoImporteNeto” | Importe final al que queda el grupo, formato decimal. Obligatorio con “comoAplica” = 112. | Decimal (10,5) | No |
| Reparto descuento importe “repartoDescuentoImporte” | Importe que descuenta el grupo, formato decimal. Obligatorio con “comoAplica” = 111. | Decimal (10,5) | No |
Lista Bundle Grupo Producto:
| Campo “Nombre campo” | Descripción/Ejemplo | Formato | Oblig. |
|---|---|---|---|
| Código de producto “codigo” | Código del producto del Bundle. | Literal (50 caracteres máx.) | Si |
| Unidades mínimas “unidadesMinimas” | Condición por producto, cuantas unidades mínimas por producto (por defecto 1). | Decimal (10,5) | No |
| Prioridad “prioridad” | Cuando hay varios productos que puedan entran en el Bundle, se usa este campo para determinar cual se incluye. | Numérico | No |
Ofertas
El archivo JSON de un ofertas tiene el siguiente formato:
| Campo “Nombre campo” | Descripción/Ejemplo | Formato | Oblig. |
|---|---|---|---|
| Código “codigo” | Código que identifica la oferta de forma distintiva. | Literal (30 caracteres max.) | Sí |
| Promoción “promocion” | Código que identifica la promoción de forma distintiva para intercambio con la TOL | Literal (50 caracteres max.) | Sí |
| Canal “canal” | Canal en el que se hace efectiva la oferta. | Numérico entero | Sí |
| Zonas “zonas” | Zonas donde se hace efectiva la oferta. | Lista Tipo Código Zona | Sí |
| Desde “desde” | Fecha de inicio de vigencia de la oferta. | Fecha (dd/mm/aaaa hh:mm) | Sí |
| Hasta “hasta” | Fecha de caducidad de la oferta. | Fecha (dd/mm/aaaa hh:mm) | Sí |
| Visible “visible” | Define si la promoción es visible en el desplegable de promociones 0 → No visible 1 →Visible Si no aplica se informa 1 | Numerico | No |
| Visible widget “visibleWidget” | Define si la promoción es visible en el widget de producto si esta aplica a producto 0 → No visible 1 →Visible Si no aplica se informa 1 | Numerico | No |
| Visible Validar “visibleValidar” | Define si la promoción es visible en el validar carrito. 0 → No visible 1 →Visible Si no aplica se informa 1 | Numerico | No |
| Prioridad “prioridad” | Prioridad en el caso de promociones solapadas. Si no se informa, se inicializa a 1. La prioridad afecta solamente al calculo del carrito cuando las promociones usan como origen de precio el ultimo precio calculado. | Numérico entero | No |
A continuación describimos el Tipo Código Zona:
| Campo “Nombre campo” | Descripción/Ejemplo | Formato | Oblig. |
|---|---|---|---|
| Código “codigo” | Código que identifica de forma distintiva la Zona | Numérico entero | Sí |
Cupones
El archivo JSON de cupones tiene el siguiente formato:
| Campo “Nombre campo” | Descripción/Ejemplo | Formato | Oblig. |
|---|---|---|---|
| Código “codigo” | Código que identifica al cupón de forma distintiva. | Literal (30 caracteres máx.) | Sí |
| Promoción “promocion” | Código que identifica la promoción de forma distintiva para intercambio con la TOL | Literal (50 caracteres max.) | Sí |
| Código usuario “codigoUsuario” | Código que identifica al usuario de forma distintiva. | Literal (50 caracteres máx.) | Sí |
| Desde “desde” | Fecha de inicio de vigencia del cupón. | Fecha (dd/mm/aaaa hh:mm) | Sí |
| Hasta “hasta” | Fecha de caducidad el cupón. | Fecha (dd/mm/aaaa hh:mm) | Sí |
| Usos “usos” | Nº de usos máximo que tiene el cupón dentro del periodo de vigencia. -1 ilimitado | Numérico entero | Sí |
| Consumos “consumos” | Indica el número de veces que se ha utilizado el cupón. | Numérico entero | Sí |
| Usos Automáticos “usosAutomaticos” | Indica el número de usos automáticos que se aplican en el cupón. | Numérico entero | Sí |
| Usos globales “usosGlobales” | Número de usos total de cupones para todos los clientes Si no se aplica: -1(usos ilimitados) | Numérico entero | No |
| Codigo Validación “códigoValidacion” | Codigo alfanúmerico que puede utilizarse para que el cliente valide el cupn. | Literal (30 caracteres máx.) | No |
| Visible “visible” | Define si la promoción es visible en el desplegable de promociones 0 → No visible 1 →Visible Si no aplica se informa 1 | Numerico | No |
| Visible widget “visibleWidget” | Define si la promoción es visible en el widget de producto si esta aplica a producto 0 → No visible 1 →Visible Si no aplica se informa 1 | Numerico | No |
| Visible Validar “visibleValidar” | Define si la promoción es visible en el validar carrito. 0 → No visible 1 →Visible Si no aplica se informa 1 | Numerico | No |
| Canal “canal” | Canal en el que se hace efectivo el cupón. | Numérico entero | Sí |
| Zonas “zonas” | Zonas donde se hace efectiva el cupón. | Lista del Tipo Código Zona | No |
Zonas
| Campo “Nombre campo” | Descripción/Ejemplo | Formato | Oblig. |
|---|---|---|---|
| Código “codigo” | Código que identifica de forma distintiva la Zona | Numérico entero | Sí |
¿En que orden se aplican las promociones?
Al definir una oferta o cupon, se puede usar el campo "prioridad" para determinar el orden de ejecución de una promoción. Cuanta más alta sea la prioridad antes será el orden de ejecución de la prioridad. Por defecto todas las promociones de tipo oferta tienen prioridad 1.000.000, son siempre las primeras a ejecutar. El resto de promociones si no tienen prioridad asignada, se marca la prioridad a 1. En caso de que 2 promociones tengan la misma prioridad, la promoción más nueva será la que se aplique antes. La prioridad es importante en ciertos tipos de promociones, ya que usan el último precio calculado para calcular el descuento. Por ello es importante saber en que instante se hará ese cálculo.
Por ejemplo si tenemos las siguientes promociones que aplican a un producto con precio 2€:
- PromoA: Precio Oferta 1€. Prioridad 1.000.000 (Por defecto)
- PromoB: 10% descuento sobre último precio calculado. Prioridad 100
- PromoC: 10% descuento sobre precio oferta. Prioridad 50
- PromoD: 10% descuento sobre último precio calculado. Prioridad 10
El orden de ejecución sería:
- Paso 0
- Resultado: Artículo - PrecioOriginal: 2€, PrecioOferta: -, UltimoPrecio: 2€
- Paso 1
- Aplica PromoA: Cambia el precio a 1€
- Resultado: Artículo - PrecioOriginal: 2€, PrecioOferta: 1€, UltimoPrecio: 1€
- Paso 2
- Aplica PromoB: Aplica 10% sobre el último precio (1€). Descuento de 0.10€
- Resultado: Artículo - PrecioOriginal: 2€, PrecioOferta: 1€, UltimoPrecio:0.90€
- Paso 3
- Aplica PromoC: Aplica 10% sobre el precio oferta a 1€. Descuento de 0.10€
- Resultado: Artículo - PrecioOriginal: 2€, PrecioOferta: 1€, UltimoPrecio:0.80€
- Paso 4
- Aplica PromoD: Aplica 10% sobre el último precio (0.80€). Descuento de 0.08€
- Resultado: Artículo - PrecioOriginal: 2€, PrecioOferta: 1€, UltimoPrecio:0.72€
Campos obligatorios en dependencia de otros campos
En la siguiente tabla se muestran los campos que deberán tener definido un valor si están definidos los campos de los que dependen.
- En la columna Valor del Campo se muestran los diferentes valores que tienen las entidades definidas en la columna Campo
- En la columna Campos dependientes, se encuentran todos los campos que deberán tener un valor definido obligatoriamente en el Json, si depende de definida en la columna Campo
| Campo | Valor del campo | Campos dependientes obligatorios | Observaciones |
|---|---|---|---|
| Donde aplica promoción | 1 → Producto | producto | |
| Donde aplica promoción | 2 → Categoría | categoria | |
| Donde aplica promoción | 3 → Jerarquía | → jerarquiaCodigo → jerarquiaNivel o → jerarquias | . |
| Donde aplica promoción | 5 → Lote | lote | |
| Donde aplica promoción | 6 → Agrupación | agrupacion | |
| Tipo descuento promoción | 1 → MxN | → Unidades M → Unidades N | |
| Tipo descuento promoción | 2 → Tramo importe | → Tramo importe | |
| Tipo descuento promoción | 3 → Tramo unidades | → Tramo unidad | |
| Tipo descuento promoción | 4 → Pack | → N/A | |
| Tipo descuento promoción | 5 → Unitario | ||
| Importe mínimo | informado | Alcance importe mínimo | 1 → Total 2 → Donde Aplica |
| Como aplica promoción | 1 → Descuento neto | → Importe promoción | |
| Como aplica promoción | 2 → Precio neto | → Importe promoción | |
| Como aplica promoción | 3 → Porcentaje | → Descuento | |
| Como aplica promoción | 4 → Regalo | → Regalo | |
| Precio Oferta | 1 → Precio oferta | → Origen precio descuento | Valor obligatorio 1 Precio artículo |
| Precio Oferta | 1 → Precio oferta | → Inmediato | Valor obligatorio 1 |
| Precio Oferta | 1 → Precio oferta | tipo_descuento_promocion | Valor obligatorio 5 |
| Precio Oferta | 1 → Precio oferta | id_donde_aplica_promocion | Valor obligatorio 1 |
| Precio Oferta | 1 → Precio oferta | id_como_aplica_promocion | Valores posibles 1,2,3 |
Proceso de carga
El proceso de carga de promociones se basa en campo “codigo” y “accion” para definir el proceso a realizar:
- Alta (“accion” = A)
Se da de alta una promoción con el “codigo” informado.
Si se vuelve a enviar una promoción con el mismo “código” el sistema la rechaza por duplicado.
- Baja (“accion” = B)
Se da de baja una promoción con el “codigo” informado.
- Modifiación (“accion” = M)
Funcionalidad no soportada.
Función campos código
- “codigo” – que se utiliza como campo intercambio TOL – sistemas de cliente y que es un campo único en la TOL.
- “codigo_promocion_cliente” – que permite guardar el código de promoción de los clientes.
En resumen para modificar una promoción hay que darla de baja y volverla a carga con otro “codigo” aunque puede mantener el “codigo_promocion_cliente”
Gestión de versiones
| Versión | Cambios |
|---|---|
| 25.0 | Agregado campos para definir atributos de la promoción y zonas de envío de la promoción |
| 25.3 | Eliminación versionJ |