PROMO 7.2 - Manual de Integración - Motor
Acerca del manual
Propósito y alcance
El presente manual tiene como finalidad la capacitación al usuario que desee integrar su aplicación de ventas con el Motor de Promociones.
Se provee una descripción detallada de los mensajes que deben ser enviados al mismo y de cómo interpretar los mensajes de respuesta que dará ante un requerimiento.
Documentación de PROMO
PROMO provee la siguiente documentación:
- Manual de usuario:
Este documento tiene la finalidad de capacitar al usuario que desee utilizar la consola de Administración de Promociones de PROMO.
- Manual de instalación:
Este documento describe los procedimientos para instalar los componentes de Motor y Consola, la creación e inicialización de la Base de Datos y los requerimientos necesarios para el correcto funcionamiento de dichos componentes.
- Manual de integración:
Este documento describe detalladamente los mensajes que deben ser enviados al Motor de Promociones y la forma de interpretar los mensajes de respuesta que el mismo dará ante un requerimiento.
Nota: Antes de continuar con la lectura del presente manual, se recomienda leer los capítulos 2 y 3 del Manual de usuario.
Introducción a la Integración
El motor de promociones es el componente de PROMO encargado de recibir requerimientos desde el punto de venta y luego responderlos. Esta interacción se realizará a través de una serie de mensajes con formato XML (a partir de la versión de Promo 7.2.5 el motor acepta también mensajes con formato JSON) que siguen un Protocolo de Comunicación definido. En este sentido el motor de promociones puede funcionar tanto como servidor TCP/IP o bien como servidor REST, dependiendo de las necesidades, preferencias y requerimientos tecnológicos que posea el punto de venta.
Comunicación con el Motor de Promociones
Como mencionamos anteriormente, la forma de dialogar con el Motor de Promociones es a través de la mensajería XML o JSON (a partir de Promo 7.2.5) presentada más adelante en este documento. Estos mensajes utilizan como transporte dos formas de comunicación:
Servidor TCP/IP
Uno de los protocolos más comunes en la actualidad. Permite enrutamiento y envío seguro. En este caso, el motor actúa como un servidor que espera conexiones entrantes en un puerto TCP/IP determinado. El punto de venta debe enviar y recibir paquetes TCP/IP que poseen el siguiente formato:
HEADER | MESSAGE
Donde:
- Header (encabezado): son 6 Bytes que indican la cantidad de bytes que tendrá el cuerpo del mensaje que se envía al motor de promociones.
- Message (mensaje): mensaje enviado al Motor de Promociones con el formato XML o JSON descripto en este documento.
Servidor REST
REST (Representational State Transfer) es un estilo de arquitectura utilizado en aplicaciones distribuidas en red. Se basa en protocolos cliente-servidor, sin estado, y como en el caso de PROMO mayoritariamente se implementa utilizando protocolo HTTP. La idea es una alternativa simple al uso de mecanismos más complejos como CORBA, RPC o SOAP.
El motor de promociones se presenta aquí como un servidor HTTP que espera conexiones en un puerto TCP/IP determinado.
Como servidor REST, el motor posee dos formas de trabajo: Mediante solicitudes modo GET o modo POST (>v 7.EP2.1).
Modo GET
Para utilizar esta forma de comunicación la aplicación cliente debe enviar requerimientos HTTP y esperar las respuestas correspondientes. La invocación o formato de utilización es: (puede realizarse en un browser como FireFox, Chrome, etc.)
http://servidor:puerto/engine/evaluate?request=message
Donde:
- http://servidor:puerto: es la url para acceder al servidor donde se encuentra en ejecución el motor de PROMO.
- message: es el mensaje correspondiente que debe evaluar el motor, como se especifica en el presente documento.
Importante
- Si el motor posee la opción de seguridad vía https, entonces todas las referencias a http:// deben leerse como https://
- Si se encuentra activa la autenticación por usuario/clave, entonces los request deberán incorporar en el encabezado (headers) las siguiente propiedad: "Authorization":"Basic user:encrypted_password_MD5"
- Para mayor información consultar el manual de instalación y configuración
Presentaremos aquí varios ejemplos utilizando dos clientes: el navegador Firefox y la aplicación "curl" de dominio público (https://curl.haxx.se/). Suponemos entonces que necesitamos enviar el siguiente mensaje para ser evaluado por el motor:
<message companyId="sts" store="9905" terminal="001" date-time="2016-11-20 23:01" messageId="0001" void-trx="false" suggest="true" response="true" init-tck="true" evaluate="true" msg-version="2.4" status="init" ><item-add seq="1" unitprice="1" xprice="1" qty="1" magnitude="1" code="P001" discountable="true"/> </message>
Ejemplo genérico JSON request
{
"message": {
"companyId": "napse",
"store": "Tienda1",
"terminal": "1",
"date-time": "2023-04-17 17:00:00",
"init-tck": "true",
"messageId": "10",
"void-trx": "false",
"response": "true",
"status": "init",
"evaluate": "true",
"suggest": "true",
"customer-add": [{
"seq": "1",
"id": "1"
}]
}
}
Al mismo tiempo el servidor donde se encuentra disponible el motor de PROMO es http://demoserver.net y el puerto 3625.
En Firefox la url a utilizar sería la siguiente:
http://demoserver.net:3625/engine/evaluate?request=<?xml version="1.0"?><message companyId="sts" store="9905" terminal="001" date-time="2016-11-20 23:01" messageId="0001" void-trx="false" suggest="true" response="true" init-tck="true" evaluate="true" msg-version="2.4" status="init" ><item-add seq="1" unitprice="1" xprice="1" qty="1" magnitude="1" code="P001" discountable="true"/> </message>
Esto en una sola línea como se ve en la figura siguiente.
Acorde a los resultados de la evaluación del mapa se verá en el browser una respuesta del tipo:
De la misma forma, otro ejemplo es realizar lo mismo pero utilizando curl. En este caso entonces por línea de comandos se envía el mensaje de la siguiente forma:
curl -v http://demoserver.net:3625/engine/evaluate?request=%3C?xml%20version=%221.0%22?%3E%3Cmessage%20store= %229901%22%20terminal=%22001%22%20date-time=%222016-11-20%2023:01%22%20messageId=%220001%22%20void-trx=%22false%22%20suggest=%22true%22%20response=%22true%22%20init-tck=%22true%22%20evaluate=%22true%22%20msg-version=%222.4%22%20status=%22init%22%20%20%3E%3Citem-add%20seq=%221%22%20unitprice=%22219%22%20xprice=%22219%22%20qty=%221%22%20magnitude=%221%22%20code=%22P001%22%20discountable=%22true%22/%3E%3C/message%3E
Nótese que el mensaje xml debe ser codificado, cosa que en caso como Firefox, el navegador se encarga de esta conversión automáticamente.
En la siguiente figura se muestra el ejemplo completo con el requerimiento y la respuesta. Se han borrado algunos datos relativos al servidor en que se ejecutó ya que no hacen al ejemplo.
Modo POST
Para utilizar esta forma de comunicación la aplicación cliente debe enviar requerimientos HTTP y esperar las respuestas correspondientes. La invocación o formato de utilización es:
http://servidor:puerto/engine/evaluate
Donde:
- http://servidor:puerto: es la url para acceder al servidor donde se encuentra en ejecución el motor de PROMO.
- En el cuerpo del mensaje POST debe incluirse el parámetro "request" con el mensaje correspondiente que debe evaluar el motor, como se especifica en el presente documento.
Importante
- Si el motor posee la opción de seguridad via https, entonces todas las referencias a http:// deben leerse como https://
- Si se encuentra activa la autenticación por usuario/clave, entonces los request deberán incorporar en el encabezado(headers) las siguiente propiedad: "Authorization":"Basic user:encrypted_password_MD5"
- Para mayor información consultar el manual de instalación y configuración
Al mismo tiempo el servidor donde se encuentra disponible el motor de PROMO es http://demoserver.net y el puerto 3625.
En Firefox la url que usamos para esta prueba es:
http://demoserver.net:3625/engine/evaluate?request=<?xml version="1.0"?><message companyId="sts" store="9905" terminal="001" date-time="2016-11-20 23:01" messageId="0001" void-trx="false" suggest="true" response="true" init-tck="true" evaluate="true" msg-version="2.4" status="init" ><item-add seq="1" unitprice="1" xprice="1" qty="1" magnitude="1" code="P001" discountable="true"/> </message>
Otra opción es utilizar un programa como POSTMAN para generar la consulta como se ven la siguiente figura:
De la misma forma, otro ejemplo es realizar lo mismo pero utilizando curl. En este caso entonces por línea de comandos se envía el mensaje de la siguiente forma:
curl --location --request POST 'http://myserver:8888/engine/evaluate' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'request=<message companyId="napse" store="1" terminal="1" date-time="2020-10-23 18:36:01" init-tck="true" messageId="12" void-trx="false" response="true" status="sales" evaluate="true" suggest="true"> <item-add seq="1" qty="1.000" magnitude="1.000" xprice="291.90000" unitprice="291.90" code="87406291" discountable="true" level1="15" level2="07" level3="50" level4="10" accumDiscount="false"/> </message>
Sesiones
Antes de comenzar con la descripción del mensaje utilizado para el envío de requerimientos al Motor de Promociones, es necesario introducir al lector en el manejo de sesiones que éste realiza.
Una sesión es un espacio reservado dentro del Motor de Promociones para el manejo de la información que respecta a una transacción. De esta forma es capaz de manejar diversas transacciones concurrentemente, teniendo una sesión por cada una de ellas. Podemos asimilar este concepto con la apertura de una transacción que ha comenzado a realizarse en el punto de venta y que irá incorporando elementos hasta el cierre de la misma.
La sesión se identifica por la concatenación de los siguientes campos contenidos en el encabezado del mensaje (explicado en la sección siguiente):
SessionId = CompanyId + Store + Terminal
Al iniciarse una nueva sesión los datos de la transacción correspondiente estarán vacíos, pudiendo ser luego completados como se indicará más adelante, es decir se reserva solamente una transacción sin elementos pero con los datos de encabezado como puede ser la fecha y hora de la misma, más la tienda y terminal donde ocurre.
Asimismo, la sesión tendrá un time-out (tiempo de expiración) configurable, el cual una vez transcurrido sin que se registre alguna recepción de mensaje hará que la sesión se elimine automáticamente, haciendo necesaria la apertura de una nueva y, si se continúa con la transacción, el reenvío de los datos que la sesión expirada contenía. Ver el manual de instalación y Configuración para mayor detalle.
Hay que notar de lo visto hasta aquí, que tanto se opte por comunicaciones con el motor de promociones en su servidor TCP/IP como REST, ambos utilizan la misma mensajería que será presentada en este documento y que se ha denominado "MESSAGE" en ambos casos.
Motor: Engine Request
Anteriormente mencionamos que el motor de promociones es el componente de PROMO encargado de recibir requerimientos desde el punto de venta y luego responderlos. Esta interacción se realizará a través de una serie de mensajes con formato XML que seguirá una serie de reglas definidas.
En esta sección se presentará la estructura de los mensajes XML o JSON enviados por el punto de venta que desea interactuar con Promo. Estos mensajes se denominan REQUEST o solicitudes. El formato General es:
<message ... propiedades del encabezado ...> ... elementos del cuerpo del mensaje ... </message>
JSON
{
"message": {
... todos los atributos de respuesta ....
}
}
Encabezado
Como se mencionó anteriormente, los mensajes que se envíen al Motor de Promociones serán en XML. El elemento raíz de ese mensaje XML deberá ser la etiqueta <message>, siendo esta etiqueta a la que se le llamará encabezado, y contendrá una serie de atributos que serán utilizados por el Motor de Promociones para conocer el momento y lugar de la transacción, si debe o no iniciar una nueva sesión, etc. Contenidos dentro de esta etiqueta se encontrarán los comandos que quieran ejecutarse en el Motor, los cuales formarán el cuerpo del mensaje, tema desarrollado en la sección siguiente.
Los atributos que puede poseer el encabezado son:
Propiedad | Tipo de dato | Descripción | Requerido | Valor ante ausencia |
companyId | Alfanumérico | Identifica la compañía que envía el mensaje | SI | |
store | Alfanumérico | Identifica el local que envía el mensaje. | Sí | |
channel | Alfanumérico | Identifica el canal donde asociado a la transacción. | No | "" |
terminal | Numérico | Identifica la terminal emisora | Sí | |
date-time | YYYY-MM-DD HH:MM:SS | Fecha y hora del mensaje. (date-time="2017-03-21 15:20:26") | Sí | |
messageId | Numérico positivo | Identifica cada uno de los mensajes enviados por la terminal, siendo este número utilizado por el Motor de Promociones como identificador cuando envíe una respuesta. | Sí | |
void-trx | Booleano | Indica si la transacción es una devolución. | No | "false" |
response | Booleano | Indica si se desea que el Motor dé una respuesta ante el mensaje enviado. | No | "false" |
init-tck | Booleano | Indica si con este mensaje se debe iniciar una nueva sesión. | No | "false" |
evaluate | Booleano | Le indica al motor que calcule las promociones utilizando los elementos ingresado hasta ese momento. | No | "false" |
status | Alfanumérico | Indica en que estado se encuentra el punto de venta
| No | "" |
msg-version | Alfanumérico | Indica la versión del mensaje en cuestión | No | "" |
map-version | Entero positivo | Indica al motor que mapa utilizar. Tendrá sentido sólo si el valor de "void-trx" es verdadero. | No | "" |
suggest | Booleano | Le indica al motor si debe sugerir promociones o no. Si suggest-seq y suggest-seq-type no están presentes se tomará todo el contexto para realizar la sugerencia. | No | "false" |
suggest-seq | Numérico | Indica el número de secuencia sobre el que el motor realizará la sugerencia en caso de que el atributo suggest="true". Este atributo será acompañado por el suggest-seq-type, que de no ser especificado, se asumirá suggest-seq-type="item" | No | "1" o null |
suggest-seq-type | Alfabético | Indica el tipo de línea sobre la que deberá hacerse la sugerencia en caso de que el atributo suggest="true". Este atributo será acompañado por el suggest-seq, que de no estar especificado, se asumirá sugget-seq="1". Los valores que puede tomar este atributo son: item, coupon, payment, event, customer. | No | "item" o null |
suggest-per-type | Booleano | Le indica al motor si deben sugerir promociones teniendo en cuenta el tipo de los conjuntos participantes de la promoción o no. Si suggest-filter-type no está presente se sugerirán todas las promociones que estén disponibles para sugerencia teniendo en cuenta el atributo suggest del mapa y las promociones. Si está presente y en verdadero, los atributos suggest, suggest-seq y suggest-seq-type serán ignorados. | No | "false" |
suggest-filter-type | Alfabético | Indica el tipo de conjunto participante de la promoción que deberá tenerse en cuenta para la sugerencia en caso de que el atributo suggest-per-type="true". Los valores que puede tomar este atributo son: item, coupon, payment, event, customer. Si no estuviera presente, se asume todos los tipos de conjuntos. | No | "null" |
suggest-extended | Booleano | Le indica al motor si debe mostrar la información de los beneficios de cada promoción sugerida. Si suggest es false, el valor de este campo no tiene relevancia. | No | "false" |
offline | Booleano | Le indica al motor que la transacción será tratada en modo offline, es decir ante una contingencia de comunicación con PROMO Central se almacenará para su posterior envío (ver nota debajo "Comportamiento de Promo en modo offline"). | No | "false" |
originalTransaction | Alfabético | Para el caso de un valor de status = requestTransaction, esta propiedad indicará la transacción que se requiere consultar | No | "" |
chosenOption | Entero positivio | En el caso de que el resultado de la evaluación haya resultado en una serie de opciones (varios bloques "optional") este atributo permite que el sistema externo informe al motor de Promo, cual de esas opciones fue la que finalmente se han aplicado u otorgado al cliente. El valor es basado en 0, es decir la primer opción es la número 0, la siguiente la número 1 y así sucesivamente. | No | 0 |
storeChain | Alfabético | Identificador de la "Cadena" a la que pertenece la tienda (Store) de la transacción. Puede ser utilizada en la condición de una promoción. | No | "" |
format | Alfabético | Identificador del Formato al cual pertenece la tienda (Store) de la transacción. Puede ser utilizada en la condición de una promoción. | No | "" |
zone | Alfabético | Identificador de la Zona a la cual pertenece la tienda (Store) de la transacción. Puede ser utilizada en la condición de una promoción. | No | "" |
subZone | Alfabético | Identificador de la SubZona a la cual pertenece la tienda (Store) de la transacción. Puede ser utilizada en la condición de una promoción. | No | "" |
tenderGroupCode | Alfabético | Cuando se utilice preciadores, si se envía el valor "cr" retornara el precio a crédito, en caso de otro valor o de no enviarlo retornara el precio de venta. | No | "" |
currencyCode | Alfabético | Código de la moneda en la cual se está realizando la transacción. Puede ser utilizada en la condición de una promoción, por ejemplo para condicionar la entrega de puntos a esa moneda. | No | "" |
limitBalances | Booleano | Cuando se envíe en 'true' se devolverá en la respuesta del motor al POS los saldos de limites de Tienda y General (retail) que tengan definido las promociones que hayan participado de la transacción en curso. Valor por defecto "false" (A partir de Promo 7.0.2) | No | "false" |
Comportamiento de Promo en modo offline
Si por regla de negocio, el POS envía al motor de Promo en el encabezado en el atributo offline=true. Si se corta la comunicación entre el POS y el motor de Promo, dependiendo del momento en que se haya cortado la comunicación, Promo podrá grabar la transacción localmente y cuando haya comunicación la enviará al POS. Es el POS el que decide si la transacción offline se puede realizar o no.
- El loyaltyvalidation no se puede usar offline.
- Si está offline al momento de enviar el finish o el rollback, Promo guardará la transacción. Luego hace un commit automático. Si había cupones o consumo de tarjetas, si puede Promo realiza la operación y si no puede da error y se lo guarda.
- Se pueden agregar cupones, tarjetas, y si están bien los datos, la promo los consume. Es como hacer una transacción de débito offline: se asume que el saldo alcanza, es una decisión de negocio permitir o no ese tipo de transacción.
- Si se está offline y viene una persona con un cupón: si por regla de negocio el POS decide que es válido tomar un cupón y otorgar la promo que lo canjea, lo toma offline y cuando llega a la consola se quema el cupón.
- Si se va a aplicar una promo que emite un cupón: lo genera, lo emite, pero Promo se lo guarda. Promo no envía los datos del cupón. Para el caso de los tipos de cupones virtuales, esto no tiene ningún impacto porque no necesitan el barcode, en el próximo loyaltyvalidation tendrán el total. Pero sí genera un barcode. Y después cuando se restablece la conexión el motor manda automáticamente todos los offline que son finish con commit.
- Si no hay conexión al comenzar la transacción (o sea si no se pudo hacer el loyatyvalidation) no se van a dar las promociones con límites. Si el offline se produce en el finish: va a tomar lo que evaluó durante la promo (en ese caso ya realizó el loyaltyvalidation y por lo tanto ya tiene los límites actualizados).
- El motor embebido usa el mismo directorio offline que el motor estándar. Usa los directorios defaults.
Ejemplo:
<message companyId="sts" store="00001" terminal="010" date-time="2017-12-04 12:30:33:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="payment" msg-version="2.0" map-version="15"> ... cuerpo del mensaje ... </message>
JSON
{
"message": {
"companyId": "sts",
"store": "00001",
"terminal": "010",
"date-time": "2017-12-04 12:30:33:00",
"messageId": "0010",
"void-trx": "false",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"status": "payment",
"msg-version": "2.0",
"map-version": "15",
... cuerpo del mensaje ...
}
}
Con sugerencia sobre el tipo de línea; en este caso "payment"(suggest-seq-type):
<message companyId="sts" store="00001" terminal="010" date-time="2017-12-04 12:30:50:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="payment" msg-version="2.0" map-version="15" suggest="true" suggest-seq="3" suggest-seq-type="payment"> ... cuerpo del mensaje ... </message>
JSON
{
"message": {
"companyId": "sts",
"store": "00001",
"terminal": "010",
"date-time": "2017-12-04 12:30:50:00",
"messageId": "0010",
"void-trx": "false",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"status": "payment",
"msg-version": "2.0",
"map-version": "15",
"suggest": "true",
"suggest-seq": "3",
"suggest-seq-type": "payment",
... cuerpo del mensaje ...
}
}
EJ: la sugerencia se debe hacer sobre el cupón (suggest-filter-type="coupon):
<message companyId="sts" store="00001" terminal="010" date-time="2017-12-04 12:30:50:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="payment" msg-version="2.0" map-version="15" suggest-per-type="true" suggest-filter-type="coupon"> ... cuerpo del mensaje ... </message>
JSON
{
"message": {
"companyId": "sts",
"store": "00001",
"terminal": "010",
"date-time": "2017-12-04 12:30:50:00",
"messageId": "0010",
"void-trx": "false",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"status": "payment",
"msg-version": "2.0",
"map-version": "15",
"suggest-per-type": "true",
"suggest-filter-type": "coupon",
... cuerpo del mensaje ...
}
}
Ej: el motor debe mostrar información de los beneficios de cada promoción sugerida (suggest-extended="true):
<message companyId="sts" store="00001" terminal="010" date-time="2017-12-04 12:30:50:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="payment" msg-version="2.0" map-version="15" suggest="true" suggest-extended="true"> ... cuerpo del mensaje ... </message>
JSON
{
"message": {
"companyId": "sts",
"store": "00001",
"terminal": "010",
"date-time": "2017-12-04 12:30:50:00",
"messageId": "0010",
"void-trx": "false",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"status": "payment",
"msg-version": "2.0",
"map-version": "15",
"suggest": "true",
"suggest-extended": "true",
... cuerpo del mensaje ...
}
}
Cuerpo
El cuerpo del mensaje que se envía al Motor de Promociones estará compuesto por los comandos que se quieran ejecutar. Básicamente, los comandos pueden ser de dos tipos:
Acción | Descripción |
add | Agrega el elemento a la sesión. |
void | Elimina el elemento de la sesión. El elemento se identifica por el número de secuencia. |
Estos comandos pueden ser utilizados sobre los distintos elementos que pueden pertenecer a un ticket. A su vez, estos elementos pueden ser tipificados en 5 clases:
Elemento | Descripción |
item | Identifica a los artículos. |
coupon | Identifica a los cupones. |
loyaltycard | Identifica a los elementos de fidelidad loyalty. |
payment | Identifica a los medios de pago. |
event | Identifica a los eventos u otros elementos no representables mediante los otros tipos. |
customer | Identifica a los clientes. |
benefit | Identifica a los beneficios externos |
La manera de ejecutar un comando es utilizando una etiqueta con la forma <elemento-comando>.
De esta manera, si se desea, por ejemplo, agregar un nuevo artículo a la sesión el comando a utilizar será <item-add>, si se quiere cancelar un cupón agregado anteriormente se enviará un comando del tipo <coupon-void>.
En el cuerpo del mensaje podrá contener uno, ninguno o varios de estos comandos.
Pueden ser enviados los comandos, al mismo tiempo que se abre una nueva sesión o se pide una evaluación.
También puede enviarse un mensaje sin comandos para, por ejemplo, solicitar la evaluación de un ticket.
Como ejemplo para clarificar el uso de estos comandos podemos presentar su relación con el buffer de sesión.
Comenzamos una transacción desde la terminal 256, agregando 2 productos a la sesión.
<message companyId="sts" store="0001" terminal="256" date-time="2022-04-04 12:30:00:" messageId="001" void-trx="false" response="true" init-tck="true" evaluate="true" status="test"> <item-add ... propiedades del primer producto ... /> <item-add ... propiedades del segundo producto ... /> </message>
Request JSON
{
"message": {
"companyId": "sts",
"store": "0001",
"terminal": "256",
"date-time": "2022-04-04 12:30:00:",
"messageId": "001",
"void-trx": "false",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"status": "test",
"item-add": [
{
... propiedades del primer producto ...
},
{
... propiedades del segundo producto ...
}
]
}
}
Con esta acción, la sesión asociada a Empresa 'sts', Store="0001", terminal="256" tendría:
En el siguiente mensaje, nótese que la transacción continúa (init-tck="false") y además agregamos un cliente y un medio de pago a la misma:
<message companyId="sts" store="0001" terminal="256" date-time="2022-04-04 12:30:00:" messageId="001" void-trx="false" response="true" init-tck="false" evaluate="true" status="test" > <customer-add ... propiedades del primer cliente... /> <payment-add ... propiedades del primer pago ... /> </message>
Request JSON
{
"message": {
"companyId": "sts",
"store": "0001",
"terminal": "256",
"date-time": "2022-04-04 12:30:00:",
"messageId": "001",
"void-trx": "false",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"status": "test",
"customer-add": [{
... propiedades del primer cliente...
}],
"payment-add": [{
... propiedades del primer pago ...
}]
}
}
Como consecuencia, el buffer de sesión quedaría:
En el mensaje siguiente, el cliente a decidido no llevar el producto 2 y por consiguiente decidimos retirarlo de la transacción.
<message companyId="sts" store="0001" terminal="256" date-time="2022-04-04 12:30:00:" messageId="001" void-trx="false" response="true" init-tck="false" evaluate="true" status="test"> <item-void... propiedades del segundo producto ... /> </message>
Request JSON
{
"message": {
"companyId": "sts",
"store": "0001",
"terminal": "256",
"date-time": "2022-04-04 12:30:00:",
"messageId": "001",
"void-trx": "false",
"response": "true",
"init-tck": "false",
"evaluate": "true",
"status": "test",
"item-void": [{
... propiedades del segundo producto ...
}]
}
}
El buffer de sesión resultante es:
Esto quiere decir que las promociones serán evaluadas en base a este escenario final, con 1 producto, 1 cliente y 1 medio de pago.
Atributos de comandos
Cada uno de los comandos que se envían Motor de Promociones posee diversos atributos, los cuales identifican al elemento que se está enviando y definen diversas propiedades que poseen los mismos. Tanto add, como void poseerán un número de secuencia, el cual identifica cada elemento unívocamente:
Propiedad | Tipo de dato | Descripción | Requerido |
seq | Entero positivo | Número identificador único del elemento dentro de la transacción. | Sí |
Este será el único atributo que poseerán los comandos del tipo void, siendo este el atributo que indica el elemento que se desea eliminar.
Por otro lado, el comando add poseerá una serie de atributos que definirán las distintas propiedades del elemento que se está agregando (además del número de secuencia antes mencionado). Dependiendo del elemento en cuestión, los atributos serán los siguientes:
Elemento | Propiedad | Tipo de dato | Descripción | Requerido | Valor ante ausencia |
Ítem | unitprice | Numérico positivo | Precio unitario del artículo en cuestión. | Si | |
xprice | Numérico positivo | Precio extendido del artículo en cuestión. Es igual a la cantidad por el precio unitario. | Si | ||
qty | Entero positivo | Cantidad de artículos en la línea. | Si | ||
magnitude | Numérico positivo | Si el artículo es mensurable por otro unidad que no sea la cantidad, deberá ser expresad en esta propiedad. | No | 0 | |
code | Alfanumérico | Código propio del artículo. | No | "-" | |
Productcode | Alfanumérico | Código del Producto | No | ||
Barcode | Alfanumérico | Código de Barras del Producto | No | ||
brand | Alfanumérico | Marca del artículo. | No | "-" | |
supplier | Alfanumérico | Proveedor al que pertenece el artículo. | No | "-" | |
discountable | Alfanumérico | Si el artículo es puede recibir descuentos o no. | No | "-" | |
level1 | Alfanumérico | Nivel 1 de categorización del artículo. Anteriormente este nivel se conocía con el nombre de Departamento. | No | "-" | |
level2 | Alfanumérico | Nivel 2 de categorización del artículo. Anteriormente este nivel se conocía como la Familia del artículo. | No | "-" | |
level3 | Alfanumérico | Nivel 3 de categorización del artículo. Anteriormente este nivel se conocía como la Categoría del artículo. | No | "-" | |
level4 | Alfanumérico | Nivel 4 de categorización del artículo. Anteriormente este nivel se conocía como la subcategoría del artículo. | No | "-" | |
discontinuous | booleano | Determina si el producto es un producto discontinuo | No | false | |
lowTurnover | booleano | Determina si el producto es un producto de baja rotación | No | false | |
keyProduct | booleano | Determina si el producto es un producto estrella | No | false | |
applyCatalogRedeem | booleano | Determina si el producto participa en el Canje de Puntos por Catálogo | No | false | |
taxes | Numérico positivo | Valor de los impuestos discriminados respecto al precio unitario. (Ver atributo valueWithTaxes) | No | 0 | |
qty2 | Entero positivo | (Versión > 7.EP2.1) Cantidad del producto a superar para otorgar el precio 2 (price2). Solo para Promociones de Nuevo Precio que indican usar monto externo. | No | 0 | |
price2 | Numérico positivo | (Versión > 7.EP2.1) Precio una vez superada la cantidad 2 (qty2). Solo para Promociones de Nuevo Precio que indican usar monto externo. | No | 0 | |
qty3 | Entero positivo | (Versión > 7.EP2.1) Cantidad del producto a superar para otorgar el precio 3 (price3). Solo para Promociones de Nuevo Precio que indican usar monto externo. | No | 0 | |
price3 | Numérico positivo | (Versión > 7.EP2.1) Precio una vez superada la cantidad 3 (qty3). Solo para Promociones de Nuevo Precio que indican usar monto externo. | No | 0 | |
redeemOption | Alfanumérico | (Versión > 7.EP2.1) Beneficio "Canje con opciones" - informara las opciones entre las que puede elegir el cliente para acceder a un determinado beneficio canjeando una determinada cantidad de puntos (del cliente y/o elemento de fidelidad) Mas detalle en Apéndice I - Canje con opciones | No | ||
Coupon | amount | Numérico positivo | Se utiliza para indicar el valor monetario del cupón. Si no tiene no se utiliza. | No | 0 |
type | Alfanumérico | Tipo de cupón. | No | "-" | |
qty | Entero positivo | Cantidad | No | 1 | |
id | Alfanumérico | Identificador del cupón. | No | "-" | |
LoyaltyCard | type | Alfanumérico | Tipo de elemento de fidelidad loyalty | No | "-" |
id | Alfanumérico | Idenficiador del elemento de fidelidad loyalty | Si | "-" | |
amount | Numérico positivo | Saldo del elemento de fidelidad loyalty | No | 0 | |
chargeAmount | Numérico positivo | Saldo a acreditar a un elemento de fidelidad loyalty | No | 0 | |
consumeAmount | Numérico positivo | Saldo a debitar a un elemento de fidelidad loyalty | No | 0 | |
status | Alfanumérico | ENABLED o DISABLED para habilitar o deshabilitar un elemento de fidelidad (solo valido en status LoyatyActivation) | No | "ENABLED" | |
nextExpDate | Numérico | Fecha de la próxima expiración de puntos en format YYYYmmdd. Solo es informado en elementos de fidelidad que posean vencimiento de carga definido. | No | "-" | |
nextExpValue | Numérico | Cantidad de puntos que vencerán en el próximo vencimiento (nextExpDate) y se informa solo si el elemento de fidelidad posee vencimiento de carga definido. | No | "-" | |
reason | Alfanumérico | Código del motivo por el cual se está realizando el chargeAmount o consumeAmount pertinente. Este código corresponde a los valores de motivos definidos en la consola de Promo | No | "-" | |
cvv | Alfanumérico | Corresponde al código de seguridad o cvv asociado al elemento de fidelidad. | No | "-" | |
validFrom | Alfanumérico | Fecha de inicio de vigencia . Formato "YYYY-MM-DD" (Año-Mes-Dia) .Ejemplo"2021-07-16" | No | "-" | |
validTo | Alfanumérico | Fecha de fin de vigencia . Formato "YYYY-MM-DD" (Año-Mes-Dia) .Ejemplo"2021-07-16" | No | "-" | |
Customer | type | Alfanumérico | Tipo de cliente. | No | "-" |
id | Alfanumérico | Identifica al cliente a través del Código. | No | "-" | |
remainingAmount | Numérico positivo | Propiedad que se puede utilizar para indicar el saldo a favor o en contra del cliente en cuestión. (compatibilidad con PROMO 4 y versiones anteriores) | No | 0 | |
points | Entero positivo | Saldo que posee el cliente. (compatibilidad con PROMO 4 y versiones anteriores) | No | 0 | |
Alfanumérico | Atributo incluido para la consulta de clientes | No | "" | ||
name | Alfanumérico | Atributo incluido para la consulta de clientes | No | "" | |
lastName | Alfanumérico | Atributo incluido para la consulta de clientes | No | "" | |
Identifier | Numérico positivo | Atributo incluido para la consulta de clientes | No | "" | |
cardNumber | Numérico positivo | Atributo incluido para la consulta de clientes | No | "" | |
creditCampaignCode | Alfanumérico | Código de la Campaña crediticia | No | "" | |
profileCode | Alfanumérico | Código del perfil del cliente | No | "" | |
limitedBenefits | Alfanumérico | Consiste en un listado de Limites asociados a Convenios. El mismo es del tipo: limitedBenefits:"limite1:valor1;limite2:valor2;limite3:valor3.....". Estos valores pueden ser informados desde el Punto de Venta o bien son obtenidos mediante una respuesta a LoyaltyValidation y reinjectados por parte del Puntos de venta como han sido recibidos. | No | "" | |
segment | Alfanumérico | Lista de Códigos de Segmento a los cuales pertenece el cliente, separados por ;. Se listarán tanto los segmentos internos como los externos. | No | "" | |
amount | Numérico positivo | Propiedad que se puede utilizar para indicar el saldo correspondiente a un cliente | No | 0 | |
raffleData | Alfanumérico | Datos para imprimir en cupones informativos, orientado principalmente a sorteos. Ver Manual de Usuario para información sobre cupones Informativos. | No | "-" | |
"Payment Los atributos amount e itemamount son excluyentes y su uso depende de la versión de la promoción codificada que se | type | Alfanumérico | Tipo de medio de pago. | No | "-" |
id | Alfanumérico | Identificador del pago. | No | "-" | |
plan | Alfanumérico | Plan del medio de pago. | No | "-" | |
amount | Numérico positivo | Dinero que se utiliza con ese medio de pago. Dado que el monto del pago (PA) se calcula como PA = PIA (1 - %desc) o PA = PIA * (1+%recargo)* | No | 0 | |
bank | Alfanumérico | Banco relacionado con el medio de pago. | No | "-" | |
itemamount | Numérico positivo | Dinero que representa el monto de ítems que se desea pagar. | No | 0 | |
balance | Booleano | Indica si con este medio de pago se cancela el saldo de la transacción. Si el valor es true, entonces no es necesario enviar el amount o itemaount. | No | false | |
pointsType | Alfanumérico | Identifica el tipo de pago con puntos (ver manual de usuario Final Promo 7 - "Ignorar pago con Puntos" - Ver también beneficio PromotionPaidInPoints) | No | "" | |
installments | Numérico positivo | Indica la cantidad de cuotas asociadas al pago | No | "" | |
prefix | Alfanumérico | Indica el Prefijo asociado al pago | No | "" | |
Alfanumérico | Indica el Bolsillo asociado al pago | No | "" | ||
prefixGroup | Alfanumérico | Indica el grupo de Prefijos asociado al pago | No | "" | |
payCreditCampaign | Alfanumérico | Indica la Campaña Crediticia asociada al pago | No | "" | |
Event | type | Alfanumérico | Tipo de evento. | No | "-" |
id | Alfanumérico | Identificador del evento. | No | "-" | |
value | Alfanumérico | Valor que representa el evento. | No | "-" | |
Benefit | id | Alfanumérico | Identificador del beneficio externo. | Si | |
type | Alfanumérico | Tipo de beneficio externo. | Si | ||
amount | Numérico positivo | Se utiliza para indicar el monto a descontar o el porcentaje de descuento (de acuerdo al benefitType). | Si | ||
benefitType | Alfanumérico | Indica el tipo de beneficio a generar.
| No | "desc" | |
seqItem | Alfanumérico | Número de secuencia de los ítems a los cuales hay que aplicar el descuento. Si no viene el atributo o viene vacío se asume que es para todo el ticket. En caso de tener varios secuencias, las mismas deben venir separados por coma. Si algún alguna secuencia tiene mas de una cantidad, se debe concatenar con un =. Ejemplo: 1=2,2,3=3 (indica que el descuento se aplica a dos elementos de la secuencia uno, uno de la secuencia dos y tres la secuencia 3 | No |
Ejemplo:
A continuación se presenta un ejemplo de un mensaje que agrega a la sesión del Motor de Promociones un ítem y un medio de pago (ambos con secuencia "1"), y elimina un cupón (de secuencia "2"):
<message companyId="sts" store="00001" terminal="010" date-time="2017-12-04 12:30:00:" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="payment" msg-version="2.0" map-version="15"> <item-add seq="1" code="0001" discountable="true" unitPrice="25.0" qty="1.0" productcode= "111000110" barcode="100101" level1="MEN" level2="CASUAL" supplier="" brand="LEVIS" xPrice="25.0" magnitude="1.0" /> <payment-add seq="1" type="CreditCard" amount="" id="000009" planId="10"/> <coupon-void seq="2" /> <loyaltycard-add seq="5" id="3330000000222" type="puntos" /> </message>
Ejemplo en JSON
{
"message": {
"companyId": "sts",
"store": "00001",
"terminal": "010",
"date-time": "2017-12-04 12:30:00:",
"messageId": "0010",
"void-trx": "false",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"status": "payment",
"msg-version": "2.0",
"map-version": "15",
"item-add": [{
"seq": "1",
"code": "0001",
"discountable": "true",
"unitPrice": "25.0",
"qty": "1.0",
"productcode": "111000110",
"barcode": "100101",
"level1": "MEN",
"level2": "CASUAL",
"supplier": "",
"brand": "LEVIS",
"xPrice": "25.0",
"magnitude": "1.0"
}],
"payment-add": [{
"seq": "1",
"type": "CreditCard",
"amount": "",
"id": "000009",
"planId": "10"
}],
"coupon-void": [{"seq": "2"}],
"loyaltycard-add": [{
"seq": "5",
"id": "3330000000222",
"type": "puntos"
}]
}
}
Ejemplo de Codificada de Medio de Pago:
A continuación se presenta un ejemplo de la mensajería enviada y recibida teniendo configurada una Promoción Codificada con Medio de Pago (method of payment: ON_ITEMS_PAID=Calcular promociones sobre ítems pagados) con las siguientes características:
<message companyId="napse" store="Tienda1" terminal="1" date-time="2021-06-28 09:33:00" init-tck="true" messageId="114" void-trx="false" response="true" status="sales" evaluate="true" map-version="19" suggest="true"> <item-add seq="1" qty="1" code="1029" level1="85" magnitude="0" xprice="1000" unitprice="1000"/> <payment-add seq="2" id="1" amount="1000" type="TAR" planId="10" installments="6" itemamount="1000"/> </message>
Request JSON
{
"message": {
"companyId": "napse",
"store": "Tienda1",
"terminal": "1",
"date-time": "2021-06-28 09:33:00",
"init-tck": "true",
"messageId": "114",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"map-version": "19",
"suggest": "true",
"item-add": [{
"seq": "1",
"qty": "1",
"code": "1029",
"level1": "85",
"magnitude": "0",
"xprice": "1000",
"unitprice": "1000"
}],
"payment-add": [{
"seq": "2",
"id": "1",
"amount": "1000",
"type": "TAR",
"planId": "10",
"installments": "6",
"itemamount": "1000"
}]
}
}
<?xml version="1.0" encoding="UTF-8" standalone="no"?><message ack="0" companyId="napse" engine="7.0.10#42" mapversion="19" messageId="114" store="Tienda1" terminal="1"> <optional> <promo id="Promo Codif Medio de Pago Con Intereses" nro="60d9b152e830a5618c9d1cf2"> <benefit TLOGMessage="Promo Codif Medio de Pago Con Intereses" account="" applicationMethod="resume" bank="HSBC" baseAmount="1000.00" benefitType="PaymentPlanBenefit" displayMessage="Promo Codif Medio de Pago Con Intereses" installments="6" installmentsToDisplay="6" limitAmount="6000.00" name="60d9b152e830a5618c9d1cf2" nro="60d9b74ee830a5618c9d1cfa" order="1" paymentAmount="1000.00" percent="10" percenttype="surcharge" planId="a" printerMessage="Promo Codif Medio de Pago Con Intereses" tender="Visa" type="Crédito"> <apply> <item magnitude="0.00" qty="1.00" seq="1" value="0.00" valueWithTaxes="0.00" xprice="1000.00"/> </apply> </benefit> </promo> </optional></message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.0.10#42",
"mapversion": "19",
"messageId": "114",
"store": "Tienda1",
"terminal": "1",
"optional": [{
"promo": [{
"id": "Promo Codif Medio\nde Pago Con Intereses",
"nro": "60d9b152e830a5618c9d1cf2",
"benefit": [{
"TLOGMessage": "Promo Codif\nMedio de Pago Con Intereses",
"account": "",
"applicationMethod": "resume",
"bank": "HSBC",
"baseAmount": "1000.00",
"benefitType": "PaymentPlanBenefit",
"displayMessage": "Promo Codif Medio de Pago Con Intereses",
"installments": "6",
"installmentsToDisplay": "6",
"limitAmount": "6000.00",
"name": "60d9b152e830a5618c9d1cf2",
"nro": "60d9b74ee830a5618c9d1cfa",
"order": "1",
"paymentAmount": "1000.00",
"percent": "10",
"percenttype": "surcharge",
"planId": "a",
"printerMessage": "Promo\nCodif Medio de Pago Con Intereses",
"tender": "Visa",
"type": "Crédito",
"apply": {
"item": [{
"magnitude": "0.00",
"qty": "1.00",
"seq": "1",
"value": "0.00",
"valueWithTaxes": "0.00",
"xprice": "1000.00"
}]
}
}]
}]
}]
}
}
Nota
Tanto en la simulación desde la consola como en la mensajería, deberá de informarse en el pago el atributo “itemamount” con el monto del pago realizado sobre los ítems.
Descuento condicionado a un cupo
El atributo Balance; es como un límite externo que indica el saldo y en base a eso otorgar el beneficio hasta que se consuma el saldo en su totalidad, sin otorgar demás.
Por ejemplo:
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-06 11:16:30" init-tck="true" messageId="1" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="7002"> <item-add seq="1" code="1" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="30:1000" balance2="20000"/> </message>
Decuento condicionado a un cupo - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-06 11:16:30",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "7002",
"item-add": [{
"seq": "1",
"code": "1",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "30:1000",
"balance2": "20000"
}]
}
}
Se debe detectar, en este caso, de que el value del beneficio no debe superar $20.000 que sería el saldo del balance “2”.
El motor debe estar listo para recibir el atributo de balance cómo una lista y poder interpretar el saldo de cada ID, limitar el beneficio a otorgar del saldo informado según el “balance” indicado en el beneficio.
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-06 11:16:30" init-tck="true" messageId="1" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="7002"> <item-add seq="1" code="1" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="30:1000" balance2="20000"/> </message>
Request con Balance - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-06 11:16:30",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "7002",
"item-add": [{
"seq": "1",
"code": "1",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "30:1000",
"balance2": "20000"
}]
}
}
<message ack="0" companyId="napse" engine="7.2.3-SNAPSHOT" mapversion="7002" messageId="1" store="napse" terminal="8"> <optional> <promo code="jmm_x1" id="jmm_x1" nro="62c5a109677f912b04181c2d"> <benefit TLOGMessage="jmm_x1" account="" applicationMethod="resume" balance="30" baseAmount="10000.00" benefitType="PercentageDiscount" discountPercentage="15.00" displayMessage="jmm_x1" name="62c5a109677f912b04181c2d" nro="62c5a07d677f912b04181c18" order="1" printerMessage="jmm_x1" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="1000.00" valueWithTaxes="1000.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> </message>
Response de Benecicio con Balance - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.2.3-SNAPSHOT",
"mapversion": "7002",
"messageId": "1",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "jmm_x1",
"id": "jmm_x1",
"nro": "62c5a109677f912b04181c2d",
"benefit": [{
"TLOGMessage": "jmm_x1",
"account": "",
"applicationMethod": "resume",
"balance": "30",
"baseAmount": "10000.00",
"benefitType": "PercentageDiscount",
"discountPercentage": "15.00",
"displayMessage": "jmm_x1",
"name": "62c5a109677f912b04181c2d",
"nro": "62c5a07d677f912b04181c18",
"order": "1",
"printerMessage": "jmm_x1",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "1000.00",
"valueWithTaxes": "1000.00",
"xprice": "10000.00"
}]
}
}]
}]
}]
}
}
En este ejemplo se ve que se aplica el limite del balance ya que el valor de descuento seria 1500 (value) que es el 15% de 10000, como el beneficio tiene configurado para el balance con código 30 y el customer se envía el tag balances con el código del balance 30 y su saldo de 1000.
Ejemplo de balances:
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:30" init-tck="true" messageId="7" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="5" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="2:100;3:3500"/> </message>
Ejemplo con Balances - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:30",
"init-tck": "true",
"messageId": "7",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "5",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "2:100;3:3500"
}]
}
}
Por compatibilidad se sigue soportando el envío de balance1 y balance2
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:30" init-tck="true" messageId="7" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="5" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balance1="100" balance2="3500"/> </message>
Request con tag balance1 y balance2 - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:30",
"init-tck": "true",
"messageId": "7",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "5",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balance1": "100",
"balance2": "3500"
}]
}
}
El mensaje anterior es similar al siguiente:
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:30" init-tck="true" messageId="7" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="5" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="balance1:100;balance2:3500"/> </message>
Request con tags balances - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:30",
"init-tck": "true",
"messageId": "7",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "5",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "balance1:100;balance2:3500"
}]
}
}
En caso de combinar el tag balances con balance1 y balance2:
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:30" init-tck="true" messageId="7" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="5" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="3:100;4:3500" balance1="100" balance2="300"/> </message>
Request con tag balances - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:30",
"init-tck": "true",
"messageId": "7",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "5",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "3:100;4:3500",
"balance1": "100",
"balance2": "300"
}]
}
}
Este último caso es similar al siguiente :
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:30" init-tck="true" messageId="7" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="5" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="balance1:100;balance2:300;3:100;4:3500"/> </message>
Request con tag balances - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:30",
"init-tck": "true",
"messageId": "7",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "5",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "balance1:100;balance2:300;3:100;4:3500"
}]
}
}
En el siguiente ejemplo solo se considerará balances="balance1:50;balance2:800;3:100;4:3500" ignorando balance1="100" balance2="300":
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:30" init-tck="true" messageId="7" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="5" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="balance1:50;balance2:800;3:100;4:3500" balance1="100" balance2="300"/> </message>
Request con tag balances, balance1 y balance2 sobreescritos - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:30",
"init-tck": "true",
"messageId": "7",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "5",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "balance1:50;balance2:800;3:100;4:3500",
"balance1": "100",
"balance2": "300"
}]
}
}
Consideración del Balance
Cuando el beneficio tiene configurado un balance y no se envía en el request, no se dará el beneficio.
Consideración del balance con saldo 0 o ya consumido por otro beneficio
Cuando el balance informado tenga saldo 0 o exista en la mismo mapa a evaluar promociones que apliquen al mismo balance y el saldo del mismo no alcanza para todos los beneficios solo se dará los beneficios que alcancen.
Ejemplos de beneficios monetarios con balances:
Canje de cupón Calculado:
- Con Balance con saldo
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:23" init-tck="true" messageId="1" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="1" qty="1" magnitud="0" xprice="1000" unitprice="1000"/> <coupon-add seq="1" id="12321321" type="cupcal" amount="1000" /> <customer-add seq="1" type="vip" id="1234" balances="1:2000"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:23",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "1",
"qty": "1",
"magnitud": "0",
"xprice": "1000",
"unitprice": "1000"
}],
"coupon-add": [{
"seq": "1",
"id": "12321321",
"type": "cupcal",
"amount": "1000"
}],
"customer-add": [{
"seq": "1",
"type": "vip",
"id": "1234",
"balances": "1:2000"
}]
}
}
<message ack="0" companyId="napse" engine="2.6" mapversion="5469" messageId="1" store="napse" terminal="8"> <optional> <promo code="balance1cupcal" id="balance1cupcal" nro="62bf19ce8275810d9cc9f643"> <benefit TLOGMessage="balance1" account="" applicationMethod="resume" balance="1" baseAmount="1000.00" benefitType="CalculatedCouponApplicationBenefit" couponId="cupcal" discountAmount="1000.00" displayMessage="balance1" name="62bf19ce8275810d9cc9f643" nro="62bf51168275812a6488efdd" order="1" printerMessage="balance1" prorationMethod="PROPORTIONAL" unit="" usedCoupons="12321321"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="1000.00" valueWithTaxes="1000.00" xprice="1000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "2.6",
"mapversion": "5469",
"messageId": "1",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance1cupcal",
"id": "balance1cupcal",
"nro": "62bf19ce8275810d9cc9f643",
"benefit": [{
"TLOGMessage": "balance1",
"account": "",
"applicationMethod": "resume",
"balance": "1",
"baseAmount": "1000.00",
"benefitType": "CalculatedCouponApplicationBenefit",
"couponId": "cupcal",
"discountAmount": "1000.00",
"displayMessage": "balance1",
"name": "62bf19ce8275810d9cc9f643",
"nro": "62bf51168275812a6488efdd",
"order": "1",
"printerMessage": "balance1",
"prorationMethod": "PROPORTIONAL",
"unit": "",
"usedCoupons": "12321321",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "1000.00",
"valueWithTaxes": "1000.00",
"xprice": "1000.00"
}]
}
}]
}]
}]
}
}
- Con balance con saldo insuficiente
<message companyId="napse"store="napse" terminal="8" date-time="2022-07-01 11:16:24" init-tck="true" messageId="2" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="1" qty="1" magnitud="0" xprice="1000" unitprice="1000"/> <coupon-add seq="1" id="12321321" type="cupcal" amount="1000"/> <customer-add seq="1" balances="1:10" type="vip" id="1234"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:24",
"init-tck": "true",
"messageId": "2",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "1",
"qty": "1",
"magnitud": "0",
"xprice": "1000",
"unitprice": "1000"
}],
"coupon-add": [{
"seq": "1",
"id": "12321321",
"type": "cupcal",
"amount": "1000"
}],
"customer-add": [{
"seq": "1",
"balances": "1:10",
"type": "vip",
"id": "1234"
}]
}
}
<message companyId="napse" ack="0" engine="2.6" mapversion="5469" messageId="2" store="napse" terminal="8"> <optional> <promo code="balance1cupcal" id="balance1cupcal" nro="62bf19ce8275810d9cc9f643"> <benefit TLOGMessage="balance1" account="" applicationMethod="resume" balance="1" baseAmount="1000.00" benefitType="CalculatedCouponApplicationBenefit" couponId="cupcal" discountAmount="10.00" displayMessage="balance1" name="62bf19ce8275810d9cc9f643" nro="62bf51168275812a6488efdd" order="1" printerMessage="balance1" prorationMethod="PROPORTIONAL" unit="" usedCoupons="12321321"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="10.00" valueWithTaxes="10.00" xprice="1000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"companyId": "napse",
"ack": "0",
"engine": "2.6",
"mapversion": "5469",
"messageId": "2",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance1cupcal",
"id": "balance1cupcal",
"nro": "62bf19ce8275810d9cc9f643",
"benefit": [{
"TLOGMessage": "balance1",
"account": "",
"applicationMethod": "resume",
"balance": "1",
"baseAmount": "1000.00",
"benefitType": "CalculatedCouponApplicationBenefit",
"couponId": "cupcal",
"discountAmount": "10.00",
"displayMessage": "balance1",
"name": "62bf19ce8275810d9cc9f643",
"nro": "62bf51168275812a6488efdd",
"order": "1",
"printerMessage": "balance1",
"prorationMethod": "PROPORTIONAL",
"unit": "",
"usedCoupons": "12321321",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "10.00",
"valueWithTaxes": "10.00",
"xprice": "1000.00"
}]
}
}]
}]
}]
}
}
Beneficio Externo:
- Con Balance con saldo
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:25" init-tck="true" messageId="3" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="2" qty="1" magnitud="0" xprice="1000" unitprice="1000"/> <customer-add seq="1" balances="2:1000" type="vip" id="1234"/> <benefit-add seq="1" type="ben" amount="10" benefitType="porc"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:25",
"init-tck": "true",
"messageId": "3",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "2",
"qty": "1",
"magnitud": "0",
"xprice": "1000",
"unitprice": "1000"
}],
"customer-add": [{
"seq": "1",
"balances": "2:1000",
"type": "vip",
"id": "1234"
}],
"benefit-add": [{
"seq": "1",
"type": "ben",
"amount": "10",
"benefitType": "porc"
}]
}
}
<message ack="0" companyId="napse" engine="2.6" mapversion="5469" messageId="3" store="napse" terminal="8"> <optional> <promo code="balance2_benext" id="balance2_benext" nro="62bf1d5a8275810d9cc9f650"> <benefit TLOGMessage="balance2" account="" applicationMethod="resume" balance="2" baseAmount="1000.00" benefitType="ExternalBenefit" discountPercentage="10.00" displayMessage="balance2" id="-" nro="62bf51478275812a6488efe3" order="1" printerMessage="balance2" prorationMethod="PROPORTIONAL" seq="1" type="ben"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="100.00" valueWithTaxes="0.00" xprice="1000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "2.6",
"mapversion": "5469",
"messageId": "3",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance2_benext",
"id": "balance2_benext",
"nro": "62bf1d5a8275810d9cc9f650",
"benefit": [{
"TLOGMessage": "balance2",
"account": "",
"applicationMethod": "resume",
"balance": "2",
"baseAmount": "1000.00",
"benefitType": "ExternalBenefit",
"discountPercentage": "10.00",
"displayMessage": "balance2",
"id": "-",
"nro": "62bf51478275812a6488efe3",
"order": "1",
"printerMessage": "balance2",
"prorationMethod": "PROPORTIONAL",
"seq": "1",
"type": "ben",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "100.00",
"valueWithTaxes": "0.00",
"xprice": "1000.00"
}]
}
}]
}]
}]
}
}
- Con balance con saldo insuficiente
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:27" init-tck="true" messageId="5" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="2" qty="1" magnitud="0" xprice="1000" unitprice="1000"/> <customer-add seq="1" balances="2:90" type="vip" id="1234"/> <benefit-add seq="1" type="ben" amount="10" benefitType="porc"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:27",
"init-tck": "true",
"messageId": "5",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "2",
"qty": "1",
"magnitud": "0",
"xprice": "1000",
"unitprice": "1000"
}],
"customer-add": [{
"seq": "1",
"balances": "2:90",
"type": "vip",
"id": "1234"
}],
"benefit-add": [{
"seq": "1",
"type": "ben",
"amount": "10",
"benefitType": "porc"
}]
}
}
<message companyId="napse" ack="0" engine="2.6" mapversion="5469" messageId="5" store="napse" terminal="8"> <optional> <promo code="balance2_benext" id="balance2_benext" nro="62bf1d5a8275810d9cc9f650"> <benefit TLOGMessage="balance2" account="" applicationMethod="resume" balance="2" baseAmount="1000.00" benefitType="ExternalBenefit" discountPercentage="10.00" displayMessage="balance2" id="-" nro="62bf51478275812a6488efe3" order="1" printerMessage="balance2" prorationMethod="PROPORTIONAL" seq="1" type="ben"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="90.00" valueWithTaxes="0.00" xprice="1000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"companyId": "napse",
"ack": "0",
"engine": "2.6",
"mapversion": "5469",
"messageId": "5",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance2_benext",
"id": "balance2_benext",
"nro": "62bf1d5a8275810d9cc9f650",
"benefit": [{
"TLOGMessage": "balance2",
"account": "",
"applicationMethod": "resume",
"balance": "2",
"baseAmount": "1000.00",
"benefitType": "ExternalBenefit",
"discountPercentage": "10.00",
"displayMessage": "balance2",
"id": "-",
"nro": "62bf51478275812a6488efe3",
"order": "1",
"printerMessage": "balance2",
"prorationMethod": "PROPORTIONAL",
"seq": "1",
"type": "ben",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "90.00",
"valueWithTaxes": "0.00",
"xprice": "1000.00"
}]
}
}]
}]
}]
}
}
Descuento Fijo:
- Con balance con saldo
<message companyId="napse"store="napse" terminal="8" date-time="2022-07-01 11:16:30" init-tck="true" messageId="7" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="5" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="5:10000"/> <loyaltycard-add seq="1" id="123123123" type="tipo" amount="1000"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:30",
"init-tck": "true",
"messageId": "7",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "5",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "5:10000"
}],
"loyaltycard-add": [{
"seq": "1",
"id": "123123123",
"type": "tipo",
"amount": "1000"
}]
}
}
<message ack="0" companyId="napse" engine="2.6" mapversion="5469" messageId="7" store="napse" terminal="8"> <optional> <promo code="balance5DescuentoFijo" id="balance5DescuentoFijo" nro="62bf521c8275812a6488eff8"> <benefit TLOGMessage="balance5" account="" applicationMethod="resume" balance="5" baseAmount="10000.00" benefitType="FixedDiscount" discountAmount="100.00" displayMessage="balance5" name="62bf521c8275812a6488eff8" nro="62bf523e8275812a6488efff" order="1" printerMessage="balance5" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="100.00" valueWithTaxes="100.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "2.6",
"mapversion": "5469",
"messageId": "7",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance5DescuentoFijo",
"id": "balance5DescuentoFijo",
"nro": "62bf521c8275812a6488eff8",
"benefit": [{
"TLOGMessage": "balance5",
"account": "",
"applicationMethod": "resume",
"balance": "5",
"baseAmount": "10000.00",
"benefitType": "FixedDiscount",
"discountAmount": "100.00",
"displayMessage": "balance5",
"name": "62bf521c8275812a6488eff8",
"nro": "62bf523e8275812a6488efff",
"order": "1",
"printerMessage": "balance5",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "100.00",
"valueWithTaxes": "100.00",
"xprice": "10000.00"
}]
}
}]
}]
}]
}
}
- Con balance con saldo insuficiente
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:31" init-tck="true" messageId="8" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="5" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="5:10"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:31",
"init-tck": "true",
"messageId": "8",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "5",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "5:10"
}]
}
}
<message ack="0" companyId="napse" engine="2.6" mapversion="5469" messageId="8" store="napse" terminal="8"> <optional> <promo code="balance5DescuentoFijo" id="balance5DescuentoFijo" nro="62bf521c8275812a6488eff8"> <benefit TLOGMessage="balance5" account="" applicationMethod="resume" balance="5" baseAmount="10000.00" benefitType="FixedDiscount" discountAmount="10.00" displayMessage="balance5" name="62bf521c8275812a6488eff8" nro="62bf523e8275812a6488efff" order="1" printerMessage="balance5" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="10.00" valueWithTaxes="10.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "2.6",
"mapversion": "5469",
"messageId": "8",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance5DescuentoFijo",
"id": "balance5DescuentoFijo",
"nro": "62bf521c8275812a6488eff8",
"benefit": [{
"TLOGMessage": "balance5",
"account": "",
"applicationMethod": "resume",
"balance": "5",
"baseAmount": "10000.00",
"benefitType": "FixedDiscount",
"discountAmount": "10.00",
"displayMessage": "balance5",
"name": "62bf521c8275812a6488eff8",
"nro": "62bf523e8275812a6488efff",
"order": "1",
"printerMessage": "balance5",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "10.00",
"valueWithTaxes": "10.00",
"xprice": "10000.00"
}]
}
}]
}]
}]
}
}
Descuento por Convenio:
- Con balance con saldo
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:32" init-tck="true" messageId="8" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="6" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="6:10000"/> <loyaltycard-add seq="1" id="123123123" type="tipo" amount="1000"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:32",
"init-tck": "true",
"messageId": "8",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "6",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "6:10000"
}],
"loyaltycard-add": [{
"seq": "1",
"id": "123123123",
"type": "tipo",
"amount": "1000"
}]
}
}
<message ack="0" companyId="napse" engine="2.6" mapversion="5469" messageId="8" store="napse" terminal="8"> <optional> <promo code="balance6Convenio" id="balance6Convenio" nro="62bf52708275812a6488f004"> <benefit TLOGMessage="balance6" account="" applicationMethod="resume" balance="6" baseAmount="10000.00" benefitType="ContractPercentageDiscount" discountPercentage="10.00" displayMessage="balance6" name="62bf52708275812a6488f004" nro="62bf528e8275812a6488f00b" order="1" printerMessage="balance6" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="1000.00" valueWithTaxes="1000.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "2.6",
"mapversion": "5469",
"messageId": "8",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance6Convenio",
"id": "balance6Convenio",
"nro": "62bf52708275812a6488f004",
"benefit": [{
"TLOGMessage": "balance6",
"account": "",
"applicationMethod": "resume",
"balance": "6",
"baseAmount": "10000.00",
"benefitType": "ContractPercentageDiscount",
"discountPercentage": "10.00",
"displayMessage": "balance6",
"name": "62bf52708275812a6488f004",
"nro": "62bf528e8275812a6488f00b",
"order": "1",
"printerMessage": "balance6",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "1000.00",
"valueWithTaxes": "1000.00",
"xprice": "10000.00"
}]
}
}]
}]
}]
}
}
- Con balance con saldo insuficiente
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:33" init-tck="true" messageId="9" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="6" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="6:10"/> <loyaltycard-add seq="1" id="123123123" type="tipo" amount="1000"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:33",
"init-tck": "true",
"messageId": "9",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "6",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "6:10"
}[,
"loyaltycard-add": [{
"seq": "1",
"id": "123123123",
"type": "tipo",
"amount": "1000"
}]
}
}
<message ack="0" companyId="napse" engine="2.6" mapversion="5469" messageId="9" store="napse" terminal="8"> <optional> <promo code="balance6Convenio" id="balance6Convenio" nro="62bf52708275812a6488f004"> <benefit TLOGMessage="balance6" account="" applicationMethod="resume" balance="6" baseAmount="10000.00" benefitType="ContractPercentageDiscount" discountPercentage="10.00" displayMessage="balance6" name="62bf52708275812a6488f004" nro="62bf528e8275812a6488f00b" order="1" printerMessage="balance6" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="10.00" valueWithTaxes="10.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "2.6",
"mapversion": "5469",
"messageId": "9",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance6Convenio",
"id": "balance6Convenio",
"nro": "62bf52708275812a6488f004",
"benefit": [{
"TLOGMessage": "balance6",
"account": "",
"applicationMethod": "resume",
"balance": "6",
"baseAmount": "10000.00",
"benefitType": "ContractPercentageDiscount",
"discountPercentage": "10.00",
"displayMessage": "balance6",
"name": "62bf52708275812a6488f004",
"nro": "62bf528e8275812a6488f00b",
"order": "1",
"printerMessage": "balance6",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "10.00",
"valueWithTaxes": "10.00",
"xprice": "10000.00"
}]
}
}]
}]
}]
}
}
Descuento por Porcentaje:
- Con Balance con saldo
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:34" init-tck="true" messageId="10" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="7" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="7:10000"/> <loyaltycard-add seq="1" id="123123123" type="tipo" amount="1000"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:34",
"init-tck": "true",
"messageId": "10",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "7",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "7:10000"
}],
"loyaltycard-add": [{
"seq": "1",
"id": "123123123",
"type": "tipo",
"amount": "1000"
}]
}
}
<message ack="0" companyId="napse"engine="2.6" mapversion="5469" messageId="10" store="napse" terminal="8"> <optional> <promo code="balance7Porcentaje" id="balance7Porcentaje" nro="62bf52b78275812a6488f010"> <benefit TLOGMessage="balance7" account="" applicationMethod="resume" balance="7" baseAmount="10000.00" benefitType="PercentageDiscount" discountPercentage="15.00" displayMessage="balance7" name="62bf52b78275812a6488f010" nro="62bf52d18275812a6488f017" order="1" printerMessage="balance7" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="1500.00" valueWithTaxes="1500.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "2.6",
"mapversion": "5469",
"messageId": "10",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance7Porcentaje",
"id": "balance7Porcentaje",
"nro": "62bf52b78275812a6488f010",
"benefit": [{
"TLOGMessage": "balance7",
"account": "",
"applicationMethod": "resume",
"balance": "7",
"baseAmount": "10000.00",
"benefitType": "PercentageDiscount",
"discountPercentage": "15.00",
"displayMessage": "balance7",
"name": "62bf52b78275812a6488f010",
"nro": "62bf52d18275812a6488f017",
"order": "1",
"printerMessage": "balance7",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "1500.00",
"valueWithTaxes": "1500.00",
"xprice": "10000.00"
}]
}
}]
}]
}]
}
}
- Con Balance con saldo insuficiente
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:35" init-tck="true" messageId="11" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="7" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="7:10"/> <loyaltycard-add seq="1" id="123123123" type="tipo" amount="1000"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:35",
"init-tck": "true",
"messageId": "11",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "7",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "7:10"
}],
"loyaltycard-add": [{
"seq": "1",
"id": "123123123",
"type": "tipo",
"amount": "1000"
}]
}
}
<message ack="0" companyId="napse" engine="2.6" mapversion="5469" messageId="11" store="napse" terminal="8"> <optional> <promo code="balance7Porcentaje" id="balance7Porcentaje" nro="62bf52b78275812a6488f010"> <benefit TLOGMessage="balance7" account="" applicationMethod="resume" balance="7" baseAmount="10000.00" benefitType="PercentageDiscount" discountPercentage="15.00" displayMessage="balance7" name="62bf52b78275812a6488f010" nro="62bf52d18275812a6488f017" order="1" printerMessage="balance7" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="10.00" valueWithTaxes="10.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "2.6",
"mapversion": "5469",
"messageId": "11",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance7Porcentaje",
"id": "balance7Porcentaje",
"nro": "62bf52b78275812a6488f010",
"benefit": [{
"TLOGMessage": "balance7",
"account": "",
"applicationMethod": "resume",
"balance": "7",
"baseAmount": "10000.00",
"benefitType": "PercentageDiscount",
"discountPercentage": "15.00",
"displayMessage": "balance7",
"name": "62bf52b78275812a6488f010",
"nro": "62bf52d18275812a6488f017",
"order": "1",
"printerMessage": "balance7",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "10.00",
"valueWithTaxes": "10.00",
"xprice": "10000.00"
}]
}
}]
}]
}]
}
}
Nuevo Precio
- Con Balance con saldo
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:34" init-tck="true" messageId="12" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="8" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="8:10000"/> <loyaltycard-add seq="1" id="123123123" type="tipo" amount="1000"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:34",
"init-tck": "true",
"messageId": "12",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "8",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "8:10000"
}],
"loyaltycard-add": [{
"seq": "1",
"id": "123123123",
"type": "tipo",
"amount": "1000"
}]
}
}
<message ack="0" companyId="napse" engine="2.6" mapversion="5469" messageId="12" store="napse" terminal="8"> <optional> <promo code="balance8NuevoPrecio" id="balance8NuevoPrecio" nro="62bf52f58275812a6488f01c"> <benefit TLOGMessage="balance8" account="" applicationMethod="resume" balance="8" baseAmount="10000.00" benefitType="NewPrice" displayMessage="balance8" name="62bf52f58275812a6488f01c" newPrice="300.00" nro="62bf53128275812a6488f023" order="1" printerMessage="balance8" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="9700.00" valueWithTaxes="9700.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "2.6",
"mapversion": "5469",
"messageId": "12",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance8NuevoPrecio",
"id": "balance8NuevoPrecio",
"nro": "62bf52f58275812a6488f01c",
"benefit": [{
"TLOGMessage": "balance8",
"account": "",
"applicationMethod": "resume",
"balance": "8",
"baseAmount": "10000.00",
"benefitType": "NewPrice",
"displayMessage": "balance8",
"name": "62bf52f58275812a6488f01c",
"newPrice": "300.00",
"nro": "62bf53128275812a6488f023",
"order": "1",
"printerMessage": "balance8",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "9700.00",
"valueWithTaxes": "9700.00",
"xprice": "10000.00"
}]
}
}]
}]
}]
}
}
- Con Balance con saldo insuficiente
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:35" init-tck="true" messageId="13" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="8" qty="1" magnitud="0" xprice="10000" unitprice="10000" /> <customer-add seq="1" id="1" type="vip" balances="8:10" /> <loyaltycard-add seq="1" id="123123123" type="tipo" amount="1000" /> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:35",
"init-tck": "true",
"messageId": "13",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "8",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "8:10"
}],
"loyaltycard-add": [{
"seq": "1",
"id": "123123123",
"type": "tipo",
"amount": "1000"
}]
}
}
<message ack="0" companyId="napse" engine="2.6" mapversion="5469" messageId="13" store="napse" terminal="8"> <optional> <promo code="balance8NuevoPrecio" id="balance8NuevoPrecio" nro="62bf52f58275812a6488f01c"> <benefit TLOGMessage="balance8" account="" applicationMethod="resume" balance="8" baseAmount="10000.00" benefitType="NewPrice" displayMessage="balance8" name="62bf52f58275812a6488f01c" newPrice="300.00" nro="62bf53128275812a6488f023" order="1" printerMessage="balance8" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="10.00" valueWithTaxes="10.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> </message>
Response -JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "2.6",
"mapversion": "5469",
"messageId": "13",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance8NuevoPrecio",
"id": "balance8NuevoPrecio",
"nro": "62bf52f58275812a6488f01c",
"benefit": [{
"TLOGMessage": "balance8",
"account": "",
"applicationMethod": "resume",
"balance": "8",
"baseAmount": "10000.00",
"benefitType": "NewPrice",
"displayMessage": "balance8",
"name": "62bf52f58275812a6488f01c",
"newPrice": "300.00",
"nro": "62bf53128275812a6488f023",
"order": "1",
"printerMessage": "balance8",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "10.00",
"valueWithTaxes": "10.00",
"xprice": "10000.00"
}]
}
}]
}]
}]
}
}
Canje de Puntos
- Con Balance con saldo
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:36" init-tck="true" messageId="14" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="9" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="9:10000"/> <loyaltycard-add seq="1" id="123123123" type="tipo" amount="1000"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:36",
"init-tck": "true",
"messageId": "14",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "9",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "9:10000"
}],
"loyaltycard-add": [{
"seq": "1",
"id": "123123123",
"type": "tipo",
"amount": "1000"
}]
}
}
<message ack="0" companyId="napse" engine="2.6" mapversion="5469" messageId="14" store="napse" terminal="8"> <optional> <promo code="balance9CanjeDePtos" id="balance9CanjeDePtos" nro="62bf53708275812a6488f028"> <benefit TLOGMessage="balance9" account="" applicationMethod="resume" balance="9" baseAmount="10000.00" benefitType="RedeemPointsBenefit" discountAmount="1000.00" displayMessage="balance9" factor="1" name="62bf53708275812a6488f028" nro="62bf538e8275812a6488f02f" order="1" printerMessage="balance9" prorationMethod="PROPORTIONAL" type="tipo" unit="" usedPoints="1000.0"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="1000.00" valueWithTaxes="1000.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "2.6",
"mapversion": "5469",
"messageId": "14",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance9CanjeDePtos",
"id": "balance9CanjeDePtos",
"nro": "62bf53708275812a6488f028",
"benefit": [{
"TLOGMessage": "balance9",
"account": "",
"applicationMethod": "resume",
"balance": "9",
"baseAmount": "10000.00",
"benefitType": "RedeemPointsBenefit",
"discountAmount": "1000.00",
"displayMessage": "balance9",
"factor": "1",
"name": "62bf53708275812a6488f028",
"nro": "62bf538e8275812a6488f02f",
"order": "1",
"printerMessage": "balance9",
"prorationMethod": "PROPORTIONAL",
"type": "tipo",
"unit": "",
"usedPoints": "1000.0",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "1000.00",
"valueWithTaxes": "1000.00",
"xprice": "10000.00"
}]
}
}]
}]
}]
}
}
- Con Balance con saldo insuficiente
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:37" init-tck="true" messageId="15" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="9" qty="1" magnitud="0" xprice="10000" unitprice="10000"/> <customer-add seq="1" id="1" type="vip" balances="9:10"/> <loyaltycard-add seq="1" id="123123123" type="tipo" amount="1000"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:37",
"init-tck": "true",
"messageId": "15",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "9",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "9:10"
}],
"loyaltycard-add": [{
"seq": "1",
"id": "123123123",
"type": "tipo",
"amount": "1000"
}]
}
}
<message ack="0" companyId="napse" engine="2.6" mapversion="5469" messageId="15" store="napse" terminal="8"> <optional> <promo code="balance9CanjeDePtos" id="balance9CanjeDePtos" nro="62bf53708275812a6488f028"> <benefit TLOGMessage="balance9" account="" applicationMethod="resume" balance="9" baseAmount="10000.00" benefitType="RedeemPointsBenefit" discountAmount="10.00" displayMessage="balance9" factor="1" name="62bf53708275812a6488f028" nro="62bf538e8275812a6488f02f" order="1" printerMessage="balance9" prorationMethod="PROPORTIONAL" type="tipo" unit="" usedPoints="10.0"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="10.00" valueWithTaxes="10.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "2.6",
"mapversion": "5469",
"messageId": "15",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance9CanjeDePtos",
"id": "balance9CanjeDePtos",
"nro": "62bf53708275812a6488f028",
"benefit": [{
"TLOGMessage": "balance9",
"account": "",
"applicationMethod": "resume",
"balance": "9",
"baseAmount": "10000.00",
"benefitType": "RedeemPointsBenefit",
"discountAmount": "10.00",
"displayMessage": "balance9",
"factor": "1",
"name": "62bf53708275812a6488f028",
"nro": "62bf538e8275812a6488f02f",
"order": "1",
"printerMessage": "balance9",
"prorationMethod": "PROPORTIONAL",
"type": "tipo",
"unit": "",
"usedPoints": "10.0",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "10.00",
"valueWithTaxes": "10.00",
"xprice": "10000.00"
}]
}
}]
}]
}]
}
}
Canje con Opciones
- Con Balance con saldo
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:32" init-tck="true" messageId="8" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="3" qty="1" magnitud="0" xprice="10000" unitprice="10000" redeemOption="62bf51a78275812a6488efea_1"/> <customer-add seq="1" id="1" type="vip" balances="3:10000" points="40000" redeemPointsPriceFactor="2"/> <loyaltycard-add seq="1" id="123123123" type="tipo" amount="1000"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:32",
"init-tck": "true",
"messageId": "8",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "3",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000",
"redeemOption": "62bf51a78275812a6488efea_1"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "3:10000",
"points": "40000",
"redeemPointsPriceFactor": "2"
}],
"loyaltycard-add": [{
"seq": "1",
"id": "123123123",
"type": "tipo",
"amount": "1000"
}]
}
}
<message ack="0" companyId="napse" engine="7.2.3-SNAPSHOT" mapversion="5469" messageId="8" store="napse" terminal="8"> <optional> <promo code="balance3CanjeConOpc" id="balance3CanjeConOpc" nro="62bf22208275811c604149c6"> <benefit TLOGMessage="balance3" account="" applicationMethod="resume" balance="3" baseAmount="10000.00" benefitType="RedeemWithOptionsBenefit" displayMessage="balance3" name="62bf22208275811c604149c6" nro="62bf51a78275812a6488efea" order="1" printerMessage="balance3" prorationMethod="PROPORTIONAL" usedPoints="0.00"> <apply> <item benefitTypeOption="percentageDiscount" benefitUnitOption="qty" cardType="tipo" cardUsedPoints="100.00" magnitude="0.000" nominalDiscount="1000.00" percentageDiscount="10.00" priceinPoints="5000.00" qty="1.000" redeemOption="62bf51a78275812a6488efea_1" seq="1" usedPoints="0.00" value="1000.00" valuePoints="0.00" valueWithTaxes="1000.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.2.3-SNAPSHOT",
"mapversion": "5469",
"messageId": "8",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance3CanjeConOpc",
"id": "balance3CanjeConOpc",
"nro": "62bf22208275811c604149c6",
"benefit": [{
"TLOGMessage": "balance3",
"account": "",
"applicationMethod": "resume",
"balance": "3",
"baseAmount": "10000.00",
"benefitType": "RedeemWithOptionsBenefit",
"displayMessage": "balance3",
"name": "62bf22208275811c604149c6",
"nro": "62bf51a78275812a6488efea",
"order": "1",
"printerMessage": "balance3",
"prorationMethod": "PROPORTIONAL",
"usedPoints": "0.00",
"apply": {
"item": [{
"benefitTypeOption": "percentageDiscount",
"benefitUnitOption": "qty",
"cardType": "tipo",
"cardUsedPoints": "100.00",
"magnitude": "0.000",
"nominalDiscount": "1000.00",
"percentageDiscount": "10.00",
"priceinPoints": "5000.00",
"qty": "1.000",
"redeemOption": "62bf51a78275812a6488efea_1",
"seq": "1",
"usedPoints": "0.00",
"value": "1000.00",
"valuePoints": "0.00",
"valueWithTaxes": "1000.00",
"xprice": "10000.00"
}]
}
}]
}]
}]
}
}
- Con Balance con saldo insuficiente
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-01 11:16:32" init-tck="true" messageId="8" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="5469"> <item-add seq="1" code="3" qty="1" magnitud="0" xprice="10000" unitprice="10000" redeemOption="62bf51a78275812a6488efea_1"/> <customer-add seq="1" id="1" type="vip" balances="3:10" points="40000" redeemPointsPriceFactor="2"/> <loyaltycard-add seq="1" id="123123123" type="tipo" amount="1000"/> </message>
Request - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-01 11:16:32",
"init-tck": "true",
"messageId": "8",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "5469",
"item-add": [{
"seq": "1",
"code": "3",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000",
"redeemOption": "62bf51a78275812a6488efea_1"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "3:10",
"points": "40000",
"redeemPointsPriceFactor": "2"
}],
"loyaltycard-add": [{
"seq": "1",
"id": "123123123",
"type": "tipo",
"amount": "1000"
}]
}
}
<message ack="0" companyId="napse" engine="7.2.3-SNAPSHOT" mapversion="5469" messageId="8" store="napse" terminal="8"> <optional> <promo code="balance3CanjeConOpc" id="balance3CanjeConOpc" nro="62bf22208275811c604149c6"> <benefit TLOGMessage="balance3" account="" applicationMethod="resume" balance="3" baseAmount="10000.00" benefitType="RedeemWithOptionsBenefit" displayMessage="balance3" name="62bf22208275811c604149c6" nro="62bf51a78275812a6488efea" order="1" printerMessage="balance3" prorationMethod="PROPORTIONAL" usedPoints="0.00"> <apply> <item benefitTypeOption="percentageDiscount" benefitUnitOption="qty" cardType="tipo" cardUsedPoints="100.00" magnitude="0.000" nominalDiscount="10.00" percentageDiscount="10.00" priceinPoints="5000.00" qty="1.000" redeemOption="62bf51a78275812a6488efea_1" seq="1" usedPoints="0.00" value="10.00" valuePoints="0.00" valueWithTaxes="10.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> </message>
Response - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.2.3-SNAPSHOT",
"mapversion": "5469",
"messageId": "8",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "balance3CanjeConOpc",
"id": "balance3CanjeConOpc",
"nro": "62bf22208275811c604149c6",
"benefit": [{
"TLOGMessage": "balance3",
"account": "",
"applicationMethod": "resume",
"balance": "3",
"baseAmount": "10000.00",
"benefitType": "RedeemWithOptionsBenefit",
"displayMessage": "balance3",
"name": "62bf22208275811c604149c6",
"nro": "62bf51a78275812a6488efea",
"order": "1",
"printerMessage": "balance3",
"prorationMethod": "PROPORTIONAL",
"usedPoints": "0.00",
"apply": {
"item": [{
"benefitTypeOption": "percentageDiscount",
"benefitUnitOption": "qty",
"cardType": "tipo",
"cardUsedPoints": "100.00",
"magnitude": "0.000",
"nominalDiscount": "10.00",
"percentageDiscount": "10.00",
"priceinPoints": "5000.00",
"qty": "1.000",
"redeemOption": "62bf51a78275812a6488efea_1",
"seq": "1",
"usedPoints": "0.00",
"value": "10.00",
"valuePoints": "0.00",
"valueWithTaxes": "10.00",
"xprice": "10000.00"
}]
}
}]
}]
}]
}
}
Consideración canje con opciones
El canje con opciones se aplicará el recorte en el descuento (value) pero no alterará el consumo de los puntos.
Canje de puntos por catálogo
Primero se debe cargar el catálogo
{ "companyId": "napse", "catalog": "CatalogRedeemBenefit", "params": [], "items": [ { "store": "1", "code": "10", "points": "10.5", "discountValue":"15" , "discountType": "perc", "operation": "I" }, { "store": "1", "code": "20", "points": "20.5", "discountValue":"20" , "discountType": "fix", "operation": "I" }, { "store": "-", "code": "30", "points": "50", "discountValue":"25" , "discountType": "nprice", "operation": "I" } ] }
También se debe haber distribuido el mapa con la promoción que contenga el beneficio.
Luego enviar el status catalogRedeemValidation con init-tck en true para la tienda (store) y para el código del ítem definido en el catálogo (code).
<message companyId="napse" store="napse" terminal="1" date-time="2022-07-06 11:17:30" messageId="5" void-trx="false" suggest="true" response="true" init-tck="true" evaluate="true" msg-version="2.4" status="catalogRedeemValidation"> <item-add seq="1" code="10" qty="1" unitprice="1000" xprice="1000" applyCatalogRedeem="true" /> </message>
Request status catalogRedeemValidation - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "1",
"date-time": "2022-07-06 11:17:30",
"messageId": "5",
"void-trx": "false",
"suggest": "true",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"msg-version": "2.4",
"status": "catalogRedeemValidation",
"item-add": [{
"seq": "1",
"code": "10",
"qty": "1",
"unitprice": "1000",
"xprice": "1000",
"applyCatalogRedeem": "true"
}]
}
}
<message ack="0" companyId="napse" engine="7.2.3-SNAPSHOT" mapversion="0" messageId="5" store="napse" terminal="1" transaction="napse_1_1_20220706111730"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers/> <redeemTable> <redeemItem code="10" discountType="perc" discountValue="15.00" points="10.50"/> </redeemTable> </loyalty> </message>
Response status catalogRedeemValidation - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.2.3-SNAPSHOT",
"mapversion": "0",
"messageId": "5",
"store": "napse",
"terminal": "1",
"transaction": "napse_1_1_20220706111730",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {
"redeemItem": [{
"code": "10",
"discountType": "perc",
"discountValue": "15.00",
"points": "10.50"
}]
}
}
}
}
Una vez enviado el catalogRedeemValidation se deberá enviar el request con init-tck=false para evaluar la promoción.
<message companyId="napse" store="napse" terminal="1" date-time="2022-07-06 11:17:30" init-tck="false" messageId="1" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="7004"> <item-add seq="1" code="10" qty="1" magnitud="0" xprice="10000" unitprice="10000" /> <customer-add seq="1" id="1" type="vip" balances="10:1000" balance2="20000" /> <loyaltycard-add seq="1" type="tipo" id="1111000000000000" amount="10000" /> </message>
Request catalogRedeemValidation con balance - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "1",
"date-time": "2022-07-06 11:17:30",
"init-tck": "false",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "7004",
"item-add": [{
"seq": "1",
"code": "10",
"qty": "1",
"magnitud": "0",
"xprice": "10000",
"unitprice": "10000"
}],
"customer-add": [{
"seq": "1",
"id": "1",
"type": "vip",
"balances": "10:1000",
"balance2": "20000"
}],
"loyaltycard-add": [{
"seq": "1",
"type": "tipo",
"id": "1111000000000000",
"amount": "10000"
}]
}
}
<message ack="0" companyId="napse" engine="7.2.3-SNAPSHOT" mapversion="7004" messageId="1" store="napse" terminal="1"> <optional> <promo code="canjePtosCatalogo" id="canjePtosCatalogo" nro="62c5b86c677f912b04181c4f"> <benefit TLOGMessage="canjePtosCatalogo" account="" applicationMethod="resume" balance="10" baseAmount="10000.00" benefitType="CatalogRedeemBenefit" discountAmount="1000.00" displayMessage="canjePtosCatalogo" name="62c5b86c677f912b04181c4f" nro="62c5cf8f677f912b04181c73" order="1" printerMessage="canjePtosCatalogo" prorationMethod="PROPORTIONAL" type="tipo" unit="" usedPoints="10.50"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="1000.00" valueWithTaxes="1000.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> </message>
Response catalogRedeemValidation con balance - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.2.3-SNAPSHOT",
"mapversion": "7004",
"messageId": "1",
"store": "napse",
"terminal": "1",
"optional": [{
"promo": [{
"code": "canjePtosCatalogo",
"id": "canjePtosCatalogo",
"nro": "62c5b86c677f912b04181c4f",
"benefit": [{
"TLOGMessage": "canjePtosCatalogo",
"account": "",
"applicationMethod": "resume",
"balance": "10",
"baseAmount": "10000.00",
"benefitType": "CatalogRedeemBenefit",
"discountAmount": "1000.00",
"displayMessage": "canjePtosCatalogo",
"name": "62c5b86c677f912b04181c4f",
"nro": "62c5cf8f677f912b04181c73",
"order": "1",
"printerMessage": "canjePtosCatalogo",
"prorationMethod": "PROPORTIONAL",
"type": "tipo",
"unit": "",
"usedPoints": "10.50",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "1000.00",
"valueWithTaxes": "1000.00",
"xprice": "10000.00"
}]
}
}]
}]
}]
}
}
Ejemplo de convivencia entre límites y balance
Consideración de límites y balances
Siempre aplicará el recorte por límite primero y luego aplicará el recorte por balance, es decir si el límite es menor al beneficio dado recortara el mismo, mas allá de que el balance sea suficiente, si el límite es superior al descuento pero el balance es menor a este último, se aplicará el recorte del balance.
Se configura una promoción que tiene como límite 1.000 por cantidad de dinero y se define un balance balance1 en el mismo beneficio.
En este ejemplo se realizaron varias transacciones hasta que al límite solo le quedan 250 por consumir.
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-14 11:16:32" init-tck="false" messageId="5" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="1"> <item-add seq="1" code="321" qty="4" magnitud="0" xprice="400" unitprice="100"/> <item-add seq="2" code="123" qty="4" magnitud="0" xprice="200" unitprice="200"/> <item-add seq="2" code="1234" qty="4" magnitud="0" xprice="4000" unitprice="4000"/> <customer-add seq="1" id="cod1" type="vip" balances="balance1:1000" /> </message>
Request con límites y balances suficientes - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-14 11:16:32",
"init-tck": "false",
"messageId": "5",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "1",
"item-add": [
{
"seq": "1",
"code": "321",
"qty": "4",
"magnitud": "0",
"xprice": "400",
"unitprice": "100"
},
{
"seq": "2",
"code": "123",
"qty": "4",
"magnitud": "0",
"xprice": "200",
"unitprice": "200"
},
{
"seq": "2",
"code": "1234",
"qty": "4",
"magnitud": "0",
"xprice": "4000",
"unitprice": "4000"
}
],
"customer-add": [{
"seq": "1",
"id": "cod1",
"type": "vip",
"balances": "balance1:1000"
}]
}
}
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.2.3-SNAPSHOT" mapversion="1" messageId="5" store="napse" terminal="8"> <optional> <promo code="test" id="test" nro="62cf2c296ef35a0b84c18538"> <benefit TLOGMessage="test" account="" applicationMethod="resume" balance="balance1" baseAmount="4400.00" benefitType="PercentageDiscount" discountPercentage="15.00" displayMessage="test" hasLimit="true" limitApplied="true" name="62cf2c296ef35a0b84c18538" nro="62d0285a6ef35a0aac785743" order="1" printerMessage="test" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="4.000" seq="1" value="60.00" valueWithTaxes="60.00" xprice="400.00"/> <item magnitude="0.000" qty="4.000" seq="2" value="190.00" valueWithTaxes="190.00" xprice="4000.00"/> </apply> </benefit> </promo> </optional> </message>
Response con límites y balances suficiente - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.2.3-SNAPSHOT",
"mapversion": "1",
"messageId": "5",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "test",
"id": "test",
"nro": "62cf2c296ef35a0b84c18538",
"benefit": [{
"TLOGMessage": "test",
"account": "",
"applicationMethod": "resume",
"balance": "balance1",
"baseAmount": "4400.00",
"benefitType": "PercentageDiscount",
"discountPercentage": "15.00",
"displayMessage": "test",
"hasLimit": "true",
"limitApplied": "true",
"name": "62cf2c296ef35a0b84c18538",
"nro": "62d0285a6ef35a0aac785743",
"order": "1",
"printerMessage": "test",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [
{
"magnitude": "0.000",
"qty": "4.000",
"seq": "1",
"value": "60.00",
"valueWithTaxes": "60.00",
"xprice": "400.00"
},
{
"magnitude": "0.000",
"qty": "4.000",
"seq": "2",
"value": "190.00",
"valueWithTaxes": "190.00",
"xprice": "4000.00"
}
]
}
}]
}]
}]
}
}
En esta última respuesta se ve como se está aplicando el recorte por el límite ya que otorga hasta 250 de descuento.
<message companyId="napse" store="napse" terminal="8" date-time="2022-07-14 11:16:33" init-tck="false" messageId="5" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="false" map-version="1"> <item-add seq="1" code="321" qty="4" magnitud="0" xprice="400" unitprice="100"/> <item-add seq="2" code="123" qty="4" magnitud="0" xprice="200" unitprice="200"/> <item-add seq="3" code="1234" qty="4" magnitud="0" xprice="4000" unitprice="4000"/> <customer-add seq="1" id="cod1" type="vip" balances="balance1:10" /> </message>
Request con límites y balances Insuficientes - JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "8",
"date-time": "2022-07-14 11:16:33",
"init-tck": "false",
"messageId": "5",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "false",
"map-version": "1",
"item-add": [
{
"seq": "1",
"code": "321",
"qty": "4",
"magnitud": "0",
"xprice": "400",
"unitprice": "100"
},
{
"seq": "2",
"code": "123",
"qty": "4",
"magnitud": "0",
"xprice": "200",
"unitprice": "200"
},
{
"seq": "3",
"code": "1234",
"qty": "4",
"magnitud": "0",
"xprice": "4000",
"unitprice": "4000"
}
],
"customer-add": [{
"seq": "1",
"id": "cod1",
"type": "vip",
"balances": "balance1:10"
}]
}
}
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.2.3-SNAPSHOT" mapversion="1" messageId="5" store="napse" terminal="8"> <optional> <promo code="test" id="test" nro="62cf2c296ef35a0b84c18538"> <benefit TLOGMessage="test" account="" applicationMethod="resume" balance="balance1" baseAmount="4400.00" benefitType="PercentageDiscount" discountPercentage="15.00" displayMessage="test" hasLimit="true" limitApplied="true" name="62cf2c296ef35a0b84c18538" nro="62d0285a6ef35a0aac785743" order="1" printerMessage="test" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="4.000" seq="1" value="60.00" valueWithTaxes="60.00" xprice="400.00"/> <item magnitude="0.000" qty="4.000" seq="2" value="40.00" valueWithTaxes="40.00" xprice="4000.00"/> </apply> </benefit> </promo> </optional> </message>
Response con límites y balances Insuficiente - JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.2.3-SNAPSHOT",
"mapversion": "1",
"messageId": "5",
"store": "napse",
"terminal": "8",
"optional": [{
"promo": [{
"code": "test",
"id": "test",
"nro": "62cf2c296ef35a0b84c18538",
"benefit": [{
"TLOGMessage": "test",
"account": "",
"applicationMethod": "resume",
"balance": "balance1",
"baseAmount": "4400.00",
"benefitType": "PercentageDiscount",
"discountPercentage": "15.00",
"displayMessage": "test",
"hasLimit": "true",
"limitApplied": "true",
"name": "62cf2c296ef35a0b84c18538",
"nro": "62d0285a6ef35a0aac785743",
"order": "1",
"printerMessage": "test",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [
{
"magnitude": "0.000",
"qty": "4.000",
"seq": "1",
"value": "60.00",
"valueWithTaxes": "60.00",
"xprice": "400.00"
},
{
"magnitude": "0.000",
"qty": "4.000",
"seq": "2",
"value": "40.00",
"valueWithTaxes": "40.00",
"xprice": "4000.00"
}
]
}
}]
}]
}]
}
}
En esta última respuesta se ve como se está aplicando el recorte por el límite y también el del balance ya que el balance1 es de 100 y el descuento es de 100.
Engine Response
En esta sección se describirá la estructura e interpretación del mensaje de respuesta que entregará el Motor de Promociones.
Como se mencionó con anterioridad, al igual que el mensaje de solicitud, el mensaje de respuesta que ofrece el Motor de Promociones tendrá un formato XML o JSON y constará de un encabezado y un cuerpo. En el encabezado contendrá información relativa a la terminal a la que se está respondiendo, errores que hayan podido suceder y versión del Motor.
En el cuerpo del mensaje se encontrarán las promociones que deberán aplicarse o sugerirse, los artículos a beneficiar, etc. En caso que no existan promociones a aplicar o sugerir o que no se haya solicitado la evaluación o sugerencia, el mensaje de respuesta constará sólo del encabezado.
Encabezado
Al igual que en el mensaje de solicitud el elemento raíz de la respuesta será la etiqueta <message>, siendo esta también lo que se denominará encabezado de la respuesta. Contendrá atributos que indican la tienda y terminal a la que va dirigido, identificación del mensaje, versión del mapa y del Motor con el que se realizó la evaluación, y código de retorno (acknowledge); siendo todos ellos enviados con obligatoriedad:
Propiedad | Tipo de dato | Descripción |
mapversion | Alfanumérico | Versión del mapa utilizado para la evaluación de las promociones. |
companyId | Alfanumérico | El mismo que se envió en el en el mensaje de solicitud. |
store | Alfanumérico | El mismo que se envió en el en el mensaje de solicitud. |
terminal | Entero | El mismo que se envió en el en el mensaje de solicitud. |
messageId | Entero | El mismo que se envió en el en el mensaje de solicitud. |
engine | Alfanumérico | Versión del Motor de promociones que realizó la evaluación. |
ack | entero | Código de retorno (ver apartado siguiente). |
transaction | Alfanumérico | Código que identifica la transacción en PROMO central (solo se informa con la respuesta a un status de Loyalty) |
Valores del atributo "ack"
El atributo ack Del inglés acknowledge. es un atributo dentro del encabezado del mensaje de respuesta que indica la existencia o no de errores en la recepción y/o procesamiento del mensaje de solicitud. Dependiendo del tipo de error o si el mensaje fue recibido correctamente, este atributo tendrá un valor particular:
Valor de ack | Descripción | Acción recomendada |
0 | No existieron errores. | Utilizar la respuesta. |
1 | Error de comunicación o el mensaje es ilegible. | Reenviar el mensaje y si el error persiste re validar su formato. |
2 | La sesión no fue inicializada o no existe dicha sesión. | Iniciar sesión como se indica en "Manejo de sesiones". |
3 | Error de validación en el mensaje. | Revalidar el formato del mensaje. También puede consultarse el archivo de log del Motor establecer con mayor exactitud cuál fue el error. |
2001 | Error de evaluación. | Comunicarse con el administrador del Motor de Promociones para que, por medio del archivo de log, se establezca cuál fue el error. |
2002 | No existe un mapa válido para el cálculo del ticket o mensaje recibido. | Utilizar un mapa previo existente o no aplicar promociones. |
2003 | La sesión se encuentra en uso. | Esperar unos 3 segundos aproximadamente y reintentar el envío. |
2004 | Error general de instanciamiento de la sesión. | Comunicarse con el administrador del Motor de Promociones para monitorear el equipo donde esté en funcionamiento el Motor. |
2005 | Time out de la sesión. La sesión expiró. | Si durante la evaluación de la sesión, la misma termina por time out, se envía un mensaje con ack 2005. Esperar y reintentar el envío. |
4001 | El motor se encuentra en proceso de inicialización. | Esperar porque el motor está arrancando y cargando la información. |
8296 | Existen errores en la validación | Este error se da con Status=loyaltyvalidationex y FinishEx, debera analizarse el archivo de log a fin de establecer cual fue el error. Este error de validacion sera informado dentro del tag </errors> en el cuerpo de la respuesta con el ACK="8296". |
8297 | Se indica cuerpo del message es vacío. | Este error se da con Status=LoyaltyValidation, LoyaltyActivation y LoyaltyTransfer, y ocurre cuando el tag message no contienen ningún elemento de fidelidad. |
8298 | Si solicita recuperar la transacción original pero no envía cual es. | Revisar la conformación del mensaje que se envía del pos a PROMO Central a fin de chequear la existencia del atributo originalTransaction. |
8299 | Error genérico en el envío a PROMO central. | Comunicarse con el administrador de PROMO para monitorear el equipo donde esté en funcionamiento la consola de PROMO. |
A continuación se detalla una serie de errores 9xxx los cuales aplican a Errores producidos en el procesamiento de la Consola de PROMO Central:
1 | Valor de ack | Descripción | Acción recomendada |
2 | 9000 | El mensaje no posee un ticket asociado. | Reenviar el mensaje y si el error persiste re validar su formato. Verificar la secuencia que mensajes que se está enviando. |
3 | 9001 | Existe una transacción pendiente. Se ha recibido una nueva transacción para ser procesada pero existe una anterior que se encuentra pendiente. | Se debe enviar un mensaje con status=commit/rollback para finalizar la transacción anterior. |
4 | 9002 | No existe transacción pendiente. Se ha recibido un mensaje con status=commit o rollback pero no existía una transacción previa pendiente. | Revisar la mensajería que se está enviando al motor, mayormente en su secuencia lógica. |
5 | 9003 | Se ha solicitado la información de una transacción previa pero no se ha informado el identificador de la misma. | Verificar que la propiedad originalTransaction tenga un valor y sea válido. |
6 | 9004 | Se ha solicitado la información de una transacción previa pero la transacción no existe. | Verificar el identificador de la transacción original que se está informando. |
7 | 9005 | Indica que la Consola está en modo Offline | En algunos casos como loyaltyTransfer, si la consola está en modo Offline, esta operación no se puede realizar. Contactar al administrador de PROMO para que chequee el equipo donde se encuentra corriendo la consola de PROMO. |
8 | 9006 | Job de Finalización de Transacciones | Contactar al administrador de la aplicación y revisar las configuraciones de la consola para restablecer el servicio. |
9 | 9007 | No se indica "CompanyId" en el header del mensaje. | Verificar los datos enviados |
10 | 9008 | Se obtiene este valor cuando se detecta una devolución parcial hecha previamente para la transacción que se trata de hacer la devolución total sin escaneo de items. | Verificar que no existan este tipo de transacciones pendientes. |
11 | 9101 | No se ha encontrado el Cupón | Verificar los datos solicitados |
12 | 9102 | Cupón Consumido | Verificar que el cupón no haya sido utilizado |
13 | 9103 | Cupón Inactivo | Verificar que el cupón solicitado se encuentre activo. |
14 | 9104 | No se ha encontrado el tipo de cupón | Verificar valor informado en el mensaje. |
15 | 9105 | El Cupón ha expirado. | La fecha de vencimiento del cupón se ha alcanzado, con lo cual verificar dicha situación. |
16 | 9106 | Se ha alcanzado el máximo número de usos | Verificar dicha situación |
17 | 9107 | El cupón es nominado y no se ha informado un cliente o bien el cliente informado no se corresponde con el cliente asociado al cupón | Verificar dicha situación |
18 | 9108 | El tipo de cupón no está activo | Verificar el tipo de cupón |
19 | 9109 | El monto enviado no corresponde al monto del cupón | Verificar monto del cupón |
20 | 9110 | Cupón no usado | El cupón ingresado a la transacción no ha participado de ninguna promoción. |
21 | 9111 | Cupón utilizado Parcialmente | Indica que el cupón no adminte uso parcial pero se está intentando usar parcialmente. En este caso si un commit es enviado confirmando la transaccion el cupón será consumido (Detección de Fraudes). |
22 | 9114 | Barcode duplicado | Ya existe un cupón con el mismo barcode. |
23 | 9201 | No se encontró el encabezado de la transacción. | Normalmente debido a un error interno, consultar con el administrador del sistema. |
24 | 9500 | No se encontró el elemento de fidelidad loyalty | Verificar los datos solicitados |
25 | 9501 | Elemento de fidelidad inhabilitada | Verificar los datos solicitados. Para algunas acciones, solo se puede procesar Elementos de fidelidad habilitadas |
26 | 9502 | Elemento de fidelidad cancelada | Verificar los datos solicitados. No se puede interactuar con elementos de fidelidad canceladas |
27 | 9503 | No se encontró el Tipo de elemento de fidelidad loyalty | Verificar los datos solicitados |
28 | 9504 | Tipo de elemento de fidelidad no activa | Verificar los datos solicitados. No se puede interactuar con tipos de elementos de fidelidad inactivos |
29 | 9505 | Tipo de fidelidad no recargable | Verificar los datos solicitados. Para opciones de Carga o Recarga, el tipo de elemento de fidelidad debe ser recargable |
30 | 9506 | El elemento de fidelidad ya tiene un cliente asociado | Verificar que el elemento de fidelidad en la activación el customer enviado. |
31 | 9507 | El estado enviado del elemento de fidelidad no existe. | Verificar que se haya enviado un estado del elemento de fidelidad, en la activación, valido (ENABLED, DISABLED) – En Mayúscula – |
32 | 9508 | El elemento de fidelidad no aplica al beneficio | Verificar que el tipo de elemento de fidelidad sea recargable o que el elemento de fidelidad este habilitada. Otro error puede ser que el tipo de elemento de fidelidad con el que se armó el beneficio, este inactivo o no exista en la transacción. |
33 | 9509 | El elemento de fidelidad requiere un cliente | Verificar si el tipo de elemento de fidelidad es requerido, en la transacción debe viajar al menos un cliente. |
34 | 9510 | Elemento de fidelidad no autorizado | Existen varias situaciones en las que se puede obtener este codigo de error:
|
35 | 9511 | Amount invalido | Cuando se intenta descontar un amount que es mayor al total del amount del elemento de fidelidad, este mensaje aparecerá. Verificar que el amount sea menor al total. |
36 | 9512 | Se requiere al menos dos elementos de fidelidad | Este mensaje se utiliza para las transferencias. Se requiere que haya dos tarjetas en el mensaje. La de origen en la Seq="1" y la de destino en la Seq="2" |
37 | 9513 | El elemento de fidelidad no admite transferencia. | Verificar que el elemento de fidelidad origen admita Transferencia. Ya sea parcial o total. |
38 | 9514 | El elemento de fidelidad destino esta activo | Verificar que el elemento de fidelidad destino esta inactiva para realizar una transferencia total. |
39 | 9515 | Los tipos de elementos de fidelidad no son iguales | Verificar que los tipos de elemento de fidelidad sean iguales, es decir, el mismo. |
40 | 9516 | El saldo ingresado es mayor al tope de saldo | Verificar que el valor ingresado para la carga de un elemento de fidelidad, no sea mayor al Tope de saldo del tipo de elemento de fidelidad. |
41 | 9517 | El tipo de elemento de fidelidad no admite asignación de clientes | Este error es especifico del servicio de próximo número del elemento de fidelidad cuando el tipo de elemento de fidelidad no es nominado. |
42 | 9518 | No se ha especificado el parámetro companyId | Este error es especifico del servicio de próximo número cuando no se informa el identificador de la empresa que realiza el pedido. |
43 | 9519 | CompanyId inválido | No se ha podido encontrar el companyId especificado. |
44 | 9520 | Operación Inválida | La operación solicitada no corresponde a una operación válida |
45 | 9603 | Cliente inexistente | Verificar datos de cliente ingresado en la transacción |
46 | 9610 | identificador de cliente vacío | Verificar datos de cliente ingresado en la transacción |
47 | 9611 | Nombre de cliente vacío | Verificar datos de cliente ingresado en la transacción |
48 | 9612 | Apellido de cliente vacío | Verificar datos de cliente ingresado en la transacción |
49 | 9613 | ID de cliente Vacío | Verificar datos de cliente ingresado en la transacción |
50 | 9614 | No se recibieron parámetros del cliente | Verificar datos de cliente ingresado en la transacción |
51 | 9620 | Cliente ya existente | Verificar datos de cliente ingresado en la transacción |
52 | 9629 | Cliente inactivo | Verificar datos de cliente ingresado en la transacción |
53 | 9901 | Error de Cupón inesperado. | Todo error relacionado al procesamiento de cupones que no se encuentre tipificado en los códigos anteriores. Consultar al administrador del sistema. |
54 | 9999 | Error inesperado | Todo error en el procesamiento de PROMO Central que no se encuentre tipificado en los casos anteriores. |
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards/> <coupons/> <errors/> </loyalty> </message>
Ejemplo de Respuesta correcta JSON pero sin elementos informados
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170515152511",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {}
}
}
}
Cuerpo
El cuerpo del mensaje de respuesta otorgado por el Motor de Promociones informa las promociones que deben ser aplicadas al ticket enviado hasta el momento y las promociones que deben ser sugeridas de acuerdo a lo especificado en el requerimiento. Estará compuesto por:
- Una o más opciones
- Cada opciones estará compuesta por una o más promociones
- Cada promoción contendrá los participantes de condición (pueden no informarse)
- Cada promoción estará compuesta por uno o más beneficios
- Cada beneficio contendrá los participantes de combo (puede ser vacío)
- Cada beneficio contendrá también los elementos ítem aplicados (puede ser vacío)
- Cada opciones estará compuesta por una o más promociones
- Un conjunto de sugerencias (esta parte del contenido puede no estar presente)
- Las sugerencias están compuestas por una o más promociones
- Por cada promoción se informará descripción, nombre, secuencias y tipos de secuencia que dieron lugar a la sugerencia.
- Las sugerencias están compuestas por una o más promociones
Para el caso de evaluaciones a realizarse en PROMO Central, la composición de la respuesta será:
- Un elemento fidelidad
- Cada elemento de fidelidad puede estar compuesto por uno o más elementos fidelidad (cupones y/o elemento de fidelidad)
- Cada cupón contendrá el detalle de los mismos para su emisión(opcional, puede no existir dicha información)
- Cada elemento de fidelidad contendrá el detalle del elemento de fidelidad
- Cada elemento de fidelidad puede estar compuesto también por errores
- Cada elemento de fidelidad puede estar compuesto por uno o más elementos fidelidad (cupones y/o elemento de fidelidad)
Opciones
Una opción, es uno de los tipos de funciones disponibles al generar un mapa, que permite optar al cliente entre dos o más promociones. Cada una surge de la aplicación de la función de convivencia OPTION (ver Manual de usuario). De esta forma, PROMO ya informa las combinaciones posibles. Las opciones se representan con la etiqueta <optional>. De no existir opciones, el cuerpo del mensaje de respuesta constará de una sola opción, es decir, existirá sólo una etiqueta <optional> que contendrá a las promociones a aplicar. Esta etiqueta no posee atributos.
<message companyId="napse" store="tienda 1" terminal="1" date-time="2022-12-05 18:00:00" init-tck="true" messageId="1" void-trx="false" response="true" status="sale" evaluate="true" map-version="139" suggest="false"> <item-add seq="1" unitprice="1400" xprice="1400" qty="1" code="Coca-Cola" discountable="true"/> </message>
Request de Opciones JSON
{
"message": {
"companyId": "napse",
"store": "tienda 1",
"terminal": "1",
"date-time": "2022-12-05 18:00:00",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "sale",
"evaluate": "true",
"map-version": "139",
"suggest": "false",
"item-add": [{
"seq": "1",
"unitprice": "1400",
"xprice": "1400",
"qty": "1",
"code": "Coca-Cola",
"discountable": "true"
}]
}
}
El pos muestra al cliente todas las promociones que contiene el mapa:
----- message ------ <?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.2.2#236" mapversion="139" messageId="1" store="tienda 1" terminal="1"> <optional> <promo id="PromoO1" nro="638e15f77e8f8e2654b40864"> <benefit TLOGMessage="PromoO1" account="" applicationMethod="resume" baseAmount="1400.00" benefitType="PercentageDiscount" discountPercentage="50.00" displayMessage="PromoO1" name="638e15f77e8f8e2654b40864" nro="638e16157e8f8e2654b4086b" order="1" printerMessage="PromoO1" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="700.00" valueWithTaxes="700.00" xprice="1400.00"/> </apply> </benefit> </promo> </optional> <optional> <promo id="PromoO2" nro="638e16317e8f8e2654b4086e"> <benefit TLOGMessage="PromoO2" account="" applicationMethod="resume" baseAmount="1400.00" benefitType="FixedDiscount" discountAmount="1000.00" displayMessage="PromoO2" name="638e16317e8f8e2654b4086e" nro="638e16427e8f8e2654b40872" order="1" printerMessage="PromoO2" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="1000.00" valueWithTaxes="1000.00" xprice="1400.00"/> </apply> </benefit> </promo> </optional> <optional> <promo id="PromoO3" nro="638e16757e8f8e2654b40878"> <benefit TLOGMessage="PromoO3" account="" amount="" applicationMethod="resume" baseAmount="1400.00" benefitType="CouponBenefit" couponId="601" displayMessage="PromoO3" infoPos="0" name="638e16757e8f8e2654b40878" nro="638e16997e8f8e2654b4087f" order="1" printerMessage="PromoO3" qty="1.000"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="0.00" valueWithTaxes="0.00" xprice="1400.00"/> </apply> </benefit> </promo> </optional> </message>
Response de Opciones JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.2.2#236",
"mapversion": "139",
"messageId": "1",
"store": "tienda 1",
"terminal": "1",
"optional": [
{
"promo": {
"id": "PromoO1",
"nro": "638e15f77e8f8e2654b40864",
"benefit": [{
"TLOGMessage": "PromoO1",
"account": "",
"applicationMethod": "resume",
"baseAmount": "1400.00",
"benefitType": "PercentageDiscount",
"discountPercentage": "50.00",
"displayMessage": "PromoO1",
"name": "638e15f77e8f8e2654b40864",
"nro": "638e16157e8f8e2654b4086b",
"order": "1",
"printerMessage": "PromoO1",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "700.00",
"valueWithTaxes": "700.00",
"xprice": "1400.00"
}]
}
}]
}
},
{
"promo": [{
"id": "PromoO2",
"nro": "638e16317e8f8e2654b4086e",
"benefit": {
"TLOGMessage": "PromoO2",
"account": "",
"applicationMethod": "resume",
"baseAmount": "1400.00",
"benefitType": "FixedDiscount",
"discountAmount": "1000.00",
"displayMessage": "PromoO2",
"name": "638e16317e8f8e2654b4086e",
"nro": "638e16427e8f8e2654b40872",
"order": "1",
"printerMessage": "PromoO2",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "1000.00",
"valueWithTaxes": "1000.00",
"xprice": "1400.00"
}]
}
}]
}
},
{
"promo": [{
"id": "PromoO3",
"nro": "638e16757e8f8e2654b40878",
"benefit": [{
"TLOGMessage": "PromoO3",
"account": "",
"amount": "",
"applicationMethod": "resume",
"baseAmount": "1400.00",
"benefitType": "CouponBenefit",
"couponId": "601",
"displayMessage": "PromoO3",
"infoPos": "0",
"name": "638e16757e8f8e2654b40878",
"nro": "638e16997e8f8e2654b4087f",
"order": "1",
"printerMessage": "PromoO3",
"qty": "1.000",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "0.00",
"valueWithTaxes": "0.00",
"xprice": "1400.00"
}]
}
}]
}]
}
]
}
}
Siempre va a haber por lo menos un optional (sin importar que función de convivencia se esté utilizando). Solo la función de convivencia OPTION tiene un tag. Las otras funciones de convivencia modifican el resultado sin tener un tag, lo maneja internamente el motor. En el caso que se utilice la función de convivencia "OPTION" pueden venir varios optional para que puedan ser informados en pantalla, y la persona elija en el POS qué opción va a preferir. El POS deberá usar el campo "chosenOption" en el mensaje Finish, para informarle a Promo qué opción eligió la persona en la pantalla del POS. Para elegir la primer promoción deberá ingresar en chosenOption="0", para la segunda promoción chosenOption="1", y así sucesivamente.
Promociones
Como se mencionó anteriormente, cada una de las opciones contendrá una o más promociones.
Estas estarán identificadas por su nombre, siendo este su único atributo.
Las promociones estarán representadas con la etiqueta <promo>, teniendo el atributo id representando su nombre:
Propiedad | Tipo de dato | Descripción |
id | Alfanumérico | Nombre de la promoción. |
nro | Alfanumérico | Identificador de la base de datos de la promoción |
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> <promo id="Promoción navideña" nro="1"> … participantes de condición … … beneficios … </promo> <promo id="Promoción 2x1 en juguetes" nro="2"> … participantes de condición … … beneficios … </promo> </optional> </message>
Ejemplo JSON
{
"message": {
"companyId": "sts",
"store": "MX",
"mapversion": "3241",
"messageId": "160",
"terminal": "100",
"engine": "2.6",
"ack": "0",
"optional": {
"promo": [
{
"id": "Promoción navideña",
"nro": "1",
… participantes de condición …
… beneficios …
},
{
"id": "Promoción 2x1 en juguetes",
"nro": "2",
… participantes de condición …
… beneficios …
}
]
}
}
}
A su vez, cada promoción podrá informar una serie de elementos participantes de condición y beneficios, ambos detallados en las secciones siguientes.
Participantes de condición
Los participantes de condición son un componente opcional que indica los elementos que influyeron en la condición (ver Manual de usuario) que provocaron que se otorgue el beneficio. Estos elementos estarán agrupados dentro de una etiqueta del tipo <conditionParticipants>. Los elementos participantes de condición estarán representados por la etiqueta que corresponda al tipo de elemento, agrupados como ya se describió dentro de <conditionParticipants>. Los elementos participantes poseerán los atributos informados al momento de agregarlos a la sesión.
Los participantes de condición son completamente opcionales, pudiendo no ser informados si así se configura en el archivo de definición de promociones (mapa) o si no existen participantes de condición. En ese caso la etiqueta <conditionParticipants> no formará parte de la promoción. Esta etiqueta no posee atributos.
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> <promo id="Promoción navideña" nro="1"> <conditionParticipants> <item code="0056" brand="PANASONIC" xprice="99.0" magnitude="0.0" family="TV" type="qty" dept="ELECTRONIC" qty="1.0" seq="2"/> <customer seq="2" id="000004" type="preferred" /> <coupon seq="1" id="0001" amount="" qty="1.0" type="A" /> </conditionParticipants> … beneficios … </promo> </optional> </message>
Ejemplo JSON
{
"message": {
"companyId": "sts",
"store": "MX",
"mapversion": "3241",
"messageId": "160",
"terminal": "100",
"engine": "2.6",
"ack": "0",
"optional": [{
"promo": [{
"id": "Promoción navideña",
"nro": "1",
"conditionParticipants": [{
"item": [{
"code": "0056",
"brand": "PANASONIC",
"xprice": "99.0",
"magnitude": "0.0",
"family": "TV",
"type": "qty",
"dept": "ELECTRONIC",
"qty": "1.0",
"seq": "2"
}],
"customer": [{
"seq": "2",
"id": "000004",
"type": "preferred"
}],
"coupon": [{
"seq": "1",
"id": "0001",
"amount": "",
"qty": "1.0",
"type": "A"
}]
}],
… beneficios …
}]
}]
}
}
Importante
Promo limita a 3000 los participantes de condición por promoción.
Beneficios
Dentro de cada promoción existirá uno o más beneficios. Los beneficios son los elementos más importantes de la respuesta y definen la ventaja (económica o no) que debe darse al cliente, correspondientes a la promoción a la que pertenecen. Se definirán a través de la etiqueta <benefit>.
Existen beneficios de diversos tipos, cada uno con diferentes características. Es por ello que dependiendo del beneficio que se trate variarán los atributos correspondientes a la etiqueta <benefit> que lo representa. No obstante, existen algunos atributos que son comunes a todos ellos:
Propiedad | Tipo de dato | Descripción |
order | Entero positivo | Número que identifica unívocamente al beneficio dentro del mensaje de respuesta. Su valor surge del orden en que se realizó su aplicación al realizar la evaluación. |
benefitType | Alfanumérico | Tipo de beneficio que se trata. |
displayMessage | Alfanumérico | Mensaje a mostrar por display en el punto de venta. |
printerMessage | Alfanumérico | Mensaje a imprimir en la boleta o ticket al finalizar la compra. |
applicationMethod | Alfanumérico | Forma de mostrar el beneficio. Puede poseer dos valores:
|
baseAmount | Real positivo | Indica el monto total sobre el cual se calculó el beneficio en cuestión. |
TLOGMessage | Alfanumérico | Mensaje a guardar en el TLOG |
account | Alfanumérico | Cuenta contable a la cual será imputado el beneficio. |
nro | Alfanumérico | Identificador de la base de datos del beneficio. |
name | Alfanumérico | Identificador de la base de datos de la promoción que contiene al beneficio. |
Sin importar de qué tipo de beneficio se trate, estos pueden tener elementos aplicados y participantes de combo. Cada uno de estos se detallarán en las secciones siguientes.
Tipos de beneficios
PROMO posee ocho tipos de beneficio, siendo tres de ellos monetarios y cinco no monetarios. Los beneficios monetarios son aquellos que otorgan una ventaja económica al cliente, mientras que los no monetarios no.
Los tipos de beneficio estarán dados por el valor del atributo benefitType de la etiqueta <benefit>, y son los siguientes:
- Monetarios:
- FixedDiscount
- Es un descuento fijo que se realiza sobre un conjunto de artículos.
- PercentageDiscount
- Representa un porcentaje de descuento sobre un conjunto de artículos.
- NewPrice
- Asigna un nuevo precio a uno o varios artículos.
- TenderDiscountBenefit
- Representa un % de descuento o recargo sobre un conjunto de artículos. La información para calcular este porcentaje se obtiene de los planes de pago (PaymentPlanBenefit) aplicados.
- RedeemPointsBenefit
- Realiza la conversión de saldo a dinero e informa un monto de descuento a aplicar en base al valor informado.
- CalculatedCouponApplicationBenefit
- Aplica como descuento el monto informado por un cupón calculado
- ContractPercentageDiscountBenefit
- Descuento Porcentual que se aplica a un determinado Convenio y limitado por un saldo asociado al mismo
- CatalogRedeemBenefit
- Realiza una conversión de puntos y otorga un monto de descuento basado en datos tabulares definidos para los productos
- RedeemWithOptionsBenefit
- (A partir de Promo 7.0-EP2) Realiza la redención de una determinada cantidad de puntos (Cliente/Elementos de fidelidad) para habilitar un descuento monetario. Para mas información sobre el beneficio ver Anexo I en este documento
- FixedDiscount
- No monetarios
- PaymentPlanBenefit
- Otorga un plan de pagos específico para una serie de artículos o para la compra.
- CouponBenefit
- Otorga una cierta cantidad de cupones específicos al cliente.
- GiftBenefit
- Entrega al cliente uno o más regalos específicos.
- GeneralBenefit
- Entrega al cliente uno o más beneficios generales.
- LoyaltyBenefit
- Beneficia al cliente con una cierta cantidad de saldo de fidelidad (millas, puntos de monedero, dinero, etc.). A partir de la versión 2.8.0, este beneficio calcula la cantidad de saldo por cada elemento de aplicación y la cantidad de saldo en total que otorga.
- FactorLoyaltyBenefit
- Representa el otorgamiento de puntos, dinero, millas, etc. de fidelidad en relación a un factor dado.
- PercentLoyaltyBenefit
- Representa el otorgamiento de puntos, dinero, millas, etc. de fidelidad en relación a un porcentaje dado. Este beneficio calcula la cantidad de puntos, dinero, millas, etc. por cada elemento de aplicación y la cantidad de puntos, dinero, millas, etc. en total que otorga.
- CalculatedCouponBenefit
- Representa el otorgamiento de un cupón cuyo monto de descuento a otorgar está definido por un porcentaje de los participantes.
- PaymentPlanBenefit
Como se mencionó en párrafos anteriores, cada tipo de beneficio tendrá atributos propios. Cada uno de estos atributos representa un parámetro específico del beneficio al que pertenece (indicado en benefitType). En la siguiente tabla se enumeran dichos atributos y en la columna "Requerido" se indica si el atributo estará siempre presente en la respuesta ("Si") o bien dependerá de su valor para ser incluido o no en la misma ("No")
Beneficio | Propiedad | Tipo de dato | Requerido | Descripción |
FixedDiscount | unit | Alfanumérico | No | El valor de "unit" indicará si el descuento estará aplicado sobre todo el conjunto o sobre cada unidad de la propiedad seleccionada. Los valores posibles son:
|
discountAmount | Real positivo | Si | Descuento que se realizará sobre los elementos aplicados. El valor a descontar a cada artículo variará dependiendo de la unidad de aplicación. | |
prorationMethod | Alfanumérico | Si | Método que se utilizará para prorratear el beneficio entre los elementos aplicados, pudiendo ser:
| |
PercentageDiscount | unit | Alfanumérico | No | Indicará si debe aplicarse el porcentaje de descuento a cada unidad o al total. Los valores que puede tener son los indicados anteriormente. |
discountPercentage | Real positivo | Si | Porcentaje de descuento que se realizará sobre los elementos participantes. El valor a descontar a cada artículo variará dependiendo de la unidad de aplicación. | |
name | Alfanumérico | No | Nombre de la promoción que ha originado el beneficio. | |
prorationMethod | Alfanumérico | Si | Método que se utilizará para prorratear el beneficio entre los elementos aplicados. Los valores que a tomar son los mismos indicados anteriormente. | |
NewPrice | unit | Alfanumérico | No | Indicará si debe aplicarse el nuevo precio a cada unidad o al total. Los valores que puede tener son los indicados anteriormente. |
newPrice | Real positivo | Si | Descuento fijo que se realizará sobre los elementos participantes. El valor a descontar a cada artículo variará dependiendo de la unidad de aplicación. | |
prorationMethod | Alfanumérico | Si | Método que se utilizará para prorratear el beneficio entre los elementos aplicados. Los valores que puede tomar son los mismos indicados anteriormente. | |
TenderDiscountBenefit | tender | Alfanumérico | Si | Medio/s de pago que se pueden utilizar. Puede ser una lista separada por comas. |
limit | Real positivo | No | Indica el máximo que se podrá abonar con el medio de pago. Este tope sólo tendrá utilidad en el punto de venta sin afectar los calculos del Motor de Promociones. Si este valor es vacío significa que el monto es ilimitado. | |
planId | Alfanumérico | Si | Identificador del plan que se otorga. | |
Type | Alfanumérico | No | Tipo de medio de pago. | |
Bank | Alfanumérico | No | Banco asociado al medio de pago. | |
Percent | Real positivo | Si | Porcentaje de descuento o recargo que se realizará sobre los elementos participantes. | |
percenttype | Alfanumérico | No | Indica si el porcentaje es un descuento (valor=discount) o recargo (valor=surcharge). | |
tenderseq | Entero positivo | Si | Número identificador único del elemento medio de pago (payment) dentro de la transacción. | |
amount | Real positivo | Si | Dinero que se utiliza con ese medio de pago | |
itemamount | Real positivo | Si | Dinero que representa el monto de ítems que se desea pagar. | |
paymentAmount | Real positivo | Si | Indica el monto total sobre el cual se calculó el beneficio en cuestión. | |
installments | Real positivo | No | Indica la cantidad de cuotas asociadas al plan de pago | |
benefitedamount | Real positivo | Si | Descuento que se realizará sobre los elementos aplicados. | |
RedeemPointsBenefit | Type | Alfanumérico | Si | Indica el tipo de elemento de fidelidad a la que se aplicara el beneficio |
factor | Real positivo | Si | Indica el factor de conversión para el cálculo del descuento en base al monto informado en el amount | |
usedPoints | Real positivo | Si | Indica la cantidad de saldo (punto, dinero, etc.) que será utilizado para la aplicación de dicho beneficio | |
discountAmount | Real positivo | Si | Descuento que se realizará sobre los elementos aplicados. El valor a descontar a cada artículo variará dependiendo de la unidad de aplicación. | |
prorationMethod | Alfanumérico | Si | Método que se utilizará para prorratear el beneficio entre los elementos aplicados. Los valores que puede tomar son los mismos indicados anteriormente. | |
unit | Alfanumérico | Si | Indicará si debe aplicarse el nuevo precio a cada unidad o al total. Los valores que puede tener son los indicados anteriormente. | |
CalculatedCouponApplicationBenefit | discountAmount | Real positivo | Si | Descuento que se realizará sobre los elementos aplicados. El valor a descontar a cada artículo variará dependiendo de la unidad de aplicación. |
couponId | Alfanumérico | Si | Identificador del cupón a redimir. | |
usedCoupons | Alfanumérico | Si | Consiste en una cadena con valores separados por coma indicando cada uno de los códigos de cupón utilizados en la redención. Este dato es basado en los cupones utilizados para cubrir el monto de redención. Ejemplo usedCoupons=A645746566, BCD8383, P39393A9393 | |
PaymentPlanBenefit | tender | Alfanumérico | Si | Medio/s de pago que se pueden utilizar. Puede ser una lista separada por comas. Cuando en el request de una transacción no se especifica el Id y/o el nombre, y/o cuotas, y/o tipos, y/o plan, y/o prefijo y/o pocket del plan de pago; el mismo igual se aplica. |
limitAmount | Real positivo | No | Indica el máximo que se podrá abonar con el medio de pago. Este tope sólo tendrá utilidad en el punto de venta sin afectar los cálculos del Motor de Promociones. Si este valor es vacío significa que el monto es ilimitado. | |
planid | Alfanumérico | Si | Identificador del plan que se otorga. | |
type | Alfanumérico | No | Tipo de medio de pago. | |
bank | Alfanumérico | Si | Banco asociado al medio de pago. | |
percent | Real positivo | No | Porcentaje de descuento o recargo que se realizará sobre los elementos participantes. El descuento o recargo será informado como un beneficio TenderDiscountBenefit | |
percenttype | Alfanumérico | No | Indica si el porcentaje es un descuento (valor=discount) o recargo (valor=surcharge). | |
installments | Real positivo | No | Indica la cantidad de cuotas asociadas al plan de pago | |
paymentAmount | Real positivo | Si | Indica el monto total sobre el cual se calculó el beneficio en cuestión. | |
CouponBenefit | couponId | Alfanumérico | Si | Identificador del cupón a otorgar. |
amount | Real positivo | Si | Indicara el monto asociado a un cupón cuyo monto fue calculado | |
qty | Entero positivo | Si | Cantidad de cupones a otorgar. | |
infoPos | Alfanumérico | No | En el caso de Cupones Informativos existe la posibilidad de enviar al Punto de Venta la opción seleccionada de las disponibles para configurar por el usuario. Ver manual de Usuario para Cupones Informativos. | |
GiftBenefit | giftid | Alfanumérico | Si | Identificador del regalo a entregar. En caso de que sea un producto en stock, puede representar el código del artículo a regalar. |
giftType | Alfanumérico | Si | Tipo de regalo a entregar. Puede ser vacío. | |
qty | Entero positivo | Si | Cantidad de regalos con el identificador indicado. | |
LoyaltyBenefit | type | Alfanumérico | Si | Tipo de valor (puntos, dinero, millas, etc.) de fidelidad que se están otorgando. |
amount | Entero positivo | Si | Cantidad de puntos, dinero, millas, etc. a otorgar del tipo especificado en el atributo anterior. | |
unit | Alfanumérico | Si | Indicará si debe aplicarse la cantidad de puntos, dinero, millas, etc. a cada unidad o al total. Los valores que puede tener son los indicados anteriormente. | |
totalpoints | Real positivo | Si | Indica la cantidad total de puntos, dinero, millas, etc. que otorga el beneficio luego de ser calculado. | |
FactorLoyaltyBenefit | type | Alfanumérico | Si | Tipo de puntos, dinero, millas, etc. de fidelidad que se están otorgando. |
factor | Real positivo | Si | Factor multiplicador a utilizar para el cálculo de los puntos, dinero, millas, etc. | |
PercentLoyaltyBenefit | type | Alfanumérico | Si | Tipo de puntos, dinero, millas, etc. de fidelidad que se están otorgando. |
percent | Real positivo | Si | Porcentaje de puntos, dinero, millas, etc., que se aplica sobre el xprice u originalXPrice para calcular la cantidad de puntos, dinero, millas, etc. que corresponden otorgar. | |
totalpoints | Real positivo | Si | Indica la cantidad total de puntos, dinero, millas, etc. que otorga el beneficio luego de ser calculado. | |
CalculatedCouponBenefit | couponId | Alfanumérico | Si | Identificador del cupón a otorgar. |
amount | Entero positivo | Si | Indicara el monto asociado a un cupón cuyo monto fue calculado | |
Percentage | Alfanumérico | Si | Indica el porcentaje en base al cual fue calculado el monto del cupón | |
qty | Entero positivo | Si | Cantidad de cupones a otorgar. | |
PromotionPaidInPoints | qty | Entero positivo | Si | Cantidad de ítems a beneficiar. |
points | Alfanumérico | Si | Cantidad de puntos a descontar del beneficio que ha entregado puntos en la transacción en curso (informado en el apply) Se informara cuando en el pago se envíe el atributo pointsType="" (ver manual de usuario final Promo 7 - Ingnorar pago con puntos.) |
CatalogRedeemBenefit | discountAmount | Real positivo | Si | Descuento que se realizará sobre los elementos aplicados. El valor a descontar a cada artículo variará dependiendo de la unidad de aplicación. |
type | Alfanumérico | Si | Tipo de puntos, dinero, millas, etc. de fidelidad que se están otorgando. | |
unit | Alfanumérico | Si | Actualmente el beneficio se aplica sobre la cantidad o magnitud de cada producto en cuestión por lo cual no se espera funcionalidad en este atributo. | |
usedPoints | Real positivo | Si | Indica la cantidad de saldo (punto, dinero, etc.) que será utilizado para la aplicación de dicho beneficio |
GeneralBenefit | generalid | Alfanumérico | Si | Identificador del beneficio a entregar. En caso de que sea un producto en stock, puede representar el código del artículo a regalar. |
generaltype | Alfanumérico | Si | Tipo de beneficio a entregar. Puede ser vacío. | |
qty | Entero positivo | Si | Cantidad de beneficios con el identificador indicado. |
ContractPercentageDiscount | unit | Alfanumérico | No | Indicará si debe aplicarse el porcentaje de descuento a cada unidad o al total. Los valores que puede tener son los indicados anteriormente. |
discountPercentage | Real positivo | Si | Porcentaje de descuento que se realizará sobre los elementos participantes. El valor a descontar a cada artículo variará dependiendo de la unidad de aplicación. | |
name | Alfanumérico | No | Nombre de la promoción que ha originado el beneficio. | |
prorationMethod | Alfanumérico | Si | Método que se utilizará para prorratear el beneficio entre los elementos aplicados. Los valores que a tomar son los mismos indicados anteriormente. |
Ejemplos:
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> <promo id="Promoción navideña" nro="1"> <conditionParticipants> <item code="0056" brand="PANASONIC" xprice="99.0" magnitude="0.0" family="TV" type="qty" dept="ELECTRONIC" qty="1.0" seq="2"/> <customer seq="2" id="000004" type="preferred" /> <coupon seq="1" id="0001" amount="" qty="1.0" type="A" /> </conditionParticipants> <benefit order="1" benefitType="FixedAmount" displayMessage="" printerMessage="" unit="qty" prorationMethod="PROPORTIONAL" applicationMethod="lineByLine" nro="3" amount="20.00" baseAmount="165.00"> … participantes de combo y/o elementos aplicados … </benefit> </promo> </optional> </message>
FixedDiscount JSON
{
"message": {
"companyId": "sts",
"store": "MX",
"mapversion": "3241",
"messageId": "160",
"terminal": "100",
"engine": "2.6",
"ack": "0",
"optional": [{
"promo": [{
"id": "Promoción navideña",
"nro": "1",
"conditionParticipants": [{
"item": [{
"code": "0056",
"brand": "PANASONIC",
"xprice": "99.0",
"magnitude": "0.0",
"family": "TV",
"type": "qty",
"dept": "ELECTRONIC",
"qty": "1.0",
"seq": "2"
}],
"customer": [{
"seq": "2",
"id": "000004",
"type": "preferred"
}],
"coupon": [{
"seq": "1",
"id": "0001",
"amount": "",
"qty": "1.0",
"type": "A"
}]
}],
"benefit": [{
"order": "1",
"benefitType": "FixedAmount",
"displayMessage": "",
"printerMessage": "",
"unit": "qty",
"prorationMethod": "PROPORTIONAL",
"applicationMethod": "lineByLine",
"nro": "3",
"amount": "20.00",
"baseAmount": "165.00",
… participantes de combo y/o elementos aplicados …
}]
}]
}]
}
}
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> <promo id="Promoción navideña" nro="1"> <benefit order="1" benefitType="PercentageDiscount" displayMessage="" printerMessage="" unit="" prorationMethod="PROPORTIONAL" applicationMethod="lineByLine" nro="3" Percentage="20.00" baseAmount="165.00"> … participantes de combo y/o elementos aplicados … </benefit> </promo> </optional> </message>
PercentageDiscount JSON
{
"message": {
"companyId": "sts",
"store": "MX",
"mapversion": "3241",
"messageId": "160",
"terminal": "100",
"engine": "2.6",
"ack": "0",
"optional": [{
"promo": [{
"id": "Promoción navideña",
"nro": "1",
"benefit": [{
"order": "1",
"benefitType": "PercentageDiscount",
"displayMessage": "",
"printerMessage": "",
"unit": "",
"prorationMethod": "PROPORTIONAL",
"applicationMethod": "lineByLine",
"nro": "3",
"Percentage": "20.00",
"baseAmount": "165.00",
… participantes de combo y/o elementos aplicados …
}]
}]
}]
}
}
<?xml version="1.0" encoding="UTF-8" standalone="no"?><message ack="0" companyId="napse" engine="7.2.3-SNAPSHOT#206" mapversion="164" messageId="10" store="Tienda1" terminal="1"> <optional> <promo id="Promo Plan de Pagos" nro="62d808251e49e74f30e086f9"> <benefit TLOGMessage="Promo Reintegro Bancario" account="" applicationMethod="resume" baseAmount="1300.00" benefitType="PaymentPlanBenefit" displayMessage="Promo Reintegro Bancario" installments="12" name="62d808251e49e74f30e086f9" nro="62d80a951e49e74f30e08704" order="1" paymentAmount="1300.00" percent="10" percenttype="discount" planId="si" printerMessage="Promo Reintegro Bancario" tender="si" type="si"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="0.00" valueWithTaxes="0.00" xprice="300.00"/> <item magnitude="0.000" qty="1.000" seq="2" value="0.00" valueWithTaxes="0.00" xprice="100.00"/> <item magnitude="0.000" qty="1.000" seq="3" value="0.00" valueWithTaxes="0.00" xprice="200.00"/> <item magnitude="0.000" qty="1.000" seq="4" value="0.00" valueWithTaxes="0.00" xprice="700.00"/> </apply> </benefit> </promo> <promo id="Promociones basadas en items" nro="1"> <benefit TLOGMessage="Promo Reintegro Bancario" account="" amount="1170.00" applicationMethod="resume" baseAmount="1300.00" benefitType="TenderDiscountBenefit" benefitedamount="130.00" displayMessage="Promo Reintegro Bancario" installments="12" itemamount="1300.00" order="2" paymentAmount="1300.00" percent="10" percenttype="discount" planId="si" printerMessage="Promo Reintegro Bancario" promotionId="Promo Plan de Pagos" tender="si" tenderseq="1,2" type="si"> <apply> <item magnitude="0.000" qty="1.000" seq="1" tenderseq="1" value="30.00" valueWithTaxes="0.00" xprice="300.00"/> <item magnitude="0.000" qty="1.000" seq="2" tenderseq="1" value="10.00" valueWithTaxes="0.00" xprice="100.00"/> <item magnitude="0.000" qty="1.000" seq="3" tenderseq="1" value="20.00" valueWithTaxes="0.00" xprice="200.00"/> <item magnitude="0.000" qty="1.000" seq="4" tenderseq="1" value="30.00" valueWithTaxes="0.00" xprice="700.00"/> <item magnitude="0.000" qty="1.000" seq="4" tenderseq="2" value="40.00" valueWithTaxes="0.00" xprice="700.00"/> </apply> </benefit> </promo> </optional> </message>
TenderDiscountBenefit JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.2.3-SNAPSHOT#206",
"mapversion": "164",
"messageId": "10",
"store": "Tienda1",
"terminal": "1",
"optional": [{
"promo": [
{
"id": "Promo Plan de Pagos",
"nro": "62d808251e49e74f30e086f9",
"benefit": [{
"TLOGMessage": "Promo Reintegro Bancario",
"account": "",
"applicationMethod": "resume",
"baseAmount": "1300.00",
"benefitType": "PaymentPlanBenefit",
"displayMessage": "Promo Reintegro Bancario",
"installments": "12",
"name": "62d808251e49e74f30e086f9",
"nro": "62d80a951e49e74f30e08704",
"order": "1",
"paymentAmount": "1300.00",
"percent": "10",
"percenttype": "discount",
"planId": "si",
"printerMessage": "Promo Reintegro Bancario",
"tender": "si",
"type": "si",
"apply": {
"item": [
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "0.00",
"valueWithTaxes": "0.00",
"xprice": "300.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "2",
"value": "0.00",
"valueWithTaxes": "0.00",
"xprice": "100.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "3",
"value": "0.00",
"valueWithTaxes": "0.00",
"xprice": "200.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "4",
"value": "0.00",
"valueWithTaxes": "0.00",
"xprice": "700.00"
}
]
}
}]
},
{
"id": "Promociones basadas en items",
"nro": "1",
"benefit": [{
"TLOGMessage": "Promo Reintegro Bancario",
"account": "",
"amount": "1170.00",
"applicationMethod": "resume",
"baseAmount": "1300.00",
"benefitType": "TenderDiscountBenefit",
"benefitedamount": "130.00",
"displayMessage": "Promo Reintegro Bancario",
"installments": "12",
"itemamount": "1300.00",
"order": "2",
"paymentAmount": "1300.00",
"percent": "10",
"percenttype": "discount",
"planId": "si",
"printerMessage": "Promo Reintegro Bancario",
"promotionId": "Promo Plan de Pagos",
"tender": "si",
"tenderseq": "1,2",
"type": "si",
"apply": {
"item": [
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"tenderseq": "1",
"value": "30.00",
"valueWithTaxes": "0.00",
"xprice": "300.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "2",
"tenderseq": "1",
"value": "10.00",
"valueWithTaxes": "0.00",
"xprice": "100.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "3",
"tenderseq": "1",
"value": "20.00",
"valueWithTaxes": "0.00",
"xprice": "200.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "4",
"tenderseq": "1",
"value": "30.00",
"valueWithTaxes": "0.00",
"xprice": "700.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "4",
"tenderseq": "2",
"value": "40.00",
"valueWithTaxes": "0.00",
"xprice": "700.00"
}
]
}
}]
}
]
}]
}
}
<message ack="0" engine="2.6" mapversion="2" messageId="1" companyId="sts" store="1" terminal="1"> <optional> <promo id="redime puntos" nro="58ff57be6772781234e7915e"> <benefit TLOGMessage="redime puntos" account="" applicationMethod="resume" baseAmount="100.00" benefitType="RedeemPointsBenefit" discountAmount="100.00" displayMessage="redime puntos" factor="1" name="58ff57be6772781234e7915e" nro="58ff57e76772781234e79164" order="1" printerMessage="redime puntos" prorationMethod="PROPORTIONAL" unit="" usedPoints="100.0"> <apply> <item magnitude="0.000" qty="1.000" seq="2" value="100.00" xprice="100.00"/> </apply> </benefit> </promo> </optional> </message>
RedeemPointsBenefit JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "2",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"optional": [{
"promo": [{
"id": "redime puntos",
"nro": "58ff57be6772781234e7915e",
"benefit": [{
"TLOGMessage": "redime puntos",
"account": "",
"applicationMethod": "resume",
"baseAmount": "100.00",
"benefitType": "RedeemPointsBenefit",
"discountAmount": "100.00",
"displayMessage": "redime puntos",
"factor": "1",
"name": "58ff57be6772781234e7915e",
"nro": "58ff57e76772781234e79164",
"order": "1",
"printerMessage": "redime puntos",
"prorationMethod": "PROPORTIONAL",
"unit": "",
"usedPoints": "100.0",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "2",
"value": "100.00",
"xprice": "100.00"
}]
}
}]
}]
}]
}
}
<message ack="0" engine="2.6" mapversion="2" messageId="1" companyId="sts" store="1" terminal="1"> <optional> <promo id="redime impreso calculado" nro="5900e1a6a846390de08a7afe"> <benefit TLOGMessage="redime impreso calculado" account="" applicationMethod="resume" baseAmount="100.00" benefitType="CalculatedCouponApplicationBenefit" couponId="1" discountAmount="10.00" displayMessage="redime impreso calculado" name="5900e1a6a846390de08a7afe" nro="5900e1bca846390de08a7b04" order="1" printerMessage="redime impreso calculado" prorationMethod="PROPORTIONAL" unit="" usedCoupons="A39383883,B39393839,C333333333"> <apply> <item magnitude="0.000" qty="1.000" seq="2" value="10.00" xprice="100.00"/> </apply> </benefit> </promo> </optional> </message>
calculatedcouponaplicationbenefit JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "2",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"optional": [{
"promo": [{
"id": "redime impreso calculado",
"nro": "5900e1a6a846390de08a7afe",
"benefit": [{
"TLOGMessage": "redime impreso calculado",
"account": "",
"applicationMethod": "resume",
"baseAmount": "100.00",
"benefitType": "CalculatedCouponApplicationBenefit",
"couponId": "1",
"discountAmount": "10.00",
"displayMessage": "redime impreso calculado",
"name": "5900e1a6a846390de08a7afe",
"nro": "5900e1bca846390de08a7b04",
"order": "1",
"printerMessage": "redime impreso calculado",
"prorationMethod": "PROPORTIONAL",
"unit": "",
"usedCoupons": "A39383883,B39393839,C333333333",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "2",
"value": "10.00",
"xprice": "100.00"
}]
}
}]
}]
}]
}
}
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> <promo id="Promoción navideña" nro="1"> <benefit order="1" benefitType="PaymentPlanBenefit" displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" tender="VISA" planId="A3" limitAmount="200.00" baseAmount="165.00" bank="HSBC" percent="5.000" percenttype="discount" paymentAmount="2500.00"> … participantes de combo y/o elementos aplicados … </benefit> </promo> </optional> </message>
PaymentPlanBenefit JSON
{
"message": {
"companyId": "sts",
"store": "MX",
"mapversion": "3241",
"messageId": "160",
"terminal": "100",
"engine": "2.6",
"ack": "0",
"optional": [{
"promo": [{
"id": "Promoción navideña",
"nro": "1",
"benefit": [{
"order": "1",
"benefitType": "PaymentPlanBenefit",
"displayMessage": "",
"printerMessage": "",
"applicationMethod": "lineByLine",
"nro": "3",
"tender": "VISA",
"planId": "A3",
"limitAmount": "200.00",
"baseAmount": "165.00",
"bank": "HSBC",
"percent": "5.000",
"percenttype": "discount",
"paymentAmount": "2500.00",
… participantes de combo y/o elementos aplicados …
}]
}]
}]
}
}
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> <promo id="Promoción navideña" nro="1"> <conditionParticipants> <item code="0056" brand="PANASONIC" xprice="99.0" magnitude="0.0" family="TV" type="qty" dept="ELECTRONIC" qty="1.0" seq="2"/> <customer seq="2" id="000004" type="preferred" /> <coupon seq="1" id="0001" amount="" qty="1.0" type="A" /> </conditionParticipants> <benefit order="1" benefitType="CouponBenefit" displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" couponId="C0032" qty="2" baseAmount="165.00"> … participantes de combo y/o elementos aplicados … </benefit> </promo> </optional> </message>
CouponBenefit JSON
{
"message": {
"companyId": "sts",
"store": "MX",
"mapversion": "3241",
"messageId": "160",
"terminal": "100",
"engine": "2.6",
"ack": "0",
"optional": [{
"promo": [{
"id": "Promoción navideña",
"nro": "1",
"conditionParticipants": [{
"item": [{
"code": "0056",
"brand": "PANASONIC",
"xprice": "99.0",
"magnitude": "0.0",
"family": "TV",
"type": "qty",
"dept": "ELECTRONIC",
"qty": "1.0",
"seq": "2"
}],
"customer": [{
"seq": "2",
"id": "000004",
"type": "preferred"
}],
"coupon": [{
"seq": "1",
"id": "0001",
"amount": "",
"qty": "1.0",
"type": "A"
}]
}],
"benefit": [{
"order": "1",
"benefitType": "CouponBenefit",
"displayMessage": "",
"printerMessage": "",
"applicationMethod": "lineByLine",
"nro": "3",
"couponId": "C0032",
"qty": "2",
"baseAmount": "165.00",
… participantes de combo y/o elementos aplicados …
}]
}]
}]
}
}
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> <promo id="Promoción navideña" nro="1"> <benefit order="1" benefitType="GiftBenefit" displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" qty="2" giftType="A" giftId="00452" baseAmount="165.00"> … participantes de combo y/o elementos aplicados … </benefit> </promo> </optional> </message>
GiftBenefit JSON
{
"message": {
"companyId": "sts",
"store": "MX",
"mapversion": "3241",
"messageId": "160",
"terminal": "100",
"engine": "2.6",
"ack": "0",
"optional": [{
"promo": [{
"id": "Promoción navideña",
"nro": "1",
"benefit": [{
"order": "1",
"benefitType": "GiftBenefit",
"displayMessage": "",
"printerMessage": "",
"applicationMethod": "lineByLine",
"nro": "3",
"qty": "2",
"giftType": "A",
"giftId": "00452",
"baseAmount": "165.00",
… participantes de combo y/o elementos aplicados …
}]
}]
}]
}
}
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> <promo id="Promoción navideña" nro="1"> <conditionParticipants> <item code="0056" brand="PANASONIC" xprice="99.0" magnitude="0.0" family="TV" type="qty" dept="ELECTRONIC" qty="1.0" seq="2"/> <customer seq="2" id="000004" type="preferred" /> <coupon seq="1" id="0001" amount="" qty="1.0" type="A" /> </conditionParticipants> <benefit order="1" benefitType="LoyaltyBenefit" displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" value="1000" type="points" baseAmount="99.00" totalpoints="1000.00" > … participantes de combo y/o elementos aplicados … <item value="0.000" seq="2" qty="1.000" points="1000.00" xprice="99.00"/> </benefit> </promo> </optional> </message>
LoyaltyBenefit JSON
{
"message": {
"companyId": "sts",
"store": "MX",
"mapversion": "3241",
"messageId": "160",
"terminal": "100",
"engine": "2.6",
"ack": "0",
"optional": {
"promo": {
"id": "Promoción navideña",
"nro": "1",
"conditionParticipants": {
"item": {
"code": "0056",
"brand": "PANASONIC",
"xprice": "99.0",
"magnitude": "0.0",
"family": "TV",
"type": "qty",
"dept": "ELECTRONIC",
"qty": "1.0",
"seq": "2"
},
"customer": {
"seq": "2",
"id": "000004",
"type": "preferred"
},
"coupon": {
"seq": "1",
"id": "0001",
"amount": "",
"qty": "1.0",
"type": "A"
}
},
"benefit": {
"order": "1",
"benefitType": "LoyaltyBenefit",
"displayMessage": "",
"printerMessage": "",
"applicationMethod": "lineByLine",
"nro": "3",
"value": "1000",
"type": "points",
"baseAmount": "99.00",
"totalpoints": "1000.00",
… participantes de combo y/o elementos aplicados …
"item": {
"value": "0.000",
"seq": "2",
"qty": "1.000",
"points": "1000.00",
"xprice": "99.00"
}
}
}
}
}
}
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> <promo id="Promoción navideña" nro="1"> <benefit order="1" benefitType="FactorLoyaltyBenefit " displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" factor="2" type="points" baseAmount="165.00"> … participantes de combo y/o elementos aplicados … </benefit> </promo> </optional> </message>
FactorLoyaltyBenefit JSON
{
"message": {
"companyId": "sts",
"store": "MX",
"mapversion": "3241",
"messageId": "160",
"terminal": "100",
"engine": "2.6",
"ack": "0",
"optional": [{
"promo": [{
"id": "Promoción navideña",
"nro": "1",
"benefit": [{
"order": "1",
"benefitType": "FactorLoyaltyBenefit ",
"displayMessage": "",
"printerMessage": "",
"applicationMethod": "lineByLine",
"nro": "3",
"factor": "2",
"type": "points",
"baseAmount": "165.00",
… participantes de combo y/o elementos aplicados …
}]
}]
}]
}
}
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> <promo id="Promoción navideña" nro="1"> <conditionParticipants> <item code="0056" brand="PANASONIC" xprice="99.0" magnitude="0.0" family="TV" type="qty" dept="ELECTRONIC" qty="1.0" seq="2"/> <customer seq="2" id="000004" type="preferred" /> <coupon seq="1" id="0001" amount="" qty="1.0" type="A" /> </conditionParticipants> <benefit order="1" benefitType="PercentLoyaltyBenefit" displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" percent="10.0" type="points" baseAmount="165.00" totalpoints="16.50" > … participantes de combo y/o elementos aplicados … <item value="0.000" seq="2" qty="1.000" points="16.50" xprice="99.00"/> </benefit> </promo> </optional> </message>
PercentLoyaltyBenefit JSON
{
"message": {
"companyId": "sts",
"store": "MX",
"mapversion": "3241",
"messageId": "160",
"terminal": "100",
"engine": "2.6",
"ack": "0",
"optional": [{
"promo": [{
"id": "Promoción navideña",
"nro": "1",
"conditionParticipants": {
"item": [{
"code": "0056",
"brand": "PANASONIC",
"xprice": "99.0",
"magnitude": "0.0",
"family": "TV",
"type": "qty",
"dept": "ELECTRONIC",
"qty": "1.0",
"seq": "2"
}],
"customer": [{
"seq": "2",
"id": "000004",
"type": "preferred"
}],
"coupon": [{
"seq": "1",
"id": "0001",
"amount": "",
"qty": "1.0",
"type": "A"
}]
},
"benefit": [{
"order": "1",
"benefitType": "PercentLoyaltyBenefit",
"displayMessage": "",
"printerMessage": "",
"applicationMethod": "lineByLine",
"nro": "3",
"percent": "10.0",
"type": "points",
"baseAmount": "165.00",
"totalpoints": "16.50",
… participantes de combo y/o elementos aplicados … ,
"item": [{
"value": "0.000",
"seq": "2",
"qty": "1.000",
"points": "16.50",
"xprice": "99.00"
}]
}]
}]
}]
}
}
<message ack="0" engine="2.6" mapversion="2" messageId="1" companyId="sts" store="1" terminal="1"> <optional> <promo id="emite impreso calculado" nro="5900e173a846390de08a7af7"> <benefit TLOGMessage="emite impreso calculado" account="" amount="10.00" applicationMethod="resume" baseAmount="100.00" benefitType="CalculatedCouponBenefit" couponId="1" displayMessage="emite impreso calculado" name="5900e173a846390de08a7af7" nro="5900e18ea846390de08a7afd" order="1" percentage="10" printerMessage="emite impreso calculado" qty="1.000"> <apply> <item magnitude="0.000" qty="1.000" seq="2" value="0.00" xprice="100.00"/> </apply> </benefit> </promo> </optional> </message>
CalculatedCouponBenefit JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "2",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"optional": [{
"promo": [{
"id": "emite impreso calculado",
"nro": "5900e173a846390de08a7af7",
"benefit": [{
"TLOGMessage": "emite impreso calculado",
"account": "",
"amount": "10.00",
"applicationMethod": "resume",
"baseAmount": "100.00",
"benefitType": "CalculatedCouponBenefit",
"couponId": "1",
"displayMessage": "emite impreso calculado",
"name": "5900e173a846390de08a7af7",
"nro": "5900e18ea846390de08a7afd",
"order": "1",
"percentage": "10",
"printerMessage": "emite impreso calculado",
"qty": "1.000",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "2",
"value": "0.00",
"xprice": "100.00"
}]
}
}]
}]
}]
}
}
<message ack="0" companyId="napse" engine="6.5.1" mapversion="5555" messageId="5" store="b320" terminal="1"> <optional> <promo code="catred01" id="catred01" nro="5e937332c142d70ac486ebb3"> <benefit TLOGMessage="catred01" account="" applicationMethod="qty" baseAmount="7000.00" benefitType="CatalogRedeemBenefit" type="02" discountAmount="1201.22" displayMessage="catred01" name="5e937332c142d70ac486ebb3" nro="5e937384c142d70ac486ebb7" order="1" printerMessage="catred01" prorationMethod="PROPORTIONAL" unit="" usedPoints="330.00"> <apply> <item magnitude="0.000" points="100.00" qty="1.000" seq="1" value="100.00" valueWithTaxes="100.00" xprice="1000.00"/> <item magnitude="0.000" points="30.00" qty="1.000" seq="2" value="50.00" valueWithTaxes="50.00" xprice="1000.00"/> <item magnitude="0.000" points="60.00" qty="1.000" seq="3" value="27.00" valueWithTaxes="27.00" xprice="1000.00"/> <item magnitude="0.000" points="140.00" qty="2.000" seq="4" value="1024.22" valueWithTaxes="1024.22" xprice="2000.00"/> <item magnitude="0.000" points="0.00" qty="2.000" seq="5" value="0.00" valueWithTaxes="0.00" xprice="2000.00"/> </apply> </benefit> </promo> </optional> </message>
CatalogRedeemBenefit JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.5.1",
"mapversion": "5555",
"messageId": "5",
"store": "b320",
"terminal": "1",
"optional": [{
"promo": [{
"code": "catred01",
"id": "catred01",
"nro": "5e937332c142d70ac486ebb3",
"benefit": [{
"TLOGMessage": "catred01",
"account": "",
"applicationMethod": "qty",
"baseAmount": "7000.00",
"benefitType": "CatalogRedeemBenefit",
"type": "02",
"discountAmount": "1201.22",
"displayMessage": "catred01",
"name": "5e937332c142d70ac486ebb3",
"nro": "5e937384c142d70ac486ebb7",
"order": "1",
"printerMessage": "catred01",
"prorationMethod": "PROPORTIONAL",
"unit": "",
"usedPoints": "330.00",
"apply": {
"item": [
{
"magnitude": "0.000",
"points": "100.00",
"qty": "1.000",
"seq": "1",
"value": "100.00",
"valueWithTaxes": "100.00",
"xprice": "1000.00"
},
{
"magnitude": "0.000",
"points": "30.00",
"qty": "1.000",
"seq": "2",
"value": "50.00",
"valueWithTaxes": "50.00",
"xprice": "1000.00"
},
{
"magnitude": "0.000",
"points": "60.00",
"qty": "1.000",
"seq": "3",
"value": "27.00",
"valueWithTaxes": "27.00",
"xprice": "1000.00"
},
{
"magnitude": "0.000",
"points": "140.00",
"qty": "2.000",
"seq": "4",
"value": "1024.22",
"valueWithTaxes": "1024.22",
"xprice": "2000.00"
},
{
"magnitude": "0.000",
"points": "0.00",
"qty": "2.000",
"seq": "5",
"value": "0.00",
"valueWithTaxes": "0.00",
"xprice": "2000.00"
}
]
}
}]
}]
}]
}
}
<message companyId="napse" store="napse" terminal="10" date-time="2020-06-18 16:46:64" init-tck="true" messageId="7" void-trx="false" response="true" status="sales" evaluate="true" offline="false" suggest="true"> <item-add seq="1" code="315" unitprice="1000.00" xprice="1000.00" qty="1" magnitude="0" discountable="true" brand="Coca"/> <item-add seq="2" code="315" unitprice="1000.00" xprice="1000.00" qty="1" magnitude="0" discountable="true" brand="Coca"/> </message>
GeneralBenefit - Request JSON
{
"message": {
"companyId": "napse",
"store": "napse",
"terminal": "10",
"date-time": "2020-06-18 16:46:64",
"init-tck": "true",
"messageId": "7",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"offline": "false",
"suggest": "true",
"item-add": [
{
"seq": "1",
"code": "315",
"unitprice": "1000.00",
"xprice": "1000.00",
"qty": "1",
"magnitude": "0",
"discountable": "true",
"brand": "Coca"
},
{
"seq": "2",
"code": "315",
"unitprice": "1000.00",
"xprice": "1000.00",
"qty": "1",
"magnitude": "0",
"discountable": "true",
"brand": "Coca"
}
]
}
}
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT" mapversion="47" messageId="7" store="napse" terminal="10"> <optional> <promo code="p2" id="Copia - p2" nro="5ea190989db04432e4db2c22"> <benefit TLOGMessage="p2" account="" applicationMethod="resume" baseAmount="2000.00" benefitType="GeneralBenefit" displayMessage="p2" generalid="2" generaltype="3" hasLimit="true" name="5ea190989db04432e4db2c22" nro="5ea190989db04432e4db2c20" order="1" printerMessage="p2" qty="2.000"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="0.00" valueWithTaxes="0.00" xprice="1000.00"/> <item magnitude="0.000" qty="1.000" seq="2" value="0.00" valueWithTaxes="0.00" xprice="1000.00"/> </apply> </benefit> </promo> </optional> </message>
GeneralBenefit - Response JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.0.0-SNAPSHOT",
"mapversion": "47",
"messageId": "7",
"store": "napse",
"terminal": "10",
"optional": [{
"promo": [{
"code": "p2",
"id": "Copia - p2",
"nro": "5ea190989db04432e4db2c22",
"benefit": [{
"TLOGMessage": "p2",
"account": "",
"applicationMethod": "resume",
"baseAmount": "2000.00",
"benefitType": "GeneralBenefit",
"displayMessage": "p2",
"generalid": "2",
"generaltype": "3",
"hasLimit": "true",
"name": "5ea190989db04432e4db2c22",
"nro": "5ea190989db04432e4db2c20",
"order": "1",
"printerMessage": "p2",
"qty": "2.000",
"apply": {
"item": [
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "0.00",
"valueWithTaxes": "0.00",
"xprice": "1000.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "2",
"value": "0.00",
"valueWithTaxes": "0.00",
"xprice": "1000.00"
}
]
}
}]
}]
}]
}
}
Prorrateo entre participantes
Cuando un beneficio, tenga tildada la opción de "Prorratear entre Participantes", el monto del descuento a otorgar será distribuido proporcionalmente entre los ítems participantes de la promoción.
Ejemplo de mensajería donde se visualiza la distribución del descuento entre los participantes.
<?xml version="1.0" encoding="UTF-8"?> <message companyId="napse" store="1" terminal="1" date-time="2021-03-01 10:35:22" init-tck="true" messageId="1" void-trx="false" response="true" limitBalances="true" status="sales" evaluate="true" map-version="7" tckpath="Y" suggest="true"> <item-add seq="1" qty="1" code="123" level1="1121" magnitude="0" brand="Kumho" xprice="150" unitprice="150" /> <item-add seq="2" qty="1" code="456" level1="1121" magnitude="0" brand="Kumho" xprice="90" unitprice="90" /> <item-add seq="4" qty="1" code="789" level1="1121" magnitude="0" brand="Kumho" xprice="75" unitprice="75" /> </message>
Prorrateo entre participantes - INPUT JSON
{
"message": {
"companyId": "napse",
"store": "1",
"terminal": "1",
"date-time": "2021-03-01 10:35:22",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"limitBalances": "true",
"status": "sales",
"evaluate": "true",
"map-version": "7",
"tckpath": "Y",
"suggest": "true",
"item-add": [
{
"seq": "1",
"qty": "1",
"code": "123",
"level1": "1121",
"magnitude": "0",
"brand": "Kumho",
"xprice": "150",
"unitprice": "150"
},
{
"seq": "2",
"qty": "1",
"code": "456",
"level1": "1121",
"magnitude": "0",
"brand": "Kumho",
"xprice": "90",
"unitprice": "90"
},
{
"seq": "4",
"qty": "1",
"code": "789",
"level1": "1121",
"magnitude": "0",
"brand": "Kumho",
"xprice": "75",
"unitprice": "75"
}
]
}
}
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT#78" mapversion="7" messageId="1" store="1" terminal="1"> <optional> <promo id="Prorratear entre Participantes" nro="603afe841082e836908173d1"> <benefit TLOGMessage="Prorratear entre Participantes" account="" applicationMethod="resume" baseAmount="75.0000" benefitType="PercentageDiscount" discountPercentage="100.0000" displayMessage="Prorratear entre Participantes" name="603afe841082e836908173d1" nro="603afed81082e836908173e1" order="1" printerMessage="Prorratear entre Participantes" prorateBCP="true" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="35.71" valueWithTaxes="150.00" xprice="150.00"/> <item magnitude="0.000" qty="1.000" seq="2" value="21.43" valueWithTaxes="90.00" xprice="90.00"/> <item magnitude="0.000" qty="1.000" seq="4" value="17.86" valueWithTaxes="75.00" xprice="75.00"/> </apply> </benefit> </promo> </optional> </message>
Prorrateo entre participantes - OUTPUT JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.0.0-SNAPSHOT#78",
"mapversion": "7",
"messageId": "1",
"store": "1",
"terminal": "1",
"optional": [{
"promo": [{
"id": "Prorratear entre Participantes",
"nro": "603afe841082e836908173d1",
"benefit": [{
"TLOGMessage": "Prorratear entre Participantes",
"account": "",
"applicationMethod": "resume",
"baseAmount": "75.0000",
"benefitType": "PercentageDiscount",
"discountPercentage": "100.0000",
"displayMessage": "Prorratear entre Participantes",
"name": "603afe841082e836908173d1",
"nro": "603afed81082e836908173e1",
"order": "1",
"printerMessage": "Prorratear entre Participantes",
"prorateBCP": "true",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "35.71",
"valueWithTaxes": "150.00",
"xprice": "150.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "2",
"value": "21.43",
"valueWithTaxes": "90.00",
"xprice": "90.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "4",
"value": "17.86",
"valueWithTaxes": "75.00",
"xprice": "75.00"
}
]
}
}]
}]
}]
}
}
Promociones Escalonadas
En el caso de beneficios con promociones escalonadas, dentro de las propiedades de los elementos aplicados (apply), se encontrará otra propiedad denominada "stagger" cuyo valor corresponde al valor del escalón aplicado si es aplicable (propiedad opcional que solo se informa en ese caso).
Por ejemplo: en la siguiente respuesta se puede observar que a los productos de secuencia 1 y 2 se le ha aplicado el escalon con valor 2 por lo cual se utilizaron 400 puntos para canjear por el descuento de 200 en total.
<message ack="0" engine="2.6" mapversion="5433" messageId="5" store="3105" terminal="8"> <optional> <promo code="canjedePuntos" id="canjedePuntos" nro="6080383cabe768428094afce"> <benefit TLOGMessage="canjedePuntos" account="" applicationMethod="resume" baseAmount="200.00" benefitType="RedeemPointsBenefit" discountAmount="200.00" displayMessage="canjedePuntos" factor="1" name="6080383cabe768428094afce" nro="60803ad5abe768428094b006" order="1" printerMessage="canjedePuntos" prorationMethod="PROPORTIONAL" type="dot" unit="" usedPoints="400.0"> <apply> <item magnitude="0.000" qty="1.000" seq="1" stagger="2.00" value="100.00" valueWithTaxes="100.00" xprice="100.00"/> <item magnitude="0.000" qty="1.000" seq="2" stagger="2.00" value="100.00" valueWithTaxes="100.00" xprice="100.00"/> </apply> </benefit> </promo> </optional> </message>
Promociones Escalonadas JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "5433",
"messageId": "5",
"store": "3105",
"terminal": "8",
"optional": [{
"promo": [{
"code": "canjedePuntos",
"id": "canjedePuntos",
"nro": "6080383cabe768428094afce",
"benefit": [{
"TLOGMessage": "canjedePuntos",
"account": "",
"applicationMethod": "resume",
"baseAmount": "200.00",
"benefitType": "RedeemPointsBenefit",
"discountAmount": "200.00",
"displayMessage": "canjedePuntos",
"factor": "1",
"name": "6080383cabe768428094afce",
"nro": "60803ad5abe768428094b006",
"order": "1",
"printerMessage": "canjedePuntos",
"prorationMethod": "PROPORTIONAL",
"type": "dot",
"unit": "",
"usedPoints": "400.0",
"apply": {
"item": [
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"stagger": "2.00",
"value": "100.00",
"valueWithTaxes": "100.00",
"xprice": "100.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "2",
"stagger": "2.00",
"value": "100.00",
"valueWithTaxes": "100.00",
"xprice": "100.00"
}
]
}
}]
}]
}]
}
}
Participantes de combo
En el caso de que la promoción contenga asociado algún combo Agrupación finita de elementos. Para mayor detalle se recomienda consultar el Manual de usuario "condición por composición"., los beneficios de la promoción que se apliquen a este combo asociado contendrán una etiqueta denominada <comboParticipants>. Dentro de ella se enumerarán los elementos que forman el combo al cual se aplica el beneficio al que pertenecen, denominados participantes de combo, de manera similar a los participantes de condición y poseyendo los mismos atributos.
Si la promoción no está definida por combos o no se exige el cálculo de participantes en el archivo de definición (mapa), <comboParticipants> no estará presente. Esta etiqueta no posee atributos.
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> <promo id="Promoción navideña" nro="1"> <benefit order="1" benefitType="FactorLoyaltyBenefit " displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" factor="2" type="points" baseAmount="165.00"> <comboParticipants> <item seq="1" code="0010" qty="2.0" magnitude="1.0" xPrice="90.0" unitPrice="50.0" /> <item seq="2" code="0011" qty="2.0" magnitude="1.0" xPrice="72.0" unitPrice="40.0" /> </comboParticipants> … elementos aplicados … </benefit> </promo> </optional> </message>
Ejemplo JSON
{
"message": {
"companyId": "sts",
"store": "MX",
"mapversion": "3241",
"messageId": "160",
"terminal": "100",
"engine": "2.6",
"ack": "0",
"optional": [{
"promo": [{
"id": "Promoción navideña",
"nro": "1",
"benefit": [{
"order": "1",
"benefitType": "FactorLoyaltyBenefit ",
"displayMessage": "",
"printerMessage": "",
"applicationMethod": "lineByLine",
"nro": "3",
"factor": "2",
"type": "points",
"baseAmount": "165.00",
"comboParticipants": [{
"item": [
{
"seq": "1",
"code": "0010",
"qty": "2.0",
"magnitude": "1.0",
"xPrice": "90.0",
"unitPrice": "50.0"
},
{
"seq": "2",
"code": "0011",
"qty": "2.0",
"magnitude": "1.0",
"xPrice": "72.0",
"unitPrice": "40.0"
}
]
}],
… elementos aplicados …
}]
}]
}]
}
}
Elementos aplicados
Los beneficios siempre son aplicados sobre artículos. Para representar esto el Motor de Promociones al informar beneficios utiliza la etiqueta <apply>, donde se enumerarán los artículos sobre los cuales debe aplicarse el beneficio. Debido a que los beneficios solo pueden ser aplicados sobre artículos, los elementos contenidos en <apply> serán siempre <item>.
A diferencia de los elementos que se informan en los participantes (ya sean de condición, como de combo), los elementos <item> que se encontrarán dentro de <apply> poseerán los siguientes atributos:
Propiedad | Tipo de dato | Descripción |
seq | Entero positivo | Número que identifica al elemento dentro de la transacción al que se aplica el beneficio. |
value | Número En caso que se asigne a un ítem un nuevo precio que sea mayor al precio de venta informado, este valor puede tomar un valor negativo. Por este motivo deberán implementarse rutinas para el manejo de este tipo de valores. | Monto total a descontar al elemento indicado por el atributo seq. |
valueWithTaxes | Número (ver value) | Monto total a descontar al elemento indicado por el atributo seq, pero considerando impuestos (ver atributo taxes). |
qty | Entero positivo | Cantidad de ítems afectados entre los cuales deberá repartirse el descuento expresado en value. |
magnitude | Real positivo | Magnitud afectada sobre la que deberá aplicarse el descuento expresado en value. Si no se definió una magnitud para el ítem, se informará como "0.0". Cuando se calculen puntos, dinero, millas, etc., si este valor es "0.0" entonces no se informará. |
points | Real positivo | Cantidad total de puntos, dinero, millas, etc. que otorga la secuencia identificada por seq. Aparece siempre que el elemento de aplicación forme parte de un beneficio LoyaltyBenefit o PercentLoyaltyBenefit para los cuales se calculan los puntos, dinero, millas, etc. |
xprice | Real positivo | Xprice o precio original de la secuencia en el momento en que se calculó el beneficio. El que sea xprice o precio original dependerá de cómo esté configurado el beneficio y sobre cuál de estos dos valores aplique (a partir de versión 2.8.0). |
Los beneficios del tipo monetario siempre informarán elementos aplicados, mientras que los no monetarios pueden no hacerlo. Por otro lado, dentro de los artículos aplicados de beneficios no monetarios el atributo value de estos artículos será siempre "0.0", dado que no existe un descuento para realizar.
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> <promo id="Promoción navideña" nro="1"> <benefit order="1" benefitType="PercentageDiscount" displayMessage="" printerMessage="" unit="" prorationMethod="PROPORTIONAL" applicationMethod="lineByLine" nro="3" Percentage="20.00" baseAmount="162.00"> <comboParticipants> <item seq="1" code="0010" qty="2.0" magnitude="1.0" xPrice="90.0" unitPrice="50.0" /> <item seq="2" code="0011" qty="2.0" magnitude="1.5" xPrice="72.0" unitPrice="40.0" /> </comboParticipants> <apply> <item seq="1" value="18.00" magnitude="0.0" qty="1.0" xprice="90.00"/> <item seq="2" value="14.40" magnitude="1.5" qty="1.0" xprice="72.00" /> </apply> </benefit> </promo> </optional> </message>
Ejemplo JSON
{
"message": {
"companyId": "sts",
"store": "MX",
"mapversion": "3241",
"messageId": "160",
"terminal": "100",
"engine": "2.6",
"ack": "0",
"optional": [{
"promo": [{
"id": "Promoción navideña",
"nro": "1",
"benefit": [{
"order": "1",
"benefitType": "PercentageDiscount",
"displayMessage": "",
"printerMessage": "",
"unit": "",
"prorationMethod": "PROPORTIONAL",
"applicationMethod": "lineByLine",
"nro": "3",
"Percentage": "20.00",
"baseAmount": "162.00",
"comboParticipants": {
"item": [
{
"seq": "1",
"code": "0010",
"qty": "2.0",
"magnitude": "1.0",
"xPrice": "90.0",
"unitPrice": "50.0"
},
{
"seq": "2",
"code": "0011",
"qty": "2.0",
"magnitude": "1.5",
"xPrice": "72.0",
"unitPrice": "40.0"
}
]
},
"apply": {
"item": [
{
"seq": "1",
"value": "18.00",
"magnitude": "0.0",
"qty": "1.0",
"xprice": "90.00"
},
{
"seq": "2",
"value": "14.40",
"magnitude": "1.5",
"qty": "1.0",
"xprice": "72.00"
}
]
}
}]
}]
}]
}
}
Elemento Redeemoptions - Canje con opciones
(A partir de Promo 7.0 - EP2)
Las opciones que propone el beneficio "canje con opciones" (RedeemWithOptionsBenefit) tienen los siguientes atributos
atributo | tipo | Descripción |
---|---|---|
id | Alfanumérico | Identificador de la opción** |
requiredPoints | Numérico | Puntos requeridos a canjear para aplicar el beneficio |
cardType | Alfanumérico | Tipo de elemento de fidelidad a la cual se puede hacer el canje de puntos de tarjeta (cardPoints) |
cardPoints | Numérico | Puntos de elementos de fidelidad requeridos a canjear para aplicar el beneficio |
benefitType | Alfanumérico | Tipo de calculo a aplicar (fixedDiscount / percentageDiscount / newPrice) |
unit | Alfanumérico | Unidad de Medida a aplicar en el calculo (qty / magnitude) |
value | Numérico | Valor aplicar en el calculo según el benefitType (fixedDiscount:DescuentoFijo, percentageDiscount:porcentaje, newPrice: nuevoPrecio) a su vez a este valor se le restara el valuePoints del item-apply |
Ejemplo:
<redeemOptions> <option benefitType="percentageDiscount" cardPoints="200.0" cardType="089" id="5e567f0506773d1c14528761_0" requiredPoints="100.0" unit="qty" value="10.0"/> <option benefitType="percentageDiscount" cardPoints="1000.0" cardType="089" id="5e567f0506773d1c14528761_2" requiredPoints="0.0" unit="qty" value="20.0"/> <option benefitType="percentageDiscount" cardPoints="0.0" cardType="-" id="5e567f0506773d1c14528761_3" requiredPoints="500.0" unit="qty" value="20.0"/> </redeemOptions>
RedeemOptions JSON
{
"redeemOptions": {
"option": [
{
"benefitType": "percentageDiscount",
"cardPoints": "200.0",
"cardType": "089",
"id": "5e567f0506773d1c14528761_0",
"requiredPoints": "100.0",
"unit": "qty",
"value": "10.0"
},
{
"benefitType": "percentageDiscount",
"cardPoints": "1000.0",
"cardType": "089",
"id": "5e567f0506773d1c14528761_2",
"requiredPoints": "0.0",
"unit": "qty",
"value": "20.0"
},
{
"benefitType": "percentageDiscount",
"cardPoints": "0.0",
"cardType": "-",
"id": "5e567f0506773d1c14528761_3",
"requiredPoints": "500.0",
"unit": "qty",
"value": "20.0"
}
]
}
}
Para mas Información sobre el beneficio ver Anexo I - Canje como opciones en este documento.
Sugerencias
Las sugerencias agregan al mensaje de respuesta aquellas promociones que no han sido otorgadas, ya sea porque la condición de la misma no puede ser verdadera o el combo no se pudo formar, o el beneficio no se pudo aplicar. Esta información puede ser utilizada por el vendedor para ofrecer las condiciones necesarias para que la promoción se aplique antes de proceder a cerrar la venta. Las sugerencias se representan con la etiqueta <suggestions> que aparecerá posterior a la última etiqueta <optional>. De no existir sugerencias, la etiqueta <suggestions> no aparecerá en el mensaje de respuesta. Esta etiqueta no posee atributos.
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> … promociones que componen la opción … </optional> <optional> … promociones que componen la opción … </optional> <suggestions> … promociones que pueden ser sugeridas … </suggestions> </message>
Ejemplo JSON
{
"message": {
"companyId": "sts",
"store": "MX",
"mapversion": "3241",
"messageId": "160",
"terminal": "100",
"engine": "2.6",
"ack": "0",
"optional": [{
… promociones que componen la opción … ,
… promociones que componen la opción …
],
"suggestions": {… promociones que pueden ser sugeridas …}
}
}
Promociones sugeridas
Como se mencionó anteriormente, cada una de las sugerencias contendrá una o más promociones. Estas estarán identificadas por su nombre. Las promociones estarán representadas con la etiqueta <promo>, teniendo el atributo id representando su nombre.
Propiedad | Tipo de dato | Descripción |
id | Alfanumérico | Nombre de la promoción. |
descriptor | Alfanumérico | Descripción de sugerencia de la promoción. Puede no estar en la etiqueta si no fue especificado para la promoción que se sugiere. |
item-seq | Lista de números | Las secuencias de tipo ítem que hacen posible que la promoción sea sugerida. Si no hubiera secuencias de este tipo para la promoción, entonces este atributo no se incluye en la etiqueta. |
payment-seq | Lista de números | Las secuencias de tipo medio de pago que hacen posible que la promoción sea sugerida. Si no hubiera secuencias de este tipo para la promoción, entonces este atributo no se incluye en la etiqueta. |
customer-seq | Lista de números | Las secuencias de tipo cliente que hacen posible que la promoción sea sugerida. Si no hubiera secuencias de este tipo para la promoción, entonces este atributo no se incluye en la etiqueta. |
event-seq | Lista de números | Las secuencias de tipo evento que hacen posible que la promoción sea sugerida. Si no hubiera secuencias de este tipo para la promoción, entonces este atributo no se incluye en la etiqueta. |
coupon-seq | Lista de números | Las secuencias de tipo cupón que hacen posible que la promoción sea sugerida. Si no hubiera secuencias de este tipo para la promoción, entonces este atributo no se incluye en la etiqueta. |
loyaltycard-seq | Lista de Elementos de fidelidad de Fidelidad | Las secuencias de tipo elementos de fidelidad de fidelidad que hacen posible que la promoción sea sugerida. Si no hubiera secuencias de este tipo para la promoción, entonces este atributo no se incluye en la etiqueta. |
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <suggestions> <promo id="Promoción navideña" descriptor="llevando un árbol de navidad te regalamos las guirnaldas" item-seq="1,2,3"/> <promo id="Promoción 2x1 en juguetes" item-seq="1,2" coupon-seq="2" payment-seq="1"/> </suggestions> </message>
Ejemplo JSON
{
"message": {
"companyId": "sts",
"store": "MX",
"mapversion": "3241",
"messageId": "160",
"terminal": "100",
"engine": "2.6",
"ack": "0",
"suggestions": {
"promo": [
{
"id": "Promoción navideña",
"descriptor": "llevando un árbol de navidad te regalamos las guirnaldas",
"item-seq": "1,2,3"
},
{
"id": "Promoción 2x1 en juguetes",
"item-seq": "1,2",
"coupon-seq": "2",
"payment-seq": "1"
}
]
}
}
}
Sugerencias sujetas a stock
Se pueden sugerir promociones a los clientes, basados en el stock existente. Para ello se carga el documento .txt con el SKU de los productos en stock.
El archivo de stock, se encontrará en el raíz del motor (o carpeta configurada), será texto plano en el formato de 1 SKU por linea. Por ejemplo: el archivo de texto stock.txt muestra que cada una de las líneas contiene un SKU:
El motor, ante la presencia de una promoción con sugerencia con control de stock, va a:
- Buscar si existe el archivo de stock configurado, si no existe, la promocion no sera sugerida.
- Si el archivo de stock existe, si ningún producto en el conjunto de aplicación (SKUs) posee stock (figura en el archivo), no será sugerida.
El archivo de stock será actualizado cada vez que se lean los mapas (10 min default).
Fidelidad
Valores reservados para la propiedad Status
Históricamente, el valor de la propiedad Status, era de libre uso y no tenía restricciones. Actualmente existen valores específicos y reservados para la propiedad "status" que indicarán al motor determinadas acciones a realizar con la Consola de PROMO Central. Estas acciones son:
LoyaltyValidation
A partir de 7.2.3 al realizar un loyaltyValidation de un cliente, además de mostrar los datos del cliente, si este posee tarjetas o cupones, mostrará la misma información que al realizar un loyaltyValidation de tarjetas o cupones por separado".
<message companyId="2" store="1" terminal="1" date-time="2023-03-17 19:300:00" init-tck="false" messageId="1" void-trx="false" response="true" status="loyaltyvalidation" evaluate="true" suggest="false"> <customer-add seq="1" id="1"/> </message>
Request JSON
{
"message": {
"companyId": "2",
"store": "1",
"terminal": "1",
"date-time": "2023-03-17 19:300:00",
"init-tck": "false",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "loyaltyvalidation",
"evaluate": "true",
"suggest": "false",
"customer-add": [{
"seq": "1",
"id": "1"
}]
}
}
----- message ------ <?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="2" engine="7.2.4#264" mapversion="3" messageId="1" store="1" terminal="1" transaction="2_1_1_20230318000000"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="1" email="[email protected]" identifier="12345" lastName="perez" limitedBenefits="" name="juan" segment="" seq="1" type="empleado"> <coupon ack="0" amount="0.00" barcode="1010010016471" couponId="1"/> <coupon ack="0" amount="0.00" barcode="1020010016470" couponId="2"/> <loyaltycard ack="0" amount="0.00" amountChargeLimit="0.00" contract="" id="1000000009" status="Activa" type="1" usePartial="true"/> </customer> </customers> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "2",
"engine": "7.2.4#264",
"mapversion": "3",
"messageId": "1",
"store": "1",
"terminal": "1",
"transaction": "2_1_1_20230318000000",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {
"customer": [{
"code": "1",
"email": "promonapse@gmail.com",
"identifier": "12345",
"lastName": "perez",
"limitedBenefits": "",
"name": "juan",
"segment": "",
"seq": "1",
"type": "empleado",
"coupon": [
{
"ack": "0",
"amount": "0.00",
"barcode": "1010010016471",
"couponId": "1"
},
{
"ack": "0",
"amount": "0.00",
"barcode": "1020010016470",
"couponId": "2"
}
],
"loyaltycard": [{
"ack": "0",
"amount": "0.00",
"amountChargeLimit": "0.00",
"contract": "",
"id": "1000000009",
"status": "Activa",
"type": "1",
"usePartial": "true"
}]
}]
},
"redeemTable": {}
}
}
}
A partir de Promo 7.2.6 en la respuesta del mensaje loyaltyvalidation se envía el campo: paymentCode. Dicho campo utiliza el catálgo catalogPaymetCode.catalog.
<message ack="0" companyId="napse" engine="7.2.5" mapversion="1" messageId="1" store="1" terminal="10" transaction="napse_1_10_20230413105251"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="123456" email="[email protected]" identifier="123456" lastName="ELII" limitedBenefits="" name="ELIENE" segment="" seq="1" type="01"> <loyaltycard ack="0" amount="0.00" amountChargeLimit="0.00" contract="" id="1000000000000000" paymentCode="PC1" status="Activa" type="ef1" usePartial="true"/> </customer> </customers> <redeemTable/> </loyalty></message>
Ejemplo de respuesta mensaje LoyaltyValidation de Cliente con formato JSON:
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.2.5",
"mapversion": "1",
"messageId": "1",
"store": "1",
"terminal": "10",
"transaction": "napse_1_10_20230413105251",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {
"customer": [{
"code": "123456",
"email": "eliene.costa@gmail.com",
"identifier": "123456",
"lastName": "ELII",
"limitedBenefits": "",
"name": "ELIENE",
"segment": "",
"seq": "1",
"type": "01",
"loyaltycard": [{
"ack": "0",
"amount": "0.00",
"amountChargeLimit": "0.00",
"contract": "",
"id": "1000000000000000",
"paymentCode": "PC1",
"status": "Activa",
"type": "ef1",
"usePartial": "true"
}]
}]
},
"redeemTable": {}
}
}
}
<message ack="0" companyId="napse" engine="7.2.5" mapversion="1" messageId="1" store="1" terminal="10" transaction="napse_1_10_20230413105251"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="0.00" amountChargeLimit="0.00" contract="" customer="123456" id="1000000000000000" paymentCode="PC1" seq="1" type="ef1" usePartial="true"/> </loyaltycards> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty></message>
Ejemplo de respuesta mensaje LoyaltyValidation de Tarjeta JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.2.5",
"mapversion": "1",
"messageId": "1",
"store": "1",
"terminal": "10",
"transaction": "napse_1_10_20230413105251",
"loyalty": {
"loyaltycards": {
"loyaltycard": [{
"ack": "0",
"amount": "0.00",
"amountChargeLimit": "0.00",
"contract": "",
"customer": "123456",
"id": "1000000000000000",
"paymentCode": "PC1",
"seq": "1",
"type": "ef1",
"usePartial": "true"
}]
},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Existen dos funciones opcionales (a habilitar) respecto a validación de clientes:
- Creación de clientes: Si se envía información de cliente completa (es decir email o identifier) y el cliente no existe en Promo, el mismo será dado de alta automáticamente.
- Actualización de clientes: Si se recibe información de un cliente completa y el cliente existe, entonces se considera que la validación no es una mera consulta de datos sino que al enviar datos como el "nombre del cliente" se requiere hacer una actualización de los mismos.
(Ver también,Engine Response - LoyaltyValidation)
Esta acción no requiere tercer mensaje (commit o rollback), y cancela el elemento fidelidad que se informe.
Extensión en consulta de Elemento de Fidelidad con el loyaltyValidation
Actualmente, desde el punto de venta puede enviarse una consulta de elemento de fidelidad utilizando el status LoyaltyValidation, en donde se informa el Id del elemento y el tipo, y la consola retorna todos los datos referentes al elemento consultada.
En caso de enviar solo el Type del elemento en una consulta de LoyaltyValidation, se devolverá el próximo número del elemento inactivo y sin cliente asociado disponible.
Por ejemplo, el último número de elemento activo para el tipo "aaa" es el 333000000000000007, al realizar la consulta solo con el tipo de elemento, Promo devolverá el id de tarjeta 333000000000000008 que corresponde al próximo número de elemento inactivo y sin cliente disponible.
<?xml version="1.0" encoding="UTF-8"?> <message companyId="2" store="1" terminal="2" date-time="2023-04-10 12:00:00" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyvalidation" evaluate="true" tckpath="Y" suggest="false"> <loyaltycard-add seq="1" type="1" /> </message>
Input Message JSON
{
"message": {
"companyId": "2",
"store": "1",
"terminal": "2",
"date-time": "2023-04-10 12:00:00",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "loyaltyvalidation",
"evaluate": "true",
"tckpath": "Y",
"suggest": "false",
"loyaltycard-add": [{
"seq": "1",
"type": "1"
}]
}
}
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="2" engine="7.2.4#264" mapversion="0" messageId="1" store="1" terminal="2" transaction="2_1_2_20230410130000"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9500" cardType="1" info="1" seq="1" type="QUERY"/> </errors> <customers> <customer code="1" email="[email protected]" identifier="12345" lastName="perez" limitedBenefits="" name="juan" segment="" seq="1" type="empleado"> <coupon ack="0" amount="0.00" barcode="1010010016471" couponId="1"/> <coupon ack="0" amount="0.00" barcode="1020010016470" couponId="2"/> <loyaltycard ack="0" amount="0.00" amountChargeLimit="0.00" contract="" id="1000000009" status="Activa" type="1" usePartial="true"/> </customer> </customers> <redeemTable/> </loyalty> </message>
Output Message JSON
{
"message": {
"ack": "0",
"companyId": "2",
"engine": "7.2.4#264",
"mapversion": "0",
"messageId": "1",
"store": "1",
"terminal": "2",
"transaction": "2_1_2_20230410130000",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {
"error": [{
"ack": "9500",
"cardType": "1",
"info": "1",
"seq": "1",
"type": "QUERY"
}]
},
"customers": {
"customer": [{
"code": "1",
"email": "promonapse@gmail.com",
"identifier": "12345",
"lastName": "perez",
"limitedBenefits": "",
"name": "juan",
"segment": "",
"seq": "1",
"type": "empleado",
"coupon": [
{
"ack": "0",
"amount": "0.00",
"barcode": "1010010016471",
"couponId": "1"
},
{
"ack": "0",
"amount": "0.00",
"barcode": "1020010016470",
"couponId": "2"
}
],
"loyaltycard": [{
"ack": "0",
"amount": "0.00",
"amountChargeLimit": "0.00",
"contract": "",
"id": "1000000009",
"status": "Activa",
"type": "1",
"usePartial": "true"
}]
}]
},
"redeemTable": {}
}
}
}
LoyaltyActivation
Realiza la activación de un elemento de fidelidad.
Para activar un elemento de fidelidad que se encuentre en estado inactiva podrá enviarse un mensaje con Status="loyaltyActivation".
Deberá enviarse con el formato y atributos que se muestran en los siguientes ejemplos.
<message companyId="2" store="1" terminal="1" date-time="2023-04-10 12:00:00" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyactivation" evaluate="true" suggest="false"> <loyaltycard-add seq="1" id="4010000000"/> </message>
Request JSON
{
"message": {
"companyId": "2",
"store": "1",
"terminal": "1",
"date-time": "2023-04-10 12:00:00",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "loyaltyactivation",
"evaluate": "true",
"suggest": "false",
"loyaltycard-add": [{
"seq": "1",
"id": "4010000000"
}]
}
}
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="2" engine="7.2.4#264" mapversion="0" messageId="1" store="1" terminal="1" transaction="2_1_1_20230410120000"> <loyalty> <loyaltycards> <loyaltycard ack="0" id="4010000000" seq="1" type="3"/> </loyaltycards> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "2",
"engine": "7.2.4#264",
"mapversion": "0",
"messageId": "1",
"store": "1",
"terminal": "1",
"transaction": "2_1_1_20230410120000",
"loyalty": {
"loyaltycards": {
"loyaltycard": [{
"ack": "0",
"id": "4010000000",
"seq": "1",
"type": "3"
}]
},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
También pude realizarse la inactivación de una elemento de fidelidad activa con el LoyaltyActivation, agregando en el tag <loyaltycard-add/> el status="DISABLED".
<message companyId="2" store="1" terminal="1" date-time="2023-04-10 17:00:00" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyactivation" evaluate="true" suggest="false"> <loyaltycard-add seq="1" id="4010000000" status="DISABLED"/> </message>
Request JSON
{
"message": {
"companyId": "2",
"store": "1",
"terminal": "1",
"date-time": "2023-04-10 17:00:00",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "loyaltyactivation",
"evaluate": "true",
"suggest": "false",
"loyaltycard-add": [{
"seq": "1",
"id": "4010000000",
"status": "DISABLED"
}]
}
}
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="2" engine="7.2.4#264" mapversion="0" messageId="1" store="1" terminal="1" transaction="2_1_1_20230410170000"> <loyalty> <loyaltycards> <loyaltycard ack="0" id="4010000000" seq="1" type="3"/> </loyaltycards> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "2",
"engine": "7.2.4#264",
"mapversion": "0",
"messageId": "1",
"store": "1",
"terminal": "1",
"transaction": "2_1_1_20230410170000",
"loyalty": {
"loyaltycards": {
"loyaltycard": [{
"ack": "0",
"id": "4010000000",
"seq": "1",
"type": "3"
}]
},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
(Ver también Engine Response – LoyaltyActivation)
Esta acción no requiere tercer mensaje (commit o rollback), y cancela el elemento fidelidad que se informe.
Crear Elementos de Fidelidad
El status "loyaltyActivation" es un valor para la propiedad status del elemento loyaltcard, un valor CREATE para indicar que se desea crear el elemento.
Si se especifica un cvv el mismo será registrado y asociado al elemento de fidelidad que se ha creado.
En la siguiente figura se muestra un tipo de ejemplo denominado tn1
Procedemos a la creación sin carga del primer elemento de fidelidad:
<message companyId="2" store="2" terminal="10" date-time="2023-04-10 17:00:00" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyActivation" evaluate="false" offline="false"> <loyaltycard-add seq="1" id="4010000010" type="3" status="CREATE" /> </message>
Request JSON
{
"message": {
"companyId": "2",
"store": "2",
"terminal": "10",
"date-time": "2023-04-10 17:00:00",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "loyaltyActivation",
"evaluate": "false",
"offline": "false",
"loyaltycard-add": [{
"seq": "1",
"id": "4010000010",
"type": "3",
"status": "CREATE"
}]
}
}
La respuesta es: (Ack =0 es correcto)
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="2" engine="7.2.4#264" mapversion="0" messageId="1" store="2" terminal="10" transaction="2_2_10_20230410170000"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="0.00" id="4010000010" seq="1" type="3"/> </loyaltycards> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "2",
"engine": "7.2.4#264",
"mapversion": "0",
"messageId": "1",
"store": "2",
"terminal": "10",
"transaction": "2_2_10_20230410170000",
"loyalty": {
"loyaltycards": {
"loyaltycard": [{
"ack": "0",
"amount": "0.00",
"id": "4010000010",
"seq": "1",
"type": "3"
}]
},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Adicionalmente si se desea dar una carga inicial se puede agregar la propiedad "chargeAmount" del elemento loyaltyCard. De esta forma ademas de crearlo, se cargara iniciamente ese saldo.
Luego procedemos a crear un segundo con saldo:
<message companyId="2" store="2" terminal="10" date-time="2023-04-10 17:00:00" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyActivation" evaluate="false" offline="false"> <loyaltycard-add seq="1" id="4010000012" type="3" status="CREATE" chargeAmount="105.00" /> </message>
Request JSON
{
"message": {
"companyId": "2",
"store": "2",
"terminal": "10",
"date-time": "2023-04-10 17:00:00",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "loyaltyActivation",
"evaluate": "false",
"offline": "false",
"loyaltycard-add": [{
"seq": "1",
"id": "4010000012",
"type": "3",
"status": "CREATE",
"chargeAmount": "105.00"
}]
}
}
Respuesta
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="2" engine="7.2.4#264" mapversion="0" messageId="1" store="2" terminal="10" transaction="2_2_10_20230410170000"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="105.00" id="4010000012" seq="1" type="3"/> </loyaltycards> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "2",
"engine": "7.2.4#264",
"mapversion": "0",
"messageId": "1",
"store": "2",
"terminal": "10",
"transaction": "2_2_10_20230410170000",
"loyalty": {
"loyaltycards": {
"loyaltycard": [{
"ack": "0",
"amount": "105.00",
"id": "4010000012",
"seq": "1",
"type": "3"
}]
},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Si observamos el detalle de alguna de ellas:
Cambio y reseteo de CVV de un elemento de fidelidad (CVVCHANGE y CVVRESET)
Se habilita la posibilidad de realizar el cambio o el reset del CVV de un elemento de fidelidad.
Es requerido que el tipo de elemento al que pertenezca el elemento de fidelidad a la que se le desea realizar el cambio o reset de CVV tenga tildada la opción de "CVV Requerido".
Las acciones de cambio y de reset del cvv de un elemento de fidelidad podrán realizarse tanto con elementos en estado activos como inactivos.
LoyaltyTransfer
Realiza la transferencia de saldo de un elemento de fidelidad a otra del mismo tipo.
Para poder realizar una transferencia de saldos, tanto el elemento de origen (la que da saldo) como la de destino (la que recibe saldo) deben ser del mismo tipo.
En la seq=1 enviada por el POS se informara la tarjeta origen, es decir, a quien se le descontaran los puntos, dinero, millas, etc.
En la seq=2 enviada por el POS se informara la tarjeta destino, es decir, la que recibirá los puntos, dinero, millas, etc.
(Ver también Manual de Usuario, "Conceptos de Tarjetas de Fidelidad" para más detalle sobe los distintos tipos de transferencia posible,)
<message companyId="sts" store="1" terminal="1" date-time="2017-12-29 16:49:16" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyTransfer" msg-version="9" map-version="1"> <loyaltycard-add seq="1" type="2" id="2220000000000"/> <loyaltycard-add seq="2" type="2" id="2220000000001" chargeAmount="4" /> </message>
Request JSON
{
"message": {
"companyId": "sts",
"store": "1",
"terminal": "1",
"date-time": "2017-12-29 16:49:16",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "loyaltyTransfer",
"msg-version": "9",
"map-version": "1",
"loyaltycard-add": [
{
"seq": "1",
"type": "2",
"id": "2220000000000"
},
{
"seq": "2",
"type": "2",
"id": "2220000000001",
"chargeAmount": "4"
}
]
}
}
(Ver también Engine Response - LoyaltyTransfer)
Se requiere COMMIT o ROLLBACK para confirmar o reversar la transacción.
LoyaltyVoid
Este status se utilizara para anular elementos de fidelidad que iban a ser emitidos u otorgados, pero donde la transacción en curso que los emitía no prospero.
Los cupones dados de baja por medio de este mensaje quedaran en estado "Rechazados" (rejected).
<message companyId="2" store="2" terminal="010" date-time="2023-04-10 17:00:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="loyaltyVoid"> <coupon-add seq="1" qty="1" id="1030BC0030007" type="3"/> <loyaltycard-add seq="2" id="4010000002" type="3" /> </message>
Request JSON
{
"message": {
"companyId": "2",
"store": "2",
"terminal": "010",
"date-time": "2023-04-10 17:00:00",
"messageId": "0010",
"void-trx": "false",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"status": "loyaltyVoid",
"coupon-add": [{
"seq": "1",
"qty": "1",
"id": "1030BC0030007",
"type": "3"
}],
"loyaltycard-add": [{
"seq": "2",
"id": "4010000002",
"type": "3"
}]
}
}
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="2" engine="7.2.4#264" mapversion="0" messageId="0010" store="2" terminal="010" transaction="2_2_010_20230410170000"> <loyalty> <loyaltycards> <loyaltycard ack="0" id="4010000002" seq="2" type="3"/> </loyaltycards> <coupons> <coupon ack="0" amount="0.00" barcode="1030BC0030007" couponId="1030BC0030007" seq="1"/> </coupons> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "2",
"engine": "7.2.4#264",
"mapversion": "0",
"messageId": "0010",
"store": "2",
"terminal": "010",
"transaction": "2_2_010_20230410170000",
"loyalty": {
"loyaltycards": {
"loyaltycard": [{
"ack": "0",
"id": "4010000002",
"seq": "2",
"type": "3"
}]
},
"coupons": {
"coupon": [{
"ack": "0",
"amount": "0.00",
"barcode": "1030BC0030007",
"couponId": "1030BC0030007",
"seq": "1"
}]
},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
(Ver también Engine Response – Loyalty Void)
Esta acción no requiere tercer mensaje (commit o rollback), y cancela el elemento fidelidad que se informe.
LoyaltyAssign
El Status "LoyaltyAssign" permitira al POS, o cualquier canal, informar a qué cliente se asocia un elemento. Se validara que el elemento no tenga previamente asociado a un cliente, que el tipo de elemento exista, y que requiera asociación vía "Canal de Ventas".
<message companyId="2" store="2" terminal="010" date-time="2023-04-10 17:30:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="loyaltyAssign"> <loyaltycard-add seq="2" id="4010000003" type="3" /> <customer-add seq="1" id="4"/> </message>
Request JSON
{
"message": {
"companyId": "2",
"store": "2",
"terminal": "010",
"date-time": "2023-04-10 17:30:00",
"messageId": "0010",
"void-trx": "false",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"status": "loyaltyAssign",
"loyaltycard-add": [{
"seq": "2",
"id": "4010000003",
"type": "3"
}],
"customer-add": [{
"seq": "1",
"id": "4"
}]
}
}
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="2" engine="7.2.4#264" mapversion="0" messageId="0010" store="2" terminal="010" transaction="2_2_010_20230410173000"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9510" amount="0.00" cardType="4010000003" id="4010000003" info="4010000003" seq="2" type="loyaltycard-assign"/> </errors> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "2",
"engine": "7.2.4#264",
"mapversion": "0",
"messageId": "0010",
"store": "2",
"terminal": "010",
"transaction": "2_2_010_20230410173000",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {
"error": [{
"ack": "9510",
"amount": "0.00",
"cardType": "4010000003",
"id": "4010000003",
"info": "4010000003",
"seq": "2",
"type": "loyaltycard-assign"
}]
},
"customers": {},
"redeemTable": {}
}
}
}
(Ver también Engine Response – Loyalty Void)
Se requiere COMMIT o ROLLBACK para confirmar o reversar la transacción.
FINISH
Indica el procesamiento del ticket en PROMO Central.
<message companyId="sts" store="00001" terminal="010" date-time="2017-01-04 12:30:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="finish" msg-version="2.0" map-version="15" suggest="true" suggest-seq="3"> .. cuerpo del mensaje ... </message>
Request JSON
{
"message": {
"companyId": "sts",
"store": "00001",
"terminal": "010",
"date-time": "2017-01-04 12:30:00",
"messageId": "0010",
"void-trx": "false",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"status": "finish",
"msg-version": "2.0",
"map-version": "15",
"suggest": "true",
"suggest-seq": "3",
.. cuerpo del mensaje ...
}
}
Otra opción con la que se cuenta para la activación de un elemento de fidelidad es mediante el envío del atributo "status" en el tag <LoyaltyCard-ADD> cuando se envía un "Finish", en donde deberá indicarse el estado ENABLED a fin de que el elemento incluido en la transacción sea activado
<message companyId="sts" store="1" terminal="1" date-time="2017-05-30 12:06:10" init-tck="true" messageId="1" void-trx="false" response="true" status="finish" evaluate="true" map-version="1" suggest="true"> <loyaltycard-add seq="2" id="3330000000002" type="3" status="ENABLED" /> </message>
Request JSON
{
"message": {
"companyId": "sts",
"store": "1",
"terminal": "1",
"date-time": "2017-05-30 12:06:10",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "finish",
"evaluate": "true",
"map-version": "1",
"suggest": "true",
"loyaltycard-add": [{
"seq": "2",
"id": "3330000000002",
"type": "3",
"status": "ENABLED"
}]
}
}
(Ver también Engine Response – Activación en Finish)
COMMIT
Confirma la transacción en curso.
<message companyId="sts" store="1" terminal="1" date-time="2017-05-30 12:06:10" init-tck="true" messageId="1" void-trx="false" response="true" status="commit" msg-version="2.0" map-version="15" suggest="true" suggest-seq="3"> ... cuerpo del mensaje ... </message>
Request JSON
{
"message": {
"companyId": "sts",
"store": "1",
"terminal": "1",
"date-time": "2017-05-30 12:06:10",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "commit",
"msg-version": "2.0",
"map-version": "15",
"suggest": "true",
"suggest-seq": "3",
... cuerpo del mensaje ...
}
}
ROLLBACK
Reversa la transacción en curso.
<message companyId="sts" store="1" terminal="1" date-time="2017-05-30 12:06:10" init-tck="true" messageId="1" void-trx="false" response="true" status="rollback" msg-version="2.0" map-version="15" suggest="true" suggest-seq="3">... cuerpo del mensaje ... </message>
Request JSON
{
"message": {
"companyId": "sts",
"store": "1",
"terminal": "1",
"date-time": "2017-05-30 12:06:10",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "rollback",
"msg-version": "2.0",
"map-version": "15",
"suggest": "true",
"suggest-seq": "3",
... cuerpo del mensaje ...
}
}
TransactionRequest
Consulta información de una transacción de PROMO determinada. (La transacción a consultar debe ser Informada en el atributo "OriginalTransaction")
<message companyId="sts" store="1" terminal="1" date-time="2017-05-30 12:06:10" init-tck="true" messageId="1" void-trx="false" response="true" status="transactionrequest" originalTransaction ="001_025_20161212134555" map-version="15" suggest="true" suggest-seq="3"> </message>
Request JSON
{
"message": {
"companyId": "sts",
"store": "1",
"terminal": "1",
"date-time": "2017-05-30 12:06:10",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "transactionrequest",
"originalTransaction": "001_025_20161212134555",
"map-version": "15",
"suggest": "true",
"suggest-seq": "3"
}
}
ReturnFinish
Registra todos los elementos de una transacción de devolución en PROMO y marca para el proceso background los elementos de fidelidad participantes de la devolución para ser procesados y reversados en caso de que aplique. Deberá informarse junto con el ReturnFinish el cambo OriginalTransaction para que la operación sea tomada correctamente.
Se requiere COMMIT o ROLLBACK para confirmar o reversar la transacción.
Se aplica en transacciones donde intervengan los siguientes elementos de fidelidad:
- Cupones emitidos (sean cupones o cupones calculados)
- Puntos otorgados (los descuenta, para devolver los puntos el POS tiene que mandar un Charge amount)
En cambio no aplica cuando en la transacción intervienen:
- Cupón calculado aplicado ( ya redimido), se debe generar otro nuevo que reemplace el anterior
- Redención de puntos (no devuelve los puntos canjeados).
En el ejemplo se han registrado cada uno de los ítem que se desean devolver, junto al cupón que recibió en la compra
<message companyId="2" store="3" terminal="1" date-time="2023-02-09 20:32:00" init-tck="true" messageId="1" void-trx="false" response="true" status="returnFinish" evaluate="true" suggest="false" originalTransaction="2_3_1_20230209200200"> <item-add seq="1" unitprice="6000" xprice="6000" qty="1" code="325"/> <coupon-add seq="3" qty="1" id="1010BCtc19411" type="tc1"/> </message>
Request ReturnFinish JSON
{
"message": {
"companyId": "2",
"store": "3",
"terminal": "1",
"date-time": "2023-02-09 20:32:00",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "returnFinish",
"evaluate": "true",
"suggest": "false",
"originalTransaction": "2_3_1_20230209200200",
"item-add": [{
"seq": "1",
"unitprice": "6000",
"xprice": "6000",
"qty": "1",
"code": "325"
}],
"coupon-add": [{
"seq": "3",
"qty": "1",
"id": "1010BCtc19411",
"type": "tc1"
}]
}
}
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="2" engine="7.2.4#262" mapversion="23" messageId="1" store="3" terminal="1" transaction="2_3_1_20230209203200"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers/> <redeemTable/> <goalsPrograms/> </loyalty> </message>
Response ReturnFinish JSON
{
"message": {
"ack": "0",
"companyId": "2",
"engine": "7.2.4#262",
"mapversion": "23",
"messageId": "1",
"store": "3",
"terminal": "1",
"transaction": "2_3_1_20230209203200",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {},
"goalsPrograms": {}
}
}
}
En el ejemplo se han registrado cada uno de los ítem que se desean devolver, junto a los elementos de fidelidad asociados al cliente: Cupón y Elemento de Fidelidad.
Devolución Total
A partir de la versión 7.2.3, no requiere que el operador tenga la necesidad de escanear todos los productos para hacer la devolución total de la compra.
En este ejemplo se observa que sólo se ingresa el ID de la transacción original, sin necesidad de ingresar los ítems de la compra:
<message companyId="2" store="3" terminal="1" date-time="2023-02-09 21:35:00" init-tck="true" messageId="1" void-trx="false" response="true" status="returnFinish" evaluate="true" suggest="false" originalTransaction="2_3_1_20230209210500"> </message>
Request ReturnFinish para una devolucion Total JSON
{
"message": {
"companyId": "2",
"store": "3",
"terminal": "1",
"date-time": "2023-02-09 21:35:00",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "returnFinish",
"evaluate": "true",
"suggest": "false",
"originalTransaction": "2_3_1_20230209210500"
}
}
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="2" engine="7.2.4#262" mapversion="23" messageId="1" store="3" terminal="1" transaction="2_3_1_20230209213500"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Response ReturnFinish para una devolución total JSON
{
"message": {
"ack": "0",
"companyId": "2",
"engine": "7.2.4#262",
"mapversion": "23",
"messageId": "1",
"store": "3",
"terminal": "1",
"transaction": "2_3_1_20230209213500",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Se observa que se ha obtenido el mismo resultado que cuando se ingresan los ítems a devolver.
Importante
Esta devolución total funcionará solamente cuando no haya devoluciones parciales previas procesadas (commit) o pendientes de procesar (commit pending). En el caso de que existan, se obtendrá un código de error 9008.
La devolución total preexistente, donde el operador escanea todos los ítems, va a seguir estando disponible y sin cambios.
El detalle de la devolución se podrá ver en la consola, Módulo de Informes, Transacciones, Detalle de Transacción.
CatalogRedeemValidation
Basado en los items que se informen en el request y teniendo en cuanta la tienda desde la cual se realiza la transacción, informará los productos existentes en la tabla de Canje de Puntos por Catálogo (explicado en este documento mas adelante).
Es importante comprender que para que se aplique una redención de Puntos por Catálogo se deberá enviar previamente este mensaje.
En el siguiente ejemplo se envia un mensaje de este tipo informando 5 codigos de Producto diferentes:
<message companyId="napse" store="b320" terminal="1" date-time="2020-04-12 19:09" messageId="5" void-trx="false" suggest="true" response="true" init-tck="true" evaluate="true" msg-version="2.4" status="catalogRedeemValidation"> <item-add seq="1" code="1000" qty="1" unitprice="1000" xprice="1000" applyCatalogRedeem="true" /> <item-add seq="2" code="3000" qty="1" unitprice="1000" xprice="1000" applyCatalogRedeem="true" /> <item-add seq="3" code="2000" qty="1" unitprice="1000" xprice="1000" applyCatalogRedeem="true" /> <item-add seq="4" code="1002" qty="2" unitprice="1000" xprice="2000" applyCatalogRedeem="true" /> <item-add seq="5" code="9004" qty="2" unitprice="1000" xprice="2000" applyCatalogRedeem="true" /> </message>
Request JSON
{
"message": {
"companyId": "napse",
"store": "b320",
"terminal": "1",
"date-time": "2020-04-12 19:09",
"messageId": "5",
"void-trx": "false",
"suggest": "true",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"msg-version": "2.4",
"status": "catalogRedeemValidation",
"item-add": [
{
"seq": "1",
"code": "1000",
"qty": "1",
"unitprice": "1000",
"xprice": "1000",
"applyCatalogRedeem": "true"
},
{
"seq": "2",
"code": "3000",
"qty": "1",
"unitprice": "1000",
"xprice": "1000",
"applyCatalogRedeem": "true"
},
{
"seq": "3",
"code": "2000",
"qty": "1",
"unitprice": "1000",
"xprice": "1000",
"applyCatalogRedeem": "true"
},
{
"seq": "4",
"code": "1002",
"qty": "2",
"unitprice": "1000",
"xprice": "2000",
"applyCatalogRedeem": "true"
},
{
"seq": "5",
"code": "9004",
"qty": "2",
"unitprice": "1000",
"xprice": "2000",
"applyCatalogRedeem": "true"
}
]
}
}
Como respuesta al anterior se recibirá la tabla correspondiente, por ejemplo:
<message ack="0" companyId="napse" engine="6.5.1" mapversion="5555" messageId="5" store="b320" terminal="1" transaction="napse_b320_1_20200411190900"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers/> <redeemTable> <redeemItem code="1000" discountType="perc" discountValue="10.00" points="100.00"/> <redeemItem code="1002" discountType="nprice" discountValue="487.89" points="70.00"/> <redeemItem code="2000" discountType="fix" discountValue="27.00" points="60.00"/> <redeemItem code="3000" discountType="perc" discountValue="5.00" points="30.00"/> </redeemTable> </loyalty> </message>
Request JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.5.1",
"mapversion": "5555",
"messageId": "5",
"store": "b320",
"terminal": "1",
"transaction": "napse_b320_1_20200411190900",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {
"redeemItem": [
{
"code": "1000",
"discountType": "perc",
"discountValue": "10.00",
"points": "100.00"
},
{
"code": "1002",
"discountType": "nprice",
"discountValue": "487.89",
"points": "70.00"
},
{
"code": "2000",
"discountType": "fix",
"discountValue": "27.00",
"points": "60.00"
},
{
"code": "3000",
"discountType": "perc",
"discountValue": "5.00",
"points": "30.00"
}
]
}
}
}
}
Ver definiciones de los elementos en las tablas correspondientes en este documento.
Fidelidad: Engine Response
Cada uno de los elementos de fidelidad informados en la respuesta a un "finish" contendrá los datos de los beneficios obtenidos por la aplicación de un beneficio.
Dentro del tag <loyalty> podrán informarse uno o varios de los siguientes elementos:
- <coupons/>
- <loyaltycards/>
- <errors/>
- <customers/>
- <redeemTable/>
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <coupons/> <loyaltycards/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Request JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170515152511",
"loyalty": {
"coupons": {},
"loyaltycards": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Las propiedades para el encabezado de la respuesta de fidelidad serán los mismos que los informados en la respuesta de cualquier otro elemento PROMO (Ver capítulo 3.1 Encabezado),
Response - LoyaltyValidation
Como respuesta a una consulta de uno o varios elementos de fidelidad
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="2" engine="7.2.4#264" mapversion="8" messageId="1" store="3" terminal="1" transaction="2_3_1_20230425090000"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="1" email="[email protected]" identifier="12345" lastName="perez" limitedBenefits="" name="juan" segment="" seq="1" type="empleado"> <loyaltycard ack="0" amount="0.00" amountChargeLimit="0.00" contract="" id="1000000009" status="Activa" type="1" usePartial="true"/> </customer> </customers> <redeemTable/> </loyalty> </message>
Response OK JSON
{
"message": {
"ack": "0",
"companyId": "2",
"engine": "7.2.4#264",
"mapversion": "8",
"messageId": "1",
"store": "3",
"terminal": "1",
"transaction": "2_3_1_20230425090000",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {
"customer": [{
"code": "1",
"email": "promonapse@gmail.com",
"identifier": "12345",
"lastName": "perez",
"limitedBenefits": "",
"name": "juan",
"segment": "",
"seq": "1",
"type": "empleado",
"loyaltycard": [{
"ack": "0",
"amount": "0.00",
"amountChargeLimit": "0.00",
"contract": "",
"id": "1000000009",
"status": "Activa",
"type": "1",
"usePartial": "true"
}]
}]
},
"redeemTable": {}
}
}
}
La propiedad useTotalAmount es retornada solo si el cupón es del tipo calculado y además no se ha enviado en la consulta el tipo. Esta propiedad indicará si el mismo es de uso total (true) o parcial (false). También hay que notar que el uso parcial implica la cancelación total del cupón pero por menos que su monto. Es decir, si poseo un cupón con valor $100, de uso parcial y en la transacción consumo solo $ 5 de ese cupón, el mismo será marcado como utilizado perdiendo en este caso los $ 95 restantes.
La propiedad amountChargeLimit es un dato de elemento del fidelidad que se da en la respuesta del loyaltyValidation y es "el límite de carga que tiene definido ese elemento".
Output – No OK (Ver capítulo 3.1.1 Valores del atributo "ack")
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="2" engine="7.2.4#264" mapversion="8" messageId="1" store="3" terminal="1" transaction="2_3_1_20230425090000"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9503" cardType="4" info="4" seq="1" type="QUERY"/> </errors> <customers> <customer code="1" email="[email protected]" identifier="12345" lastName="perez" limitedBenefits="" name="juan" segment="" seq="1" type="empleado"> <loyaltycard ack="0" amount="0.00" amountChargeLimit="0.00" contract="" id="1000000009" status="Activa" type="1" usePartial="true"/> </customer> </customers> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "2",
"engine": "7.2.4#264",
"mapversion": "8",
"messageId": "1",
"store": "3",
"terminal": "1",
"transaction": "2_3_1_20230425090000",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {
"error": [{
"ack": "9503",
"cardType": "4",
"info": "4",
"seq": "1",
"type": "QUERY"
}]
},
"customers": {
"customer": [{
"code": "1",
"email": "promonapse@gmail.com",
"identifier": "12345",
"lastName": "perez",
"limitedBenefits": "",
"name": "juan",
"segment": "",
"seq": "1",
"type": "empleado",
"loyaltycard": [{
"ack": "0",
"amount": "0.00",
"amountChargeLimit": "0.00",
"contract": "",
"id": "1000000009",
"status": "Activa",
"type": "1",
"usePartial": "true"
}]
}]
},
"redeemTable": {}
}
}
}
En el caso del Tag "errors", la respuesta dependerá del elemento de fidelidad informado. En el caso particular de Elementos de fidelidad se informaran junto a las propiedades comunes, las propiedades amount, cardType, id, customer, contract, amountChargeLimit, nextExpDate, nextExpValue y usePartial solo en los casos en que esta información se encuentre disponible (es decir se pueda recuperar el tipo de elemento de fidelidad por ejemplo) tal como sucede en el caso de respuesta sin errores (ack=0).
Nota: Cuando el elemento de fidelidad que se consulte este inactiva, se informara en el atributo "amount" el saldo del elemento de fidelidad al momento de la consulta y en "cardType" el tipo de elemento.
(ver también Engine Request – loyaltyValidation)
Response - Cupones
Se agrega al mensaje de respuesta aquellos cupones que han sido otorgados como resultado de los beneficios de una promoción. Vale aclarar que se trata del detalle de los cupones otorgados, es decir, si como resultado de evaluar una promoción han sido otorgados X cantidad de cupones de algún tipo, entonces la respuesta de fidelidad contendrá el detalle de esos X cupones otorgados.
<message ack="0" companyId="2" engine="7.2.4#264" mapversion="8" messageId="1" store="3" terminal="2" transaction="2_3_2_20230425120000"> <loyaltycards/> <coupons> <coupon ack="0" barcode="1030BC0031172" benefitNro="58d2a8f8ef5a63133c3ca31d" couponId="TC_IM" format="PRINTED" encoding="EAN13" promotionName="Emisión C-impreso" promotionNro="58d2acdaef5a63133c3ca346">*<!\[CDATA\[.....\]\]>* </coupon> </coupons> <errors/> <customers/> </message>
Request JSON
{
"message": {
"ack": "0",
"companyId": "2",
"engine": "7.2.4#264",
"mapversion": "8",
"messageId": "1",
"store": "3",
"terminal": "2",
"transaction": "2_3_2_20230425120000",
"loyaltycards": {},
"coupons": {
"coupon": [{
"ack": "0",
"barcode": "1030BC0031172",
"benefitNro": "58d2a8f8ef5a63133c3ca31d",
"couponId": "TC_IM",
"format": "PRINTED",
"encoding": "EAN13",
"promotionName": "Emisión C-impreso",
"promotionNro": "58d2acdaef5a63133c3ca346",
"cdata": respuesta de consola codificada en base64
}]
},
"errors": {},
"customers": {}
}
}
Como hemos mencionado por cada uno de los cupones generados tendremos un elemento cupón, como se muestra en el siguiente ejemplo para 3 cupones:
<message companyId="sts" ack="0" engine="2.6" mapversion="1" messageId="1" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards/> <coupons> <coupon ack="0" barcode="1030BC0037648" format="PRINTED" benefitNro="58d2a8f8ef5a63133c3ca31d" couponId="TC_IM" format="PRINTED" encoding="EAN13" promotionName="Emisión C-impreso" promotionNro="58d2acdaef5a63133c3ca346"><!\[CDATA\[..datos libres...\]\]> </coupon> <coupon ack="0" barcode="1030BC0034111" benefitNro="58d2a8f8ef5a63133c3ca31d" couponId="TC_IM" format="PRINTED" encoding="EAN13" promotionName="Emisión C-impreso" promotionNro="58d2acdaef5a63133c3ca346"> <!CDATA\[ … datos libres …. \]> </coupon> <coupon ack="0" amount="10.0" barcode="1030BC0030588" benefitNro="5900e18ea846390de08a7afd" couponId="1" encoding="EAN13" format="PRINTED" promotionName="emite impreso calculado" promotionNro="5900e173a846390de08a7af7"><!\[CDATA\[..datos libres...\]\]> </coupon> </coupons> <errors/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"companyId": "sts",
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "1",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170515152511",
"loyalty": {
"loyaltycards": {},
"coupons": {
"coupon": [
{
"ack": "0",
"barcode": "1030BC0037648",
"format": [
"PRINTED",
"PRINTED"
],
"benefitNro": "58d2a8f8ef5a63133c3ca31d",
"couponId": "TC_IM",
"encoding": "EAN13",
"promotionName": "Emisión C-impreso",
"promotionNro": "58d2acdaef5a63133c3ca346",
"cdata": "..." (string codificada en base64 de la respuesta de consola para el campo CDATA)
},
{
"ack": "0",
"barcode": "1030BC0034111",
"benefitNro": "58d2a8f8ef5a63133c3ca31d",
"couponId": "TC_IM",
"format": "PRINTED",
"encoding": "EAN13",
"promotionName": "Emisión C-impreso",
"promotionNro": "58d2acdaef5a63133c3ca346",
"cdata": "..." (string codificada en base64 de la respuesta de consola para el campo CDATA)
},
{
"ack": "0",
"amount": "10.0",
"barcode": "1030BC0030588",
"benefitNro": "5900e18ea846390de08a7afd",
"couponId": "1",
"encoding": "EAN13",
"format": "PRINTED",
"promotionName": "emite impreso calculado",
"promotionNro": "5900e173a846390de08a7af7",
"cdata": "..." (string codificada en base64 de la respuesta de consola para el campo CDATA)
}
]
},
"errors": {},
"redeemTable": {}
}
}
}
Las propiedades de cada elemento cupón será:
Propiedad | Tipo de dato | Descripción |
barcode | Alfanumérico | Código de barras del cupón, o lo que es lo mismo, el identificador unívoco del mismo. |
ack | entero | Código de retorno |
couponId | Alfanumérico | Identificador del tipo de cupón. |
format | Alfanumérico | Formato del cupón. Los valores posibles son: PRINTED (impreso), ELECTRONIC (Electrónico), THIRD_PARTY (de terceros), EXTERNAL (Externo), PRE_PRINTED (Pre impreso). |
encoding | Alfanumérico | Formato en que deberá imprimirse el barcode (EAN13 - UPCA – CODE128) |
promotionName | Alfanumérico | Es el nombre que se le dio a la promoción que aplica el beneficio |
promotionNro | Alfanumérico | Identifica a la promoción que aplica el beneficio. |
benefitNro | Alfanumérico | Identifica al beneficio que aplica la promoción |
amount | Entero positivo | Indicara el monto asociado a un cupón cuyo monto fue calculado |
Enmascarar ID del cliente
Al confirmarse una transacción, a través del Finish, donde se aplique un beneficio de emisión de cupón o emisión de cupón calculado, siendo que la plantilla de dicho cupón contiene una o las dos variables: cutomerin, customerid, y se encuentre activa la funcionalidad de enmascarar id del cliente, el motor de Promo responderá en el campo ![CDATA[Cliente:****4556 el id del cliente enmascarado dejando solo visible la cantidad de dígitos configurados."
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message channel="T" cia="napse" ciudad="" companyId="napse" date-time="2021-09-19 17:10:10" evaluate="true" format="H" init-tck="true" limitBalances="true" localidad="1" map-version="652" status="finish" store="0013" storeChain="E" subZone="1" terminal="004" tipologia="HI" zonaprecio="E22" zone="1"> <customer-add customerType="7" email="[email protected]" id="50224556" identifier="50224556" identifierType="cpf" mobile="573013711717" name="50224556" points="277421041" publico="1" redeemPointsPriceFactor="7" segment="34,35,36,37,7710,11943,11951" seq="1" status="1" type="2"/> <item-add brand="3685" calCouponVal="7983" code="111" darPuntos="true" discountable="true" level3="1615" level4="1520" qty="1" seq="1" unitprice="100" xprice="1000"/> </message>
Input JSON
{
"message": {
"channel": "T",
"cia": "napse",
"ciudad": "",
"companyId": "napse",
"date-time": "2021-09-19 17:10:10",
"evaluate": "true",
"format": "H",
"init-tck": "true",
"limitBalances": "true",
"localidad": "1",
"map-version": "652",
"status": "finish",
"store": "0013",
"storeChain": "E",
"subZone": "1",
"terminal": "004",
"tipologia": "HI",
"zonaprecio": "E22",
"zone": "1",
"customer-add": [{
"customerType": "7",
"email": "prueba@gmail.com",
"id": "50224556",
"identifier": "50224556",
"identifierType": "cpf",
"mobile": "573013711717",
"name": "50224556",
"points": "277421041",
"publico": "1",
"redeemPointsPriceFactor": "7",
"segment": "34,35,36,37,7710,11943,11951",
"seq": "1",
"status": "1",
"type": "2"
}],
"item-add": [{
"brand": "3685",
"calCouponVal": "7983",
"code": "111",
"darPuntos": "true",
"discountable": "true",
"level3": "1615",
"level4": "1520",
"qty": "1",
"seq": "1",
"unitprice": "100",
"xprice": "1000"
}]
}
}
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="7.1.7-SNAPSHOT" mapversion="652" messageId="0" store="0013" terminal="004" transaction="napse_0013_004_20210919171010"> <loyalty> <loyaltycards/> <coupons> <coupon ack="0" amount="500.00" barcode="1280130046478" benefitNro="6147bcf316f79a304cceca47" couponId="190068" encoding="EAN13" format="PRINTED" promotionName="emision cupon hu 190068-4280453" promotionNro="6147bcd216f79a304cceca3d"><![CDATA[Cliente:****4556 Codigo de barras:1280130046478 Promocion:emision cupon hu 190068-4280453 Monto:500.00]]></coupon> </coupons> <errors/> <customers/> <redeemTable/> </loyalty> </message>
En este ejemplo se observa que el id del cliente es: id="50224556" y como se imprime en el cupón: ![CDATA[Cliente:****4556
output JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.1.7-SNAPSHOT",
"mapversion": "652",
"messageId": "0",
"store": "0013",
"terminal": "004",
"transaction": "napse_0013_004_20210919171010",
"loyalty": {
"loyaltycards": {},
"coupons": {
"coupon": [{
"ack": "0",
"amount": "500.00",
"barcode": "1280130046478",
"benefitNro": "6147bcf316f79a304cceca47",
"couponId": "190068",
"encoding": "EAN13",
"format": "PRINTED",
"promotionName": "emision cupon hu 190068-4280453",
"promotionNro": "6147bcd216f79a304cceca3d",
"cdata": "Q2xpZW50ZToqKioqNDU1NiBDb2RpZ28gZGUgYmFycmFzOjEyODAxMzAwNDY0NzggUHJvbW9jaW9uOmVtaXNpb24gY3Vwb24gaHUgMTkwMDY4LTQyODA0NTMgTW9udG86NTAwLjAw"
}]
},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
La respuesta del finish donde se devuelve el tempate del cupón que en XML viene en el tag CDATA, en la respuesta JSON vendrá en el campo "cdata" del cupón, codificado en base64.
<message ack="0" companyId="napse" engine="7.3.0RC3#64" mapversion="216" messageId="10" store="napse" terminal="1" transaction="napse_napse_1_20230419164015"> <loyalty> <loyaltycards/> <coupons> <coupon ack="0" amount="0.00" barcode="107pse0016475" benefitNro="644042ef469ac77238b0bd9a" couponId="16963" encoding="EAN13" format="PRINTED" promotionName="promo cupon emite" promotionNro="6440427c469ac77238b0bd8f"><![CDATA[promocionpromo cupon emite codigo de barras107pse0016475 tiendanapse TIENDAnapse]]></coupon> </coupons> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Ejemplo JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.3.0RC3#64",
"mapversion": "216",
"messageId": "10",
"store": "napse",
"terminal": "1",
"transaction": "napse_napse_1_20230419164015",
"loyalty": {
"loyaltycards": {},
"coupons": {
"coupon": [{
"ack": "0",
"amount": "0.00",
"barcode": "107pse0016475",
"benefitNro": "644042ef469ac77238b0bd9a",
"couponId": "16963",
"encoding": "EAN13",
"format": "PRINTED",
"promotionName": "promo cupon emite",
"promotionNro": "6440427c469ac77238b0bd8f",
"cdata": "cHJvbW9jaW9ucHJvbW8gY3Vwb24gZW1pdGUKCmNvZGlnbyBkZSBiYXJyYXMxMDdwc2UwMDE2NDc1Cgp0aWVuZGFuYXBzZQoKVElFTkRBbmFwc2U="
}]
},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Response - Elementos de Fidelidad
En la respuesta del motor se agregan al mensaje los datos del/los elementos de fidelidad que han sido beneficiadas como resultado de la aplicación de beneficios.
Vale aclarar que se trata del detalle de los puntos, dinero, millas, etc. otorgados, es decir, si como resultado de evaluar una promoción han sido otorgado o redimidos X cantidad de puntos, dinero, millas, etc., entonces la respuesta de fidelidad contendrá el detalle para ese elemento.
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards>… detalle de la tarjeta fidelidad … </loyaltycards> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Request JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170515152511",
"loyalty": {
"loyaltycards": {… detalle de la tarjeta fidelidad …},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Como hemos mencionado por cada uno de elementos de fidelidad tendremos un elemento, como en el siguiente ejemplo:
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="10.0" id="3335999932200" seq="1" type="plata"/> <loyaltycard ack="0" amount="500.0" id="5550000000444" seq="2" type="gold"/> </loyaltycards> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170515152511",
"loyalty": {
"loyaltycards": {
"loyaltycard": [
{
"ack": "0",
"amount": "10.0",
"id": "3335999932200",
"seq": "1",
"type": "plata"
},
{
"ack": "0",
"amount": "500.0",
"id": "5550000000444",
"seq": "2",
"type": "gold"
}
]
},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Las propiedades de cada elemento de fidelidad será:
Propiedad | Tipo de dato | Descripción |
Id | Alfanumérico | Número identificador del Elemento de fidelidad |
Type | Alfanumérico | Identificador del tipo de elemento de fidelidad. |
ack | entero | Código de retorno |
amount | Número positivo | Saldo con el que quedaría el elemento de fidelidad |
cardType | Alfanumérico | Informa el tipo del elemento de fidelidad (se informara solo en el tag <errors/> cuando el ACK sea 9501 – tarjeta inactiva) |
Response - Activación del elemento de fidelidad (en LoyaltyActivation)
Response OK (ACK="0" no se informan datos en el tag de loyaltycards)
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530124002"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "11",
"companyId": "sts",
"store": "00001",
"terminal": "010",
"transaction": "00001_010_20170530124002",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Response – No OK (Ver capítulo 3.1.1 Valores del atributo "ack")
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="2" engine="7.2.4#264" mapversion="8" messageId="1" store="1" terminal="2" transaction="2_1_2_20230410120000"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9517" cardType="3" info="3" seq="1" type="QUERY"/> </errors> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "2",
"engine": "7.2.4#264",
"mapversion": "8",
"messageId": "1",
"store": "1",
"terminal": "2",
"transaction": "2_1_2_20230410120000",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {
"error": [{
"ack": "9517",
"cardType": "3",
"info": "3",
"seq": "1",
"type": "QUERY"
}]
},
"customers": {},
"redeemTable": {}
}
}
}
(Ver también Engine Request - LoyaltyActivation)
Response - Activación del elemento de fidelidad (en Finish)
Response OK (ACK="0" y se informan los datos del elemento de fidelidad que se esta activando")
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170530124539"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="0.0" id="3330000000002" seq="2" type="3"/> </loyaltycards> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170530124539",
"loyalty": {
"loyaltycards": {
"loyaltycard": [{
"ack": "0",
"amount": "0.0",
"id": "3330000000002",
"seq": "2",
"type": "3"
}]
},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Output – No OK (Ver capítulo3.1.1 Valores del atributo "ack")
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170530124833"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9500" info="33300000002" seq="2" type="loyaltycard-consume"/> </errors> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170530124833",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {
"error": [{
"ack": "9500",
"info": "33300000002",
"seq": "2",
"type": "loyaltycard-consume"
}]
},
"customers": {},
"redeemTable": {}
}
}
}
(Ver también Engine Request – FINISH)
Response - LoyaltyTransfer
Response OK
En el mensaje de respuesta se informa en cada una de las seq el saldo final y el estado con el que quedaran los elementos de fidelidad luego de la transacción de transferencia.
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530130305"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="296.0" id="2220000000000" seq="1" type="2"/> <loyaltycard ack="0" amount="4.0" id="2220000000001" seq="2" type="2"/> </loyaltycards> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "11",
"companyId": "sts",
"store": "00001",
"terminal": "010",
"transaction": "00001_010_20170530130305",
"loyalty": {
"loyaltycards": {
"loyaltycard": [
{
"ack": "0",
"amount": "296.0",
"id": "2220000000000",
"seq": "1",
"type": "2"
},
{
"ack": "0",
"amount": "4.0",
"id": "2220000000001",
"seq": "2",
"type": "2"
}
]
},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Response– No OK (Ver capítulo 3.1.1 Valores del atributo "ack")
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530131342"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9500" info="22200000001" seq="2" type="loyaltycard-transfer"/> </errors> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "11",
"companyId": "sts",
"store": "00001",
"terminal": "010",
"transaction": "00001_010_20170530131342",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {
"error": [{
"ack": "9500",
"info": "22200000001",
"seq": "2",
"type": "loyaltycard-transfer"
}]
},
"customers": {},
"redeemTable": {}
}
}
}
(Ver también Engine Request - LoyaltyTransfer)
Response - LoyaltyVoid
Response OK – Cupón y Elementos de Fidelidad
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <errors/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170515152511",
"loyalty": {
"errors": {},
"redeemTable": {}
}
}
}
(Ver también Engine Request – LoyaltyVoid)
Imputación de saldos en elementos de fidelidad
<message companyId="sts" store="00001" terminal="010" date-time="2017-05-30 12:35:58" messageId="11" void-trx="false" response="true" init-tck="false" evaluate="false" status="finish" msg-version="9" map-version="1"> <loyaltycard-add seq="2" type="2" id="2220000000001" chargeAmount="10" /> </message>
Request JSON
{
"message": {
"companyId": "sts",
"store": "00001",
"terminal": "010",
"date-time": "2017-05-30 12:35:58",
"messageId": "11",
"void-trx": "false",
"response": "true",
"init-tck": "false",
"evaluate": "false",
"status": "finish",
"msg-version": "9",
"map-version": "1",
"loyaltycard-add": [{
"seq": "2",
"type": "2",
"id": "2220000000001",
"chargeAmount": "10"
}]
}
}
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530132245"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="10.0" id="2220000000001" seq="2" type="2"/> </loyaltycards> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "11",
"companyId": "sts",
"store": "00001",
"terminal": "010",
"transaction": "00001_010_20170530132245",
"loyalty": {
"loyaltycards": {
"loyaltycard": [{
"ack": "0",
"amount": "10.0",
"id": "2220000000001",
"seq": "2",
"type": "2"
}]
},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Response– No OK (Ver capítulo 3.1.1 Valores del atributo "ack")
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530132536"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9500" info="22200000001" seq="2" type="loyaltycard-recharge"/> </errors> <customers/> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "11",
"companyId": "sts",
"store": "00001",
"terminal": "010",
"transaction": "00001_010_20170530132536",
"loyalty": {
"loyaltycards": "",
"coupons": "",
"errors": {
"error": [{
"ack": "9500",
"info": "22200000001",
"seq": "2",
"type": "loyaltycard-recharge"
}]
},
"customers": {},
"redeemTable": {}
}
}
}
Descuento de saldo en elemento de fidelidad
<message companyId="sts" store="00001" terminal="010" date-time="2005-01-04 12:35:28" messageId="11" void-trx="false" response="true" init-tck="false" evaluate="false" status="finish" msg-version="2.0" map-version="1"> <loyaltycard-add seq="2" type="gold" id="2220000000002" consumeAmount="6" /> </message>
Request JSON
{
"message": {
"companyId": "sts",
"store": "00001",
"terminal": "010",
"date-time": "2005-01-04 12:35:28",
"messageId": "11",
"void-trx": "false",
"response": "true",
"init-tck": "false",
"evaluate": "false",
"status": "finish",
"msg-version": "2.0",
"map-version": "1",
"loyaltycard-add": [{
"seq": "2",
"type": "gold",
"id": "2220000000002",
"consumeAmount": "6"
}]
}
}
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="18.0" id="2220000000002" seq="2" type="gold"/> </loyaltycards> <coupons/> <errors/> <redeemTable/> </loyalty> </message>
Response OK JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170515152511",
"loyalty": {
"loyaltycards": {
"loyaltycard": [{
"ack": "0",
"amount": "18.0",
"id": "2220000000002",
"seq": "2",
"type": "gold"
}]
},
"coupons": {},
"errors": {},
"redeemTable": {}
}
}
}
Response – No OK (Ver capítulo 3.1.1 Valores del atributo "ack")
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9500" info="4445000002200" seq="2" type="loyaltycard-recharge"/> </errors> <redeemTable/> </loyalty> </message>
Response ERROR JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170515152511",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {
"error": [{
"ack": "9500",
"info": "4445000002200",
"seq": "2",
"type": "loyaltycard-recharge"
}]
},
"redeemTable": {}
}
}
}
Elementos de Fidelidad: Proceso de actualización de saldos
Se ha incorporado al status "loyaltyActivation" un valor para la propiedad status del elemento loyaltcard, un valor CONFIRM para indicar que se desea confirmar los puntos utilizados en una transacción previa referenciada en el atributo: "confirmationReference".
Realizar un consumo con vencimiento el 14/11:
<message companyId="test" store="1" terminal="10" date-time="2018-11-09 10:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="finish" evaluate="true" offline="false"> <loyaltycard-add seq="1" id="10012" type="t1" amount="1000" consumeAmount="10" confirmationDate="201811141400" /> <item-add seq="2" code="2" unitprice="20" xprice="10000" qty="500" discountable="true" taxes="2100" /> <item-add seq="3" code="3" unitprice="10" xprice="10000" qty="1000" discountable="true" taxes="2100" /> </message>
Ejemplo JSON
{
"message": {
"companyId": "test",
"store": "1",
"terminal": "10",
"date-time": "2018-11-09 10:51:50",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "finish",
"evaluate": "true",
"offline": "false",
"loyaltycard-add": [{
"seq": "1",
"id": "10012",
"type": "t1",
"amount": "1000",
"consumeAmount": "10",
"confirmationDate": "201811141400"
}],
"item-add": [
{
"seq": "2",
"code": "2",
"unitprice": "20",
"xprice": "10000",
"qty": "500",
"discountable": "true",
"taxes": "2100"
},
{
"seq": "3",
"code": "3",
"unitprice": "10",
"xprice": "10000",
"qty": "1000",
"discountable": "true",
"taxes": "2100"
}
]
}
}
Respuesta:
<message ack="0" companyId="test" engine="6.1.4" mapversion="0" messageId="1" store="1" terminal="10" transaction="test_1_10_20181116163505"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="35.0" id="10012" seq="1" type="t1"/> </loyaltycards> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Ejemplo JSON
{
"message": {
"ack": "0",
"companyId": "test",
"engine": "6.1.4",
"mapversion": "0",
"messageId": "1",
"store": "1",
"terminal": "10",
"transaction": "test_1_10_20181116163505",
"loyalty": {
"loyaltycards": {
"loyaltycard": [{
"ack": "0",
"amount": "35.0",
"id": "10012",
"seq": "1",
"type": "t1"
}]
},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Confirmamos la transacción con Commit:
<message companyId="test" store="1" terminal="10" date-time="2018-11-09 10:51:50" init-tck="false" messageId="1" void-trx="false" response="true" status="commit" evaluate="true" offline="false"></message>
Ejemplo JSON
{
"message": {
"companyId": "test",
"store": "1",
"terminal": "10",
"date-time": "2018-11-09 10:51:50",
"init-tck": "false",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "commit",
"evaluate": "true",
"offline": "false"
}
}
Respuesta:
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="test" engine="6.1.4" mapversion="0" messageId="1" store="1" terminal="10" transaction="test_1_10_20181116163505"/>
Ejemplo JSON
{
"message": {
"ack": "0",
"companyId": "test",
"engine": "6.1.4",
"mapversion": "0",
"messageId": "1",
"store": "1",
"terminal": "10",
"transaction": "test_1_10_20181116163505"
}
}
En la consola/Fidelidad/elemento de Fidelidad/detalle se ve como resultado el consumo de puntos en la tarjeta:
Como paso siguiente en el ejemplo, dejamos pasar el día 14-11 para observar la reversión del consumo ya que no ha sido confirmado antes de esa fecha:
Ahora vamos a realizar otra pero confirmando el consumo:
Primero como hicimos anteriormente, generamos un consumo con vencimiento 18-11
<message companyId="test" store="1" terminal="10" date-time="2018-11-09 10:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="finish" evaluate="true" offline="false"><loyaltycard-add seq="1" id="10012" type="t1" amount="1000" consumeAmount="10" confirmationDate="201811181400" /> <item-add seq="2" code="2" unitprice="20" xprice="10000" qty="500" discountable="true" taxes="2100" /> <item-add seq="3" code="3" unitprice="10" xprice="10000" qty="1000" discountable="true" taxes="2100" /> </message>
Ejemplo JSON
{
"message": {
"companyId": "test",
"store": "1",
"terminal": "10",
"date-time": "2018-11-09 10:51:50",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "finish",
"evaluate": "true",
"offline": "false",
"loyaltycard-add": [{
"seq": "1",
"id": "10012",
"type": "t1",
"amount": "1000",
"consumeAmount": "10",
"confirmationDate": "201811181400"
}],
"item-add": [
{
"seq": "2",
"code": "2",
"unitprice": "20",
"xprice": "10000",
"qty": "500",
"discountable": "true",
"taxes": "2100"
},
{
"seq": "3",
"code": "3",
"unitprice": "10",
"xprice": "10000",
"qty": "1000",
"discountable": "true",
"taxes": "2100"
}
]
}
}
Respuesta
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="test" engine="6.1.4" mapversion="0" messageId="1" store="1" terminal="10" transaction="test_1_10_20181116165337"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="35.0" id="10012" seq="1" type="t1"/> </loyaltycards> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Ejemplo JSON
{
"message": {
"ack": "0",
"companyId": "test",
"engine": "6.1.4",
"mapversion": "0",
"messageId": "1",
"store": "1",
"terminal": "10",
"transaction": "test_1_10_20181116165337",
"loyalty": {
"loyaltycards": {
"loyaltycard": [{
"ack": "0",
"amount": "35.0",
"id": "10012",
"seq": "1",
"type": "t1"
}]
},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Confirmamos la transacción:
<message companyId="test" store="1" terminal="10" date-time="2018-11-09 10:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="commit" evaluate="true" offline="false"><loyaltycard-add seq="1" id="10012" type="t1" amount="1000" consumeAmount="10" confirmationDate="201811181400" /> <item-add seq="2" code="2" unitprice="20" xprice="10000" qty="500" discountable="true" taxes="2100" /> <item-add seq="3" code="3" unitprice="10" xprice="10000" qty="1000" discountable="true" taxes="2100" /> </message>
Ejemplo JSON
{
"message": {
"companyId": "test",
"store": "1",
"terminal": "10",
"date-time": "2018-11-09 10:51:50",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "commit",
"evaluate": "true",
"offline": "false",
"loyaltycard-add": [{
"seq": "1",
"id": "10012",
"type": "t1",
"amount": "1000",
"consumeAmount": "10",
"confirmationDate": "201811181400"
}],
"item-add": [
{
"seq": "2",
"code": "2",
"unitprice": "20",
"xprice": "10000",
"qty": "500",
"discountable": "true",
"taxes": "2100"
},
{
"seq": "3",
"code": "3",
"unitprice": "10",
"xprice": "10000",
"qty": "1000",
"discountable": "true",
"taxes": "2100"
}
]
}
}
Respuesta
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="test" engine="6.1.4" mapversion="0" messageId="1" store="1" terminal="10" transaction="test_1_10_20181116165337"/>
Ejemplo JSON
{
"message": {
"ack": "0",
"companyId": "test",
"engine": "6.1.4",
"mapversion": "0",
"messageId": "1",
"store": "1",
"terminal": "10",
"transaction": "test_1_10_20181116165337"
}
}
En el detalle de movimiento del elemento de fidelidad se observa el consumo y que el identificador de transacción fue "test_1_10_20181116165337":
Ahora enviamos la confirmación
<message companyId="test" store="1" terminal="10" date-time="2018-11-09 09:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyActivation" evaluate="false" offline="false"> <loyaltycard-add seq="1" id="10012" type="t1" status="CONFIRM" confirmationReference="test_1_10_20181116165337" /> </message>
Ejemplo JSON
{
"message": {
"companyId": "test",
"store": "1",
"terminal": "10",
"date-time": "2018-11-09 09:51:50",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "loyaltyActivation",
"evaluate": "false",
"offline": "false",
"loyaltycard-add": [{
"seq": "1",
"id": "10012",
"type": "t1",
"status": "CONFIRM",
"confirmationReference": "test_1_10_20181116165337"
}]
}
}
Respuesta
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="test" engine="6.1.4" mapversion="0" messageId="1" store="1" terminal="10" transaction="test_1_10_20181116165603"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Ejemplo JSON
{
"message": {
"ack": "0",
"companyId": "test",
"engine": "6.1.4",
"mapversion": "0",
"messageId": "1",
"store": "1",
"terminal": "10",
"transaction": "test_1_10_20181116165603",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Mediante esta operación entonces el consumo ha sido confirmado y pasado el 18-11 no será reversado.
Engine Response: Tag Errors
Además de cupones y elementos de fidelidad, puede agregarse al elemento fidelidad de la respuesta, un bloque de reportes de errores. Dentro del mismo se informarán los errores en el procesamiento de determinados cupones y/o elementos de fidelidad, tanto en su emisión como en su redención.
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards/> <errors> <error ack="9505" id="4445901938700" info="4445901938700" amount= "" seq="1" type="loyaltycard-activation"/> </errors> <redeemTable/> </loyalty> </message>
Ejemplo JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170515152511",
"loyalty": {
"loyaltycards": "",
"errors": {
"error": [{
"ack": "9505",
"id": "4445901938700",
"info": "4445901938700",
"amount": "",
"seq": "1",
"type": "loyaltycard-activation"
}]
},
"redeemTable": {}
}
}
}
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <coupons/> <loyaltycards/> <errors> <error ack="9501" id="5550010012948" info="5550010012948" amount= "100" seq="1" type="loyaltycard-validation"/> </errors> <redeemTable/> </loyalty> </message>
Ejemplo JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170515152511",
"loyalty": {
"coupons": {},
"loyaltycards": {},
"errors": {
"error": [{
"ack": "9501",
"id": "5550010012948",
"info": "5550010012948",
"amount": "100",
"seq": "1",
"type": "loyaltycard-validation"
}]
},
"redeemTable": {}
}
}
}
Las propiedades de los elementos informados en el Tag <Errors/> son:
Propiedad | Tipo de dato | Descripción |
type | Alfanumérico | Informa el tipo de transacción asociado. Valores actuales son: "coupon-create", "coupon-redeem", "loyalty-redeem", "loyalty-sale", "loyalty-activation" |
ack | Alfanumérico | El valor del código de error como se ha descripto en los valores de la propiedad ack antes en este documento. Ver capítulo 3.1.1 Valores del atributo "ACK" |
id | Alfanumérico | En el caso de Cupones y Elementos de Fidelidad aquí se informa el id/barcode de los mismos |
info | Alfanumérico | Información adicional que depende del valor del campo "type". Por ejemplo puede ser el valor del tipo de cupón a generarse, el valor del barcode informado para su redención, etc. |
description | Alfanumérico | Es un atributo extra para dar una mejor lectura al error ocurrido. En el caso de los elementos de fidelidad, se puede identificar el nombre de la promociones + el número de beneficio donde ocurrió el error |
amount | Numérico | Opcional – Solo se mostrara este atributo cuando se esté informando un error para la consulta de validación (loyaltyValidation) |
seq | Entero positivo | Número que identifica al elemento dentro de la transacción al que se aplica el beneficio. |
Fidelidad: Status Extendidos
Con la finalidad de atender a necesidades especiales, como podría ser el caso de ecommerce, se han agregados versiones extendidas a algunos de los valores de status ya conocidos.
LOYALTYVALIDATIONEX
Este valor de estado unifica en un mismo mensaje lo ya conocido en loyaltyValidation mas una evaluación de Promociones (sales). Si la validación retorna errores, no se evaluaran promociones y la respuesta será la respuesta tradicional del loyaltyValidation. Si no existen errores la respuesta incluirá los resultados de la validación mas la respuesta de la evaluación de promociones.
Caso: Se envía el siguiente mensaje para validar y evaluar
<message companyId="test" store="test" terminal="001" date-time="2020-12-28 11:25" messageId="0011" void-trx="false" response="true" init-tck="true" evaluate="true" status="loyaltyvalidtionex"> <customer-add seq="1" id="12345" /> <coupon-add seq="1" id="1010BCup10000x" /> <item-add seq="1" qty="1" code="111" magnitude="0" xprice="5000" unitprice="5000" /> </message>
Request JSON
{
"message": {
"companyId": "test",
"store": "test",
"terminal": "001",
"date-time": "2020-12-28 11:25",
"messageId": "0011",
"void-trx": "false",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"status": "loyaltyvalidtionex",
"customer-add": [{
"seq": "1",
"id": "12345"
}],
"coupon-add": [{
"seq": "1",
"id": "1010BCup10000x"
}],
"item-add": [{
"seq": "1",
"qty": "1",
"code": "111",
"magnitude": "0",
"xprice": "5000",
"unitprice": "5000"
}]
}
}
Respuesta 1: Todo ocurre correctamente
<message ack="0" companyId="test" engine="2.6" mapversion="2" messageId="0014" store="test" terminal="001" transaction="test_test_001_20201228112802"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> <optional> <promo code="TEST" id="TEST" nro="5fe9e7d1abe76823b4bd151d"> <benefit TLOGMessage="TEST" account="" applicationMethod="resume" baseAmount="5000.00" benefitType="PercentageDiscount" discountPercentage="10.00" displayMessage="TEST" name="5fe9e7d1abe76823b4bd151d" nro="5fe9e84fabe76823b4bd1529" order="1" printerMessage="TEST" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="500.00" valueWithTaxes="500.00" xprice="5000.00"/> </apply> </benefit> </promo> </optional> </message>
Request JSON
{
"message": {
"ack": "0",
"companyId": "test",
"engine": "2.6",
"mapversion": "2",
"messageId": "0014",
"store": "test",
"terminal": "001",
"transaction": "test_test_001_20201228112802",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
},
"optional": [{
"promo": [{
"code": "TEST",
"id": "TEST",
"nro": "5fe9e7d1abe76823b4bd151d",
"benefit": [{
"TLOGMessage": "TEST",
"account": "",
"applicationMethod": "resume",
"baseAmount": "5000.00",
"benefitType": "PercentageDiscount",
"discountPercentage": "10.00",
"displayMessage": "TEST",
"name": "5fe9e7d1abe76823b4bd151d",
"nro": "5fe9e84fabe76823b4bd1529",
"order": "1",
"printerMessage": "TEST",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "500.00",
"valueWithTaxes": "500.00",
"xprice": "5000.00"
}]
}
}]
}]
}]
}
}
Respuesta 2: Existen errores en la validación
<message ack="8296" companyId="test" engine="2.6" mapversion="2" messageId="0011" store="test" terminal="001" transaction="test_test_001_20201228112501"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9101" id="1010BCup10000x" info="1010BCup10000x" seq="1" type="coupon-redeem"/> </errors> <customers> <customer code="123456" email="[email protected]" identifier="1" lastName="perez" limitedBenefits="" name="jorge" segment="" seq="1" type="test"/> </customers> <redeemTable/> </loyalty> </message>
Request JSON
{
"message": {
"ack": "8296",
"companyId": "test",
"engine": "2.6",
"mapversion": "2",
"messageId": "0011",
"store": "test",
"terminal": "001",
"transaction": "test_test_001_20201228112501",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {
"error": [{
"ack": "9101",
"id": "1010BCup10000x",
"info": "1010BCup10000x",
"seq": "1",
"type": "coupon-redeem"
}]
},
"customers": {
"customer": [{
"code": "123456",
"email": "jorge.perez@correo.com",
"identifier": "1",
"lastName": "perez",
"limitedBenefits": "",
"name": "jorge",
"segment": "",
"seq": "1",
"type": "test"
}]
},
"redeemTable": {}
}
}
}
Inyeccion automaticamente Segmentos en Clientes (loyaltyValidationex)
Se incluye la funcionalidad de agregar de forma automática, en la validación del cliente, los segmentos a los que este pertenece, utilizando la funcionalidad loyaltyValidationex.
IMPORTANTE
Lo segmentos podrán ser dados de alta desde consola (Negocio/Segmentos) o vía servicio REST. Para mas información sobre asociación de clientes a Segmentos Promo vía REST, ver "Servicio de importación de Segmentos" en Manual de Integración Promo - Servicios.
Cuando se reciba en Promo una consulta del tipo loyaltyValidationex y se informe un cliente, se incluirán en el mensaje de respuesta los segmentos a los que este cliente pertenece junto con el resultado de la evaluacion de promociones con el mapa vigente.
FINISHEX
Consiste en un mensaje que unifica o realiza lo conocido en Finish y dependiendo de la evaluación de este, un commit (respuesta de finish exitosa) o rollback (finish reporta un error) automático.
Caso: Se envía el siguiente mensaje para finalizar la transacción
<message companyId="test" store="test" terminal="001" date-time="2020-12-28 11:25" messageId="0011" void-trx="false" response="true" init-tck="true" evaluate="true" status="finishex"> <customer-add seq="1" id="12345" /> <coupon-add seq="1" id="1010BCup10000x" /> <item-add seq="1" qty="1" code="111" magnitude="0" xprice="5000" unitprice="5000" /> </message>
Request JSON
{
"message": {
"companyId": "test",
"store": "test",
"terminal": "001",
"date-time": "2020-12-28 11:25",
"messageId": "0011",
"void-trx": "false",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"status": "finishex",
"customer-add": [{
"seq": "1",
"id": "12345"
}],
"coupon-add": [{
"seq": "1",
"id": "1010BCup10000x"
}],
"item-add": [{
"seq": "1",
"qty": "1",
"code": "111",
"magnitude": "0",
"xprice": "5000",
"unitprice": "5000"
}]
}
}
Respuesta 1: Todo ocurre correctamente (Finish + commit exitosos)
<message ack="0" companyId="test" engine="2.6" mapversion="2" messageId="0014" store="test" terminal="001" transaction="test_test_001_20201228112802"> <loyalty><loyaltycards/> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Request JSON
{
"message": {
"ack": "0",
"companyId": "test",
"engine": "2.6",
"mapversion": "2",
"messageId": "0014",
"store": "test",
"terminal": "001",
"transaction": "test_test_001_20201228112802",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Respuesta 2: Existen errores en la validación (Finish + rollback fueron ejecutados)
<message ack="8296" companyId="test" engine="2.6" mapversion="2" messageId="0011" store="test" terminal="001" transaction="test_test_001_20201228112501"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9101" id="1010BCup10000x" info="1010BCup10000x" seq="1" type="coupon-redeem"/> </errors> <customers> <customer code="123456" email="[email protected]" identifier="1" lastName="perez" limitedBenefits="" name="jorge" segment="" seq="1" type=" test"/> </customers> <redeemTable/> </loyalty> </message>
Request JSON
{
"message": {
"ack": "8296",
"companyId": "test",
"engine": "2.6",
"mapversion": "2",
"messageId": "0011",
"store": "test",
"terminal": "001",
"transaction": "test_test_001_20201228112501",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {
"error": [{
"ack": "9101",
"id": "1010BCup10000x",
"info": "1010BCup10000x",
"seq": "1",
"type": "coupon-redeem"
}]
},
"customers": {
"customer": [{
"code": "123456",
"email": "jorge.perez@correo.com",
"identifier": "1",
"lastName": "perez",
"limitedBenefits": "",
"name": "jorge",
"segment": "",
"seq": "1",
"type": "\ntest"
}]
},
"redeemTable": {}
}
}
}
Herramienta para métricas de fidelidad
(A partir de Promo 7.2) Con el objetivo de medir los tiempos de proceso de elementos de fidelidad, se han incorporado métricas en el log de aplicación.
Se implementa la actualización en el log a nivel INFO tanto del lado consola como del motor, de las siguientes operaciones:
- LoyaltyValidation
- LoyaltyActivation
- LoyaltyTransfer
- LoyaltyVoid
- LoyaltyAssign
- FINISH
- COMMIT
- ROLLBACK
- TransactionRequest
- ReturnFinish
- CatalogRedeemValidation
LOYALTYVALIDATIONEX
- FINISHEX
- Prices
- voidTotal
- blackList
Para habilitar los cambios realizados se agregaron las siguiente propiedades en los archivos correspondientes al logging tanto del lado consola como del motor:
Habilitar logueo en consola, ir a : ..\synthesis\promo\appserver\modules\system\layers\base\com\synthesis\configuration\main\log4j.xml
Valor por defecto ERROR, pasar a INFO para habilitar la funcionalidad.
log4j.xml (consola)
Habilitar logueo en motor, ir a: ...\synthesis\promo\engine\conf\logging.properties
Valor por defecto SEVERE, pasar a INFO para habilitar la funcionalidad.
logging.properties (engine)
Adicionalmente, una vez actualizado el valor de la propiedad engine.operation.level, se cambia el nivel de logging de SEVERE a INFO de las siguientes propiedades:
- java.util.logging.FileHandler.level = INFO
- java.util.logging.ConsoleHandler.level = INFO
Resultado del cambio:
server.log
server.log 15,52,20,949 INFO [sts.console.api.ApiService@http-nio-8080-exec-2] -->loyaltyTransfer 15,52,20,974 INFO [sts.console.api.ApiService@http-nio-8080-exec-2] <--loyaltyTransfer 0.025 seconds 15,52,23,334 INFO [sts.console.api.ApiService@Actor Thread 5] ApiService.status.mapActives Starting processing at Fri Jul 23 15:52:23 ART 2021 15,52,23,335 INFO [sts.console.api.ApiService@Actor Thread 3] ApiService.status.mapActives processed Finish at Fri Jul 23 15:52:23 ART 2021 15,52,23,357 INFO [sts.console.api.ApiService@http-nio-8080-exec-8] -->processEngineRequest: checking on console type:DYNAMIC_ATTRIBUTES ... 15,52,23,380 INFO [sts.console.api.ApiService@http-nio-8080-exec-1] -->processEngineRequest: checking if console has any pending to be process on engine... 15,52,29,749 INFO [sts.console.api.ApiService@http-nio-8080-exec-2] -->commit 15,52,29,752 INFO [sts.console.api.ApiService@http-nio-8080-exec-2] <--commit 0.003 seconds |
gengine.log
INFORMACIÓN: -->OperationFinish:remoteEvaluation jul 23, 2021 3:54:52 PM engine.operation.Operation loggerTimeStop INFORMACIÓN: <--OperationFinish:remoteEvaluation 0.913 seconds -><?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="7.1.4-SNAPSHOT" mapversion="44" messageId="1" store="napse" terminal="1" transaction="napse_napse_1_20210723100025"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="1800.00" id="550003" seq="1" type="tdf_001"/> </loyaltycards> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message> jul 23, 2021 3:55:04 PM engine.operation.Operation loggerTimeStart INFORMACIÓN: -->OperationCommit:remoteEvaluation jul 23, 2021 3:55:04 PM engine.operation.Operation loggerTimeStop INFORMACIÓN: <--OperationCommit:remoteEvaluation 0.053 seconds jul 23, 2021 4:13:57 PM engine.operation.Operation loggerTimeStart INFORMACIÓN: -->OperationLoyaltyValidation:remoteEvaluation jul 23, 2021 4:13:57 PM engine.operation.OperationLoyaltyvalidation validation INFORMACIÓN: Se valida que el cuerpo del mensaje no este vacio en LoyaltyValidation jul 23, 2021 4:13:57 PM engine.operation.Operation loggerTimeStop INFORMACIÓN: <--OperationLoyaltyValidation:remoteEvaluation 0.373 seconds
Flujos de Elementos de Fidelidad
En este apartado se expondrán los flujos desarrollados para elementos de fidelidad donde se podrán observar los distintos mensajes que se podrán intercambiar el POS, el motor y la consola de PROMO.
Alta de elemento de fidelidad
El alta de un elemento se realizara en la consola de PROMO Central
Nota: El campo CVV tiene como largo máximo 5 posiciones.
Consulta de elemento de fidelidad
Activación de elemento (loyaltyActivation)
Activación de elemento (FINISH)
Transferencia entre elementos
Imputación o descuento de saldo fuera de una transacción
Imputación o descuento de saldo devenidos de la aplicación de un beneficio.
Engine Response: ReturnFinish
La evaluación de la devolución se realiza utilizando el motor de simulación en la consola. Se trata de un proceso Background, en donde el pos envía a PROMO la transacción con STATUS="returnfinish" informando el número de transacción original y los elementos devueltos.
De manera Online solo se validara que el número de transacción original exista en la base del cliente y que el mensaje este correctamente conformado.
En el proceso background, PROMO recuperara la transacción original, quitara del contexto los elementos devueltos y volverá a evaluar promociones con el nuevo contexto de transacción con el número de mapa con que se evaluó la venta, los beneficios NO informados en esta evaluación (en comparación con los beneficios informados en la venta), serán los beneficios a anular de la transacción original.
En caso de tratarse de una transacción de cambio, el ítem devuelto será tratado como una devolución, realizando los pasos y evaluaciones descriptos anteriormente. Los elementos que se informen al motor serán responsabilidad del pos.
<?xml version="1.0" encoding="UTF-8"?><message ack="0" engine="2.6" mapversion="2" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170829162054"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Response OK JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "2",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170829162054",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Response – ERROR (Ver capítulo 3.1.1 Valores del atributo "ack")
<?xml version="1.0" encoding="UTF-8"?><message ack="9004" engine="2.6" mapversion="2" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170829162239"/>
Response ERROR JSON
{
"message": {
"ack": "9004",
"engine": "2.6",
"mapversion": "2",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170829162239"
}
}
Clientes
Se agregan al mensaje de respuesta al "LoyaltyValidation" los datos correspondientes al cliente consultado y los elementos de fidelidad que tiene asociado. Vale aclarar que si el cliente tiene un elemento de fidelidad inactivo, esos elementos no regresaran en la respuesta del loyaltyvalidation del cliente. Solo se informaran los elementos de fidelidad activos que tengan asociados.
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="6666" email="[email protected]" identifier="3055881" lastName="" name="Rojo Marcos" seq="1"> <loyaltycard ack="0" amount="100.0" id="3330000000001" type="1"/> <coupon ack="0" amount="0.0" barcode="1000010012948" couponId="1" seq="1"/> </customer> </customers> <redeemTable/> </loyalty> </message>
Ejemplo JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170515152511",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {
"customer": [{
"code": "6666",
"email": "john.promo2020@gmail.com",
"identifier": "3055881",
"lastName": "",
"name": "Rojo Marcos",
"seq": "1",
"loyaltycard": [{
"ack": "0",
"amount": "100.0",
"id": "3330000000001",
"type": "1"
}],
"coupon": [{
"ack": "0",
"amount": "0.0",
"barcode": "1000010012948",
"couponId": "1",
"seq": "1"
}]
}]
},
"redeemTable": {}
}
}
}
(Ver también Engine Request - LoyaltyValidation)
Operación con Segmentos
Imaginemos que tenemos una Promoción que da un beneficio a los clientes con segmento "ABC1". La Operatoria para trabajar con dicha Promoción seria:
- Realizamos una operación de LoyaltyValidation (Ver Engine Request - LoyaltyValidation) para conocer los segmentos a los que pertenece el cliente 9991:
<message companyId="sts" store="00001" terminal="010" date-time="2017-06-04 12:30:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="loyaltyValidation" map-version="15" suggest="true" suggest-seq="3"> <customer-add seq="1" id="9991"/> </message>
Request JSON
{
"message": {
"companyId": "sts",
"store": "00001",
"terminal": "010",
"date-time": "2017-06-04 12:30:00",
"messageId": "0010",
"void-trx": "false",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"status": "loyaltyValidation",
"map-version": "15",
"suggest": "true",
"suggest-seq": "3",
"customer-add": {
"seq": "1",
"id": "9991"
}
}
}
2. En respuesta al request anterior Promo nos informará como una de las propiedades los segmentos a los que pertenece ese cliente: Como vemos en el ejemplo el cliente pertenece a los segmentos ABC1, D18 y K1
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="9991" email="[email protected]" identifier="3055881" lastName="" name="Rojo Marcos" seq="1" segment="ABC1,D18,K1"> <loyaltycard ack="0" amount="100.0" id="3330000000001" type="1"/> <coupon ack="0" amount="0.0" barcode="1000010012948" couponId="1" seq="1"/> </customer> </customers> <redeemTable/> </loyalty> </message>
Ejemplo JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "1",
"messageId": "1",
"companyId": "sts",
"store": "1",
"terminal": "1",
"transaction": "1_1_20170515152511",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {
"customer": [{
"code": "9991",
"email": "john.promo2020@gmail.com",
"identifier": "3055881",
"lastName": "",
"name": "Rojo Marcos",
"seq": "1",
"segment": "ABC1,D18,K1",
"loyaltycard": [{
"ack": "0",
"amount": "100.0",
"id": "3330000000001",
"type": "1"
}],
"coupon": [{
"ack": "0",
"amount": "0.0",
"barcode": "1000010012948",
"couponId": "1",
"seq": "1"
}]
}]
},
"redeemTable": {}
}
}
}
3. Por último realizamos la transacción de venta con el cliente enviando su información completa:
<message companyId="sts" store="00001" terminal="010" date-time="2017-06-04 12:30:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="Finish" map-version="15" suggest="true" suggest-seq="3"> <customer-add seq="1" id="9991" segment="ABC1,D18,K1" /> </message>
Request JSON
{
"message": {
"companyId": "sts",
"store": "00001",
"terminal": "010",
"date-time": "2017-06-04 12:30:00",
"messageId": "0010",
"void-trx": "false",
"response": "true",
"init-tck": "true",
"evaluate": "true",
"status": "Finish",
"map-version": "15",
"suggest": "true",
"suggest-seq": "3",
"customer-add": [{
"seq": "1",
"id": "9991",
"segment": "ABC1,D18,K1"
}]
}
}
De esta forma la transacción será evaluada y al ser un cliente que pertenece al segmento ABC1, le será otorgada la Promoción.
Crear Clientes (Nota: Solo si se ha habilitado el funcionamiento sin clientes pre-existentes)
Existen casos en que se requieren crear clientes en el momento por ejemplo para poder enviarles cupones electrónicos por email. A este fin se ha incorporado la posibilidad de enviar la definición del cliente (datos mínimos necesarios) desde la mensajería de Promo.
Los clientes serán creados utilizando el estado "loyaltyValidation" en el caso de enviarse los datos mínimos y al mismo tiempo Promo detecte que el cliente no existe. Los datos mínimos mencionados por ejemplo serian los marcados en negrita en el siguiente ejemplo XML:
<customer-add seq=
"1"
id=
"10090504"
identifier=
"10090504"
type=
"test"
name=
"pepe"
lastName=
"rodrigues"
identifierType=
"cpf"
email=
"mimail@test.com"
/>
Ejemplo JSON:
{
"customer-add": [{
"seq": "1",
"id": "10090504",
"identifier": "10090504",
"type": "test",
"name": "pepe",
"lastName": "rodrigues",
"identifierType": "cpf",
"email": "mimail@test.com"
}]
}
Importante
Para que el alta de clientes pueda efectuarse al momento de procesarse una transacción, deberá de habilitarse en el archivo de configuraciones de la Consola de Promo (“promoplus.properties”) el siguiente atributo:
# Habilita el alta de clientes on the fly
promo.allowNonExistingCustomers = true
Una vez actualizado, deberá de reiniciarse el Wildfly para que los cambios sean tomados correctamente.
Veamos ahora un ejemplo de intercambio de estos mensajes:
Realizamos una petición con loyaltyValidation y el cliente no existe:
Request XML<message companyId="napse" store="1" terminal="10" date-time="2018-08-09 10:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyValidation" evaluate="true" offline="false" > <customer-add seq="1" id="10090504" type="test" limitedBenefits="5b7044246491fa1604a6d15b:200.00;" /> </message>
Request JSON
{
"message": {
"companyId": "napse",
"store": "1",
"terminal": "10",
"date-time": "2018-08-09 10:51:50",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "loyaltyValidation",
"evaluate": "true",
"offline": "false",
"customer-add": [{
"seq": "1",
"id": "10090504",
"type": "test",
"limitedBenefits": "5b7044246491fa1604a6d15b:200.00;"
}]
}
}
2.La respuesta entrega valores por defecto:
<message ack="0" companyId="napse" engine="6.4.6" mapversion="1" messageId="1" store="1" terminal="10" transaction="napse_1_10_20180809105150"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="10090504" email="-" identifier="-" lastName="-" limitedBenefits="" name="-" segment="" seq="1"/> </customers> <redeemTable/> </loyalty> </message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.4.6",
"mapversion": "1",
"messageId": "1",
"store": "1",
"terminal": "10",
"transaction": "napse_1_10_20180809105150",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {
"customer": [{
"code": "10090504",
"email": "-",
"identifier": "-",
"lastName": "-",
"limitedBenefits": "",
"name": "-",
"segment": "",
"seq": "1"
}]
},
"redeemTable": {}
}
}
}
En este caso enviamos datos del cliente pero no completamos todos los campos necesarios:
Code XML<message companyId="napse" store="1" terminal="10" date-time="2018-08-09 10:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyValidation" evaluate="true" offline="false" > <customer-add seq="1" id="10090504" identifier="10090504" type="test" limitedBenefits="5b7044246491fa1604a6d15b:200.00;" name="pepe" lastName="rodrigues" identifierType="cpf" /> </message>
Code JSON
{
"message": {
"companyId": "napse",
"store": "1",
"terminal": "10",
"date-time": "2018-08-09 10:51:50",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "loyaltyValidation",
"evaluate": "true",
"offline": "false",
"customer-add": [{
"seq": "1",
"id": "10090504",
"identifier": "10090504",
"type": "test",
"limitedBenefits": "5b7044246491fa1604a6d15b:200.00;",
"name": "pepe",
"lastName": "rodrigues",
"identifierType": "cpf"
}]
}
}
La respuesta aun contiene datos por defecto:
<message ack="0" companyId="napse" engine="6.4.6" mapversion="1" messageId="1" store="1" terminal="10" transaction="napse_1_10_20180809105150"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="10090504" email="-" identifier="10090504" lastName="rodrigues" limitedBenefits="" name="pepe" segment="" seq="1"/> </customers> <redeemTable/> </loyalty></message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.4.6",
"mapversion": "1",
"messageId": "1",
"store": "1",
"terminal": "10",
"transaction": "napse_1_10_20180809105150",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {
"customer": [{
"code": "10090504",
"email": "-",
"identifier": "10090504",
"lastName": "rodrigues",
"limitedBenefits": "",
"name": "pepe",
"segment": "",
"seq": "1"
}]
},
"redeemTable": {}
}
}
}
Ahora enviamos TODOS los datos obligatorios para que el cliente sea creado
Code XML<message companyId="napse" store="1" terminal="10" date-time="2018-08-09 10:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyValidation" evaluate="true" offline="false" > <customer-add seq="1" id="10090504" identifier="10090504" type="test" limitedBenefits="5b7044246491fa1604a6d15b:200.00;" name="pepe" lastName="rodrigues" identifierType="cpf" email="[email protected]" /> </message>
Code JSON
{
"message": {
"companyId": "napse",
"store": "1",
"terminal": "10",
"date-time": "2018-08-09 10:51:50",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "loyaltyValidation",
"evaluate": "true",
"offline": "false",
"customer-add": [{
"seq": "1",
"id": "10090504",
"identifier": "10090504",
"type": "test",
"limitedBenefits": "5b7044246491fa1604a6d15b:200.00;",
"name": "pepe",
"lastName": "rodrigues",
"identifierType": "cpf",
"email": "pepe@test.com"
}]
}
}
La respuesta es:
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" companyId="napse" engine="6.4.6" mapversion="1" messageId="1" store="1" terminal="10" transaction="napse_1_10_20180809105150"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="10090504" email="[email protected]" identifier="10090504" lastName="rodrigues" limitedBenefits="" name="pepe" segment="" seq="1"/> </customers> <redeemTable/> </loyalty> </message>
Code JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.4.6",
"mapversion": "1",
"messageId": "1",
"store": "1",
"terminal": "10",
"transaction": "napse_1_10_20180809105150",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {
"customer": [{
"code": "10090504",
"email": "pepe@test.com",
"identifier": "10090504",
"lastName": "rodrigues",
"limitedBenefits": "",
"name": "pepe",
"segment": "",
"seq": "1"
}]
},
"redeemTable": {}
}
}
}
Ahora vamos a enviar el mensaje que enviamos en el punto 1, el cual tiene solo los datos básicos del cliente y por el cual en el punto 1 nos retornaba valores por defecto (el cliente no era conocido) mientras que ahora nos tendría que retornar todos los datos que ya conocemos y creamos en el punto 3.
Code XML<message companyId="napse" store="1" terminal="10" date-time="2018-08-09 10:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyValidation" evaluate="true" offline="false" > <customer-add seq="1" id="10090504" type="test" limitedBenefits="" /> </message>
Code JSON
{
"message": {
"companyId": "napse",
"store": "1",
"terminal": "10",
"date-time": "2018-08-09 10:51:50",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "loyaltyValidation",
"evaluate": "true",
"offline": "false",
"customer-add": [{
"seq": "1",
"id": "10090504",
"type": "test",
"limitedBenefits": ""
}]
}
}
La respuesta efectivamente es:
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" companyId="napse" engine="6.4.6" mapversion="1" messageId="1" store="1" terminal="10" transaction="napse_1_10_20180809105150"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="10090504" email="[email protected]" identifier="10090504" lastName="rodrigues" limitedBenefits="" name="pepe" segment="" seq="1"/> </customers> <redeemTable/> </loyalty> </message>
Code JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.4.6",
"mapversion": "1",
"messageId": "1",
"store": "1",
"terminal": "10",
"transaction": "napse_1_10_20180809105150",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {
"customer": [{
"code": "10090504",
"email": "pepe@test.com",
"identifier": "10090504",
"lastName": "rodrigues",
"limitedBenefits": "",
"name": "pepe",
"segment": "",
"seq": "1"
}]
},
"redeemTable": {}
}
}
}
Operatoria (en base a los posibles escenarios):
OperatoOria | GiftCard | Monedero | Tarj de Puntos | Gift - Único Uso |
Alta de tarjeta | Por ArchivoINACTIVAS | Por Archivo/ManualInactivas o Activas | Por ArchivoINACTIVAS | Por ArchivoINACTIVAS |
Consulta de Tarjetas | Se informara en tag Errors (por estar inactiva)el Amount - Type | Se informara en tag Errors, si esta inactiva o en tag LoyaltyCard si esta activaType - Amount | Se informara en tag Errors (por estar inactiva)Amount –Customer-Type | Se informara en tag Errors (por estar inactiva)Amount - Type |
Activación de Tarjeta | Deberá activarse por medio del mensaje "Loyaltyactivation" o "finish" Valida CVV | Podrá activarse por el mensaje "Loyaltyactivation", "finish" o cuando se realiza su primera recarga | Podrá activarse por el mensaje "Loyaltyactivation", "finish" o cuando se realiza su primera recarga Si se envía Cliente lo validará | Podrá activarse por el mensaje "Loyaltyactivation", "finish" o cuando se realiza su primera recarga. Valida CVV |
Transferencia | Admite solo transferencia de saldo totales - Una vez transferido el saldo total de la tarjeta, ésta se cancela. Valida CVV | Admite transferencias parciales sin alterar el estado del elemento. | No admite transferencia de ningún tipo. | No admite transferencia de ningún tipo. |
Imputación de Saldo | No admite recarga de saldo. | Admite recargas hasta un valor máximo. | Admite recargas sin tope. Si se envía cliente se validara. | Admite recargas sin tope. Valida CVV. |
Consumo de Saldo | Admite consumir el saldo en más de una transacción sin alterar el estado de la tarjeta. Valida CVV | Admite consumir el saldo en más de una transacción sin alterar el estado de la tarjeta | Admite consumir el saldo en más de una transacción sin alterar el estado de la tarjeta Si se envía cliente se validara | Solo permite un único consumo de saldo ya sea total o parcial, luego de ese único consumo el elemento de fidelidad se INACTIVA. Valida CVV |
Saldos por convenios
Cuando el beneficio tenga limites de saldos por convenios y por clientes, la operatoria del motor deberá ser la siguiente:
Para poder operar con limites de saldos por convenios el primer mensaje enviado desde el pos debe ser un status loyaltyValidation con el elemento customer, para poder cargar los limites del cliente antes de realizar la transacción.
En caso que existan limites para beneficios de convenio; éstos vendrán en el atributo limitedBenefits,Los límites de clientes que no sean de convenio, la consola informa sólo al motor.
Importante: Para cargar el limite del cliente en el motor, se deberá hacer un loyaltyValidation con init-tck="true" con el elemento customer, debe ser el primer mensaje a operar.
Ejemplo para los mensajes de Limites
A continuación se muestra como se debe operar:
<message companyId="napse" store="1" terminal="1" date-time="2019-02-25 12:02" init-tck="true" messageId="20" void-trx="false" response="true" status="loyaltyValidation" evaluate="false" suggest="true"> <customer-add seq="1" id="2" type="test" /> <item-add seq="2" qty="1" code="1" magnitude="0" xprice="200" unitprice="200"/> </message>
Request LoyaltyValidation Limites por Clientes JSON
{
"message": {
"companyId": "napse",
"store": "1",
"terminal": "1",
"date-time": "2019-02-25 12:02",
"init-tck": "true",
"messageId": "20",
"void-trx": "false",
"response": "true",
"status": "loyaltyValidation",
"evaluate": "false",
"suggest": "true",
"customer-add": [{
"seq": "1",
"id": "2",
"type": "test"
}],
"item-add": [{
"seq": "2",
"qty": "1",
"code": "1",
"magnitude": "0",
"xprice": "200",
"unitprice": "200"
}]
}
}
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="6.4.0" mapversion="25" messageId="20" store="1" terminal="1" transaction="napse_1_1_20190225125106"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="2" email="[email protected]" identifier="25456742" lastName="Perez" limitedBenefits="5c73fa11a8b0ea2f888130c0:300.00;" name="Juan" seq="1"> <loyaltycard ack="0" amount="2088.00" id="1110000000" status="Activa" type="test"/> <limit amount="300.00" id="5c73fa11a8b0ea2f888130c0" promotionDescription="promoLimite" promotionName="promoLimite"/> </customer> </customers> <redeemTable/> </loyalty> </message>
Response LoyaltyValidation Limites por Clientes JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.4.0",
"mapversion": "25",
"messageId": "20",
"store": "1",
"terminal": "1",
"transaction": "napse_1_1_20190225125106",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {
"customer": [{
"code": "2",
"email": "juanperez88@juanperez.com",
"identifier": "25456742",
"lastName": "Perez",
"limitedBenefits": "5c73fa11a8b0ea2f888130c0:300.00;",
"name": "Juan",
"seq": "1",
"loyaltycard": [{
"ack": "0",
"amount": "2088.00",
"id": "1110000000",
"status": "Activa",
"type": "test"
}],
"limit": [{
"amount": "300.00",
"id": "5c73fa11a8b0ea2f888130c0",
"promotionDescription": "promoLimite",
"promotionName": "promoLimite"
}]
}]
},
"redeemTable": {}
}
}
}
En la respuesta podemos ver la información del cliente con el limitedBenefits que nos indica el limite por cliente del beneficio de convenio. Es decir en esta promocion la podremos utilizar 3 veces por cliente, dado que el beneficio es un monto de 100 por beneficio y el limite monetario es de 300.
<message companyId="napse" store="1" terminal="1" date-time="2019-02-25 12:02" init-tck="false" messageId="20" void-trx="false" response="true" status="sales" evaluate="true" suggest="true"> <customer-add seq="1" id="2" type="test" /> <item-add seq="2" qty="1" code="1" magnitude="0" xprice="200" unitprice="200"/> </message>
Request Sales Limites por Clientes JSON
{
"message": {
"companyId": "napse",
"store": "1",
"terminal": "1",
"date-time": "2019-02-25 12:02",
"init-tck": "false",
"messageId": "20",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"suggest": "true",
"customer-add": [{
"seq": "1",
"id": "2",
"type": "test"
}],
"item-add": [{
"seq": "2",
"qty": "1",
"code": "1",
"magnitude": "0",
"xprice": "200",
"unitprice": "200"
}]
}
}
Los límites de clientes que no sean de convenio, la consola informa sólo al motor.
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="6.4.0" mapversion="25" messageId="20" store="1" terminal="1"> <optional> <promo code="promoLimite" id="promoLimite" nro="5c73f81fa8b0ea2f888130ab"> <benefit TLOGMessage="promoLimite" account="" applicationMethod="resume" baseAmount="200.00" benefitType="FixedDiscount" discountAmount="100.00" displayMessage="promoLimite" hasLimit="true" name="5c73f81fa8b0ea2f888130ab" nro="5c73fa11a8b0ea2f888130c0" order="1" printerMessage="promoLimite" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="1.000" seq="2" value="100.00" valueWithTaxes="100.00" xprice="200.00"/> </apply> </benefit> </promo> </optional> </message>
Response sales Limites por Clientes JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.4.0",
"mapversion": "25",
"messageId": "20",
"store": "1",
"terminal": "1",
"optional": [{
"promo": [{
"code": "promoLimite",
"id": "promoLimite",
"nro": "5c73f81fa8b0ea2f888130ab",
"benefit": [{
"TLOGMessage": "promoLimite",
"account": "",
"applicationMethod": "resume",
"baseAmount": "200.00",
"benefitType": "FixedDiscount",
"discountAmount": "100.00",
"displayMessage": "promoLimite",
"hasLimit": "true",
"name": "5c73f81fa8b0ea2f888130ab",
"nro": "5c73fa11a8b0ea2f888130c0",
"order": "1",
"printerMessage": "promoLimite",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "2",
"value": "100.00",
"valueWithTaxes": "100.00",
"xprice": "200.00"
}]
}
}]
}]
}]
}
}
Luego hacemos el status finish
<message companyId="napse" store="1" terminal="1" date-time="2019-02-25 12:02" init-tck="false" messageId="20" void-trx="false" response="true" status="finish" evaluate="true" suggest="true"> <customer-add seq="1" id="2" type="test" /> <item-add seq="2" qty="1" code="1" magnitude="0" xprice="200" unitprice="200"/> </message>
Request finish Limites por Clientes JSON
{
"message": {
"companyId": "napse",
"store": "1",
"terminal": "1",
"date-time": "2019-02-25 12:02",
"init-tck": "false",
"messageId": "20",
"void-trx": "false",
"response": "true",
"status": "finish",
"evaluate": "true",
"suggest": "true",
"customer-add": [{
"seq": "1",
"id": "2",
"type": "test"
}],
"item-add": [{
"seq": "2",
"qty": "1",
"code": "1",
"magnitude": "0",
"xprice": "200",
"unitprice": "200"
}]
}
}
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="6.4.0" mapversion="25" messageId="20" store="1" terminal="1" transaction="napse_1_1_20190225125233"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers/> <redeemTable/> </loyalty> </message>
Response finish Limites por Clientes XML
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.4.0",
"mapversion": "25",
"messageId": "20",
"store": "1",
"terminal": "1",
"transaction": "napse_1_1_20190225125233",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {},
"redeemTable": {}
}
}
}
Por último el commit
<message companyId="napse" store="1" terminal="1" date-time="2019-02-25 12:02" init-tck="false" messageId="20" void-trx="false" response="true" status="commit" evaluate="true" suggest="true"> <customer-add seq="1" id="2" type="test" /> <item-add seq="2" qty="1" code="1" magnitude="0" xprice="200" unitprice="200"/> </message>
Request commit Limites por Clientes JSON
{
"message": {
"companyId": "napse",
"store": "1",
"terminal": "1",
"date-time": "2019-02-25 12:02",
"init-tck": "false",
"messageId": "20",
"void-trx": "false",
"response": "true",
"status": "commit",
"evaluate": "true",
"suggest": "true",
"customer-add": [{
"seq": "1",
"id": "2",
"type": "test"
}],
"item-add": [{
"seq": "2",
"qty": "1",
"code": "1",
"magnitude": "0",
"xprice": "200",
"unitprice": "200"
}]
}
}
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="6.4.0" mapversion="25" messageId="21" store="1" terminal="1" transaction="napse_1_1_20190225125233"/>
Response commit Limites por Clientes JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.4.0",
"mapversion": "25",
"messageId": "21",
"store": "1",
"terminal": "1",
"transaction": "napse_1_1_20190225125233"
}
}
Haciendo nuevamente el loyaltyValidation veremos que hemos consumido 100 del limite, dado que la promoción otorgaba un beneficio de 100 por cada transacción.
<message companyId="napse" store="1" terminal="1" date-time="2019-02-25 12:05" init-tck="true" messageId="21" void-trx="false" response="true" status="loyaltyValidation" evaluate="false" suggest="true"> <customer-add seq="1" id="2" type="test" /> </message>
Request LoyaltyValidation Limites por Clientes JSON
{
"message": {
"companyId": "napse",
"store": "1",
"terminal": "1",
"date-time": "2019-02-25 12:05",
"init-tck": "true",
"messageId": "21",
"void-trx": "false",
"response": "true",
"status": "loyaltyValidation",
"evaluate": "false",
"suggest": "true",
"customer-add": [{
"seq": "1",
"id": "2",
"type": "test"
}]
}
}
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="6.4.0" mapversion="25" messageId="21" store="1" terminal="1" transaction="napse_1_1_20190225125107"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="2" email="[email protected]" identifier="25456742" lastName="Perez" limitedBenefits="5c73fa11a8b0ea2f888130c0:200.00;" name="Juan" seq="1"> <loyaltycard ack="0" amount="2088.00" id="1110000000" status="Activa" type="test"/> <limit amount="200.00" id="5c73fa11a8b0ea2f888130c0" promotionDescription="promoLimite" promotionName="promoLimite"/> </customer> </customers> <redeemTable/> </loyalty> </message>
Response LoyaltyValidation Limites por Clientes JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.4.0",
"mapversion": "25",
"messageId": "21",
"store": "1",
"terminal": "1",
"transaction": "napse_1_1_20190225125107",
"loyalty": {
"loyaltycards": {},
"coupons": {},
"errors": {},
"customers": {
"customer": [{
"code": "2",
"email": "juanperez88@juanperez.com",
"identifier": "25456742",
"lastName": "Perez",
"limitedBenefits": "5c73fa11a8b0ea2f888130c0:200.00;",
"name": "Juan",
"seq": "1",
"loyaltycard": [{
"ack": "0",
"amount": "2088.00",
"id": "1110000000",
"status": "Activa",
"type": "test"
}],
"limit": [{
"amount": "200.00",
"id": "5c73fa11a8b0ea2f888130c0",
"promotionDescription": "promoLimite",
"promotionName": "promoLimite"
}]
}]
},
"redeemTable": {}
}
}
}
De realizar 2 transacciones mas ya no aplicara la promoción por haber superado el limite.
Manejo de Límites
El control de límites a través de la lista negra generada en consola implica que dicha lista negra se actualice a partir de la transacción finalizada, por lo que en el motor, el límite puede ser sobrepasado durante la transacción. Para prevenir esto último y que el límite sea evaluado durante la transacción se ha requerido realizar cambios en consola y en motor.
Por un lado la consola continua calculando y almacenando los valores máximo y corriente de los límites de beneficios al procesar el commit de una transacción, pero en vez de enviar al motor sólo la lista de los limites que fueron alcanzados o sobrepasados (blacklist), envía también al motor el estado de esos limites (dicho estado se va almacenando en la tabla limitStatus) . En realidad es el motor en el inicio de un ticket quien solicita a la consola -a través de un request http- información diversa, entre ellas limites, ahora se agrega información de estado de límites para los beneficios y cliente (de ser un ticket que involucre cliente) del mapa a procesar.
Por otro lado el motor, al recibir los registros de limitStatus además de la blacklist, los almacena en un caché para ser consultado durante la evolución del ticket, si el valor corriente iguala o sobrepasa el valor máximo definido para el beneficio, el límite se marca como alcanzado a fin de optimizar tiempos y no volver a evaluarlo.
Durante los distintas operaciones en el desarrollo del ticket, el motor evalúa antes de ingresar al cálculo de un beneficio si ya ha sido alcanzado el límite (es decir si está en la blacklist), en caso afirmativo no procede al calculo del beneficio. En caso de no encontrarse en la blacklist, se procede a calcular el beneficio y se consulta en limitStatus si el valor a otorgar se encuentra dentro del límite y procede a aplicarlo, en caso contrario no otorga el beneficio.
CONSOLA
1-OBTENCIÓN DEL ESTADO DE LIMITES
Como se mencionó anteriormente la consola envía al motor la información de límites de beneficios a través de los registros de la tabla limitStatus. No obstante, por detalles de implementación, dicho registro en limitStatus sólo existe en caso que un beneficio que tenga límites haya tenido operación en una transacción, por lo tanto al momento de iniciar un ticket es posible que no exista dicho registro, en cuyo caso se genera la información equivalente al limitStatus a partir de los limites definidos para los beneficios de las promociones contenidas en el mapa por el cual se evalúa el ticket.
La generación y envío de lista negra se mantiene vigente,
El procesamiento del requerimiento del motor, continúa en la consola realizándose en la apiService, en el método blacklist(), en cuya respuesta se agrega el limitStatus para cuando el request procede de un motor 7.0 en adelante. La consola recibe a través de la API, en el método "blacklist", un request del motor con un json en donde se indican el store, customer, mapa, entre otros valores.
MOTOR
1-PROCESAMIENTO DE REGISTROS DE ESTADO DE LIMITES RECIBIDO DE CONSOLA
Los registros de límites que hayan sido alcanzados continúan recibiéndose como en versiones anteriores en el json de respuesta de consola como blackList, y se guardan en un cache: CacheDataManager.limits. En la respuesta de consola, existe otra lista "whiteList" que corresponde a límites que han sido editados y elevado su valor máximo y por lo tanto deben quitarse de la lista negra. En caso de recibir algún elemento en la whiteList, simplemente el motor procede a remover el elemento de la blackList
Una vez recibida en el motor los registros de limitStatus, cuyo contenido son los identificadores del limite, beneficio, promoción, valor máximo, valor corriente, tipo de límite y alcance, se almacenan en el caché de limitStatus, con el benefitId como clave. En realidad bajo clave benefitId se guarda un mapa de los limitStatus correspondientes, con limitId como clave de ese mapa, ya que puede haber varios límites (por monto, por cantidad de aplicaciones, por cantidad de items, etc) para un beneficio.
2-EVALUACIÓN DE LÍMITES ANTES DE APLICAR BENEFICIO
Tal como se realizaba en la versión anterior de Promo, antes de entrar en el cálculo de beneficio, se consulta si el límite ya fue alcanzado en la blackList.
3-EVALUACIÓN DE LÍMITES CON EL VALOR A APLICAR AL BENEFICIO
Dado que dependiendo del beneficio, el valor a otorgar puede ser de diferente tipo (puntos, cantidad de aplicación, monto, etc) , no pudo ubicarse en un punto común a todos los beneficios, la evaluación de si la aplicación de un beneficio está dentro de un límite. Por lo tanto se debió agregar una nueva evaluación de límite para evaluar si el valor corriente del límite, sumado al valor a otorgar del beneficio, está dentro del valor máximo del límite o lo supera, para aplicar o no el beneficio.
Para los límites que son de tipo cantidad de aplicaciones, cantidad de cupones entregados o cantidad de regalos entregados, la evaluación de este tipo de límites se realiza al final del proceso del beneficio, ya que aplican sobre todo el beneficio.
Por cada ítem del ticket que es factible de ser beneficiado, se hace el cálculo parcial recorriendo los límites para el beneficio, y sólo se evalúan los que no son del tipo count (por ejemplo cantidad de aplicacioens, etc), y colocando una marca en el beneficio que hay limites de este tipo.
Luego al final del proceso del beneficio, se evalúan sólo lo límites de tipo count, que en caso de encontrarse que el saldo no alcanza, termina descartándose la aplicación del beneficio.
En cuanto a la evaluación de si el límite alcanza para otorgar el beneficio, existe la posibilidad de configurar que en caso que el saldo de un límite no alcance a cubrir la totalidad del beneficio, se cancela dicho otorgamiento, o bien se otorgue el saldo disponible. Ver punto 5-CONFIGURACIÓN DEL COMPORTAMIENTO
4-INFORMAR SALDO DE LIMITES AL POS
Cuando se aplican límites, es importante informar al sistema que utiliza Promo, por ejemplo un Punto de Venta (POS), los saldos de los límites, a fin que el POS pueda tomar alguna acción según dicho saldo.
Como esta nueva información puede no ser necesaria en todos los sistemas que utilicen Promo, se optó por agregar un atributo 'limitBalances' de tipo boolean en la cabecera del mensaje del POS al motor, indicando cuando viene en 'true' que se genera y devuelve en la respuesta los saldos de limites.
Ejemplo de mensaje del POS a motor con el atributo limitBalances="true" en el tag message indicando se informe el saldo de limites:
Request al motor indicando se requiere saldo de límites
XML <message companyId="napse" store="napse" terminal="1" date-time="2020-04-17 15:57:20" init-tck="false" messageId="4524" void-trx="false" response="true" status="commit" map-version="65" evaluate="true" tckpath="Y" suggest="true" limitBalances="true"> <item-add seq="1" code="315" qty="3" magnitude="0" brand="1" unitprice="100" xprice="300" supplier="1" discountable="true"/> <loyaltycard-add seq="1" id="880000000012" peso="5" type="tarfd" /> <customer-add seq="1" id="2222" tipo="na" edad="41" sexo="femenino" /> </message> JSON { |
En el metodo BenefitBase.process() se agregó una llamada a CacheDataManager.prepareInfoLimitsByBenefit() donde se recolectan los saldos de los limites del beneficio y se almacenan en un mapa en Ticket.
Luego al final de la evaluación del ticket, cuando se arma la respuesta al POS en EngineResponse.toXml() se llama al createLimitsResponse() para generar la lista de saldos de limites e insertarla dentro de la respuesta.
Ejemplo de respuesta del motor con los saldos de limites:
Response del motor con saldo de límites
XML <?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT" mapversion="65" messageId="4524" store="napse" terminal="1"> <optional> <promo code="marzo27c" id="marzo27c" nro="5e7e04b78fc4c24a14491daa"> <benefit TLOGMessage="marzo27c" account="" applicationMethod="resume" baseAmount="300.00" benefitType="PercentageDiscount" discountPercentage="15.00" displayMessage="marzo27c" hasLimit="true" name="5e7e04b78fc4c24a14491daa" nro="5e7e05588fc4c24a14491db1" order="1" printerMessage="marzo27c" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="3.000" seq="1" value="45.00" valueWithTaxes="45.00" xprice="300.00"/> </apply> </benefit> </promo> </optional> <limitBalances> <limit amount="22.00" id="5e7e0e878fc4c2219049697e" max="25000.00" promotionName="marzo27c"/> <limit amount="4369.00" id="5e7e0f9b8fc4c22190496980" max="12000.00" promotionName="marzo27c"/> <limit amount="1681.00" id="5e8251f2b85cf77dbc714f32" max="50000.00" promotionName="marzo27c"/> </limitBalances> </message> JSON { |
5-CONFIGURACIÓN DEL COMPORTAMIENTO
El nuevo proceso de limites, en el comportamiento predeterminado, deja de otorgar un beneficio si el saldo no es suficiente. Este comportamiento puede ser modificado para que entregue el beneficio con el saldo disponible aunque no cubra la totalidad del beneficio.
Configuración del motor para beneficio saldo de limites: config.xml
XML <?xml version="1.0" encoding="UTF-8" standalone="no"?> <configuration> <general> ... <!--Otorgamiento de beneficio con límites: true otorga el saldo(default), false no otorga beneficio si el apply supera el saldo --> <useExactLimitValue>true</useExactLimitValue> </general> ... </configuration> JSON { |
Tanto en el caso que no se entregue beneficio si el saldo no es suficiente, como cuando se entrega el saldo disponible menor al que debería otorgarse, se informa en el atributo "limitApplied" del tag beneficio de la respuesta al POS, con valor "true", en caso de no haber limites aplicados, el atributo no estará presente.
Ejemplo de respuesta en que se devolvió como benefició solamente el saldo disponible, informando el atributo limitApplied en el tag beneficio, y el saldo informado en cero, dado que se utilizo lo disponible para otorgar el beneficio:
Response del motor con saldo de límites
XML <?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT" mapversion="65" messageId="4524" store="napse" terminal="1"> <optional> <promo code="marzo27c" id="marzo27c" nro="5e7e04b78fc4c24a14491daa"> <benefit TLOGMessage="marzo27c" account="" applicationMethod="resume" baseAmount="300.00" benefitType="PercentageDiscount" discountPercentage="15.00" displayMessage="marzo27c" hasLimit="true" limitApplied="true" name="5e7e04b78fc4c24a14491daa" nro="5e7e05588fc4c24a14491db1" order="1" printerMessage="marzo27c" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="3.000" seq="1" value="22.00" valueWithTaxes="22.00" xprice="300.00"/> </apply> </benefit> </promo> </optional> <limitBalances> <limit amount="0.00" id="5e7e0e878fc4c2219049697e" max="25000.00" promotionName="marzo27c"/> <limit amount="4366.00" id="5e7e0f9b8fc4c22190496980" max="12000.00" promotionName="marzo27c"/> <limit amount="1680.00" id="5e8251f2b85cf77dbc714f32" max="50000.00" promotionName="marzo27c"/> </limitBalances> </message> JSON { |
Precios
A la mensajería del motor se agrego un nuevo status denominado prices, dicho estado nos informará los precios de los items a consultar, para consultar el precio se deberá informar los items con el atributo unitprice=0, este nuevo estado evaluara el ticket del mensaje enviado y responderá los precios solicitados según la evaluación de la lista de precios, en caso de agregar o quitar elementos para modificar la información del ticket usar las operaciones add y void de los elementos (para ver mas detalle de preciadores referirse al manual de usuario).
Las Listas de precios están asociadas a tiendas por lo que el campo store es clave para encontrar los precios.
Nota: Para que la funcionalidad de precios esta disponible, el motor tendrá que tener en el archivo de configuracion (config.xml) en el tag general el atributo: <disablePrices>false</disablePrices>
<message companyId="napse" store="test" terminal="1" date-time="2018-02-19 12:35" init-tck="true" messageId="1" void-trx="false" response="true" status="prices" evaluate="true" suggest="true"> <item-add seq="1" qty="2" code="00-1114298" magnitude="0" xprice="200" unitprice="0"/> <item-add seq="2" qty="1" code="768-76-8409" magnitude="0" xprice="0" unitprice="0"/> </message>
Ejemplo de request de Prices JSON
{
"message": {
"companyId": "napse",
"store": "test",
"terminal": "1",
"date-time": "2018-02-19 12:35",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "prices",
"evaluate": "true",
"suggest": "true",
"item-add": [
{
"seq": "1",
"qty": "2",
"code": "00-1114298",
"magnitude": "0",
"xprice": "200",
"unitprice": "0"
},
{
"seq": "2",
"qty": "1",
"code": "768-76-8409",
"magnitude": "0",
"xprice": "0",
"unitprice": "0"
}
]
}
}
Respuesta esperada
<message ack="0" companyId="napse" engine="6.4.0" mapversion="0" messageId="1" store="test" terminal="1"> <prices lastUpdate="19/02/2019 13:22:08"> <item code="00-1114298" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:06" priceListId="napse_LP0_test" qty="2.00" seq="1" supplierFinancial="PR3" supplierFinancialAmount="16070.00" supplierItem="PR1" supplierItemAmount="65988.00" unitprice="48535.46" xprice="97070.92"/> <item code="768-76-8409" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:00" priceListId="napse_LP0_test" qty="1.00" seq="2" supplierFinancial="PR1" supplierFinancialAmount="32340.00" supplierItem="PR3" supplierItemAmount="24791.00" unitprice="73921.00" xprice="73921.00"/> </prices> </message>
Ejemplo de Response de Prices JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.4.0",
"mapversion": "0",
"messageId": "1",
"store": "test",
"terminal": "1",
"prices": [{
"lastUpdate": "19/02/2019 13:22:08",
"item": [
{
"code": "00-1114298",
"discountable": "true",
"magnitude": "0.00",
"manualDiscount": "true",
"priceLastUpdate": "19/02/2019 13:18:06",
"priceListId": "napse_LP0_test",
"qty": "2.00",
"seq": "1",
"supplierFinancial": "PR3",
"supplierFinancialAmount": "16070.00",
"supplierItem": "PR1",
"supplierItemAmount": "65988.00",
"unitprice": "48535.46",
"xprice": "97070.92"
},
{
"code": "768-76-8409",
"discountable": "true",
"magnitude": "0.00",
"manualDiscount": "true",
"priceLastUpdate": "19/02/2019 13:18:00",
"priceListId": "napse_LP0_test",
"qty": "1.00",
"seq": "2",
"supplierFinancial": "PR1",
"supplierFinancialAmount": "32340.00",
"supplierItem": "PR3",
"supplierItemAmount": "24791.00",
"unitprice": "73921.00",
"xprice": "73921.00"
}
]
}]
}
}
Las propiedades de los elementos informados en el Tag <Prices/> son:
Propiedad | Tipo de dato | Descripción |
lastUpdate | Fecha con hora | Informa la fecha de la ultima actualización de precios (la consola se comunico con el motor para informar precios.) |
discountable | Booleano | Determina si el ítem admite descuento |
manualDiscount | Booleano | Determina si el ítem admite descuento manual |
priceLastUpdate | Alfanumérico | Fecha en la que fue actualizado el precio del ítem |
priceListId | Alfanumérico | Es el código de la empresa mas el código de la lista de precio del cual se calculo el precio <codigoEmpresa>_<codigoListaDePrecios> |
qty | Entero positivo | Número que identifica la Cantidad del ítem |
seq | Entero positivo | Número que identifica al elemento dentro de la transacción |
supplierFinancial | Alfanumérico | Opcional. Es el código del proveedor financiero del ítem |
supplierFinancialAmount | Numérico | Opcional. Es el monto que el proveedor Financiero reconoce |
supplierItem | Alfanumérico | Opcional. Es el código del proveedor del ítem |
supplierItemAmount | Numérico | Opcional. Es el monto que el proveedor reconoce |
unitprice | Numérico | Es precio del ítem consultado al motor |
xprice | Numérico | Es el precio del ítem multiplicado por la el atributo qty |
También se puede calcular los precios en otros status enviando el ítem con unitprice=0
En este caso enviamos un status sales con 2 items con unitprice=0 y uno con precio
<message companyId="napse" store="test" terminal="1" date-time="2019-02-19 14:35" init-tck="false" messageId="13" void-trx="false" response="true" status="sales" evaluate="true" suggest="true"> <item-add seq="1" qty="2" code="00-1114298" magnitude="0" xprice="200" unitprice="0"/> <item-add seq="2" qty="1" code="768-76-8409" magnitude="0" xprice="0" unitprice="0"/> <item-add seq="3" qty="1" code="769-51-6063" magnitude="0" xprice="10000" unitprice="10000"/> </message>
Request JSON
{
"message": {
"companyId": "napse",
"store": "test",
"terminal": "1",
"date-time": "2019-02-19 14:35",
"init-tck": "false",
"messageId": "13",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"suggest": "true",
"item-add": [
{
"seq": "1",
"qty": "2",
"code": "00-1114298",
"magnitude": "0",
"xprice": "200",
"unitprice": "0"
},
{
"seq": "2",
"qty": "1",
"code": "768-76-8409",
"magnitude": "0",
"xprice": "0",
"unitprice": "0"
},
{
"seq": "3",
"qty": "1",
"code": "769-51-6063",
"magnitude": "0",
"xprice": "10000",
"unitprice": "10000"
}
]
}
}
En la respuesta vemos que el beneficio de la promoción del 10% sobre cada ítem se aplica para los 3 items, para los dos con ítem con unitprice=0 se calculo el precio y se le aplico el 10%, mas abajo se ve el bloque de prices de donde se sacaron los precios.
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="6.4.0" mapversion="5" messageId="13" store="test" terminal="1"> <optional> <promo code="test" id="test" nro="5c59964c47452a7b3c22724a"> <benefit TLOGMessage="test" account="" applicationMethod="resume" baseAmount="180991.92" benefitType="PercentageDiscount" discountPercentage="10.00" displayMessage="test" name="5c59964c47452a7b3c22724a" nro="5c670e1ea8b0ea296089de8f" order="1" printerMessage="test" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="2.000" seq="1" value="9707.09" valueWithTaxes="20.00" xprice="97070.92"/> <item magnitude="0.000" qty="1.000" seq="2" value="7392.10" valueWithTaxes="0.00" xprice="73921.00"/> <item magnitude="0.000" qty="1.000" seq="3" value="1000.00" valueWithTaxes="1000.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> <prices lastUpdate="19/02/2019 15:52:56"> <item code="00-1114298" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:06" priceListId="napse_LP0_test" qty="2.00" seq="1" supplierFinancial="PR3" supplierFinancialAmount="16070.00" supplierItem="PR1" supplierItemAmount="65988.00" unitprice="48535.46" xprice="97070.92"/> <item code="768-76-8409" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:00" priceListId="napse_LP0_test" qty="1.00" seq="2" supplierFinancial="PR1" supplierFinancialAmount="32340.00" supplierItem="PR3" supplierItemAmount="24791.00" unitprice="73921.00" xprice="73921.00"/> </prices> </message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.4.0",
"mapversion": "5",
"messageId": "13",
"store": "test",
"terminal": "1",
"optional": [{
"promo": [{
"code": "test",
"id": "test",
"nro": "5c59964c47452a7b3c22724a",
"benefit": [{
"TLOGMessage": "test",
"account": "",
"applicationMethod": "resume",
"baseAmount": "180991.92",
"benefitType": "PercentageDiscount",
"discountPercentage": "10.00",
"displayMessage": "test",
"name": "5c59964c47452a7b3c22724a",
"nro": "5c670e1ea8b0ea296089de8f",
"order": "1",
"printerMessage": "test",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [
{
"magnitude": "0.000",
"qty": "2.000",
"seq": "1",
"value": "9707.09",
"valueWithTaxes": "20.00",
"xprice": "97070.92"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "2",
"value": "7392.10",
"valueWithTaxes": "0.00",
"xprice": "73921.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "3",
"value": "1000.00",
"valueWithTaxes": "1000.00",
"xprice": "10000.00"
}
]
}
}]
}]
}],
"prices": [{
"lastUpdate": "19/02/2019 15:52:56",
"item": [
{
"code": "00-1114298",
"discountable": "true",
"magnitude": "0.00",
"manualDiscount": "true",
"priceLastUpdate": "19/02/2019 13:18:06",
"priceListId": "napse_LP0_test",
"qty": "2.00",
"seq": "1",
"supplierFinancial": "PR3",
"supplierFinancialAmount": "16070.00",
"supplierItem": "PR1",
"supplierItemAmount": "65988.00",
"unitprice": "48535.46",
"xprice": "97070.92"
},
{
"code": "768-76-8409",
"discountable": "true",
"magnitude": "0.00",
"manualDiscount": "true",
"priceLastUpdate": "19/02/2019 13:18:00",
"priceListId": "napse_LP0_test",
"qty": "1.00",
"seq": "2",
"supplierFinancial": "PR1",
"supplierFinancialAmount": "32340.00",
"supplierItem": "PR3",
"supplierItemAmount": "24791.00",
"unitprice": "73921.00",
"xprice": "73921.00"
}
]
}]
}
}
Nuevo atributo del header tenderGroupCode
Para determinar si los preciadores aplican precio de crédito o precio de venta regular de la lista de precios, se agrego un atributo en el header el tenderGroupCode.
Cuando el mensaje tengatenderGroupCode y su valor sea "cr" , el motor aplicara el precio de crédito, en caso que no tenga el atributo o tenga otro valor el precio a aplicar será precio de venta.
Ejemplo de mensaje con tenderGroupCode:
<message companyId="napse" store="test" terminal="1" date-time="2019-02-19 14:35" init-tck="false" messageId="14" void-trx="false" response="true" status="sales" evaluate="true" suggest="true" tenderGroupCode="cr"> <item-add seq="1" qty="2" code="00-1114298" magnitude="0" xprice="200" unitprice="0"/> <item-add seq="2" qty="1" code="768-76-8409" magnitude="0" xprice="0" unitprice="0"/> <item-add seq="3" qty="1" code="769-51-6063" magnitude="0" xprice="10000" unitprice="10000"/> </message>
Request JSON
{
"message": {
"companyId": "napse",
"store": "test",
"terminal": "1",
"date-time": "2019-02-19 14:35",
"init-tck": "false",
"messageId": "14",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"suggest": "true",
"tenderGroupCode": "cr",
"item-add": [
{
"seq": "1",
"qty": "2",
"code": "00-1114298",
"magnitude": "0",
"xprice": "200",
"unitprice": "0"
},
{
"seq": "2",
"qty": "1",
"code": "768-76-8409",
"magnitude": "0",
"xprice": "0",
"unitprice": "0"
},
{
"seq": "3",
"qty": "1",
"code": "769-51-6063",
"magnitude": "0",
"xprice": "10000",
"unitprice": "10000"
}
]
}
}
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="6.4.0" mapversion="5" messageId="14" store="test" terminal="1" tenderGroupCode="cr"> <optional> <promo code="test" id="test" nro="5c59964c47452a7b3c22724a"> <benefit TLOGMessage="test" account="" applicationMethod="resume" baseAmount="144668.20" benefitType="PercentageDiscount" discountPercentage="10.00" displayMessage="test" name="5c59964c47452a7b3c22724a" nro="5c670e1ea8b0ea296089de8f" order="1" printerMessage="test" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="2.000" seq="1" value="6222.20" valueWithTaxes="20.00" xprice="62222.00"/> <item magnitude="0.000" qty="1.000" seq="2" value="7244.62" valueWithTaxes="0.00" xprice="72446.20"/> <item magnitude="0.000" qty="1.000" seq="3" value="1000.00" valueWithTaxes="1000.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> <prices lastUpdate="19/02/2019 16:11:13"> <item code="00-1114298" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:06" priceListId="napse_LP0_test" qty="2.00" seq="1" supplierFinancial="PR3" supplierFinancialAmount="16070.00" supplierItem="PR1" supplierItemAmount="65988.00" unitprice="31111.00" xprice="62222.00"/> <item code="768-76-8409" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:00" priceListId="napse_LP0_test" qty="1.00" seq="2" supplierFinancial="PR1" supplierFinancialAmount="32340.00" supplierItem="PR3" supplierItemAmount="24791.00" unitprice="72446.20" xprice="72446.20"/> </prices> </message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.4.0",
"mapversion": "5",
"messageId": "14",
"store": "test",
"terminal": "1",
"tenderGroupCode": "cr",
"optional": [{
"promo": [{
"code": "test",
"id": "test",
"nro": "5c59964c47452a7b3c22724a",
"benefit": [{
"TLOGMessage": "test",
"account": "",
"applicationMethod": "resume",
"baseAmount": "144668.20",
"benefitType": "PercentageDiscount",
"discountPercentage": "10.00",
"displayMessage": "test",
"name": "5c59964c47452a7b3c22724a",
"nro": "5c670e1ea8b0ea296089de8f",
"order": "1",
"printerMessage": "test",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [
{
"magnitude": "0.000",
"qty": "2.000",
"seq": "1",
"value": "6222.20",
"valueWithTaxes": "20.00",
"xprice": "62222.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "2",
"value": "7244.62",
"valueWithTaxes": "0.00",
"xprice": "72446.20"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "3",
"value": "1000.00",
"valueWithTaxes": "1000.00",
"xprice": "10000.00"
}
]
}
}]
}]
}],
"prices": [{
"lastUpdate": "19/02/2019 16:11:13",
"item": [
{
"code": "00-1114298",
"discountable": "true",
"magnitude": "0.00",
"manualDiscount": "true",
"priceLastUpdate": "19/02/2019 13:18:06",
"priceListId": "napse_LP0_test",
"qty": "2.00",
"seq": "1",
"supplierFinancial": "PR3",
"supplierFinancialAmount": "16070.00",
"supplierItem": "PR1",
"supplierItemAmount": "65988.00",
"unitprice": "31111.00",
"xprice": "62222.00"
},
{
"code": "768-76-8409",
"discountable": "true",
"magnitude": "0.00",
"manualDiscount": "true",
"priceLastUpdate": "19/02/2019 13:18:00",
"priceListId": "napse_LP0_test",
"qty": "1.00",
"seq": "2",
"supplierFinancial": "PR1",
"supplierFinancialAmount": "32340.00",
"supplierItem": "PR3",
"supplierItemAmount": "24791.00",
"unitprice": "72446.20",
"xprice": "72446.20"
}
]
}]
}
}
Ejemplo de mensaje SIN tenderGroupCode
<message companyId="napse" store="test" terminal="1" date-time="2019-02-19 14:36" init-tck="true" messageId="15" void-trx="false" response="true" status="sales" evaluate="true" suggest="true"> <item-add seq="1" qty="2" code="00-1114298" magnitude="0" xprice="200" unitprice="0"/> <item-add seq="2" qty="1" code="768-76-8409" magnitude="0" xprice="0" unitprice="0"/> <item-add seq="3" qty="1" code="769-51-6063" magnitude="0" xprice="10000" unitprice="10000"/> </message>
Request JSON
{
"message": {
"companyId": "napse",
"store": "test",
"terminal": "1",
"date-time": "2019-02-19 14:36",
"init-tck": "true",
"messageId": "15",
"void-trx": "false",
"response": "true",
"status": "sales",
"evaluate": "true",
"suggest": "true",
"item-add": [
{
"seq": "1",
"qty": "2",
"code": "00-1114298",
"magnitude": "0",
"xprice": "200",
"unitprice": "0"
},
{
"seq": "2",
"qty": "1",
"code": "768-76-8409",
"magnitude": "0",
"xprice": "0",
"unitprice": "0"
},
{
"seq": "3",
"qty": "1",
"code": "769-51-6063",
"magnitude": "0",
"xprice": "10000",
"unitprice": "10000"
}
]
}
}
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="6.4.0" mapversion="5" messageId="15" store="test" terminal="1"> <optional> <promo code="test" id="test" nro="5c59964c47452a7b3c22724a"> <benefit TLOGMessage="test" account="" applicationMethod="resume" baseAmount="180991.92" benefitType="PercentageDiscount" discountPercentage="10.00" displayMessage="test" name="5c59964c47452a7b3c22724a" nro="5c670e1ea8b0ea296089de8f" order="1" printerMessage="test" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="2.000" seq="1" value="9707.09" valueWithTaxes="20.00" xprice="97070.92"/> <item magnitude="0.000" qty="1.000" seq="2" value="7392.10" valueWithTaxes="0.00" xprice="73921.00"/> <item magnitude="0.000" qty="1.000" seq="3" value="1000.00" valueWithTaxes="1000.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> <prices lastUpdate="19/02/2019 16:15:14"> <item code="00-1114298" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:06" priceListId="napse_LP0_test" qty="2.00" seq="1" supplierFinancial="PR3" supplierFinancialAmount="16070.00" supplierItem="PR1" supplierItemAmount="65988.00" unitprice="48535.46" xprice="97070.92"/> <item code="768-76-8409" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:00" priceListId="napse_LP0_test" qty="1.00" seq="2" supplierFinancial="PR1" supplierFinancialAmount="32340.00" supplierItem="PR3" supplierItemAmount="24791.00" unitprice="73921.00" xprice="73921.00"/> </prices> </message>
Response JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "6.4.0",
"mapversion": "5",
"messageId": "15",
"store": "test",
"terminal": "1",
"optional": [{
"promo": [{
"code": "test",
"id": "test",
"nro": "5c59964c47452a7b3c22724a",
"benefit": [{
"TLOGMessage": "test",
"account": "",
"applicationMethod": "resume",
"baseAmount": "180991.92",
"benefitType": "PercentageDiscount",
"discountPercentage": "10.00",
"displayMessage": "test",
"name": "5c59964c47452a7b3c22724a",
"nro": "5c670e1ea8b0ea296089de8f",
"order": "1",
"printerMessage": "test",
"prorationMethod": "PROPORTIONAL",
"unit": "qty",
"apply": {
"item": [
{
"magnitude": "0.000",
"qty": "2.000",
"seq": "1",
"value": "9707.09",
"valueWithTaxes": "20.00",
"xprice": "97070.92"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "2",
"value": "7392.10",
"valueWithTaxes": "0.00",
"xprice": "73921.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "3",
"value": "1000.00",
"valueWithTaxes": "1000.00",
"xprice": "10000.00"
}
]
}
}]
}]
}],
"prices": [{
"lastUpdate": "19/02/2019 16:15:14",
"item": [
{
"code": "00-1114298",
"discountable": "true",
"magnitude": "0.00",
"manualDiscount": "true",
"priceLastUpdate": "19/02/2019 13:18:06",
"priceListId": "napse_LP0_test",
"qty": "2.00",
"seq": "1",
"supplierFinancial": "PR3",
"supplierFinancialAmount": "16070.00",
"supplierItem": "PR1",
"supplierItemAmount": "65988.00",
"unitprice": "48535.46",
"xprice": "97070.92"
},
{
"code": "768-76-8409",
"discountable": "true",
"magnitude": "0.00",
"manualDiscount": "true",
"priceLastUpdate": "19/02/2019 13:18:00",
"priceListId": "napse_LP0_test",
"qty": "1.00",
"seq": "2",
"supplierFinancial": "PR1",
"supplierFinancialAmount": "32340.00",
"supplierItem": "PR3",
"supplierItemAmount": "24791.00",
"unitprice": "73921.00",
"xprice": "73921.00"
}
]
}]
}
}
Dado los request anteriores con y sin tenderGroupCode los precios varían uno es el precio de crédito y el otro el precio regular de venta
- Se ve que con el tenderGroupCode el valor que respondió el motor es el siguiente:
<item magnitude="0.000" qty="1.000" seq="2" value="7244.62" valueWithTaxes="0.00" xprice="72446.20"/>
- Se ve que SIN el tenderGroupCode el valor que respondió el motor es el siguiente:
<item magnitude="0.000" qty="1.000" seq="2" value="7392.10" valueWithTaxes="0.00" xprice="73921.00"/>
Consejos prácticos
Interacción con el Motor de Promociones
Si bien el motor de promociones puede ser utilizado de muchas formas, se recomienda realizar un envío único que contenga todos los elementos de la transacción, solicitando en su encabezado la apertura de una nueva sesión, la evaluación del ticket enviado y que envíe una respuesta para esa evaluación.
Esto permitirá un uso más eficiente de los recursos, tanto de procesamiento y memoria, como de canal de comunicaciones.
Si por algún motivo (limitaciones técnicas, estándares, etc.) no pudiese realizarse el envío de un único mensaje, como segunda opción es posible el envío de los elementos en más de un mensaje (pudiendo utilizar hasta un mensaje por cada elemento a agregar), pidiendo la apertura de una nueva sesión en el primer mensaje de envío correspondiente a la transacción, y solicitando la evaluación del ticket al final de la misma. Para asegurarse del envío exitoso de cada elemento es posible solicitar un mensaje de confirmación (utilizando response en el encabezado), pero sin pedir la evaluación.
Esta última forma de interactuar es algo menos eficiente que la anterior, dado que requiere un mayor tiempo de utilización del canal de comunicaciones y de la memoria donde se encuentre funcionando el Motor de Promociones.
También podría expirar la sesión abierta en el Motor, obligando a un reenvío del ticket como se indica en ". Envío de mensaje único
Como se menciona anteriormente, la política de envío recomendada es la de utilizar un único mensaje que contenga todos los ítems. A continuación se presenta una enumeración paso a paso del envío y evaluación en único mensaje.
- Crear un mensaje único que contenga
- el encabezado
- Configurar que se espera respuesta (utilizando el atributo response).
- Configurar que el Motor debe calcular las promociones (utilizando el atributo evaluate).
- Configurar si se inicia un nuevo ticket (borrar el contexto asociado a la sesión, utilizando el atributo init-tck)
- el cuerpo
- todos los artículos de la transacción, según el formato establecido.
- todos los eventos de la transacción, según el formato establecido.
- todos los clientes de la transacción, según el formato establecido.
- todos los medio de pago de la transacción, según el formato establecido.
- todos los cupones de la transacción, según el formato establecido.
- el encabezado
- Enviar el mensaje utilizando el protocolo de comunicación correspondiente.
- Recibir la respuesta a la petición realizada. Dicha respuesta poseerá todas las promociones con sus respectivos beneficios, tal como se describe en "Engine Response". En caso de que el atributo ack del encabezado de respuesta sea distinto a 0, dirigirse a Valores del Atributo "ACK" y realizar la acción recomendada.
Manejo de sesiones
Como se mencionó con anterioridad, el Motor de Promociones es capaz de manejar múltiples sesiones, lo cual le permite atender diversas transacciones paralelamente. Cada sesión utiliza una cierta cantidad de memoria física del computador, por lo cuál no sería conveniente la creación de muchas sesiones excepto que el Motor esté atendiendo varios terminales y esté funcionando en un computador con las prestaciones adecuadas (ver Manual de instalación).
De esta forma, en caso de estar interactuando una sola terminal continuamente con el motor sería conveniente utilizar siempre la misma sesión y cada vez que se requiere borrar todo contenido de la sesión hacerlo por medio del atributo init-tck del encabezado.
Por otro lado, y debido a la naturaleza humana de la interacción del ingreso de artículos al punto de venta, si se está enviando el ticket al Motor de Promociones en varios mensajes puede que pase el tiempo de expiración de sesión. Como se describe en "Sesiones", de suceder esto el Motor de Promociones eliminará la sesión junto con todos los elementos que contenga y ante un requerimiento de la terminal donde se realiza la transacción informará que la sesión de esa transacción espiró (utilizando el atributo ack del encabezado del mensaje de respuesta). En estos casos debe recordarse abrir una nueva sesión utilizando atributo init-tck del encabezado envíos y reenviar todos los elementos que se habían ingresado hasta el momento. Luego será posible continuar con el funcionamiento normal.
Implementación de ítems aplicados
En esta sección se darán algunos lineamientos útiles a tener en cuenta al momento de interpretar los ítems aplicados dependiendo del beneficio al que pertenezcan.
Ítems aplicados en beneficios monetarios
Los artículos aplicados por un beneficio monetario son los artículos sobre los cuales debe realizarse el descuento informado por el Motor de Promociones. De esta forma, la implementación más simple es la de descontar en forma directa el monto informado por el atributo value al ítem informado por seq. El atributo qty de cada elemento indicará la cantidad total a descontar, por lo que será necesario distribuir (a criterio del implementador) el monto asignado a value entre la cantidad de ítems informada en qty. En caso de informarse una magnitud (atributo magnitude), el monto se descontará a dicha magnitud.
Ítems aplicados en beneficios no monetarios
Para el caso particular de los beneficios no monetarios, los artículos aplicados de éstos podrán ser interpretados como lo considere conveniente quien sea encargado de la integración entre el punto de venta y el Motor de Promociones. Por ejemplo, los artículos aplicados de un beneficio de plan de pagos (PaymentPlanBenefit) podrían ser interpretados como los artículos sobre los cuales se permite el plan de pago informado.
En el caso particular de FactorLoyaltyBenefit con integraciones anteriores a PROMO 5.2 (donde se incluye la administracion de saldos en la consola), la implementación recomendada es la de multiplicar el factor (atributo factor) informado por la suma de los montos (atributo unitprice) de los ítems aplicados, cada uno de ellos multiplicados por la cantidad informada por qty:
Pt = factor x Σ(unitPrice x qty)
Siendo Pt la cantidad total de puntos, dinero, millas, etc. a otorgar y Σ(unitPrice x qty) la sumatoria de los precios unitarios de los elementos aplicados, multiplicados por la cantidad correspondiente informada en <apply>.
Si no se informasen aplicados (algo que es posible para beneficios no monetarios), pueden aplicarse los puntos, dinero, millas, etc. a todo el ticket.
Para el resto de los beneficios no monetarios, los elementos aplicados pueden ser considerados meramente informativos.
ANEXO I - Beneficio - RedeemWithOptionsBenefit
A partir de Promo 7.0-EP2 se dispone de un nuevo beneficio Monetario de la clase "Canje con Opciones"
Se deberá definir las promociones pertinentes que tengan este nuevo tipo de beneficio, una vez distribuido el mapa con dichas promociones, El motor podrá evaluar este nuevo tipo de beneficio.
Básicamente este beneficio como su nombre lo indica tiene opciones, las cuales se podrán aplicar linea a linea a cada articulo.
Cada seq del elemento ítem se le podrá seleccionar una opción, dicha opción contiene puntos que el cliente tendrá que redimir para poder aplicar el beneficio de la opción.
El beneficio a aplicar se calcula con el tipo de beneficio (atributo benefitType de option), la unidad de medida a aplicar en el calculo (atributo unit de option) y el valor a aplicar ((atributo value de option).
Bloque RedeemOptions
El motor al recibir un status sales con la evaluación activada, disponibilizará las opciones del beneficio a aplicar en un nuevo bloque llamado reedemOptions, el cual esta compuesto por una lista de elementos option, los cuales representan las opciones a canjear los puntos del cliente
<redeemOptions> <option benefitType="percentageDiscount" cardPoints="200.0" cardType="089" id="5e567f0506773d1c14528761_0" requiredPoints="100.0" unit="qty" value="10.0"/> <option benefitType="percentageDiscount" cardPoints="1000.0" cardType="089" id="5e567f0506773d1c14528761_2" requiredPoints="0.0" unit="qty" value="20.0"/> <option benefitType="percentageDiscount" cardPoints="0.0" cardType="-" id="5e567f0506773d1c14528761_3" requiredPoints="500.0" unit="qty" value="20.0"/> </redeemOptions>
RedeemOptions JSON
{
"redeemOptions": {
"option": [
{
"benefitType": "percentageDiscount",
"cardPoints": "200.0",
"cardType": "089",
"id": "5e567f0506773d1c14528761_0",
"requiredPoints": "100.0",
"unit": "qty",
"value": "10.0"
},
{
"benefitType": "percentageDiscount",
"cardPoints": "1000.0",
"cardType": "089",
"id": "5e567f0506773d1c14528761_2",
"requiredPoints": "0.0",
"unit": "qty",
"value": "20.0"
},
{
"benefitType": "percentageDiscount",
"cardPoints": "0.0",
"cardType": "-",
"id": "5e567f0506773d1c14528761_3",
"requiredPoints": "500.0",
"unit": "qty",
"value": "20.0"
}
]
}
}
ELEMENTO OPTION
Las Opciones disponibles tienen los siguientes atributos
atributo | tipo | Descripción |
---|---|---|
id | Alfanumérico | Identificador de la opción** |
requiredPoints | Numérico | Puntos requeridos a canjear para aplicar el beneficio |
cardType | Alfanumérico | Tipo de elemento a la cual se puede hacer el canje de puntos de elemento (cardPoints) |
cardPoints | Numérico | Puntos de elementos de fidelidad requeridos a canjear para aplicar el beneficio |
benefitType | Alfanumérico | Tipo de calculo a aplicar (fixedDiscount / percentageDiscount / newPrice) |
unit | Alfanumérico | Unidad de Medida a aplicar en el calculo (qty / magnitude) |
value | Numérico | Valor aplicar en el calculo según el benefitType (fixedDiscount:DescuentoFijo, percentageDiscount:porcentaje, newPrice: nuevoPrecio) a su vez a este valor se le restara el valuePoints del item-apply |
Id del elemento Option
Id del elemento Option
Las opciones se pueden canjear por puntos de cliente o por puntos de tarjetas, o ambos (según lo configurado en el beneficio)
- Si se canjea por puntos de clientes no es necesario el elemento loyalty-card con type y amount
- Si se canjea puntos de tarjetas debe existir el elemento loyalty-card con el tipo igual al definido en cardType y con amount suficiente
- Si se canjea por puntos de cliente deberá tener points disponible en el elemento customer y debe estar el elemento loyalty-card con type y amount
Las opciones disponibles tienen 3 tipos de cálculos a aplicar en el beneficio de los artículos.
Estos cálculos son :
- Precio Fijo (calculo preexistente en el beneficio descuento fijo)
- Descuento Porcentual (calculo preexistente en el beneficio descuento por porcentaje)
Nuevo Precio (calculo preexistente en el beneficio descuento nuevo precio)
Una vez disponibles las opciones, el POS podrá asignarle a cada seq de articulo (element item) la opciones deseada, y el motor aplicara el beneficio de cumplirse con las siguientes validaciones:
Validaciones que permite el calculo del beneficio correctamente.
Selección de una opción valida, se deberá agregar al elemento item-add el id de la option (redeemOption) sugerida en el bloque redeemOptions (opciones disponibles)
El mensaje debe contener el elemento cliente customer-add
El elemento customer debe tener el atributo points con puntos suficientes a poder canjear los puntos requeridos por la opción seleccionada.
El elemento customer debe tener el nuevo atributo redeemPointsPriceFactor (factor de conversión permite calcular el valor del ítem en puntos)
Los puntos de un ítem se calculan de la siguiente manera ptosItem= xprice/redeempointsPriceFactor
Los puntos del item (xprice/redeemPointsPriceFactor) deben ser superior a los puntos requeridos de la opción seleccionada (requiredPoints).
Nuevos atributos en el item apply
Las Opciones disponibles tienen los siguientes atributos
atributo | tipo | Descripción |
---|---|---|
redeemOption | Alfanumérico | Identificador la opción seleccionada (Cuando no se quiera seleccionar ninguna opción el valor debe ser "0" )| |
usedPoints | Numérico | Puntos canjeados para aplicar el beneficio(xprice*requiredPoints) |
cardType | Alfanumérico | Tipo de elemento la cual se canjearon puntos |
cardUsedPoints | Numérico | Puntos de elementos de fidelidad canjeados |
benefitTypeOption | Alfanumérico | Tipo de calculo a aplicar (fixedDiscount / percentageDiscount / newPrice) |
benefitUnitOption | Alfanumérico | Unidad de Medida a aplicar en el calculo (qty / magnitude) |
valuePoints | Numérico | Equivalente en pesos de los puntos canjeados ( usedPoints * redeemPointsPriceFactor) |
priceInPoints | Numérico | Valor del ítem en puntos (xprice/redeemPointsPriceFactor) |
nominalDiscount | Numérico | Es el Descuento Nominal (value +valuePoints) |
percentageDiscount | Numérico | Valor a aplicar en el descuento cuando el benefitTypeOption = percentageDiscount) |
fixedDiscount | Numérico | Valor a aplicar en el descuento cuando el benefitTypeOption =fixedDiscount |
newPrice | Numérico | Valor a aplicar en el descuento cuando el benefitTypeOption =newPrice |
Calculo del Value
El calculo del value dependerá del benefitTypeOption(percentageDiscount/fixedDiscount/newPrice) Y a dicho calculo se le restara valuePoints
EJEMPLO DE REQUEST/RESPONSE OPCIONES
Dado el siguiente mensaje request
<message store="1" terminal="001" date-time="2020-03-11 10:21" init-tck="true" messageId="1" void-trx="false" response="true" status="sale" evaluate="true" suggest="true" map-version="5208" companyId="napse"> <customer-add seq="1" id="1" points="40000" redeemPointsPriceFactor="1" /> <loyaltycard-add seq="1" id="999999001" type="089" amount="5000"/> <item-add seq="1" qty="1" code="111" magnitude="0" xprice="5000" unitprice="5000" /> </message>
Request SALE JSON
{
"message": {
"store": "1",
"terminal": "001",
"date-time": "2020-03-11 10:21",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "sale",
"evaluate": "true",
"suggest": "true",
"map-version": "5208",
"companyId": "napse",
"customer-add": [{
"seq": "1",
"id": "1",
"points": "40000",
"redeemPointsPriceFactor": "1"
}],
"loyaltycard-add": [{
"seq": "1",
"id": "999999001",
"type": "089",
"amount": "5000"
}],
"item-add": [{
"seq": "1",
"qty": "1",
"code": "111",
"magnitude": "0",
"xprice": "5000",
"unitprice": "5000"
}]
}
}
El motor responderá el beneficio con sus opciones:
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT" mapversion="5208" messageId="1" store="1" terminal="001"> <optional> <promo code="24330" id="promo-24330" nro="5e567ea506773d1c1452875d"> <benefit RecoveryPercentage="0" RecoveryValue="0" Recuperacion="no" TLOGMessage="promo" account="" applicationMethod="lineByLine" baseAmount="5000.00" benefitType="RedeemWithOptionsBenefit" displayMessage="promo" name="5e567ea506773d1c1452875d" nro="5e567f0506773d1c14528761" order="1" printerMessage="promo" prorationMethod="PROPORTIONAL" usedPoints="0.00"> <apply> <item magnitude="0.000" qty="1.000" seq="1" value="0.00" valueWithTaxes="0.00" xprice="5000.00"/> </apply> <redeemOptions> <option benefitType="percentageDiscount" cardPoints="200.0" cardType="089" id="5e567f0506773d1c14528761_0" requiredPoints="100.0" unit="qty" value="10.0"/> <option benefitType="percentageDiscount" cardPoints="1000.0" cardType="089" id="5e567f0506773d1c14528761_2" requiredPoints="0.0" unit="qty" value="20.0"/> <option benefitType="percentageDiscount" cardPoints="0.0" cardType="-" id="5e567f0506773d1c14528761_3" requiredPoints="500.0" unit="qty" value="20.0"/> </redeemOptions> </benefit> </promo> </optional> </message>
Response SALE JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.0.0-SNAPSHOT",
"mapversion": "5208",
"messageId": "1",
"store": "1",
"terminal": "001",
"optional": [{
"promo": [{
"code": "24330",
"id": "promo-24330",
"nro": "5e567ea506773d1c1452875d",
"benefit": [{
"RecoveryPercentage": "0",
"RecoveryValue": "0",
"Recuperacion": "no",
"TLOGMessage": "promo",
"account": "",
"applicationMethod": "lineByLine",
"baseAmount": "5000.00",
"benefitType": "RedeemWithOptionsBenefit",
"displayMessage": "promo",
"name": "5e567ea506773d1c1452875d",
"nro": "5e567f0506773d1c14528761",
"order": "1",
"printerMessage": "promo",
"prorationMethod": "PROPORTIONAL",
"usedPoints": "0.00",
"apply": {
"item": [{
"magnitude": "0.000",
"qty": "1.000",
"seq": "1",
"value": "0.00",
"valueWithTaxes": "0.00",
"xprice": "5000.00"
}]
},
"redeemOptions": {
"option": [
{
"benefitType": "percentageDiscount",
"cardPoints": "200.0",
"cardType": "089",
"id": "5e567f0506773d1c14528761_0",
"requiredPoints": "100.0",
"unit": "qty",
"value": "10.0"
},
{
"benefitType": "percentageDiscount",
"cardPoints": "1000.0",
"cardType": "089",
"id": "5e567f0506773d1c14528761_2",
"requiredPoints": "0.0",
"unit": "qty",
"value": "20.0"
},
{
"benefitType": "percentageDiscount",
"cardPoints": "0.0",
"cardType": "-",
"id": "5e567f0506773d1c14528761_3",
"requiredPoints": "500.0",
"unit": "qty",
"value": "20.0"
}
]
}
}]
}]
}]
}
}
Dado el siguiente mensaje request, mensaje con el item (seq="1") seleccionando la opción "5e567f0506773d1c14528761_0" (redeemOption)
<message store="1" terminal="001" date-time="2020-03-11 10:23" init-tck="true" messageId="3" void-trx="false" response="true" status="sale" evaluate="true" suggest="true" map-version="5208" companyId="napse"> <customer-add seq="1" id="1" points="40000" redeemPointsPriceFactor="1" /> <loyaltycard-add seq="1" id="999999001" type="089" amount="5000"/> <item-add seq="1" qty="1" code="111" magnitude="0" xprice="5000" unitprice="5000" redeemOption="5e567f0506773d1c14528761_0" /> </message>
Request SALE con 1 opción Seleccionada JSON
{
"message": {
"store": "1",
"terminal": "001",
"date-time": "2020-03-11 10:23",
"init-tck": "true",
"messageId": "3",
"void-trx": "false",
"response": "true",
"status": "sale",
"evaluate": "true",
"suggest": "true",
"map-version": "5208",
"companyId": "napse",
"customer-add": [{
"seq": "1",
"id": "1",
"points": "40000",
"redeemPointsPriceFactor": "1"
}],
"loyaltycard-add": [{
"seq": "1",
"id": "999999001",
"type": "089",
"amount": "5000"
}],
"item-add": [{
"seq": "1",
"qty": "1",
"code": "111",
"magnitude": "0",
"xprice": "5000",
"unitprice": "5000",
"redeemOption": "5e567f0506773d1c14528761_0"
}]
}
}
redeemOption
Cada ítem perteneciente al apply del beneficio podrá tener solo una opción seleccionada (un solo id del option "redeemOption")
Obtendremos como respuesta:
<message ack="0" engine="2.6" mapversion="5208" messageId="3" store="1" terminal="001"> <optional> <promo code="24330" id="promo-24330" nro="5e567ea506773d1c1452875d"> <benefit RecoveryPercentage="0" RecoveryValue="0" Recuperacion="no" TLOGMessage="promo" account="" applicationMethod="lineByLine" baseAmount="5000.00" benefitType="RedeemWithOptionsBenefit" displayMessage="promo" name="5e567ea506773d1c1452875d" nro="5e567f0506773d1c14528761" order="1" printerMessage="promo" prorationMethod="PROPORTIONAL" usedPoints="100.00"> <apply> <item benefitTypeOption="percentageDiscount" benefitUnitOption="qty" cardType="089" cardUsedPoints="200.00" magnitude="0.000" nominalDiscount="500.00" percentageDiscount="10.00" priceinPoints="5000.00" qty="1.000" redeemOption="5e567f0506773d1c14528761_0" seq="1" usedPoints="100.00" value="400.00" valuePoints="100.00" valueWithTaxes="400.00" xprice="5000.00"/> </apply> </benefit> </promo> </optional> </message>
JSON
{
"message": {
"ack": "0",
"engine": "2.6",
"mapversion": "5208",
"messageId": "3",
"store": "1",
"terminal": "001",
"optional": [{
"promo": [{
"code": "24330",
"id": "promo-24330",
"nro": "5e567ea506773d1c1452875d",
"benefit": [{
"RecoveryPercentage": "0",
"RecoveryValue": "0",
"Recuperacion": "no",
"TLOGMessage": "promo",
"account": "",
"applicationMethod": "lineByLine",
"baseAmount": "5000.00",
"benefitType": "RedeemWithOptionsBenefit",
"displayMessage": "promo",
"name": "5e567ea506773d1c1452875d",
"nro": "5e567f0506773d1c14528761",
"order": "1",
"printerMessage": "promo",
"prorationMethod": "PROPORTIONAL",
"usedPoints": "100.00",
"apply": {
"item": [{
"benefitTypeOption": "percentageDiscount",
"benefitUnitOption": "qty",
"cardType": "089",
"cardUsedPoints": "200.00",
"magnitude": "0.000",
"nominalDiscount": "500.00",
"percentageDiscount": "10.00",
"priceinPoints": "5000.00",
"qty": "1.000",
"redeemOption": "5e567f0506773d1c14528761_0",
"seq": "1",
"usedPoints": "100.00",
"value": "400.00",
"valuePoints": "100.00",
"valueWithTaxes": "400.00",
"xprice": "5000.00"
}]
}
}]
}]
}]
}
}
En este caso vemos que se modifico el ítem que tiene la opción seleccionada, se agregaron los atributos del calculo del beneficio al item apply.
Bloque redeemOptions
El bloque redeemOptions siempre estará visible mientras falten ítems por seleccionar y además el ticket tenga los puntos suficientes o cumpla con el tipo de tarjeta requerida y sus puntos (si por ejemplo la opcion tiene un tipo de tarjeta y el ticket no esa opción no estará disponible, o si no tiene puntos ya sea de cliente o de algún tipo de tarjeta esa opción no se mostrara), una vez que todos los item applies tengan su redeemOption se dejara de informar (también dejara de estar disponible si los ítems que no quieran aplicase ninguna opción se le coloca redeemOption="0")
Mensaje con los item que aplican seleccionando cada uno una redeem Option
<message store="1" terminal="1" date-time="2019-10-30 09:26" init-tck="true" messageId="1" void-trx="false" response="true" status="sale" evaluate="true" suggest="true" companyId="napse" map-version="5200" > <customer-add seq="1" id="1" points="300" redeemPointsPriceFactor="2" /> <item-add seq="1" qty="1" code="111" magnitude="0" xprice="2300" unitprice="2300" redeemOption="5db9b4afa171f2314ce5704e_1"/> <item-add seq="2" qty="1" code="222" magnitude="0" xprice="5000" unitprice="5000" redeemOption="5db9b4afa171f2314ce5704e_0" /> </message>
Msg con 2 opciones Seleccionadas JSON
{
"message": {
"store": "1",
"terminal": "1",
"date-time": "2019-10-30 09:26",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "sale",
"evaluate": "true",
"suggest": "true",
"companyId": "napse",
"map-version": "5200",
"customer-add": [{
"seq": "1",
"id": "1",
"points": "300",
"redeemPointsPriceFactor": "2"
}],
"item-add": [
{
"seq": "1",
"qty": "1",
"code": "111",
"magnitude": "0",
"xprice": "2300",
"unitprice": "2300",
"redeemOption": "5db9b4afa171f2314ce5704e_1"
},
{
"seq": "2",
"qty": "1",
"code": "222",
"magnitude": "0",
"xprice": "5000",
"unitprice": "5000",
"redeemOption": "5db9b4afa171f2314ce5704e_0"
}
]
}
}
<message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT" mapversion="5200" messageId="1" store="1" terminal="1"> <optional> <promo code="17048" id="Promo 002" nro="5db9b41fa171f2314ce57042"> <benefit TLOGMessage="Promo 002" account="" applicationMethod="resume" baseAmount="7300.00" benefitType="RedeemWithOptionsBenefit" displayMessage="Promo 002" name="5db9b41fa171f2314ce57042" nro="5db9b4afa171f2314ce5704e" order="1" printerMessage="Promo 002" prorationMethod="PROPORTIONAL" usedPoints="200.00"> <apply> <item benefitTypeOption="percentageDiscount" benefitUnitOption="qty" cardType="-" cardUsedPoints="0" magnitude="0.000" nominalDiscount="0.00" percentageDiscount="10.00" priceinPoints="0.00" qty="1.000" redeemOption="5db9b4afa171f2314ce5704e_1" seq="1" usedPoints="0" value="0.00" valuePoints="0.00" valueWithTaxes="0.00" xprice="2300.00" /> <item benefitTypeOption="fixedDiscount" benefitUnitOption="qty" cardType="-" cardUsedPoints="0" fixedDiscount="100.00" magnitude="0.000" nominalDiscount="100.00" priceinPoints="2500.00" qty="1.000" redeemOption="5db9b4afa171f2314ce5704e_0" seq="2" usedPoints="200.00" value="-300.00" valuePoints="400.00" valueWithTaxes="-300.00" xprice="5000.00" /> </apply> </benefit> </promo> </optional> </message>
Response Applies Seleccionados JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.0.0-SNAPSHOT",
"mapversion": "5200",
"messageId": "1",
"store": "1",
"terminal": "1",
"optional": [{
"promo": [{
"code": "17048",
"id": "Promo 002",
"nro": "5db9b41fa171f2314ce57042",
"benefit": [{
"TLOGMessage": "Promo 002",
"account": "",
"applicationMethod": "resume",
"baseAmount": "7300.00",
"benefitType": "RedeemWithOptionsBenefit",
"displayMessage": "Promo 002",
"name": "5db9b41fa171f2314ce57042",
"nro": "5db9b4afa171f2314ce5704e",
"order": "1",
"printerMessage": "Promo 002",
"prorationMethod": "PROPORTIONAL",
"usedPoints": "200.00",
"apply": {
"item": [
{
"benefitTypeOption": "percentageDiscount",
"benefitUnitOption": "qty",
"cardType": "-",
"cardUsedPoints": "0",
"magnitude": "0.000",
"nominalDiscount": "0.00",
"percentageDiscount": "10.00",
"priceinPoints": "0.00",
"qty": "1.000",
"redeemOption": "5db9b4afa171f2314ce5704e_1",
"seq": "1",
"usedPoints": "0",
"value": "0.00",
"valuePoints": "0.00",
"valueWithTaxes": "0.00",
"xprice": "2300.00"
},
{
"benefitTypeOption": "fixedDiscount",
"benefitUnitOption": "qty",
"cardType": "-",
"cardUsedPoints": "0",
"fixedDiscount": "100.00",
"magnitude": "0.000",
"nominalDiscount": "100.00",
"priceinPoints": "2500.00",
"qty": "1.000",
"redeemOption": "5db9b4afa171f2314ce5704e_0",
"seq": "2",
"usedPoints": "200.00",
"value": "-300.00",
"valuePoints": "400.00",
"valueWithTaxes": "-300.00",
"xprice": "5000.00"
}
]
}
}]
}]
}]
}
}
Mensaje con los item que aplican seleccionando cada uno una redeem Option pero el cliente tiene puntos insuficientes.
<message store="1" terminal="1" date-time="2019-10-30 09:26" init-tck="true" messageId="1" void-trx="false" response="true" status="sale" evaluate="true" suggest="true" companyId="napse"> <customer-add seq="1" id="1" points="300" redeemPointsPriceFactor="2" /> <item-add seq="1" qty="1" code="111" magnitude="0" xprice="2300" unitprice="2300" redeemOption="5db9b4afa171f2314ce5704e_1"/> <item-add seq="2" qty="1" code="222" magnitude="0" xprice="5000" unitprice="5000" redeemOption="5db9b4afa171f2314ce5704e_2" /> </message>
Mensaje Seleccionando Opciones y Cliente con saldo insuficiente JSON
{
"message": {
"store": "1",
"terminal": "1",
"date-time": "2019-10-30 09:26",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "sale",
"evaluate": "true",
"suggest": "true",
"companyId": "napse",
"customer-add": [{
"seq": "1",
"id": "1",
"points": "300",
"redeemPointsPriceFactor": "2"
}],
"item-add": [
{
"seq": "1",
"qty": "1",
"code": "111",
"magnitude": "0",
"xprice": "2300",
"unitprice": "2300",
"redeemOption": "5db9b4afa171f2314ce5704e_1"
},
{
"seq": "2",
"qty": "1",
"code": "222",
"magnitude": "0",
"xprice": "5000",
"unitprice": "5000",
"redeemOption": "5db9b4afa171f2314ce5704e_2"
}
]
}
}
En este caso vemos como el motor responde el apply del item con seq 2 con un beneficio 0 dado que, los puntos del cliente solo alcanzaron para la opción del item seq=1.
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT" mapversion="5200" messageId="1" store="1" terminal="1"> <optional> <promo code="17048" id="Promo 002" nro="5db9b41fa171f2314ce57042"> <benefit TLOGMessage="Promo 002" account="" applicationMethod="resume" baseAmount="7300.00" benefitType="RedeemWithOptionsBenefit" displayMessage="Promo 002" name="5db9b41fa171f2314ce57042" nro="5db9b4afa171f2314ce5704e" order="1" printerMessage="Promo 002" prorationMethod="PROPORTIONAL" usedPoints="0.00"> <apply> <item benefitTypeOption="percentageDiscount" benefitUnitOption="qty" magnitude="0.000" nominalDiscount="0.00" percentageDiscount="10.00" priceinPoints="0.00" qty="1.000" redeemOption="5db9b4afa171f2314ce5704e_1" seq="1" usedPoints="0" value="0.00" valuePoints="0.00" valueWithTaxes="0.00" xprice="2300.00"/> <item benefitTypeOption="newPrice" benefitUnitOption="qty" magnitude="0.000" newPrice="500.00" nominalDiscount="0.00" priceinPoints="0.00" qty="1.000" redeemOption="5db9b4afa171f2314ce5704e_2" seq="2" usedPoints="0" value="0.00" valuePoints="0.00" valueWithTaxes="0.00" xprice="5000.00"/> </apply> </benefit> </promo> </optional> </message>
Respuesta Puntos Insuficientes JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.0.0-SNAPSHOT",
"mapversion": "5200",
"messageId": "1",
"store": "1",
"terminal": "1",
"optional": [{
"promo": [{
"code": "17048",
"id": "Promo 002",
"nro": "5db9b41fa171f2314ce57042",
"benefit": [{
"TLOGMessage": "Promo 002",
"account": "",
"applicationMethod": "resume",
"baseAmount": "7300.00",
"benefitType": "RedeemWithOptionsBenefit",
"displayMessage": "Promo 002",
"name": "5db9b41fa171f2314ce57042",
"nro": "5db9b4afa171f2314ce5704e",
"order": "1",
"printerMessage": "Promo 002",
"prorationMethod": "PROPORTIONAL",
"usedPoints": "0.00",
"apply": {
"item": [
{
"benefitTypeOption": "percentageDiscount",
"benefitUnitOption": "qty",
"magnitude": "0.000",
"nominalDiscount": "0.00",
"percentageDiscount": "10.00",
"priceinPoints": "0.00",
"qty": "1.000",
"redeemOption": "5db9b4afa171f2314ce5704e_1",
"seq": "1",
"usedPoints": "0",
"value": "0.00",
"valuePoints": "0.00",
"valueWithTaxes": "0.00",
"xprice": "2300.00"
},
{
"benefitTypeOption": "newPrice",
"benefitUnitOption": "qty",
"magnitude": "0.000",
"newPrice": "500.00",
"nominalDiscount": "0.00",
"priceinPoints": "0.00",
"qty": "1.000",
"redeemOption": "5db9b4afa171f2314ce5704e_2",
"seq": "2",
"usedPoints": "0",
"value": "0.00",
"valuePoints": "0.00",
"valueWithTaxes": "0.00",
"xprice": "5000.00"
}
]
}
}]
}]
}]
}
}
<message store="1" terminal="1" date-time="2019-10-30 09:26" init-tck="true" messageId="1" void-trx="false" response="true" status="sale" evaluate="true" suggest="true" companyId="napse" map-version="5200"> <customer-add seq="1" id="1" points="300" redeemPointsPriceFactor="2" /> <item-add seq="1" qty="1" code="111" magnitude="0" xprice="2300" unitprice="2300" redeemOption="5db9b4afa171f2314ce5704e_1"/> <item-add seq="2" qty="1" code="222" magnitude="0" xprice="5000" unitprice="5000" redeemOption="0" /> </message>
Mensaje Seleccionando Opciones con una seleccion 0 JSON
{
"message": {
"store": "1",
"terminal": "1",
"date-time": "2019-10-30 09:26",
"init-tck": "true",
"messageId": "1",
"void-trx": "false",
"response": "true",
"status": "sale",
"evaluate": "true",
"suggest": "true",
"companyId": "napse",
"map-version": "5200",
"customer-add": [{
"seq": "1",
"id": "1",
"points": "300",
"redeemPointsPriceFactor": "2"
}[,
"item-add": [
{
"seq": "1",
"qty": "1",
"code": "111",
"magnitude": "0",
"xprice": "2300",
"unitprice": "2300",
"redeemOption": "5db9b4afa171f2314ce5704e_1"
},
{
"seq": "2",
"qty": "1",
"code": "222",
"magnitude": "0",
"xprice": "5000",
"unitprice": "5000",
"redeemOption": "0"
}
]
}
}
Cuando no se quiera ver el bloque de redeemOptions deberá seleccionarse el redeemOption="0" en cada item
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT" mapversion="5200" messageId="1" store="1" terminal="1"> <optional> <promo code="17048" id="Promo 002" nro="5db9b41fa171f2314ce57042"> <benefit TLOGMessage="Promo 002" account="" applicationMethod="resume" baseAmount="7300.00" benefitType="RedeemWithOptionsBenefit" displayMessage="Promo 002" name="5db9b41fa171f2314ce57042" nro="5db9b4afa171f2314ce5704e" order="1" printerMessage="Promo 002" prorationMethod="PROPORTIONAL" usedPoints="0.00"> <apply> <item benefitTypeOption="percentageDiscount" benefitUnitOption="qty" cardType="-" cardUsedPoints="0" magnitude="0.000" nominalDiscount="0.00" percentageDiscount="10.00" priceinPoints="0.00" qty="1.000" redeemOption="5db9b4afa171f2314ce5704e_1" seq="1" usedPoints="0" value="0.00" valuePoints="0.00" valueWithTaxes="0.00" xprice="2300.00"/> <item magnitude="0.000" qty="1.000" seq="2" value="0.00" valueWithTaxes="0.00" xprice="5000.00"/> </apply> </benefit> </promo> </optional> </message>
Respuesta Puntos Insuficientes JSON
{
"message": {
"ack": "0",
"companyId": "napse",
"engine": "7.0.0-SNAPSHOT",
"mapversion": "5200",
"messageId": "1",
"store": "1",
"terminal": "1",
"optional": [{
"promo": [{
"code": "17048",
"id": "Promo 002",
"nro": "5db9b41fa171f2314ce57042",
"benefit": [{
"TLOGMessage": "Promo 002",
"account": "",
"applicationMethod": "resume",
"baseAmount": "7300.00",
"benefitType": "RedeemWithOptionsBenefit",
"displayMessage": "Promo 002",
"name": "5db9b41fa171f2314ce57042",
"nro": "5db9b4afa171f2314ce5704e",
"order": "1",
"printerMessage": "Promo 002",
"prorationMethod": "PROPORTIONAL",
"usedPoints": "0.00",
"apply": {
"item": [
{
"benefitTypeOption": "percentageDiscount",
"benefitUnitOption": "qty",
"cardType": "-",
"cardUsedPoints": "0",
"magnitude": "0.000",
"nominalDiscount": "0.00",
"percentageDiscount": "10.00",
"priceinPoints": "0.00",
"qty": "1.000",
"redeemOption": "5db9b4afa171f2314ce5704e_1",
"seq": "1",
"usedPoints": "0",
"value": "0.00",
"valuePoints": "0.00",
"valueWithTaxes": "0.00",
"xprice": "2300.00"
},
{
"magnitude": "0.000",
"qty": "1.000",
"seq": "2",
"value": "0.00",
"valueWithTaxes": "0.00",
"xprice": "5000.00"
}
]
}
}]
}]
}]
}
}
Limitaciones
Seleccion de Opciones
Existe la limitación de que un ítem solo puede seleccionar una opción sola.
Id del elemento Option
Id del elemento Option
Cuando la opción del beneficio es por cantidad, los puntos requeridos serán los definidos en la opción por la cantidad del ítem.
Aclaración se puede dar el caso de que por la cantidad no sean suficientes los puntos, pero si se hace varios ítems con cantidad 1 ,quizás algunos apliquen,
Un ejemplo seria si un cliente tiene 200 puntos, y la opción requiere 100 puntos, si el ítem tiene cantidad 3 no aplica porque los puntos son insuficientes, pero si desde el pos se generasen 3 lineas por ítem con cantidad 1 las dos primeras lineas aplicarían y la 3 no porque no le alcanzarían los puntos.
Devoluciones Automaticas RETURNFINISH
- Este beneficio por ser un caso muy raro no se ha implementado la devolución automática (es difícil de matchear la devolución de los ítems y los applies), es decir no soporta el returnFinish.
- Para devolver los puntos de elementos de fidelidad canjeados, se deberá desde el pos hacer un chargeamount para poder devolver los mismos.
Validaciones no cumplidas