Manual de integración - Motor
PROMO V7.0
Índice
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 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 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 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 posse 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 deberan incoporar 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>
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>
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 parametro "request" con el mensaje correspondiente que debe evaluar el motor, como se especifica en el presente documento.
Importante
- Si el motor posse 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 deberan incoporar 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="exito" 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 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>
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 envia 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 utlizado 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 informacion de los beneficios de cada promocion 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. | 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 envia 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 | "" |
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>
<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>
<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>
<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>
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 las tarjetas 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. |
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> etc.
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.
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 | "-" |
| 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 | (Version > 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 | (Version > 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 | (Version > 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 | (Version > 7.EP2.1) Precio una vez superada la cantidad 3 (qty3). Solo para Promociones de Nuevo Precio que indican usar monto externo. | No | 0 | |
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 tarjeta loyalty | No | "-" |
| id | Alfanumérico | Idenficiador de la tarjeta loyalty | Si | "-" |
| amount | Numérico positivo | Saldo de la tarjeta loyalty | No | 0 |
| chargeAmount | Numérico positivo | Saldo a acreditar a una tarjeta loyalty | No | 0 |
| consumeAmount | Numérico positivo | Saldo a debitar a una tarjeta loyalty | No | 0 |
| status | Alfanumérico | ENABLED o DISABLED para habilitar o deshabilitar una tarjeta fidelidad (solo valido en status LoyatyActivation) | No | "ENABLED" |
nextExpDate | Numérico | Fecha de la proxima expiracion de puntos en format YYYYmmdd. Solo es informado en tarjetas que posean vencimiento de carga definido. | No | "-" | |
nextExpValue | Numérico | Cantidad de puntos que venceran en el proximo vencimiento (nextExpDate) y se informa solo si la tarjeta 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 codigo de seguridad o cvv asociado a la tarjeta. | No | "-" | |
Customer | type | Alfanumérico | Tipo de cliente. | No | "-" |
| id | Alfanumérico | Identificador del cliente. | 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 ; | 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 princialmente 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 items 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 |
Event | type | Alfanumérico | Tipo de evento. | No | "-" |
| id | Alfanumérico | Identificador del evento. | No | "-" |
| value | Alfanumérico | Valor que representa el evento. | No | "-" |
| seqItem | Alfanumérico | Número de secuencia de los items a los cuales hay que aplicar el descuento. Si no viene el atributo o viene vacio se asume que es para todo el ticket. En caso de tener varios secuencias, las mismas deben venir separados por coma. Si algun 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" unitaryPrice="25.0" qty="1.0" 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>
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 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 | Error en evaluación de sugerencia. | Comunicarse con el administrador del Motor de promociones para que, por medio del archivo de log, se establezca cuál fue el error. Generalmente, este error puede tener que ver con un suggest-seq o suggest-seq-type inválido o algún otro error en la evaluación de sugerencias. |
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 partir de PROMO 5, se han agregado la serie de errores 9xxx los cuales aplican a Errores producidos en el procesamiento de la Consola de PROMO Central.
Dichos errores son:
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 | 9101 | No se ha encontrado el Cupón | Verificar los datos solicitados |
11 | 9102 | Cupón Consumido | Verificar que el cupón no haya sido utilizado |
12 | 9103 | Cupón Inactivo | Verificar que el cupón solicitado se encuentre activo. |
13 | 9104 | No se ha encontrado el tipo de cupón | Verificar valor informado en el mensaje. |
14 | 9105 | El Cupón ha expirado. | La fecha de vencimiento del cupón se ha alcanzado, con lo cual verificar dicha situación. |
15 | 9106 | Se ha alcanzado el máximo número de usos | Verificar dicha situación |
16 | 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 |
17 | 9108 | El tipo de cupón no está activo | Verificar el tipo de cupón |
18 | 9109 | El monto enviado no corresponde al monto del cupón | Verificar monto del cupón |
19 | 9110 | Cupón no usado | El cupón ingresado a la transacción no ha participado de ninguna promoción. |
20 | 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). |
21 | 9201 | No se encontró el encabezado de la transacción. | Normalmente debido a un error interno, consultar con el administrador del sistema. |
22 | 9500 | No se encontró la tarjeta loyalty | Verificar los datos solicitados |
23 | 9501 | Tarjeta fidelidad inhabilitada | Verificar los datos solicitados. Para algunas acciones, solo se puede procesar Tarjetas fidelidad habilitadas |
24 | 9502 | Tarjeta fidelidad cancelada | Verificar los datos solicitados. No se puede interactuar con tarjetas fidelidad canceladas |
25 | 9503 | No se encontró el Tipo de tarjeta loyalty | Verificar los datos solicitados |
26 | 9504 | Tipo de tarjeta no activa | Verificar los datos solicitados. No se puede interactuar con tipos de tarjeta inactivos |
27 | 9505 | Tipo de tarjeta no recargable | Verificar los datos solicitados. Para opciones de Carga o Recarga, el tipo de tarjeta debe ser recargable |
28 | 9506 | La tarjeta ya tiene un cliente asociado | Verificar que la tarjeta en la activación el customer enviado. |
29 | 9507 | El estado enviado de tarjeta no existe. | Verificar que se haya enviado un estado de tarjeta, en la activación, valido (ENABLED, DISABLED) – En Mayúscula – |
30 | 9508 | La tarjeta no aplica al beneficio | Verificar que el tipo de tarjeta sea recargable o que la tarjeta este habilitada. Otro error puede ser que el tipo de tarjeta con el que se armó el beneficio, este inactivo o no exista en la transacción. |
31 | 9509 | La tarjeta requiere un cliente | Verificar si el tipo de tarjeta es requerido, en la transacción debe viajar al menos un cliente. |
32 | 9510 | Tarjeta no autorizada | Esto se da, si el tipo de tarjeta requiere CVV y no fue enviado o se ingresó mal |
33 | 9511 | Amount invalido | Cuando se intenta descontar un amount que es mayor al total del amount de la tarjeta, este mensaje aparecerá. Verificar que el amount sea menor al total. |
34 | 9512 | Se requiere al menos dos tarjetas | 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" |
35 | 9513 | La tarjeta no admite transferencia. | Verificar que la tarjeta origen admita Transferencia. Ya sea parcial o total. |
36 | 9514 | La tarjeta destino esta activa | Verificar que la tarjeta destino esta inactiva para realizar una transferencia total. |
37 | 9515 | Los tipos de tarjetas no son iguales | Verificar que los tipos de tarjeta sean iguales, es decir, el mismo. |
38 | 9516 | El saldo ingresado es mayor al tope de saldo | Verificar que el valor ingresado para la carga de una tarjeta, no sea mayor al Tope de saldo del tipo de tarjeta. |
39 | 9603 | Cliente inexistente | Verificar datos de cliente ingresado en la transacción |
40 | 9610 | identificador de cliente vacío | Verificar datos de cliente ingresado en la transacción |
41 | 9611 | Nombre de cliente vacío | Verificar datos de cliente ingresado en la transacción |
42 | 9612 | Apellido de cliente vacío | Verificar datos de cliente ingresado en la transacción |
43 | 9613 | ID de cliente Vacío | Verificar datos de cliente ingresado en la transacción |
44 | 9614 | No se recibieron parámetros del cliente | Verificar datos de cliente ingresado en la transacción |
45 | 9620 | Cliente ya existente | Verificar datos de cliente ingresado en la transacción |
46 | 9629 | Cliente inactivo | Verificar datos de cliente ingresado en la transacción |
47 | 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. |
48 | 9999 | Error inesperado | Todo error en el procesamiento de PROMO Central que no se encuentre tipificado en los casos anteriores. |
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="4001"> <optional> … promociones que componen la opción … </optional> <optional> … promociones que componen la opción … </optional> </message>
<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>
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 tarjetas)
- Cada cupón contendrá el detalle de los mismos para su emisión(opcional, puede no existir dicha información)
- Cada tarjeta contendrá el detalle de la tarjeta
- 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 tarjetas)
Opciones
Cada una de las opciones representa una de las opciones entre las que puede optar el cliente. 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="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> </message>
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>
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>
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
- 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.
- GeneralBenefit
- Entrega al cliente uno o más beneficios generales.
- Entrega al cliente uno o más beneficios generales.
- 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 pado (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 items 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 tarjeta 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 codigos de cupon 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. |
| 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 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 | 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 cupon 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 cupon cuyo monto fue calculado |
| Percentage | Alfanumérico | Si | Indica el porcentaje en base al cual fue calculado el monto del cupon |
| qty | Entero positivo | Si | Cantidad de cupones a otorgar. |
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>
<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>
<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="TenderDiscountBenefit" displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" tender="VISA" planId="0A3" limitAmount="200.00" baseAmount="165.00" bank="HSBC" percent="5.000" percenttype="discount" amount="2375.000" itemamount="2500.000" paymentAmount="2500.000" benefitedamount="125.000" tenderseq="1" > … participantes de combo y/o elementos aplicados … </benefit> </promo> </optional> </message>
<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">
<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>
<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>
<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>
<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>
<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> <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="2.0" seq="2"/> < 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" unit="qty" totalpoints="2000.00" > … participantes de combo y/o elementos aplicados … <item value="0.000" seq="2" qty="2.000" points="2000.00" xprice="99.00"/> </benefit> </promo> </optional> </message>customer
<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>
<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"/> < 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> customer
<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>
<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>
<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>
<?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>
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>
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>
Elementos no aplicados
En los beneficios externos (ExternalBenefit) pueden existir ítems que no son aplicados porque no están presentes en el contexto. Para representar esto el Motor de Promociones al informar beneficios utiliza la etiqueta <notApply>, donde se enumerarán los artículos sobre los cuales no pudo aplicarse el beneficio. Debido a que los beneficios solo pueden ser aplicados sobre artículos, los elementos contenidos en <notApply> 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 <notApply> 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 que no se pudo descontar al elemento indicado por el atributo seq. |
qty | Entero positivo | Cantidad de ítems que no fueron afectados. |
magnitude | Real positivo | Magnitud que no fue afectada |
xprice | Real positivo | Ira siempre en cero. |
<message engine="2.6" companyId="sts" store="0236" terminal="004" mapversion="114" ack="0" messageId="3777"> <optional> <promo id="Desc5" nro="3"> <conditionParticipants> <benefit benefitType="desc" amount="100.00" seqItem="2=2,3=2,5" type="MktExc" seq="1" id="1234"/> </conditionParticipants> <benefit benefitType="ExternalBenefit" discountAmount="60.00" type="MktExc" TLOGMessage="" account="" applicationMethod="" displayMessage="" order="1" prorationMethod="PROPORTIONAL" nro="3" baseAmount="3000.00" printerMessage=""> <apply> <item value="20.00" magnitude="0.000" xprice="1000.00" seq="2" qty="1.000"/> <item value="40.00" magnitude="0.000" xprice="2000.00" seq="3" qty="2.000"/> </apply> <notApply> <item value="20.000" magnitude="0.000" xprice="0.000" seq="2" qty="1.000"/> <item value="20.000" magnitude="0.000" xprice="0.000" seq="5" qty="1.000"/> </notApply> </benefit> </promo> </optional> </message>
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>
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 Tarjetas de Fidelidad | Las secuencias de tipo tarjetas 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> <message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> … promociones que componen la opción … </optional> <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> <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" /> <promo id="Promoción 2x1 en juguetes"/> </suggestions> </message>
Fidelidad
Nuevos Status en <Loyalty>
Históricamente, el valor de la propiedad Status, era de libre uso y no tenía restricciones. A partir de PROMO 5 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
Consulta estado de cupones, clientes y tarjetas a PROMO central.
<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="loyaltyvalidation" evaluate="true" map-version="9" suggest="false"> <loyaltycard-add seq="2" id=" 2220000000001" /> <coupon-add seq="1" qty="1" id=" 002001001413" /> <customer-add seq="1" id="6666"/> </message>
Existen dos funciones opcionales (a habilitar) respecto a validacion de clientes: (desde 6.5.2)
- Creacion de clientes: Si se envia informacion de cliente completa (es decir email o identifier) y el cliente no existe en Promo, el mismo será dado de alta automaticamente.
- Actualizacion de clientes: Si se recibe informacion de un cliente completa y el cliente existe, entonces se considera que la validacion no es una mera consulta de datos sino que al enviar datos como el "nombre del cliente" se requiere hacer una actualizacion 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.
LoyaltyActivation
Realiza la activación de una tarjeta de fidelidad.
Para activar una tarjeta 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="sts" store="1" terminal="1" date-time="2017-12-29 16:49:16" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyactivation" evaluate="true" map-version="9" suggest="false"> <loyaltycard-add seq="1" id="3330000000000"/> </message>
También pude realizarse la inactivación de una tarjeta activa con el LoyaltyAvtivation, agregando en el tag <loyaltycard-add/> el status="DISABLED".
<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="loyaltyactivation" msg-version="9" map-version="1"> <loyaltycard-add seq="1" id="3330000000000" status="DISABLED" /> </message>
(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 Tarjetas de Fidelidad
Desde la version 6.4 de Promo, se ha incorporado al status "loyaltyActivation" un valor para la propiedad status del elemento loyaltcard, un valor CREATE para indicar que se desea crear la tarjeta.
Desde la version 6.5.14 si se especifica un cvv el mismo será registrado y asociado a la tarjeta que se ha creado.
En la siguiente figura se muestra un tipo de ejemplo denominado t1
Procedemos a la creacion sin carga de la primer tarjeta:
<message companyId="test" store="1" terminal="10" date-time="2018-10-10 09:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyActivation" evaluate="false" offline="false"> <loyaltycard-add seq="1" id="10011" type="t1" status="CREATE" /> </message>
La respuesta es: (Ack =0 es correcto)
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="test" engine="6.1.3" mapversion="0" messageId="1" store="1" terminal="10" transaction="test_1_10_20181025125336"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers/> </loyalty> </message>
Adicionalmente si se desea dar una carga inicial se puede agregar la propiedad "chargeAmount" del elemento loyaltyCard. De esta forma ademas de crearla, se cargara iniciamente ese saldo.
Luego procedemos a crear una segunda con saldo:
<message companyId="test" store="1" terminal="10" date-time="2018-10-10 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="CREATE" chargeAmount="105.00" /> </message>
Respuesta
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="test" engine="6.1.3" mapversion="0" messageId="1" store="1" terminal="10" transaction="test_1_10_20181025125336"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers/> </loyalty> </message>
Si observamos el detalle de alguna de ellas:
LoyaltyTransfer
Realiza la transferencia de saldo de una tarjeta de fidelidad a otra del mismo tipo.
Para poder realizar una transferencia de saldos, tanto la tarjeta 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>
(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="sts" store="00001" terminal="010" date-time="2017-03-27 14:57" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="loyaltyVoid" msg-version="2.0" map-version="1"> <coupon-add seq="1" qty="1" id="1000010105299" type="C-Impreso"/> <loyaltycard-add seq="2" id="6665000008801" type="roja" /> </message>
(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 una tarjeta. Se validara que la tarjeta no tenga previamente asociado a un cliente, que tanto el cliente como la tarjeta existan, que el tipo de tarjeta requiera asociación vía "Canal de Ventas" y que la tarjeta se encuentre inactiva.
<message companyId="sts" store="00001" terminal="010" date-time="2017-03-27 14:57" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="loyaltyAssign" msg-version="2.0" map-version="1"> <loyaltycard-add seq="2" id="6665000008801" type="roja" /> <customer-add seq="1" id="6666"/> </message>
(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>
Otra opción con la que se cuenta para la activación de una tarjeta 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 la tarjeta incluida en la transacción sea activada
<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>
(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>
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>
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>
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.
<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="returnFinish" originalTransaction="001_025_20161212134555" map-version="15" suggest="true" suggest-seq="3"> <item-add seq="2" qty="1" code="1" magnitude="0" xprice="100" unitprice="100"/> <payment-add seq="1" type="CreditCard" amount="100" id="000009" planId="10"/> <loyaltycard-add seq="5" id="3330000000133" /> <coupon-add seq="1" qty="1" id="xxxxxxxxxx" type="yyy" /> <customer-add seq="1" id="1"/> </message>
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>
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>
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/>
<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/> </loyalty> </message>
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" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530151500"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="0.0" customer="" id="2220000000001" seq="2" type="2"/> </loyaltycards> <coupons> <coupon ack="0" amount="10.0" barcode="002001001413" couponId="2" seq="1"/> </coupons> <errors/> <customers> <customer code="6666" email="[email protected]" identifier="30112255881" lastName="" name="Rojo Marcos" seq="1" segment="A1;B6;C11"> <coupon ack="0" amount="60.0" barcode="002009005475" couponId="2" useTotalAmount="true" /> <coupon ack="0" amount="" barcode="003090033000000002147483647" couponId="3"/> <loyaltycard ack="0" amount="0.0" id="5550000000222" type="5"/> </customer> </customers> </loyalty> </message>
La propiedad useTotalAmount es retornada solo sii el cupon es del tipo calculado y ademas 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 cupon 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.
Output – 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="9" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170529165306"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9501" amount="0.0" cardType="3" info="3330000000002" seq="2" type="loyaltycard-redeem"/> </errors> <customers/> </loyalty> </message>
Nota: Cuando la tarjeta que se consulte este inactiva, se informara en el atributo "amount" el saldo de la tarjeta al momento de la consulta y en "cardType" el tipo de tarjeta.
(ver también Engine Request – loyaltyValidation)
Response - Cupones
Se agregan 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 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="1000010019411" benefitNro="58d2a8f8ef5a63133c3ca31d" couponId="TC_IM" format="PRINTED"" encoding="EAN13" promotionName="Emisión C-impreso" promotionNro="58d2acdaef5a63133c3ca346">*<!\[CDATA\[.....\]\]>* </coupon> </coupons> <errors/> <customers/> </loyalty> </message>
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="1234567890123" 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="1234567890133" 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="1000010015888" benefitNro="5900e18ea846390de08a7afd" couponId="1" encoding="EAN13" format="PRINTED" promotionName="emite impreso calculado" promotionNro="5900e173a846390de08a7af7"><!\[CDATA\[ … datos libres… \]\]> </coupon> </coupons> <errors/> </loyalty> </message>
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 cupon cuyo monto fue calculado |
Response - Tarjetas Fidelidad
En la respuesta del motor se agregan al mensaje los datos de la o las tarjetas 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 esa tarjeta.
<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/> </loyalty> </message>
Como hemos mencionado por cada una de las tarjetas 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/> </loyalty> </message
Las propiedades de cada elemento tarjeta será:
Propiedad | Tipo de dato | Descripción |
Id | Alfanumérico | Número identificador de Tarjeta fidelidad |
Type | Alfanumérico | Identificador del tipo de tarjeta. |
ack | entero | Código de retorno |
amount | Número positivo | Saldo con el que quedaría la tarjeta |
cardType | Alfanumérico | Informa el tipo de la tarjeta (se informara solo en el tag <errors/> cuando el ACK sea 9501 – tarjeta inactiva) |
Response - Activación de tarjeta (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/> </loyalty> </message
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_20170530124222"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9500" info="333000000000" seq="1" type="loyaltycard-activation"/> </errors> <customers/> </loyalty> </message>
(Ver también Engine Request - LoyaltyActivation)
Response - Activación de tarjeta (en Finish)
Response OK (ACK="0" y se informan los datos de la tarjeta 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/> </loyalty> </message>
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/> </loyalty> </message>
(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 las tarjetas 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/> </loyalty> </message>
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/> </loyalty> </message>
(Ver también Engine Request - LoyaltyTransfer)
Response - LoyaltyVoid
Response OK – Cupón y Tarjetas
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <errors/> </loyalty> </message>
(Ver también Engine Request – LoyaltyVoid)
Imputación de saldos en tarjeta
<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>
<?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/> </loyalty> </message>
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/> </loyalty> </message>
Descuento de saldo en tarjeta
<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>
<?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/> </loyalty> </message>
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> </loyalty> </message>
Tarjetas de Fidelidad: Proceso de actualizacion 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 utlizados en una transaccion 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>
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/> </loyalty> </message>
Confirmamos la transaccion 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>
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"/>
En la siguiente pantalla se ve como resultado el consumo de puntos en la tarjeta:
Como paso siguiente en el ejemplo, dejamos pasar el dia 14-11 para observar la reversion 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 vecimiento 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>
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/> </loyalty> </message>
Confirmamos la transaccion:
<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>
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"/>
En el detalle de movimiento de la tarjeta se observa el consumo y que el identificador de transaccion fue "test_1_10_20181116165337":
Ahora enviamos la confirmacion
<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>
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/> </loyalty> </message>
Mediante esta operacion entonces el consumo ha sido confirmado y pasado el 18-11 no sera reversado.
Engine Response: Tag Errors
Además de cupones y tarjetas, 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 tarjetas, 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> </loyalty> </message>
<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> </loyalty> </message>
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 Tarjetas aqui 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 las tarjetas 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
(desde v7.0.2)
Este valor de estado unifica en un mismo mensaje lo ya conocido en loyaltyValidation mas una evaluación de Promociones. Si la validacion retorna errores, no se evaluaran promociones y la respuesta sera la respuesta tradicional del loyaltyValidation. Si no existen errores la respuesta incluira los ersultados de la validacion mas la respuesta de la evaluacion de promociones.
Caso: Se envia 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>
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>
Respuesta 2: Existen errores en la validacion
message ack="8399" 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>
FINISHEX
(desde v7.0.2)
Consiste en un mensaje que unifica o realiza lo conocido en Finish y dependiendo de la evaluacion de este, un commit (respuesta de finish exitosa) o rollback (finish reporta un error) automatico.
Caso: Se envia 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>
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>
Respuesta 2: Existen errores en la validacion (Finish+rollback fueron ejecutados)
<message ack="8399" 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>
Flujos de Tarjetas
En este apartado se expondrán los flujos desarrollados para tarjetas 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 tarjeta
El alta de una tarjeta se realizara en la consola de PROMO Central
Nota: El campo CVV tiene como largo máximo 5 posiciones.
Consulta de tarjeta
Activación de tarjeta (loyaltyActivation)
Activación de tarjeta (FINISH)
Transferencia entre tarjetas
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/> </loyalty> </message>
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"/>
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 tarjeta inactiva, esas tarjetas 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> </loyalty> </message>
(Ver también Engine Request - LoyaltyValidation)
Operacion con Segmentos
Imaginemos que tenemos una Promocion que da un beneficio a los clientes con segmento "ABC1". La Operatoria para trabajar con dicha Promocion seria:
- Realizamos una operacion 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>
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> </loyalty> </message>
3. Por ultimo realizamos la transaccion de venta con el cliente enviando su informacion 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>
De esta forma la transaccion sera evaluada y al ser un cliente que pertenece al segmento ABC1, le sera otorgada la Promocion.
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 electronicos por email. A este fin se ha incorporado la posibilidad de enviar la definicion del cliente (datos minimos necesarios) desde la mensajeria de Promo.
Los clientes serán creados utilizando el estado "loyaltyValidation" en el caso de enviarse los datos minimos y al mismo tiempo Promo detecte que el cliente no existe. Los datos minimos mencionados por ejemplo serian los marcados en negrita ne el siguiente ejemplo:
<customer-add seq=
"1"
id=
"10090504"
identifier=
"10090504"
type=
"test"
name=
"pepe"
lastName=
"rodrigues"
identifierType=
"cpf"
email=
"mimail@test.com"
/>
Veamos ahora un ejemplo de intercambio de estos mensajes:
Realizamos una peticion con loyaltyValidation y el cliente no existe:
Request<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>
La respuesta entrega valores por defecto:
Response<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> </loyalty> </message>
En este caso enviamos datos del cliente pero no completamos todos los campos necesarios:
Code<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>
La respuesta aun contiene datos por defecto:
Response<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> </loyalty></message>
Ahora enviamos TODOS los datos obligatorios para que el cliente sea creado
Code<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>
La respuesta es:
Code<?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> </loyalty> </message>
Ahora vamos a enviar el mensaje que enviamos en el punto 1, el cual tiene solo los datos basicos del cliente y por el cual en el punto 1 nos retornaba valores por defecto (el cliente no era conocido) mientras que ahora nos tendria que retornar todos los datos que ya conocemos y creamos en el punto 3.
Code<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>
La respuesta efectivamente es:
Code<?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> </loyalty> </message>
Operatoria (en base a los posibles escenarios):
Operatoria | 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 de tarjeta. | 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 la tarjeta se INACTIVA. Valida CVV |
Limites por clientes
Cuando el beneficio tenga limites por clientes, la operatoria del motor deberá ser la siguiente:
Para poder operar con limites de clientes 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.
El motor informara los limites consumidos dentro del elemento customer en el atributo limitedBenefits.
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>
<?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> </loyalty> </message>
En la respuesta podemos ver la información del cliente con el limitedBenefits que nos indica el limite por cliente del beneficio. 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>
<?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>
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>
<?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/> </loyalty> </message>
Por ultimo 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>
<?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"/>
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>
<?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> </loyalty> </message>
De realizar 2 transacciones mas ya no aplicara la promoción por haber superado el limite.
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>
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>
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>
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>
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>
<?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>
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>
<?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>
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.