...
| Informações | ||
|---|---|---|
| ||
|
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:
...
| Informações | ||
|---|---|---|
| ||
|
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:
...
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 | |
| redeemOption | Alfanumérico | (Version > 7.EP2.1) Beneficio "Canje con opciones" - informara las opciones entre las que puede elegir el cliente para acceder a un determinado beneficio canjeando una determinada cantidad de puntos (del cliente y/o tarjeta de fidelidad) Mas detalle en Apéndice I - Canje con opciones | No | ||
Coupon | amount | Numérico positivo | Se utiliza para indicar el valor monetario del cupón. Si no tiene no se utiliza. | No | 0 |
type | Alfanumérico | Tipo de cupón (Aclaración: el tipo de cupón externo son cupones no administrados por PROMO. Este tipo de cupón es emitido y/o redimido por un sistema externo a PROMO). | 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 | "-" | |
| validFrom | Alfanumérico | Fecha de inicio de vigencia . Formato "YYYY-MM-DD" (Año-Mes-Dia) .Ejemplo"2021-07-16" | No | "-" | |
| validTo | Alfanumérico | Fecha de fin de vigencia . Formato "YYYY-MM-DD" (Año-Mes-Dia) .Ejemplo"2021-07-16" | No | "-" | |
Customer | type | Alfanumérico | Tipo de cliente. | No | "-" |
id | Alfanumérico | Identifica al cliente a través del Código. | No | "-" | |
remainingAmount | Numérico positivo | Propiedad que se puede utilizar para indicar el saldo a favor o en contra del cliente en cuestión. (compatibilidad con PROMO 4 y versiones anteriores) | No | 0 | |
points | Entero positivo | Saldo que posee el cliente. (compatibilidad con PROMO 4 y versiones anteriores) | No | 0 | |
Alfanumérico | Atributo incluido para la consulta de clientes | No | "" | ||
name | Alfanumérico | Atributo incluido para la consulta de clientes | No | "" | |
lastName | Alfanumérico | Atributo incluido para la consulta de clientes | No | "" | |
Identifier | Numérico positivo | Atributo incluido para la consulta de clientes | No | "" | |
cardNumber | Numérico positivo | Atributo incluido para la consulta de clientes | No | "" | |
creditCampaignCode | Alfanumérico | Código de la Campaña crediticia | No | "" | |
profileCode | Alfanumérico | Código del perfil del cliente | No | "" | |
| limitedBenefits | Alfanumérico | Consiste en un listado de Limites asociados a Convenios. El mismo es del tipo: limitedBenefits:"limite1:valor1;limite2:valor2;limite3:valor3.....". Estos valores pueden ser informados desde el Punto de Venta o bien son obtenidos mediante una respuesta a LoyaltyValidation y reinjectados por parte del Puntos de venta como han sido recibidos. | No | "" | |
| segment | Alfanumérico | Lista de Códigos de Segmento a los cuales pertenece el cliente, separados por ; | 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 | |
| pointsType | Alfanumérico | Identifica el tipo de pago con puntos (ver manual de usuario Final Promo 7 - "Ignorar pago con Puntos" - Ver también beneficio PromotionPaidInPoints) | No | "" | |
| installments | Numérico positivo | Indica la cantidad de cuotas asociadas al pago | No | "" | |
| prefix | Alfanumérico | Indica el Prefijo asociado al pago | No | "" | |
| Alfanumérico | Indica el Bolsllo asociado al pago | No | "" | ||
| prefixGroup | Alfanumérico | Indica el grupo de Prefijos asociado al pago | No | "" | |
| payCreditCampaign | Alfanumérico | Indica la Campaña Crediticia asociada al pago | No | "" | |
Event | type | Alfanumérico | Tipo de evento. | No | "-" |
id | Alfanumérico | Identificador del evento. | No | "-" | |
value | Alfanumérico | Valor que representa el evento. | No | "-" | |
| Benefit | id | Alfanumérico | Identificador del beneficio externo. | Si | |
| type | Alfanumérico | Tipo de beneficio externo. | Si | ||
| amount | Numérico positivo | Se utiliza para indicar el monto a descontar o el porcentaje de descuento (de acuerdo al benefitType). | Si | ||
| benefitType | Alfanumérico | Indica el tipo de beneficio a generar.
| No | "desc" | |
| seqItem | Alfanumérico | Número de secuencia de los 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 |
...
| Aviso |
|---|
| Importante: Si se agrega un elemento al contexto con un número de secuencia ya utilizado por un elemento del mismo tipo, el último enviado reemplazará al anterior. |
| Aviso | ||
|---|---|---|
| ||
Si el ítem es mensurable, se debe colocar el valor de magnitude, no es necesario colocar qty. Pero en el caso de ponerlo, este valor debe ser qty= 1. El motor prevalecerá el valor de Magnitud al valor de cantidad. |
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"):
...
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:
| 1 | Valor de ack | Descripción | Acción recomendada | ||||||||||||
| 2 | 0 | No existieron errores. | Utilizar la respuesta. | ||||||||||||
| 3 | 1 | Error de comunicación o el mensaje es ilegible. | Reenviar el mensaje y si el error persiste re validar su formato. | ||||||||||||
| 4 | 2 | La sesión no fue inicializada o no existe dicha sesión. | Iniciar sesión como se indica en "Manejo de sesiones". | ||||||||||||
| 5 | 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. | ||||||||||||
| 6 | 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. | ||||||||||||
| 7 | 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. | ||||||||||||
| 8 | 2003 | La sesión se encuentra en uso. | Esperar unos 3 segundos aproximadamente y reintentar el envío. | ||||||||||||
| 9 | 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. | ||||||||||||
| 10 | 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. | ||||||||||||
| 11 | 4001 | El motor se encuentra en proceso de inicialización. | Esperar porque el motor está arrancando y cargando la información. | ||||||||||||
| 12 | 8296 | Existen errores en la validación | Este error se da con Status=loyaltyvalidationex y FinishEx, debera analizarse el archivo de log a fin de establecer cual fue el error. Este error de validacion sera informado dentro del tag </errors> en el cuerpo de la respuesta con el ACK="8296". | ||||||||||||
| 13 | 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. | ||||||||||||
| 14 |
| 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. | ||||||||||||
| 15 | 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. |
| Âncora | ||||
|---|---|---|---|---|
|
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:
...
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 Módulo de administracion/Informacion de configuracion 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.
| Aviso | ||||
|---|---|---|---|---|
| ||||
Si la variable :
es true, los participantes de condición siempre se verán, independientemente que la promoción tenga o no tildado el check de "Reporta Participantes". |
| Bloco de código | ||||||
|---|---|---|---|---|---|---|
| ||||||
<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> |
...
| Bloco de código | ||||||
|---|---|---|---|---|---|---|
| ||||||
<message companyId="test2" store="test1" terminal="0011" date-time="20202023-1210-2809 11:2513:00:20" init-tck="false" messageId="00111" void-trx="false" response="true" init-tckstatus="truefinishex" evaluate="true" statussuggest="finishexfalse"> <customer-add seq="1" id="123452" /> <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)
| Bloco de código | ||||||||
|---|---|---|---|---|---|---|---|---|
| <message
| |||||||
----- message ------ <?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="test2" engine="27.0.635#153" mapversion="263" messageId="00141" store="test1" terminal="0011" transaction="test2_test1_0011_2020122811280220231009130020"> <loyalty><loyaltycards/> <coupons/> <errors/> <customers/> <redeemTable/> <loyalty> <loyaltycards/> <coupons> <coupon ack="0" amount="0.00" barcode="1050010012356" benefitNro="64db6a1992889f3a2c4d49ac" couponId="7" encoding="EAN13" format="PRINTED" promotionName="Promo Obtene tu cupon" promotionNro="64db69e192889f3a2c4d49a6"><![CDATA[1050010012356 15/08/2023 00:00 31/12/2023 23:59]]></coupon> </coupons> <errors/> <customers/> <redeemTable/> </loyalty> </message> |
Respuesta 2: Existen errores en la validacion (Finish+rollback fueron ejecutados)
| Bloco de código | ||||||||
|---|---|---|---|---|---|---|---|---|
| <message
| |||||||
----- message ------ <?xml version="1.0" encoding="UTF-8"?><message ack="8296" companyId="test2" engine="27.0.635#153" mapversion="263" messageId="00111" store="test1" terminal="0011" transaction="test2_test1_0011_2020122811250120231009133020"> <loyalty> <loyaltycards/> <coupons/> <errors> <coupons> </coupons> <errors> <error ack="9101" id="1010BCup10000x55552385529" info="1010BCup10000x55552385529" 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> <customers/> <redeemTable/> </loyalty> </message> |
| Âncora | ||||
|---|---|---|---|---|
|
...