Manual de Integração - Motor
PROMO v7.2
Índice
Sobre o manual
Finalidade e âmbito
O objetivo deste manual é treinar os usuários que desejam integrar seu aplicativo de vendas com o Motor de Promoções.
É fornecida uma descrição detalhada das mensagens que lhe devem ser enviadas e como interpretar as mensagens de resposta que dará a um pedido.
Documentação da PROMOÇÃO
O PROMO fornece a seguinte documentação:
- Manual de usuário:
Este documento tem como objetivo treinar o usuário que deseja utilizar o console de Administração de Promoções PROMO.
- Manual de instalação:
Este documento descreve os procedimentos para instalar os componentes Engine e Console, a criação e inicialização do Banco de Dados e os requisitos necessários para o correto funcionamento dos referidos componentes.
- manual de integração:
Este documento descreve detalhadamente as mensagens que devem ser enviadas ao Motor de Promoções e a forma de interpretação das mensagens de resposta que este dará a um pedido.
Nota: Antes de prosseguir com a leitura deste manual, recomenda-se a leitura dos capítulos 2 e 3 do Manual do Usuário.
Introdução à Integração
O motor de promoções é o componente PROMO encarregado de receber as solicitações do ponto de venda e, posteriormente, respondê-las. Essa interação será realizada por meio de uma série de mensagens em formato XML que seguem um Protocolo de Comunicação definido. Neste sentido, o motor de promoções pode funcionar tanto como servidor TCP/IP como como servidor REST, dependendo das necessidades, preferências e exigências tecnológicas do ponto de venda.
Comunicação com o Motor de Promoções
Como mencionamos anteriormente, a forma de comunicação com o Motor de Promoções é através das mensagens XML apresentadas posteriormente neste documento. Essas mensagens usam duas formas de comunicação como transporte:
servidor TCP/IP
Um dos protocolos mais comuns atualmente. Permite remessa e roteamento seguros. Nesse caso, o mecanismo atua como um servidor aguardando conexões de entrada em uma determinada porta TCP/IP. O ponto de venda deve enviar e receber pacotes TCP/IP com o seguinte formato:
HEADER | MENSAGEM
Onde:
- Header (cabeçalho): são 6 Bytes que indicam a quantidade de bytes que terá o corpo da mensagem que é enviada ao motor de promoções.
- Mensagem (mensagem): mensagem enviada ao Motor de Promoções com o formato XML descrito neste documento.
servidor REST
REST (Representational State Transfer) é um estilo de arquitetura usado em aplicativos de rede distribuídos. Baseia-se em protocolos cliente-servidor, sem estado, e como no caso do PROMO, é implementado maioritariamente através do protocolo HTTP. A ideia é uma alternativa simples ao uso de mecanismos mais complexos como CORBA, RPC ou SOAP.
O mecanismo de promoções é apresentado aqui como um servidor HTTP aguardando conexões em uma determinada porta TCP/IP.
Como um servidor REST, o mecanismo tem duas maneiras de trabalhar: Através de solicitações no modo GET ou no modo POST (>v 7.EP2.1).
modo GET
Para utilizar esta forma de comunicação, a aplicação cliente deve enviar requisições HTTP e aguardar as respostas correspondentes. A invocação ou formato de uso é: (pode ser feito em um navegador como FireFox, Chrome, etc.)
http://servidor:port /engine/evaluate?request=message
Onde:
- http://servidor:porta : é a url para acessar o servidor onde o motor PROMO está rodando.
- message : é a mensagem correspondente a ser avaliada pelo motor, conforme especificado neste documento.
Importante
- Se o mecanismo tiver a opção de segurança via https, todas as referências a http:// devem ser lidas como https://
- Se a autenticação de usuário/senha estiver ativa, as solicitações devem incluir a seguinte propriedade nos cabeçalhos: "Authorization" : "Basic user :encrypted_password_MD5"
- Para mais informações consulte o manual de instalação e configuração
Apresentaremos aqui vários exemplos usando dois clientes: o navegador Firefox e o aplicativo "curl" de domínio público ( https://curl.haxx.se/ ). Assumimos então que precisamos enviar a seguinte mensagem para ser avaliada pelo motor:
<message companyId="sts" store="9905" terminal="001" date-time="2016-11-20 23:01" messageId="0001" void-trx="false" sugerir="true" response= "true" init-tck="true" avalia="true" msg-version="2.4" status="init" ><item-add seq="1" unitprice="1" xprice="1" qty=" 1" magnitude="1" código="P001" desconto="true"/> </mensagem>
Ao mesmo tempo, o servidor onde o mecanismo PROMO está disponível é http://demoserver.net e porta 3625.
No Firefox, a url que usamos para este teste é:
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" sugerem="true" response="true" init-tck="true" avalia="true" msg-version="2.4" status= "init" ><item-add seq="1" unitprice="1" xprice="1" qty="1" magnitude="1" code="P001" discountable="true"/> </mensagem>
Isso em uma única linha como visto na figura a seguir.
De acordo com os resultados da avaliação do mapa, uma resposta do tipo será vista no navegador:
Da mesma forma, outro exemplo é fazer o mesmo mas usando curl. Nesse caso, a linha de comando envia a mensagem da seguinte 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
Observe que a mensagem xml deve ser codificada, que no caso do Firefox, o navegador faz essa conversão automaticamente.
A figura a seguir mostra o exemplo completo com a solicitação e a resposta. Alguns dados relacionados ao servidor no qual foi executado foram deletados por não caberem no exemplo.
Modo POST
Para utilizar esta forma de comunicação, a aplicação cliente deve enviar requisições HTTP e aguardar as respostas correspondentes. O formato de invocação ou uso é:
http://servidor:porta /engine/evaluate
Onde:
- http://servidor:porta : é a URL para acessar o servidor onde o motor PROMO está rodando.
- O parâmetro "request" deve ser incluído no corpo da mensagem POST com a mensagem correspondente a ser avaliada pelo motor, conforme especificado neste documento.
Importante
- Se o mecanismo tiver a opção de segurança via https, todas as referências a http:// devem ser lidas como https://
- Se a autenticação de usuário/senha estiver ativa, as solicitações devem incluir a seguinte propriedade nos cabeçalhos: "Authorization" : "Basic user :encrypted_password_MD5"
- Para mais informações consulte o manual de instalação e configuração
Ao mesmo tempo, o servidor onde o mecanismo PROMO está disponível é http://demoserver.net e porta 3625.
No Firefox, a url que usamos para este teste é:
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" sugerem="true" response="true" init-tck="true" avalia="true" msg-version="2.4" status= "init" ><item-add seq="1" unitprice="1" xprice="1" qty="1" magnitude="1" code="P001" discountable="true"/> </mensagem>
Outra opção é utilizar um programa como o POSTMAN para gerar a consulta conforme a figura a seguir:
Da mesma forma, outro exemplo é fazer a mesma coisa, mas usando curl. Nesse caso, a linha de comando envia a mensagem da seguinte forma:
curl --location --request POST 'http://myserver:8888/engine/evaluate' \ --header 'Tipo de conteúdo: aplicativo/x-www-form-urlencoded' \ --data-urlencode 'request=<message companyId="napse" store="1" terminal="1" date-time="2020-10-23 18:36:01" init-tck="true" messageId= "12" void-trx="false" response="true" status="vendas" avalia="true" sugere="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"/> </mensagem>
sessões
Antes de começar com a descrição da mensagem utilizada para enviar os requisitos ao Motor de Promoções, é necessário apresentar ao leitor o tratamento de sessões que ele realiza.
Uma sessão é um espaço reservado dentro do Motor de Promoções para a gestão da informação relativa a uma transação. Desta forma, é capaz de tratar diversas transações simultaneamente, tendo uma sessão para cada uma delas. Podemos assimilar este conceito com a abertura de uma transação iniciada no ponto de venda e que vai incorporando elementos gradativamente até o seu fechamento.
A sessão é identificada pela concatenação dos seguintes campos contidos no cabeçalho da mensagem (explicados na próxima seção):
SessionId = CompanyId + Store + Terminal
Ao iniciar uma nova sessão, os dados da transação correspondente estarão vazios, podendo então ser completados conforme indicado abaixo, ou seja, apenas uma transação é reservada sem elementos, mas com dados de cabeçalho como data e hora do mesmo, mais a loja e terminal onde ocorre.
Da mesma forma, a sessão terá um time-out (tempo de expiração) configurável, que, uma vez decorrido sem que nenhuma mensagem seja recebida, fará com que a sessão seja automaticamente excluída, tornando-se necessário abrir uma nova e, se continuar com a transação, reenviando os dados que continha a sessão expirada. Consulte o manual de Instalação e Configuração para mais detalhes.
Note-se do que foi visto até agora, que ambas as comunicações com o mecanismo de promoções em seu servidor TCP/IP e REST são escolhidas, ambas usam o mesmo sistema de mensagens que será apresentado neste documento e que foi chamado de "MESSAGE" em ambos os casos.
Mecanismo: solicitação do mecanismo
Mencionamos anteriormente que o motor de promoções é o componente PROMO encarregado de receber as solicitações do ponto de venda e, posteriormente, respondê-las. Essa interação será realizada por meio de uma série de mensagens em formato XML que seguirão uma série de regras definidas.
Esta seção apresentará a estrutura das mensagens XML enviadas pelo ponto de venda que deseja interagir com o Promo. Essas mensagens são chamadas de REQUEST ou solicitações. O formato geral é:
<mensagem ... propriedades do cabeçalho ...> ... elementos do corpo da mensagem ... </mensagem>
Cabeçalho
Conforme mencionado acima, as mensagens que são enviadas ao Motor de Promoções serão em XML. O elemento raiz desta mensagem XML deve ser a tag <message>, sendo esta tag chamada de cabeçalho, e conterá uma série de atributos que serão utilizados pelo Motor de Promoções para saber a hora e o local da transação, seja ou não para não iniciar uma nova sessão, etc. O conteúdo dentro desta etiqueta serão os comandos que se deseja executar na Engine, que formarão o corpo da mensagem, tópico desenvolvido na próxima seção.
Os atributos que o cabeçalho pode possuir são:
Propriedade | Tipo de dados | Descrição | Obrigatório | Valor na ausência |
ID da empresa | alfanumérico | Identifica a empresa que enviou a mensagem | SIM | |
loja | alfanumérico | Identifica a localidade que envia a mensagem. | Sim | |
canal | alfanumérico | Identifica o canal associado à transação. | Não | "" |
terminal | Numérico | Identifica o terminal emissor | Sim | |
data hora | AAAA-MM-DD HH:MM:SS | Data e hora da mensagem. ( data-hora="2017-03-21 15:20:26" ) | Sim | |
messageId | numérico positivo | Identifica cada uma das mensagens enviadas pelo terminal, sendo este número utilizado pelo Motor de Promoções como identificador no envio de uma resposta. | Sim | |
vazio trx | boleano | Indica se a transação é uma devolução. | Não | falso |
resposta | boleano | Indica se deseja que o Motor dê uma resposta à mensagem enviada. | Não | falso |
init-tck | boleano | Indica se uma nova sessão deve ser iniciada com esta mensagem. | Não | falso |
avalie-se | boleano | Informa ao mecanismo para calcular as promoções usando os elementos inseridos até o momento. | Não | falso |
status | alfanumérico | Indica em que estado se encontra o ponto de venda
| Não | "" |
msg-versão | alfanumérico | Indica a versão da mensagem em questão | Não | "" |
versão do mapa | inteiro positivo | Ele informa ao mecanismo qual mapa usar. Só fará sentido se o valor de "void-trx" for verdadeiro. | Não | "" |
sugerir | boleano | Diz ao motor se deve sugerir promoções ou não. Se a sugestão-seq e o tipo de sugestão-seq não estiverem presentes, todo o contexto será usado para fazer a sugestão. | Não | falso |
sugerir-seq | Numérico | Indica o número de sequência no qual o engine fará a sugestão caso o atributo sugerem="true". Este atributo será acompanhado pelo sugestion-seq-type, que se não for especificado, assumirá o sugestion-seq-type="item" | Não | "1" ou nulo |
sugerir-seq-type | alfabética | Indica o tipo de linha na qual a sugestão deve ser feita caso o atributo sugerem="true". Este atributo será acompanhado pelo sugestion-seq, que se não for especificado, sugestion-seq="1" será assumido. Os valores que esse atributo pode assumir são: item, cupom, pagamento, evento, cliente. | Não | "item" ou nulo |
sugestão por tipo | boleano | Diz ao motor se deve sugerir promoções tendo em conta o tipo de conjuntos participantes na promoção ou não. Se o tipo de filtro de sugestão não estiver presente, todas as promoções disponíveis para sugestão serão sugeridas levando em consideração o atributo de sugestão do mapa e as promoções. Se presente e verdadeiro, os atributos de sugestão, sugestão de sequência e tipo de sequência de sugestão serão ignorados. | Não | falso |
tipo de filtro de sugestão | alfabética | Indica o tipo de conjunto de participantes da promoção a ser considerado para a sugestão no caso do atributo sugerir-per-type="true". Os valores que esse atributo pode assumir são: item, cupom, pagamento, evento, cliente. Se não estiver presente, todos os tipos de conjunto serão assumidos. | Não | nulo |
sugestão estendida | boleano | Diz ao motor se deve mostrar a informação dos benefícios de cada promoção sugerida. Se sugerir for false, o valor deste campo é irrelevante. | Não | falso |
desligada | boleano | Informa ao engine que a transação será processada no modo offline, ou seja, caso ocorra uma contingência de comunicação com a PROMO Central, ela será armazenada para posterior envio (vide nota abaixo “Comportamento do Promo no modo offline”). | Não | falso |
transação original | alfabética | No caso de um valor de status = requestTransaction, esta propriedade indicará a transação que deve ser consultada | Não | "" |
opção escolhida | inteiro positivo | 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 ao cliente. O valor é baseado em 0, ou seja, a primeira opção é o número 0, a próxima é o número 1 e assim por diante. | Não | 0 |
cadeia de lojas | alfabética | Identificador da “Chain” a que pertence a loja (Store) da transação. Pode ser usado na condição de promoção. | Não | "" |
formatar | alfabética | Identificador do Formato ao qual pertence a loja (Store) da transação. Pode ser usado na condição de promoção. | Não | "" |
zona | alfabética | Identificador da Zona a que pertence a loja (Store) da transação. Pode ser usado na condição de promoção. | Não | "" |
subzona | alfabética | Identificador da SubZona a que pertence a loja (Store) da transação. Pode ser usado na condição de promoção. | Não | "" |
tenderGroupCode | alfabética | Ao utilizar preços, se for enviado o valor "cr" retornará o preço a crédito, no caso de outro valor ou se não for enviado retornará o preço de venda. | Não | "" |
Código da moeda | alfabética | Código da moeda em que a transação está sendo realizada. Pode ser utilizado na condição de promoção, por exemplo para condicionar a entrega de pontos a essa moeda. | Não | "" |
LimitBalances | boleano | Quando for enviado em 'true', serão retornados na resposta da engine ao PDV os saldos dos limites de Loja e Geral ( varejo ) que foram definidos pelas promoções que participaram da transação corrente. Valor padrão " false " ( a partir da promoção 7.0.2 ) | Não | falso |
Comportamiento de Promo en modo offline
Se por regra de negócio, o PDV envia o Promo engine no cabeçalho no atributo offline=true . Se a comunicação entre o PDV e o motor Promo for cortada, dependendo de quando a comunicação foi cortada, o Promo poderá registrar a transação localmente e quando houver comunicação enviará para o PDV. É o PDV quem decide se a transação off-line pode ser realizada ou não.
- A validação de fidelidade não pode ser usada offline.
- Se você estiver off-line ao enviar a finalização ou reversão, o Promo salvará a transação. Em seguida, ele faz um commit automático. Se houve consumo de cupons ou cartão, se puder, o Promo realiza a operação e se não puder, dá erro e salva.
- Você pode adicionar cupons, cartões e, se os dados estiverem corretos, a promoção os consome. É como fazer uma transação de débito offline: presume-se que o saldo seja suficiente, é uma decisão empresarial permitir ou não esse tipo de transação.
- Se você estiver offline e uma pessoa vier com um cupom: se por regra de negócio o PDV decidir que é válido pegar um cupom e conceder a promoção que o resgata, ele tira offline e quando chega no console o cupom é queimado.
- Se vai ser aplicada uma promoção que emite um cupom: ela gera, emite, mas a Promo mantém. A Promo não envia os dados do cupom. No caso dos tipos de cupons virtuais, isso não tem impacto porque não precisam do código de barras, na próxima validação de fidelidade terão o total. Mas gera um código de barras. E então, quando a conexão for restabelecida, o mecanismo enviará automaticamente todos os off-line que terminarem com o commit.
- Caso não haja conexão no início da transação (ou seja, caso não tenha sido possível validar a fidelidade), as promoções com limites não serão concedidas. Se o offline ocorrer no final: levará o que avaliou durante a promoção (neste caso já realizou a validação de fidelidade e portanto já possui os limites atualizados).
- O mecanismo incorporado usa o mesmo diretório off-line do mecanismo padrão. Use os diretórios padrão.
Exemplo:
<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" avalia="true" status="pagamento" msg-version="2.0" map-version="15"> ... Corpo da mensagem ... </mensagem>
<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" avalia="true" status="pagamento" msg-version="2.0" map-version="15" sugere="true" sugere-seq="3" sugere-seq-tipo ="pagamento"> ... Corpo da mensagem ... </mensagem>
<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" avalia="true" status="pagamento" msg-version="2.0" map-version="15" sugerir-per-type="true" sugerir-filter-type="cupom "> ... Corpo da mensagem ... </mensagem>
<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" avalia="true" status="pagamento" msg-version="2.0" map-version="15" sugere="true" sugere-extended="true"> ... Corpo da mensagem ... </mensagem>
Corpo
O corpo da mensagem que se envia ao Motor de Promoções será constituído pelos comandos que se deseja executar. Basicamente, os comandos podem ser de dois tipos:
Ação | Descrição |
adicionar | Adicione o elemento à sessão. |
vazio | Remove o elemento da sessão. O elemento é identificado pelo número de sequência. |
Estes comandos podem ser usados nos diferentes elementos que podem pertencer a um ticket. Por sua vez, esses elementos podem ser classificados em 5 classes:
Elemento | Descrição |
item | Identifique os itens. |
cupom | Identifique os cupons. |
cartão de fidelidade | Identifica elementos de fidelidade de lealdade. |
pagamento | Identifica o meio de pagamento. |
eventos | Identifica eventos ou outros elementos não representáveis pelos outros tipos. |
cliente | Identificar clientes. |
benefícios | Identificar benefícios externos |
A maneira de executar um comando é usando uma tag no formato <command-element> .
Desta forma, se pretender, por exemplo, adicionar um novo artigo à sessão, o comando a utilizar será <item-add> , caso pretenda cancelar um cupão adicionado anteriormente, enviará um <coupon-void > digite o comando .
O corpo da mensagem pode conter um, nenhum ou vários desses comandos.
Os comandos podem ser enviados ao mesmo tempo em que uma nova sessão é aberta ou uma avaliação é solicitada.
Uma mensagem sem comandos também pode ser enviada para, por exemplo, solicitar a avaliação de um ticket.
Como exemplo para esclarecer o uso desses comandos podemos apresentar sua relação com o buffer de sessão.
Iniciamos uma transação no terminal 256, adicionando 2 produtos à sessão.
<message companyId="sts" store="0001" terminal="256" date-time="2022-04-04 12:30:00:" messageId="001" void-trx="false" response="true " init-tck="true" avalia="true" status="teste" > <item-add ... primeiras propriedades do produto ... /> <item-add ... propriedades do segundo produto ... /> </mensagem>
Com esta ação, a sessão associada a Company 'sts', Store="0001", terminal="256" teria:
Na mensagem a seguir, observe que a transação continua (init-tck="false") e também adicionamos um cliente e uma forma de pagamento a ela:
<message companyId="sts" store="0001" terminal="256" date-time="2022-04-04 12:30:00:" messageId="001" void-trx="false" response="true " init-tck="false" avalia="true" status="teste" > <customer-add ... propriedades do primeiro cliente... /> <payment-add ... propriedades do primeiro pagamento ... /> </mensagem>
Como consequência, o buffer de sessão permaneceria:
Na mensagem a seguir, o cliente decidiu não transportar o produto 2 e, portanto, decidimos retirá-lo da transação.
<message companyId="sts" store="0001" terminal="256" date-time="2022-04-04 12:30:00:" messageId="001" void-trx="false" response="true " init-tck="false" avalia="true" status="teste" > <item-void... propriedades do segundo produto... /> </mensagem>
o buffer de sessão resultante é:
Isso significa que as promoções serão avaliadas com base nesse cenário final, com 1 produto, 1 cliente e 1 meio de pagamento.
atributos de comando
Cada um dos comandos enviados pelo Motor de Promoções possui vários atributos, que identificam o elemento que está sendo enviado e definem diversas propriedades que possuem. Ambos add e void terão um número de sequência, que identifica exclusivamente cada elemento:
Propriedade | Tipo de dados | Descrição | Obrigatório |
eu sei que | inteiro positivo | Número identificador exclusivo do elemento dentro da transação. | Sim |
Este será o único atributo que os comandos do tipo void possuirão , sendo este o atributo que indica o elemento a ser deletado.
Por outro lado, o comando add terá uma série de atributos que definirão as diferentes propriedades do elemento que está sendo adicionado (além do número de sequência mencionado). Dependendo do elemento em questão, os atributos serão os seguintes:
Elemento | Propriedade | Tipo de dados | Descrição | Obrigatório | Valor na ausência |
Item | preço unitário | numérico positivo | Preço unitário do item em questão. | Sim | |
xpreço | numérico positivo | Preço estendido do item em questão. É igual à quantidade vezes o preço unitário. | Sim | ||
quantidade | inteiro positivo | Número de itens na linha. | Sim | ||
magnitude | numérico positivo | Se o item for mensurável por uma unidade diferente de quantidade, ele deve ser expresso nesta propriedade. | Não | 0 | |
código | alfanumérico | Código do próprio item. | Não | "-" | |
Código do produto | alfanumérico | Código do produto | Não | ||
código de barras | alfanumérico | Código de barras do produto | Não | ||
marca | alfanumérico | Marca do artigo. | Não | "-" | |
fornecedores | alfanumérico | Fornecedor ao qual o item pertence. | Não | "-" | |
com desconto | alfanumérico | Se o item é elegível para descontos ou não. | Não | "-" | |
nível 1 | alfanumérico | Nível 1 de categorização de artigos. Anteriormente, esse nível era conhecido como Departamento. | Não | "-" | |
nível 2 | alfanumérico | Nível 2 de categorização de artigos. Este nível era anteriormente conhecido como Família de Itens. | Não | "-" | |
nível 3 | alfanumérico | Nível 3 de categorização de artigos. Esse nível era conhecido anteriormente como Categoria do artigo. | Não | "-" | |
level4 | alfanumérico | Nível 4 de categorização de artigos. Anteriormente, esse nível era conhecido como subcategoria do artigo. | Não | "-" | |
descontínuo | boleano | Determine se o produto é um produto descontinuado | Não | falso | |
baixa rotatividade | boleano | Determine se o produto é um produto de baixa rotatividade | Não | falso | |
keyProduct | boleano | Determine se o produto é um produto principal | Não | falso | |
aplicarCatalogRedeem | boleano | Determinar se o produto participa do Resgate de Pontos por Catálogo | Não | falso | |
impostos | numérico positivo | Valor dos impostos discriminados em relação ao preço unitário. (Consulte o atributo valueWithTaxes) | Não | 0 | |
qtd2 | inteiro positivo | (Versão > 7.EP2.1) Quantidade do produto a ultrapassar ao preço de outorga 2 (preço2). Somente para Promoções de Novos Preços que indiquem o uso de valor externo. | Não | 0 | |
preço2 | numérico positivo | (Versão > 7.EP2.1) Preço quando a quantidade 2 (qty2) for excedida. Somente para Promoções de Novos Preços que indiquem o uso de valor externo. | Não | 0 | |
qtd3 | inteiro positivo | (Versão > 7.EP2.1) Quantidade do produto a ultrapassar ao preço de outorga 3 (preço3). Somente para Promoções de Novos Preços que indiquem o uso de valor externo. | Não | 0 | |
preço3 | numérico positivo | (Versão > 7.EP2.1) Preço quando a quantidade 3 (qty3) for excedida. Somente para Promoções de Novos Preços que indiquem o uso de valor externo. | Não | 0 | |
opção de resgate | alfanumérico | (Versão > 7.EP2.1) Benefício "Resgate com opções" - informará as opções dentre as quais o cliente pode escolher para acessar determinado benefício mediante resgate de determinada quantidade de pontos (do cliente e/ou elemento fidelidade) Mais detalhes no Anexo I - Troca com opções | Não | ||
Cupom | quantia | numérico positivo | É usado para indicar o valor monetário do cupom. Se você não tem, você não usa. | Não | 0 |
tipo | alfanumérico | Tipo de cupom. | Não | "-" | |
quantidade | inteiro positivo | Quantia | Não | 1 | |
eu ia | alfanumérico | ID do cupom. | Não | "-" | |
Cartão de fidelidade | tipo | alfanumérico | Tipo de elemento de lealdade lealdade | Não | "-" |
eu ia | alfanumérico | Identificador de elemento de fidelidade | Sim | "-" | |
quantia | numérico positivo | Equilíbrio do elemento de lealdade | Não | 0 | |
quantidade de carga | numérico positivo | Saldo a creditar a um elemento de fidelização | Não | 0 | |
consumirQuantidade | numérico positivo | Saldo a debitar a um elemento de fidelização | Não | 0 | |
status | alfanumérico | HABILITADO ou DESATIVADO para habilitar ou desabilitar um elemento de fidelidade (válido apenas no status LoyatyActivation) | Não | " HABILITADO " | |
nextExpDate | Numérico | Data do vencimento dos próximos pontos no formato AAAAmmdd. Só é reportado em elementos de fidelização com vencimento de cobrança definido. | Não | "-" | |
nextExpValue | Numérico | Número de pontos que expirará na próxima data de vencimento (nextExpDate) e é informado apenas se o item de fidelidade tiver uma data de vencimento de cobrança definida. | Não | "-" | |
razão | alfanumérico | Código do motivo pelo qual o chargeAmount ou consumaAmount relevante está sendo realizado. Este código corresponde aos valores de razão definidos no console Promo | Não | "-" | |
cvv | alfanumérico | Corresponde ao código de segurança ou cvv associado ao elemento de fidelização. | Não | "-" | |
válido de | alfanumérico | Data efetiva . Formato "AAAA-MM-DD" (Ano-Mês-Dia). Exemplo "2021-07-16" | Não | "-" | |
valido para | alfanumérico | Data efetiva. Formato "AAAA-MM-DD" (Ano-Mês-Dia). Exemplo "2021-07-16" | Não | "-" | |
cliente | tipo | alfanumérico | Tipo de Cliente. | Não | "-" |
eu ia | alfanumérico | Identifica o cliente através do Código. | Não | "-" | |
Montante restante | numérico positivo | Imóvel que pode ser utilizado para indicar o saldo a favor ou contra o cliente em questão. (compatibilidade com PROMO 4 e versões anteriores) | Não | 0 | |
pontos | inteiro positivo | Saldo em poder do cliente. (compatibilidade com PROMO 4 e versões anteriores) | Não | 0 | |
alfanumérico | Atributo incluído para consulta do cliente | Não | "" | ||
inhame | alfanumérico | Atributo incluído para consulta do cliente | Não | "" | |
sobrenome | alfanumérico | Atributo incluído para consulta do cliente | Não | "" | |
identificador | numérico positivo | Atributo incluído para consulta do cliente | Não | "" | |
número do cartão | numérico positivo | Atributo incluído para consulta do cliente | Não | "" | |
creditCampaignCode | alfanumérico | Código de campanha de crédito | Não | "" | |
profileCode | alfanumérico | Código do perfil do cliente | Não | "" | |
benefícios limitados | alfanumérico | Consiste em uma lista de Limites associados a Acordos. É do tipo: LimitedBenefits:"limit1:value1;limit2:value2;limit3:value3...". Estes valores podem ser informados a partir do Ponto de Venda ou são obtidos através de resposta ao LoyaltyValidation e reinjetados pelo Ponto de Venda à medida que vão sendo recebidos. | Não | "" | |
segmento | alfanumérico | Lista de Códigos de Segmentos a que pertence o cliente, separados por ; | Não | "" | |
quantia | numérico positivo | Propriedade que pode ser utilizada para indicar o saldo correspondente a um cliente | Não | 0 | |
sorteioData | alfanumérico | Dados para imprimir em cupons informativos, principalmente voltados para sorteios. Consulte o Manual do Usuário para obter informações sobre cupons informativos. | Não | "-" | |
"Pagamento Os atributos de valor e valor do item são mutuamente exclusivos e seu uso depende da versão da promoção codificada configurada | tipo | alfanumérico | Tipo de meio de pagamento. | Não | "-" |
eu ia | alfanumérico | Identificador de pagamento. | Não | "-" | |
plano | alfanumérico | Plano de meios de pagamento. | Não | "-" | |
quantia | numérico positivo | Dinheiro utilizado com esse meio de pagamento. Dado que o valor do pagamento (PA) é calculado como PA = PIA (1 - %disco) ou PA = PIA * (1+%sobretaxa)*, | Não | 0 | |
banco | alfanumérico | Banco relacionado ao meio de pagamento. | Não | "-" | |
itemmount | numérico positivo | Dinheiro que representa a quantidade de itens que você deseja pagar. | Não | 0 | |
balançado | boleano | Indica se o saldo da transação foi cancelado com este meio de pagamento.Se o valor for verdadeiro, não é necessário enviar o valor ou valor do item. | Não | falso | |
tipo de pontos | alfanumérico | Identifica o tipo de pagamento com pontos (ver manual do utilizador Final Promo 7 - " Ignorar pagamento com Pontos " - Ver também benefício PromotionPaidInPoints) | Não | "" | |
prestações | numérico positivo | Indica o número de prestações associadas ao pagamento | Não | "" | |
prefixo | alfanumérico | Indica o Prefixo associado ao pagamento | Não | "" | |
bolso | alfanumérico | Indica o bolso associado ao pagamento | Não | "" | |
prefixGroup | alfanumérico | Indica o grupo de Prefixos associados ao pagamento | Não | "" | |
payCreditCampaign | alfanumérico | Indica a Campanha de Crédito associada ao pagamento | Não | "" | |
eventos | tipo | alfanumérico | Tipo de evento. | Não | "-" |
eu ia | alfanumérico | Identificação do evento. | Não | "-" | |
valor | alfanumérico | O valor que representa o evento. | Não | "-" | |
benefícios | eu ia | alfanumérico | Identificador de benefício externo. | Sim | |
tipo | alfanumérico | Tipo de benefício externo. | Sim | ||
quantia | numérico positivo | É utilizado para indicar o valor a ser descontado ou o percentual de desconto (conforme o tipo de benefício). | Sim | ||
tipo de benefício | alfanumérico | Indica o tipo de lucro a ser gerado.
| Não | "desc" | |
seqItem | alfanumérico | Número de seqüência dos itens aos quais o desconto será aplicado. Se o atributo não aparecer ou estiver vazio, presume-se que seja para o ticket inteiro. No caso de haver várias sequências, elas devem ser separadas por vírgulas. Se alguma sequência tiver mais de uma quantidade, ela deve ser concatenada com um =. Exemplo: 1=2,2,3=3 (indica que o desconto é aplicado a dois itens da sequência um, um da sequência dois e três da sequência 3 | Não |
Exemplo: Segue abaixo um exemplo de mensagem que adiciona um item e um meio de pagamento (ambos com sequência " 1
") à sessão do Motor de Promoções , e retira um cupom (com sequência " 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" avalia="true" status="pagamento" msg-version="2.0" map-version="15"> <item-add seq="1" code="0001" discountable="true" unitaryPrice="25.0" qty="1.0" productcode= "111000110" barcode="100101" level1="MEN" level2="CASUAL" fornecedor ="" brand="LEVIS" xPrice="25.0" magnitude="1.0" /> <payment-add seq="1" type="CreditCard" amount="" id="000009" planId="10"/> <cupom-void seq="2" /> <loyaltycard-add seq="5" id="3330000000222" type="points" /> </mensagem>
Exemplo de Meio de Pagamento Codificado :
Segue abaixo um exemplo de mensagens enviadas e recebidas com um Código de Promoção com Forma de Pagamento configurada (forma de pagamento: ON_ITEMS_PAID=Calcular promoções em itens pagos) com as seguintes características:
<mensagem companyId="napse" store="Store1" terminal="1" date-time="2021-06-28 09:33:00" init-tck="true" messageId="114" void-trx="false" response="true" estado="vendas" avaliar="true" versão do mapa="19" sugerir="verdadeiro"> <item-add seq="1" qty="1" código="1029" nível1="85" magnitude="0" xpreço="1000" preço unitário="1000"/> <pagamento-adicionar seq="2" id="1" quantidade="1000" tipo="TAR" planId="10" parcelas="6" itemamount="1000"/> </mensagem>
<?xml version="1.0" encoding="UTF-8" standalone="no"?><mensagem ack="0" companyId="napse" engine="7.0.10#42" mapversion="19" messageId="114" store="Store1" terminal="1"> <opcional> <promo id="Código da mídia promocional Pagamento com Juros" nro="60d9b152e830a5618c9d1cf2"> <benefit TLOGMessage="Código promocional Meio de Pagamento Com Juros" conta="" applicationMethod="currículo" bank="HSBC" baseAmount="1000.00" BenefitType="PaymentPlanBenefit" displayMessage="Promo Codif Meio de Pagamento Com Juros" parcelas="6" parcelasToDisplay="6" limitAmount="6000.00" name="60d9b152e830a5618c9d1cf2" nro="60d9b74ee830a5618c9d1cfa" pedido="1" PaymentAmount="1000.00" percent="10" percenttype="sobretaxa" planId="a" printerMessage="Promoção Codif Meio de Pagamento Com Juros" concurso="Visa" digite="Crédito"> <aplicar> <item magnitude="0,00" quantidade="1,00" seq="1" value="0.00" valueWithTaxes="0.00" xprice="1000.00"/> </apply> </benefit> </promo> </optional></message>
Nota
Tanto na simulação do console quanto no envio de mensagens, o atributo " itemamount " deve ser informado no pagamento com o valor do pagamento efetuado nos itens.
Desconto condicionado a uma cota
Ao selecionar um ID específico no "Saldo", quando o atributo "saldo" for recebido do PDV, você deverá ter inteligência para obter o valor que corresponde a esse ID para conceder o benefício até que o saldo seja totalmente consumido, sem conceder outros.
Por exemplo:
Na consola define-se em "Saldo" = 3
O TPV envia o seguinte atributo no customer-add:
saldo=1:15000;2:25750;3:5750;4:1500
Neste caso deve ser detectado: que o valor do benefício não deve ultrapassar $ 5.750, que seria o saldo do saldo “3”.
A engine deve estar pronta para receber o atributo saldo em forma de lista e poder interpretar o saldo de cada ID, limitar o benefício a ser concedido a partir do saldo informado de acordo com o “saldo” indicado no benefício “Desconto do Convênio”.
<?xml version="1.0" encoding="UTF-8"?><message channel="T" cia="1" city="58" companyId="success" date-time="2020-10-29 11 :45:15" avalia="true" format="H" init-tck="false" localidade="1" map-version="1155" status="venda" store="0013" storeChain="E" subzona ="1" terminal="022" tipologia="oi" zona de preço="E22" zona="1"> <customer-add balance="1:75000;2:1500;5:95000;155:2000;100:0" customerType="7" email="[email protected]" id="999993" identifier="999993 " identifierType="cpf" mobile="+573013711717" name="test successdoc3" points="3230376" public="1" resgatePointsPriceFactor="7" segment="7710" seq="1" status="1" type= "2"/></mensagem>
<?xml version="1.0" encoding="UTF-8"?><message ack="0" channel="T" companyId="success" engine="7.0.0-FP1#63" mapversion="1155" messageId="" store="0013" terminal="022"> <opcional> <promo code="26519" id="PromocionCupo-26519" nro="5f9ad26c2646e3132c47df6b"> <benefit TLOGMessage="PromocionCupo" account="" applicationMethod="lineByLine" balance="5" baseAmount="35000." BenefitType="ContractPercentageDiscount" discountPercentage="50." displayMessage="PromocionCupo" name="5f9ad26c2646e3132c47df6b" nro="5f9ad2952646e3132c47df76" order="1" printerMessage="Cupo" prorationMethod="PROPORCIONAL" unit="qty"> <aplicar> <item magnitude="0.000" qty="1.000" seq="1" value="17500." valueWithTaxes="17500." xprice="35000."/> </aplicar> </benefício> </promo> </opcional> </mensagem>
Promoção definida no console:
resposta do motor
Esta seção descreverá a estrutura e a interpretação da mensagem de resposta entregue pelo Promotions Engine.
Conforme mencionado acima, assim como a mensagem de solicitação, a mensagem de resposta fornecida pelo Promotions Engine estará no formato XML e consistirá em um cabeçalho e um corpo. No cabeçalho conterá informações relacionadas ao terminal ao qual está respondendo, erros que possam ter ocorrido e versão do Engine.
No corpo da mensagem encontrará as promoções que devem ser aplicadas ou sugeridas, os artigos a beneficiar, etc. Caso não existam promoções a aplicar ou sugerir ou a avaliação ou sugestão não tenha sido solicitada, a mensagem de resposta será constituída apenas pelo cabeçalho.
Cabeçalho
Assim como na mensagem de requisição, o elemento raiz da resposta será a tag < message > , sendo esta também o que será chamado de cabeçalho da resposta. Ele conterá atributos que indicam a loja e o terminal para o qual é direcionado, identificação da mensagem, versão do mapa e do Engine com o qual foi realizada a avaliação e código de retorno (acknowledge ) ; sendo todas elas enviadas obrigatoriamente:
Propriedade | Tipo de dados | Descrição |
versão do mapa | alfanumérico | Versão do mapa utilizado para avaliação das promoções. |
ID da empresa | alfanumérico | O mesmo que foi enviado na mensagem de solicitação. |
loja | alfanumérico | O mesmo que foi enviado na mensagem de solicitação. |
terminal | Todo | O mesmo que foi enviado na mensagem de solicitação. |
messageId | Todo | O mesmo que foi enviado na mensagem de solicitação. |
motor | alfanumérico | A versão do Promotion Engine que executou a avaliação. |
ack | todo | Código de retorno (consulte a próxima seção). |
transação | alfanumérico | Código que identifica a transação na central PROMO (só é informado com a resposta a um status de Fidelidade) |
Valores do atributo "ack"
O atributo ACK Do inglês, confirme . é um atributo dentro do cabeçalho da mensagem de resposta que indica a existência ou não de erros na recepção e/ou processamento da mensagem de solicitação. Dependendo do tipo de erro ou se a mensagem foi recebida corretamente, este atributo terá um valor específico:
valor de confirmação | Descrição | Ação recomendada |
0 | Não houve erros. | Use a resposta. |
1 | Erro de comunicação ou mensagem ilegível. | Reenvie a mensagem e se o erro persistir, revalide seu formato. |
2 | A sessão não foi inicializada ou não existe tal sessão. | Faça o login conforme indicado em " Gerenciamento de sessão " . |
3 | Erro de validação na mensagem. | Revalide o formato da mensagem. Você também pode verificar o arquivo de log do mecanismo para estabelecer com mais precisão qual foi o erro. |
2001 | Erro de avaliação. | Comunique-se com o administrador do Motor de Promoções para que, através do arquivo de log, o erro possa ser estabelecido. |
2002 | Não há mapa válido para cálculo do ticket ou mensagem recebida. | Use um mapa anterior existente ou não aplique promoções. |
2003 | A sessão está em uso. | Aguarde aproximadamente 3 segundos e tente enviar novamente. |
2004 | Erro de instanciação de sessão geral. | Comunique-se com o administrador do Mecanismo de Promoções para monitorar a equipe em que o Mecanismo está sendo executado. |
2005 | Sessão expirada. A sessão expirou. | Se durante a avaliação da sessão ela terminar por timeout, é enviada uma mensagem com ack 2005. Aguarde e tente novamente o envio. |
4001 | O mecanismo está em processo de inicialização. | Aguarde porque o motor está ligando e carregando as informações. |
8296 | Há erros na validação | Este erro ocorre com Status=loyaltyvalidationex e FinishEx, o arquivo de log deve ser analisado para estabelecer qual foi o erro. Este erro de validação será relatado na tag </errors> no corpo da resposta com ACK="8296". |
8297 | Indica que o corpo da mensagem está vazio. | Este erro ocorre com Status=LoyaltyValidation, LoyaltyActivation e LoyaltyTransfer e ocorre quando a tag da mensagem não contém nenhum elemento de fidelidade. |
8298 | Se você solicitar a recuperação da transação original, mas não enviar o que é. | Revise a conformação da mensagem que é enviada do posto para a PROMO Central a fim de verificar a existência do atributo originalTransaction. |
8299 | Erro genérico ao enviar para central PROMO. | Comunique-se com o administrador PROMO para monitorar o computador onde o console PROMO está sendo executado. |
A partir do PROMO 5, foram adicionadas as séries de erros 9xxx, que se aplicam aos Erros produzidos no processamento do Console Central PROMO.
Esses erros são:
1 | valor de confirmação | Descrição | Ação recomendada |
2 | 9000 | A mensagem não possui ticket associado. | Reenvie a mensagem e se o erro persistir, revalide seu formato. Verifique a sequência de mensagens enviadas. |
3 | 9001 | Há uma transação pendente. Uma nova transação foi recebida para ser processada, mas há uma anterior que está pendente. | Uma mensagem com status=commit/rollback deve ser enviada para encerrar a transação anterior. |
4 | 9002 | Não há transação pendente. Uma mensagem com status=commit ou rollback foi recebida, mas não havia nenhuma transação anterior pendente. | Revise as mensagens enviadas ao mecanismo, principalmente em sua sequência lógica. |
5 | 9003 | Foi solicitada a informação de uma transação anterior mas não foi informado o identificador da mesma. | Verifique se a propriedade originalTransaction tem um valor e é válida. |
6 | 9004 | As informações de uma transação anterior foram solicitadas, mas a transação não existe. | Verifique o identificador da transação original que está sendo relatada. |
7 | 9005 | Indica que o Console está no modo Offline | Em alguns casos, como o deLealityTransfer, se o console estiver no modo Offline, essa operação não poderá ser executada. Entre em contato com o administrador PROMO para verificar o computador onde o console PROMO está sendo executado. |
8 | 9006 | Trabalho de conclusão da transação | Entre em contato com o administrador do aplicativo e revise as configurações do console para restaurar o serviço. |
9 | 9007 | "CompanyId" não é indicado no cabeçalho da mensagem. | Verifique os dados enviados |
10 | 9008 | Este valor é obtido quando é detectada uma devolução parcial realizada anteriormente para a transação que está tentando realizar a devolução total sem escaneamento do item. | Verifique se não existem tais transações pendentes. |
onze | 9101 | Cupom não encontrado | Verifique os dados solicitados |
12 | 9102 | cupom consumido | Verifique se o cupom não foi usado |
13 | 9103 | cupom inativo | Verifique se o cupom solicitado está ativo. |
14 | 9104 | Tipo de cupom não encontrado | Verifique o valor informado na mensagem. |
quinze | 9105 | O cupom expirou. | A data de vencimento do cupom foi atingida, com a qual verificar a referida situação. |
16 | 9106 | O número máximo de usos foi atingido | Verifique a referida situação |
17 | 9107 | O cupão está nomeado e não foi reportado um cliente ou o cliente reportado não corresponde ao cliente associado ao cupão | Verifique a referida situação |
18 | 9108 | O tipo de cupom não está ativo | Verifique o tipo de cupom |
19 | 9109 | O valor enviado não corresponde ao valor do cupom | Verifique o valor do cupom |
vinte | 9110 | cupom não utilizado | O cupom inserido na transação não participou de nenhuma promoção. |
vinte e um | 9111 | Cupom parcialmente usado | Indica que o cupom não suporta uso parcial, mas está tentando usar parcialmente. Neste caso, se for enviado um commit confirmando a transação, o cupom será consumido (Detecção de Fraude). |
22 | 9201 | Cabeçalho da transação não encontrado. | Normalmente devido a um erro interno, consulte o administrador do sistema. |
23 | 9500 | Elemento de fidelidade não encontrado | Verifique os dados solicitados |
24 | 9501 | Elemento de fidelidade desativado | Verifique os dados solicitados. Para algumas ações, apenas itens de fidelidade ativados podem ser processados |
25 | 9502 | Item de fidelidade cancelado | Verifique os dados solicitados. Não é possível interagir com itens de fidelidade cancelados |
26 | 9503 | Tipo de item de fidelidade de fidelidade não encontrado | Verifique os dados solicitados |
27 | 9504 | Tipo de elemento de fidelidade não ativo | Verifique os dados solicitados. Não é possível interagir com tipos de itens de fidelidade inativos |
28 | 9505 | Tipo de fidelidade não recarregável | Verifique os dados solicitados. Para opções de Carga ou Recarga, o tipo de item de fidelidade deve ser Recarga |
29 | 9506 | O item de fidelidade já possui um cliente associado a ele | Verifique se o elemento de fidelidade na ativação enviou o cliente. |
30 | 9507 | O status enviado do item de fidelidade não existe. | Verifique se foi enviado um status do elemento fidelidade, na ativação, válido (ATIVADO, DESATIVADO) - Em Maiúsculas - |
31 | 9508 | O elemento fidelidade não se aplica ao benefício | Verifique se o tipo de elemento de fidelidade é recarregável ou se o elemento de fidelidade está ativado. Outro erro pode ser que o tipo de elemento de fidelidade com o qual o benefício foi criado esteja inativo ou não exista na transação. |
32 | 9509 | O elemento de fidelidade requer um cliente | Verifique se é necessário o tipo de elemento de fidelidade, na transação pelo menos um cliente deve viajar. |
33 | 9510 | Item de fidelidade não autorizado | Existem várias situações em que você pode obter este código de erro:
|
3. 4 | 9511 | Montante inválido | Ao tentar deduzir um valor superior ao valor total do elemento fidelização, aparecerá esta mensagem. Verifique se o valor é menor que o total. |
35 | 9512 | São necessários pelo menos dois elementos de fidelidade | Esta mensagem é usada para transferências. Dois cartões são necessários para estar na mensagem. O de origem em Seq="1" e o de destino em Seq="2" |
36 | 9513 | O elemento de fidelidade não suporta transferência. | Verifique se o elemento de fidelidade de origem suporta Transferência. Seja parcial ou total. |
37 | 9514 | O elemento de fidelidade do destino está ativo | Verifique se o elemento de fidelidade de destino está inativo para fazer uma transferência total. |
38 | 9515 | Os tipos de itens de fidelidade não são os mesmos | Verifique se os tipos de elementos de fidelidade são iguais, ou seja, iguais. |
39 | 9516 | O saldo inserido é maior que o limite de saldo | Verifique se o valor informado para a cobrança de um elemento fidelidade não é maior que o Limite de Saldo do tipo de elemento fidelidade. |
40 | 9517 | O tipo de elemento de fidelidade não suporta atribuição de cliente | Este erro é específico para o serviço do próximo número do item de fidelidade quando o tipo de item de fidelidade não é indicado. |
41 | 9518 | O parâmetro companyId não foi especificado | Este erro é específico do serviço de próximo número quando não é informado o identificador da empresa que faz o pedido. |
42 | 9519 | Identificação da empresa inválida | Não foi possível encontrar o companyId especificado. |
43 | 9520 | Operação inválida | A operação solicitada não corresponde a uma operação válida |
44 | 9603 | cliente inexistente | Verifique os dados do cliente inseridos na transação |
Quatro cinco | 9610 | id de cliente vazio | Verifique os dados do cliente inseridos na transação |
46 | 9611 | Nome do cliente vazio | Verifique os dados do cliente inseridos na transação |
47 | 9612 | Sobrenome do cliente vazio | Verifique os dados do cliente inseridos na transação |
48 | 9613 | ID do cliente vazio | Verifique os dados do cliente inseridos na transação |
49 | 9614 | Nenhum parâmetro recebido do cliente | Verifique os dados do cliente inseridos na transação |
cinquenta | 9620 | cliente existente | Verifique os dados do cliente inseridos na transação |
51 | 9629 | cliente inativo | Verifique os dados do cliente inseridos na transação |
52 | 9901 | Erro inesperado de cupom. | Qualquer erro relacionado com o processamento de cupões que não esteja tipificado nos códigos anteriores. Consulte o administrador do sistema. |
53 | 9999 | Erro inesperado | Qualquer erro no processamento da PROMO Central que não esteja tipificado nos casos anteriores. |
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> </lealdade> </mensagem>
Corpo
O corpo da mensagem de resposta fornecido pelo Motor de Promoções informa as promoções que devem ser aplicadas ao ticket enviado até o momento e as promoções que devem ser sugeridas de acordo com o especificado na solicitação. Será composto por:
- uma ou mais opções
- Cada opção será composta por uma ou mais promoções
- Cada promoção conterá a condição de participantes (pode não ser informado)
- Cada promoção será composta por um ou mais benefícios
- Cada buff conterá os participantes do combo (pode estar vazio)
- Cada buff também conterá os elementos do item aplicado (pode estar vazio)
- Cada opção será composta por uma ou mais promoções
- Um conjunto de sugestões (esta parte do conteúdo pode não estar presente)
- As sugestões são compostas por uma ou mais promoções
- Para cada promoção, será informado a descrição, nome, sequências e tipos de sequência que deram origem à sugestão.
- As sugestões são compostas por uma ou mais promoções
No caso de avaliações a serem realizadas no PROMO Central, a composição da resposta será:
- um elemento de fidelidade
- Cada elemento de fidelidade pode ser composto por um ou mais elementos de fidelidade (cupons e/ou elemento de fidelidade)
- Cada cupom conterá os detalhes do mesmo para sua emissão (opcional, esta informação pode não existir)
- Cada elemento de fidelidade conterá os detalhes do elemento de fidelidade
- Cada elemento de fidelidade também pode ser composto por erros
- Cada elemento de fidelidade pode ser composto por um ou mais elementos de fidelidade (cupons e/ou elemento de fidelidade)
Opções
Cada uma das opções representa uma das opções que o cliente pode escolher. Cada um surge da aplicação da função de coexistência OPTION (consulte o Manual do Usuário). Dessa forma, o PROMO já informa as combinações possíveis. As opções são representadas pela tag <opcional> . Caso não existam opções, o corpo da mensagem de resposta será composto por uma única opção, ou seja, haverá apenas uma tag <opcional> que conterá as promoções a serem aplicadas. Esta tag não tem atributos.
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> … promoções que compõem a opção … </opcional> <opcional> … promoções que compõem a opção … </opcional> </mensagem>
promoções
Conforme mencionado acima, cada uma das opções conterá uma ou mais promoções .
Estes serão identificados pelo seu nome, sendo este o seu único atributo.
As promoções serão representadas com a tag <promo> , tendo o atributo id representando seu nome:
Propriedade | Tipo de dados | Descrição |
eu ia | alfanumérico | Nome da promoção. |
não | alfanumérico | Identificador do banco de dados da promoção |
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> <promo id="promoção de natal" nro="1"> ... condicionar os participantes ... … benefícios … </promo> <promo id="promoção 2x1 em brinquedos" nro="2"> ... condicionar os participantes ... … benefícios … </promo> </opcional> </mensagem>
Por sua vez, cada promoção pode informar uma série de elementos participantes de condição e benefícios, ambos detalhados nas seções a seguir.
participantes da condição
Os participantes da condição são um componente opcional que indica os elementos que influenciaram a condição (ver Manual do Usuário) que deu origem à concessão do benefício. Esses elementos serão agrupados dentro de uma tag do tipo < conditionParticipants >. Os elementos participantes da condição serão representados pelo tag correspondente ao tipo de elemento, agrupados conforme já descrito em <conditionParticipants> . Os elementos participantes terão os atributos informados ao adicioná-los à sessão.
Os participantes da condição são totalmente opcionais, podendo não ser informados caso esteja configurado no arquivo de definição das promoções (mapa) ou se não houver participantes da condição. Nesse caso, o rótulo<conditionParticipants> não fará parte da promoção. Esta tag não tem atributos.
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> <promo id="promoção de natal" nro="1"> <condiçãoParticipantes> <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" /> <cupom seq="1" id="0001" quantidade="" qty="1.0" type="A" /> </conditionParticipants> … benefícios … </promo> </opcional> </mensagem>
Benefícios
Dentro de cada promoção haverá um ou mais benefícios. Os benefícios são os elementos mais importantes da resposta e definem a vantagem (econômica ou não) que deve ser dada ao cliente, correspondente à promoção a que pertence. Eles serão definidos através da tag <benefit> .
Existem benefícios de vários tipos, cada um com características diferentes. É por isso que, dependendo do benefício em questão, os atributos correspondentes à tag <benefit> que o representa irão variar. No entanto, existem alguns atributos que são comuns a todos eles:
Propriedade | Tipo de dados | Descrição |
ordem | inteiro positivo | Número que identifica exclusivamente o benefício na mensagem de resposta. Seu valor decorre da ordem em que foi aplicado ao realizar a avaliação. |
tipo de benefício | alfanumérico | Tipo de benefício envolvido. |
exibir mensagem | alfanumérico | Mensagem a ser exibida no display do ponto de venda. |
mensagem da impressora | alfanumérico | Mensagem a imprimir na fatura ou talão no final da compra. |
método de aplicação | alfanumérico | Forma de mostrar lucro. Pode ter dois valores:
|
valor base | real positivo | Indica o valor total sobre o qual foi calculado o benefício em questão. |
Mensagem TLOG | alfanumérico | Mensagem para salvar no TLOG |
conta | alfanumérico | Conta contábil à qual o benefício será alocado. |
não | alfanumérico | Identificador do banco de dados de benefícios. |
inhame | alfanumérico | Identificador do banco de dados da promoção que contém o benefício. |
Não importa que tipo de buff seja, eles podem ter itens aplicados e participantes de combo . Cada um deles será detalhado nas seções a seguir.
tipos de benefícios
O PROMO possui oito tipos de benefícios, sendo três monetários e cinco não monetários. Os benefícios monetários são aqueles que proporcionam uma vantagem econômica ao cliente, enquanto os não monetários não.
Os tipos de benefício serão dados pelo valor do atributo BenefitType da tag <benefit> e são os seguintes:
- Monetário:
- Desconto Fixo
- É um desconto fixo que é feito em um conjunto de itens.
- PercentualDesconto
- Representa uma porcentagem de desconto em um conjunto de itens.
- Novo preço
- Atribua um novo preço a um ou mais itens.
- ConcursoDescontoBenefício
- Representa uma % de desconto ou sobretaxa em um conjunto de itens. As informações para cálculo desse percentual são obtidas dos planos de pagamento (PaymentPlanBenefit) aplicados.
- ResgatarPontosBenefício
- Faça a conversão de saldo para dinheiro e informe um valor de desconto a ser aplicado com base no valor informado.
- Cupom CalculadoBenefício do Aplicativo
- O valor informado por um cupom calculado é aplicado como desconto
- ContratoPercentagemDescontoBenefício
- Desconto percentual aplicado a um determinado Contrato e limitado por um saldo associado a ele
- Benefício de Resgate do Catálogo
- Realiza uma conversão de pontos e concede um valor de desconto com base em dados tabulares definidos para os produtos
- ResgatarComOpçõesBenefício
- (Desde Promo 7.0-EP2 ) Resgatar um determinado número de pontos (Cliente/Lealdade Elementos) para permitir um desconto monetário. Para mais informações sobre o benefício, consulte o Anexo I deste documento.
- Desconto Fixo
- Não monetário
- Plano de PagamentoBenefício
- Conceda um plano de pagamento específico para uma série de itens ou para a compra.
- CupomBenefício
- Dê um certo número de cupons específicos para o cliente.
- Presente Benefício
- Dê ao cliente um ou mais presentes específicos.
- GeralBenefício
- Oferece ao cliente um ou mais benefícios gerais.
- FidelidadeBenefício
- Beneficia o cliente com um determinado saldo de fidelização (milhas, pontos na carteira, dinheiro, etc.). A partir da versão 2.8.0, este benefício calcula o valor do crédito para cada item do aplicativo e o valor do crédito total que ele concede.
- FatorLealdadeBenefício
- Representa a atribuição de pontos, dinheiro, milhas, etc. de fidelidade em relação a um dado fator.
- PorcentagemLealdadeBenefício
- Representa a atribuição de pontos, dinheiro, milhas, etc. fidelidade em relação a um determinado percentual. Este benefício calcula o número de pontos, dinheiro, milhas, etc. para cada elemento de aplicação e a quantidade de pontos, dinheiro, milhas, etc. total que concede.
- BenefícioCupomCalculado
- Representa a atribuição de um cupão cujo valor do desconto a conceder é definido por uma percentagem dos participantes.
- Plano de PagamentoBenefício
Conforme mencionado nos parágrafos anteriores, cada tipo de benefício terá seus próprios atributos. Cada um desses atributos representa um parâmetro específico do benefício ao qual pertence (indicado em BenefitType ). A tabela a seguir lista esses atributos e a coluna "Obrigatório" indica se o atributo sempre estará presente na resposta ("Sim") ou se dependerá de seu valor ser incluído nela ou não ("Não")
Beneficiar | Propriedade | Tipo de dados | Obrigatório | Descrição |
Desconto Fixo | unidade | alfanumérico | Não | O valor de "unidade" indicará se o desconto será aplicado a todo o empreendimento ou a cada unidade do imóvel selecionado. Os valores possíveis são:
|
valor do desconto | real positivo | Sim | Desconto a efectuar nos elementos aplicados. O valor a ser descontado para cada item irá variar de acordo com a unidade de aplicação. | |
Método de rateio | alfanumérico | Sim | Método que será utilizado para repartir o benefício entre os elementos aplicados, podendo ser:
| |
PercentualDesconto | unidade | alfanumérico | Não | Ele indicará se o percentual de desconto deve ser aplicado a cada unidade ou ao total. Os valores que pode ter são os indicados acima. |
porcentagem de desconto | real positivo | Sim | Percentual de desconto que será feito nos elementos participantes. O valor a ser descontado para cada item irá variar de acordo com a unidade de aplicação. | |
inhame | alfanumérico | Não | Nome da promoção que originou o benefício. | |
Método de rateio | alfanumérico | Sim | O método a ser usado para distribuir o benefício entre os elementos aplicados. Os valores a serem tomados são os mesmos indicados acima. | |
Novo preço | unidade | alfanumérico | Não | Ele indicará se o novo preço deve ser aplicado a cada unidade ou ao total. Os valores que pode ter são os indicados acima. |
novo preço | real positivo | Sim | Desconto fixo a efetuar nos elementos participantes. O valor a ser descontado para cada item irá variar de acordo com a unidade de aplicação. | |
Método de rateio | alfanumérico | Sim | O método a ser usado para distribuir o benefício entre os elementos aplicados. Os valores que pode assumir são os mesmos indicados acima. | |
ConcursoDescontoBenefício | tratar | alfanumérico | Sim | Meio de pagamento que pode ser utilizado. Pode ser uma lista separada por vírgulas. |
limite | real positivo | Não | Indica o máximo que pode ser pago com o meio de pagamento. Este limite só será útil no ponto de venda sem afetar os cálculos do Motor de Promoções. Se este valor estiver vazio significa que o valor é ilimitado. | |
ID do plano | alfanumérico | Sim | Identificador do plano concedido. | |
tipo | alfanumérico | Não | Tipo de meio de pagamento. | |
banco | alfanumérico | Não | Banco associado ao meio de pagamento. | |
percentagem | real positivo | Sim | Percentagem de desconto ou sobretaxa que se fará sobre os elementos participantes. | |
tipo de porcentagem | alfanumérico | Não | Indica se o percentual é desconto (valor=desconto) ou acréscimo (valor=sobretaxa). | |
deitar-se | inteiro positivo | Sim | Número identificador único do elemento de meio de pagamento (pagamento) dentro da transação. | |
quantia | real positivo | Sim | Dinheiro utilizado com esse meio de pagamento | |
itemmount | real positivo | Sim | Dinheiro que representa a quantidade de itens que você deseja pagar. | |
valor do pagamento | real positivo | Sim | Indica o valor total sobre o qual foi calculado o benefício em questão. | |
prestações | real positivo | Não | Indica o número de prestações associadas ao plano de pagamento | |
valor beneficiado | real positivo | Sim | Desconto a efectuar nos elementos aplicados. | |
ResgatarPontosBenefício | tipo | alfanumérico | Sim | Indica o tipo de elemento de fidelidade ao qual o benefício será aplicado |
fator | real positivo | Sim | Indica o fator de conversão para cálculo do desconto com base no valor informado no valor | |
pontos usados | real positivo | Sim | Indica o valor do saldo (ponto, dinheiro, etc.) que será utilizado para a aplicação do referido benefício | |
valor do desconto | real positivo | Sim | Desconto a efectuar nos elementos aplicados. O valor a ser descontado para cada item irá variar de acordo com a unidade de aplicação. | |
Método de rateio | alfanumérico | Sim | O método a ser usado para distribuir o benefício entre os elementos aplicados. Os valores que pode assumir são os mesmos indicados acima. | |
unidade | alfanumérico | Sim | Ele indicará se o novo preço deve ser aplicado a cada unidade ou ao total. Os valores que pode ter são os indicados acima. | |
Cupom CalculadoBenefício do Aplicativo | valor do desconto | real positivo | Sim | Desconto a efectuar nos elementos aplicados. O valor a ser descontado para cada item irá variar de acordo com a unidade de aplicação. |
cupomId | alfanumérico | Sim | Identificador do cupom a ser resgatado. | |
cupons usados | alfanumérico | Sim | Consiste em uma string com valores separados por vírgulas indicando cada um dos códigos de cupom utilizados no resgate. Esses dados são baseados nos cupons usados para cobrir o valor do resgate. Exemplo de cupons usados=A645746566, BCD8383, P39393A9393 | |
Plano de PagamentoBenefício | tratar | alfanumérico | Sim | Meio de pagamento que pode ser utilizado. Pode ser uma lista separada por vírgulas. |
LimitAmount | real positivo | Não | Indica o máximo que pode ser pago com o meio de pagamento. Este limite só será útil no ponto de venda sem afetar os cálculos do Motor de Promoções. Se este valor estiver vazio significa que o valor é ilimitado. | |
plano | alfanumérico | Sim | Identificador do plano concedido. | |
tipo | alfanumérico | Não | Tipo de meio de pagamento. | |
banco | alfanumérico | Sim | Banco associado ao meio de pagamento. | |
por cento | real positivo | Não | Percentagem de desconto ou sobretaxa que se fará sobre os elementos participantes. O desconto ou sobretaxa será relatado como um TenderDiscountBenefit | |
tipo de porcentagem | alfanumérico | Não | Indica se o percentual é desconto (valor=desconto) ou acréscimo (valor=sobretaxa). | |
prestações | real positivo | Não | Indica o número de prestações associadas ao plano de pagamento | |
valor do pagamento | real positivo | Sim | Indica o valor total sobre o qual foi calculado o benefício em questão. | |
CupomBenefício | cupomId | alfanumérico | Sim | Identificador do cupom a ser concedido. |
quantia | real positivo | Sim | Indicará o valor associado a um cupom cujo valor foi calculado | |
quantidade | inteiro positivo | Sim | Número de cupons a serem concedidos. | |
InfoPos | alfanumérico | Não | No caso dos Cupons Informativos, existe a possibilidade de envio ao Ponto de Venda da opção selecionada dentre as disponíveis para serem configuradas pelo usuário. Veja o Manual do Usuário para Cupons Informativos. | |
Presente Benefício | código de presente | alfanumérico | Sim | Identificador do brinde a entregar. Caso seja um produto em estoque, pode representar o código do item a ser ofertado. |
giftType | alfanumérico | Sim | Tipo de presente para dar. Pode estar vazio. | |
quantidade | inteiro positivo | Sim | Quantidade de brindes com o identificador indicado. | |
FidelidadeBenefício | tipo | alfanumérico | Sim | Tipo de valor (pontos, dinheiro, milhas, etc.) de fidelidade que está sendo concedido. |
quantia | inteiro positivo | Sim | Quantidade de pontos, dinheiro, milhas, etc. conceder do tipo especificado no atributo anterior. | |
unidade | alfanumérico | Sim | Ele indicará se a quantidade de pontos, dinheiro, milhas, etc. deve ser aplicada. a cada unidade ou ao total. Os valores que pode ter são os indicados acima. | |
total de pontos | real positivo | Sim | Indica o número total de pontos, dinheiro, milhas, etc. que concede o benefício depois de calculado. | |
FatorLealdadeBenefício | tipo | alfanumérico | Sim | Tipo de pontos, dinheiro, milhas, etc. de fidelidade que estão sendo concedidas. |
fator | real positivo | Sim | Fator de multiplicação a ser usado para calcular pontos, dinheiro, milhas, etc. | |
PorcentagemLealdadeBenefício | tipo | alfanumérico | Sim | Tipo de pontos, dinheiro, milhas, etc. de fidelidade que estão sendo concedidas. |
por cento | real positivo | Sim | Porcentagem de pontos, dinheiro, milhas, etc., que se aplica ao xprice ou originalXPrice para calcular o número de pontos, dinheiro, milhas, etc. que correspondem a outorga. | |
total de pontos | real positivo | Sim | Indica o número total de pontos, dinheiro, milhas, etc. que concede o benefício depois de calculado. | |
BenefícioCupomCalculado | cupomId | alfanumérico | Sim | Identificador do cupom a ser concedido. |
quantia | inteiro positivo | Sim | Indicará o valor associado a um cupom cujo valor foi calculado | |
percentagem | alfanumérico | Sim | Indica a porcentagem com base na qual o valor do cupom foi calculado | |
quantidade | inteiro positivo | Sim | Número de cupons a serem concedidos. | |
PromotionPaidInPoints | quantidade | inteiro positivo | Sim | Número de itens a serem beneficiados. |
pontos | alfanumérico | Sim | Quantidade de pontos a serem descontados do benefício que entregou pontos na transação atual (informado no aplicativo) Será informado quando o atributo pointsType="" for enviado no pagamento (vide manual do usuário final Promo 7 - Ignorar pagamento com pontos.) |
Benefício de Resgate do Catálogo | valor do desconto | real positivo | Sim | Desconto a efectuar nos elementos aplicados. O valor a ser descontado para cada item irá variar de acordo com a unidade de aplicação. |
tipo | alfanumérico | Sim | Tipo de pontos, dinheiro, milhas, etc. de fidelidade que estão sendo concedidas. | |
unidade | alfanumérico | Sim | Atualmente, o benefício é aplicado à quantidade ou grandeza de cada produto em questão, motivo pelo qual não se espera funcionalidade neste atributo. | |
pontos usados | real positivo | Sim | Indica o valor do saldo (ponto, dinheiro, etc.) que será utilizado para a aplicação do referido benefício |
GeralBenefício | em geral | alfanumérico | Sim | Identificador do benefício a ser entregue. Caso seja um produto em estoque, pode representar o código do item a ser ofertado. |
tipo geral | alfanumérico | Sim | Tipo de benefício a entregar. Pode estar vazio. | |
quantidade | inteiro positivo | Sim | Quantidade de benefícios com o identificador indicado. |
DescontoPercentagemContrato | unidade | alfanumérico | Não | Ele indicará se o percentual de desconto deve ser aplicado a cada unidade ou ao total. Os valores que pode ter são os indicados acima. |
porcentagem de desconto | real positivo | Sim | Percentual de desconto que será feito nos elementos participantes. O valor a ser descontado para cada item irá variar de acordo com a unidade de aplicação. | |
inhame | alfanumérico | Não | Nome da promoção que originou o benefício. | |
Método de rateio | alfanumérico | Sim | O método a ser usado para distribuir o benefício entre os elementos aplicados. Os valores a serem tomados são os mesmos indicados acima. |
Exemplos :
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> <promo id="promoção de natal" nro="1"> <condiçãoParticipantes> <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" /> <cupom seq="1" id="0001" quantidade="" qty="1.0" type="A" /> </conditionParticipants> <benefit order="1" BenefitType="FixedAmount" displayMessage="" printerMessage="" unit="qty" prorationMethod="PROPORCIONAL" applicationMethod="lineByLine" nro="3" amount="20.00" baseAmount="165.00" > …participantes combinados e/ou elementos aplicados… </benefício> </promo> </opcional> </mensagem>
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> <promo id="promoção de natal" nro="1"> <benefit order="1" BenefitType="PercentageDiscount" displayMessage="" printerMessage="" unit="" prorationMethod="PROPORCIONAL" applicationMethod="lineByLine" nro="3" Percentage="20.00" baseAmount="165.00"> …participantes combinados e/ou elementos aplicados… </benefício> </promo> </opcional> </mensagem>
<?xml version="1.0" encoding="UTF-8" standalone="no"?><message ack="0" companyId="napse" engine="7.2.3-SNAPSHOT#206" mapversion="164" messageId="10" store="Store1" terminal="1"> <opcional> <promo id="Plano de pagamento promocional" nro="62d808251e49e74f30e086f9"> <benefit TLOGMessage="Promoção de Saque Bancário" account="" applicationMethod="resume" baseAmount="1300.00" BenefitType="PaymentPlanBenefit" displayMessage="Promoção de Saque Bancário" parcelas="12" name="62d808251e49e74f30e086f9" nro="62 d80a951e49e74f30e 08704 " order="1" paymentAmount="1300.00" percent="10" percenttype="discount" planId="si" printerMessage="Promoção de Retirada Bancária" tender="si" type="si"> <aplicar> <item magnitude="0.000" qty="1.000" seq="1" value="0.00" valueWithTaxes="0.00" xprice="300.00"/> <item magnitude="0.000" qty="1.000" seq="2" value="0.00" valueWithTaxes="0.00" xprice="100.00"/> <item magnitude="0.000" qty="1.000" seq="3" value="0.00" valueWithTaxes="0.00" xprice="200.00"/> <item magnitude="0.000" qty="1.000" seq="4" value="0.00" valueWithTaxes="0.00" xprice="700.00"/> </aplicar> </benefício> </promo> <promo id="Promoções baseadas em itens" nro="1"> <benefit TLOGMessage="Promoção de saque bancário" account="" amount="1170.00" applicationMethod="resume" baseAmount="1300.00" BenefitType="TenderDiscountBenefit" Benefitedamount ="130.00" displayMessage="Promoção de Saque Bancário" parcelas="12" itemamount="1300.00" order="2" paymentAmount="1300.00" percent="10" percenttype="discount" planId="si" printerMessage="Promoção Reembolso Bancário" promotionId="Plano de Pagamento Promocional" tender="si" tendereq="1,2" type="sim"> <aplicar> <item magnitude="0.000" qty="1.000" seq="1" tendereq="1" value="30.00" valueWithTaxes="0.00" xprice="300.00"/> <item magnitude="0.000" qty="1.000" seq="2" tendereq="1" value="10.00" valueWithTaxes="0.00" xprice="100.00"/> <item magnitude="0.000" qty="1.000" seq="3" tendereq="1" value="20.00" valueWithTaxes="0.00" xprice="200.00"/> <item magnitude="0.000" qty="1.000" seq="4" tendereq="1" value="30.00" valueWithTaxes="0.00" xprice="700.00"/> <item magnitude="0.000" qty="1.000" seq="4" tendereq="2" value="40.00" valueWithTaxes="0.00" xprice="700.00"/> </aplicar> </benefício> </promo> </opcional> </mensagem>
<message ack="0" engine="2.6" mapversion="2" messageId="1" companyId="sts" store="1" terminal="1"> <opcional> <promo id="resgatar pontos" nro="58ff57be6772781234e7915e"> <benefit TLOGMessage="resgatar pontos" account="" applicationMethod="resume" baseAmount="100.00" BenefitType="RedeemPointsBenefit" discountAmount="100.00" displayMessage="resgatar pontos" factor="1" name="58ff57be6772781234e7915e" nro="58ff57e76772781234e79164" order="1" printerMessage="resgatar pontos" prorationMethod="PROPORCIONAL" unit="" usedPoints="100.0"> <aplicar> <item magnitude="0.000" qty="1.000" seq="2" value="100.00" xprice="100.00"/> </aplicar> </benefício> </promo> </opcional> </mensagem">
<message ack="0" engine="2.6" mapversion="2" messageId="1" companyId="sts" store="1" terminal="1"> <opcional> <promo id="resgate impresso calculado" nro="5900e1a6a846390de08a7afe"> <benefit TLOGMessage="resgate impresso calculado" account="" applicationMethod="resume" baseAmount="100.00" BenefitType="CouponApplicationBenefit calculado" cupomId="1" discountAmount="10.00" displayMessage="resgate impresso calculado" name="5900e1a6a846390de08a7 afe " nro="5900e1bca846390de08a7b04" order="1" printerMessage="resgate impresso calculado" prorationMethod="PROPORCIONAL" unit="" usedCoupons="A39383883,B39393839,C333333333"> <aplicar> <item magnitude="0.000" qty="1.000" seq="2" value="10.00" xprice="100.00"/> </aplicar> </benefício> </promo> </opcional> </mensagem>
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> <promo id="promoção de natal" 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="2.500,00"> …participantes combinados e/ou elementos aplicados… </benefício> </promo> </opcional> </mensagem>
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> <promo id="promoção de natal" nro="1"> <condiçãoParticipantes> <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" /> <cupom seq="1" id="0001" quantidade="" 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 combinados e/ou elementos aplicados… </benefício> </promo> </opcional> </mensagem>
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> <promo id="promoção de natal" nro="1"> <benefit order="1" BenefitType="GiftBenefit" displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" qty="2" giftType="A" giftId="00452" baseAmount="165.00" > …participantes combinados e/ou elementos aplicados… </benefício> </promo> </opcional> </mensagem>
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> <promo id="promoção de natal" nro="1"> <condiçãoParticipantes> <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" /> <cupom seq="1" id="0001" quantidade="" 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 combinados e/ou elementos aplicados… <item value="0.000" seq="2" qty="1.000" points="1000.00" xprice="99.00"/> </benefício> </promo> </opcional> </mensagem> <message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> <promo id="promoção de natal" nro="1"> <condiçãoParticipantes> <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="preferido" /> <cupom seq="1" id="0001" quantidade="" 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 combinados e/ou elementos aplicados… <item value="0.000" seq="2" qty="2.000" points="2000.00" xprice="99.00"/> </benefício> </promo> </opcional> </mensagem>cliente
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> <promo id="promoção de natal" nro="1"> <benefit order="1" BenefitType="FactorLoyaltyBenefit " displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" factor="2" type="points" baseAmount="165.00"> …participantes combinados e/ou elementos aplicados… </benefício> </promo> </opcional> </mensagem>
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> <promo id="promoção de natal" nro="1"> <condiçãoParticipantes> <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="preferido" /> <cupom seq="1" id="0001" quantidade="" 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 combinados e/ou elementos aplicados… <item value="0.000" seq="2" qty="1.000" points="16.50" xprice="99.00"/> </benefício> </promo> </opcional> </mensagem> cliente
<message ack="0" engine="2.6" mapversion="2" messageId="1" companyId="sts" store="1" terminal="1"> <opcional> <promo id="emitir impressão calculada" nro="5900e173a846390de08a7af7"> <benefit TLOGMessage="impressão calculada do problema" account=""mount="10.00" applicationMethod="resume" baseAmount="100.00" nro="5900e18ea846390de08a7afd" order="1" porcentagem="10" printerMessage="problema de impressão calculado" qty="1.000"> <aplicar> <item magnitude="0.000" qty="1.000" seq="2" value="0.00" xprice="100.00"/> </aplicar> </benefício> </promo> </opcional> </mensagem>
<message ack="0" companyId="napse" engine="6.5.1" mapversion="5555" messageId="5" store="b320" terminal="1"> <opcional> <promo code="catred01" id="catred01" nro="5e937332c142d70ac486ebb3"> <benefit TLOGMessage="catred01" account="" applicationMethod="qty" baseAmount="7000.00" 5e937384c142d70ac486ebb7 " order="1" printerMessage="catred01" prorationMethod="PROPORCIONAL" unit="" usedPoints="330.00"> <aplicar> <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"/> </aplicar> </benefício> </promo> </opcional> </mensagem>
<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="vendas" avalia="true" offline="false" sugere="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"/> </mensagem>
<?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"> <opcional> <promo code="p2" id="Copiar - 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"> <aplicar> <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"/> </aplicar> </benefício> </promo> </opcional> </mensagem>
Promoções escalonadas
No caso de benefícios com promoções escalonadas, dentro das propriedades dos elementos aplicados (aplicar), haverá outra propriedade denominada "escalonar" cujo valor corresponde ao valor da etapa aplicada se aplicável (propriedade opcional que só é informada naquele caso).
Por exemplo: na resposta a seguir pode-se observar que o passo com valor 2 foi aplicado aos produtos da sequência 1 e 2, para os quais foram utilizados 400 pontos para trocar por um desconto de 200 no total.
<message ack="0" engine="2.6" mapversion="5433" messageId="5" store="3105" terminal="8"> <opcional> <promo code="canjedePuntos" id="canjedePuntos" nro="6080383cabe768428094afce"> <benefit TLOGMessage="redeemPoints" account="" applicationMethod="resume" baseAmount="200.00" 006 " order="1" printerMessage="redeemPoints" prorationMethod="PROPORCIONAL" type="dot" unit="" usedPoints="400.0"> <aplicar> <item magnitude="0.000" qty="1.000" seq="1" stagger="2.00" value="100.00" valueWithTaxes="100.00" xprice="100.00"/> <item magnitude="0.000" qty="1.000" seq="2" stagger="2.00" value="100.00" valueWithTaxes="100.00" xprice="100.00"/> </aplicar> </benefício> </promo> </opcional> </mensagem>
participantes do combo
Caso a promoção contenha algum combo associado, agrupamento finito de elementos. Para maiores detalhes, recomenda-se consultar o Manual do Usuário “condição por composição”.Os benefícios da promoção que forem aplicados a este combo associado, conterão uma etiqueta denominada <comboParticipantes> . Nela serão listados os elementos que compõem o combo ao qual se aplica o benefício ao qual pertencem, denominados participantes do combo , de forma semelhante aos participantes condicionantes e possuidores dos mesmos atributos.
Se a promoção não for definida por combos ou o cálculo de participantes não for necessário no arquivo de definição (mapa), < comboParticipants > não estará presente. Esta tag não tem atributos.
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> <promo id="promoção de natal" nro="1"> <benefit order="1" BenefitType="FactorLoyaltyBenefit " displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" factor="2" type="points" baseAmount="165.00"> <comboParticipantes> <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… </benefício> </promo> </opcional> </mensagem>
elementos aplicados
Os benefícios são sempre aplicados nos itens . Para representar isso, o Motor de Promoções utiliza a tag < apply > ao reportar os benefícios, onde serão listados os itens nos quais o benefício deverá ser aplicado. Como os benefícios só podem ser aplicados a itens, os elementos contidos em < apply > sempre serão < item >.
Ao contrário dos elementos que são informados nos participantes (seja condição ou combinação), os elementos < item > que serão encontrados dentro de < apply > terão os seguintes atributos:
Propriedade | Tipo de dados | Descrição |
eu sei que | inteiro positivo | Número que identifica o elemento dentro da transação à qual o benefício é aplicado. |
valor | Número Se for atribuído a um item um novo preço superior ao preço de venda informado, esse valor pode assumir um valor negativo. Por este motivo, devem ser implementadas rotinas para lidar com este tipo de valores. | Valor total a ser deduzido do elemento indicado pelo atributo seq . |
valorComImpostos | Número (consultar valor) | Valor total a ser deduzido do elemento indicado pelo atributo seq, mas considerando impostos (ver atributo impostos). |
quantidade | inteiro positivo | Número de itens afetados entre os quais deve ser distribuído o desconto expresso em valor . |
magnitude | real positivo | Quantidade afetada sobre a qual deve ser aplicado o desconto expresso em valor . Caso não tenha sido definida magnitude para o item, será informado como " 0,0 ". Ao calcular pontos, dinheiro, milhas, etc., se este valor for " 0,0 " então não será reportado. |
pontos | real positivo | Quantidade total de pontos, dinheiro, milhas, etc. que retorna a sequência identificada por seq . Aparece sempre que o elemento de aplicação faz parte de um LoyaltyBenefit ou PercentLoyaltyBenefit para o qual são calculados pontos, dinheiro, milhas, etc. |
xpreço | real positivo | Xprice ou preço original da sequência no momento em que o lucro foi calculado. Qual é xprice ou preço original vai depender de como o benefício é configurado e em qual desses dois valores ele se aplica (a partir da versão 2.8.0). |
Os benefícios do tipo monetário sempre relatarão itens aplicados, enquanto os não monetários podem não. Por outro lado, dentro dos artigos aplicados a prestações não pecuniárias, o valor atributo destes artigos será sempre “ 0,0 ”, uma vez que não há desconto a efetuar.
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> <promo id="promoção de natal" nro="1"> <benefit order="1" BenefitType="PercentageDiscount" displayMessage="" printerMessage="" unit="" prorationMethod="PROPORCIONAL" applicationMethod="lineByLine" nro="3" Percentage="20.00" baseAmount="162.00"> <comboParticipantes> <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> <aplicar> <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" /> </aplicar> </benefício> </promo> </opcional> </mensagem>
itens não aplicados
Nos benefícios externos (ExternalBenefit) podem existir itens que não são aplicados por não estarem presentes no contexto. Para representar isso, o Motor de Promoções ao reportar benefícios utiliza a tag <notApply> , onde serão listados os itens nos quais o benefício não pôde ser aplicado. Como os benefícios só podem ser aplicados a itens, os elementos contidos em < notApply > sempre serão < item >.
Ao contrário dos elementos que são informados nos participantes (seja condição ou combinação), os elementos < item > que serão encontrados dentro de < notApply > terão os seguintes atributos:
Propriedade | Tipo de dados | Descrição |
eu sei que | inteiro positivo | Número que identifica o elemento dentro da transação à qual o benefício é aplicado. |
valor | Número Se for atribuído a um item um novo preço superior ao preço de venda informado, esse valor pode assumir um valor negativo. Por este motivo, devem ser implementadas rotinas para lidar com este tipo de valores. | Valor total que não pôde ser descontado ao elemento indicado pelo atributo seq . |
quantidade | inteiro positivo | Número de itens que não foram afetados. |
magnitude | real positivo | Magnitude que não foi afetada |
xpreço | real positivo | Sempre irá a zero. |
<message engine="2.6" companyId="sts" store="0236" terminal="004" mapversion="114" ack="0" messageId="3777"> <opcional> <promo id="Desc5" número="3"> <condiçãoParticipantes> <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=""> <aplicar> <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"/> </aplicar> <nãoAplicar> <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> </benefício> </promo> </opcional> </mensagem>
Elemento de Resgate - Resgatar com Opções
(A partir da promoção 7.0 - EP2 )
As opções propostas pelo benefício "resgatar com opções" ( RedeemWithOptionsBenefit ) possuem os seguintes atributos
atributo | cara | Descrição |
---|---|---|
eu ia | alfanumérico | Identificador de opção** |
Pontos necessários | Numérico | Pontos necessários para resgatar para aplicar o benefício |
tipo de carta | alfanumérico | Tipo de elemento de fidelidade para o qual os pontos do cartão podem ser resgatados (cardPoints) |
cardPoints | Numérico | Pontos do elemento de fidelidade necessários para serem resgatados para aplicar o benefício |
tipo de benefício | alfanumérico | Tipo de cálculo a aplicar ( fixedDiscount / percentDiscount / newPrice ) |
unidade | alfanumérico | Unidade de medida a aplicar no cálculo (quantidade / magnitude) |
valor | Numérico | Valor aplicado no cálculo de acordo com o tipo de benefício ( fixedDiscount: FixedDiscount, percentDiscount: percentual, newPrice: newPrice ) por sua vez, esse valor será subtraído dos valuePoints do item-apply |
Exemplo:
<opções de resgate> <option BenefitType="percentageDiscount" cardPoints="200.0" cardType="089" id="5e567f0506773d1c14528761_0" requiredPoints="100.0" unit="qty" value="10.0"/> <option BenefitType="percentageDiscount" cardPoints="1000.0" cardType="089" id="5e567f0506773d1c14528761_2" requiredPoints="0.0" unit="qty" value="20.0"/> <option BenefitType="percentageDiscount" cardPoints="0.0" cardType="-" id="5e567f0506773d1c14528761_3" requiredPoints="500.0" unit="qty" value="20.0"/> </redeemOptions>
Para mais informações sobre o benefício, consulte o Anexo I - Troca como opções deste documento.
Sugestões
As sugestões adicionam à mensagem de resposta aquelas promoções que não foram concedidas, seja porque a condição da mesma não pode ser verdadeira ou o combo não pôde ser formado, ou o benefício não pôde ser aplicado. Essas informações podem ser utilizadas pelo vendedor para oferecer as condições necessárias para que a promoção seja aplicada antes de proceder ao fechamento da venda. As sugestões são representadas pela tag <suggestions> que aparecerá após a última tag <optional> . Se não houver sugestões, a tag <sugments> não aparecerá na mensagem de resposta. Esta tag não tem atributos.
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> … promoções que compõem a opção … </opcional> <opcional> … promoções que compõem a opção … </opcional> <sugestões> ... promoções que podem ser sugeridas ... </sugestões> </mensagem>
promoções sugeridas
Conforme mencionado acima, cada uma das sugestões conterá uma ou mais promoções . Estes serão identificados pelo nome. As promoções serão representadas com a tag <promo> , tendo o atributo id representando seu nome.
Propriedade | Tipo de dados | Descrição |
eu ia | alfanumérico | Nome da promoção. |
descritor | alfanumérico | Descrição da sugestão de promoção. Pode não estar no rótulo se não foi especificado para a promoção sugerida. |
item-seq | lista de números | As sequências de tipo de item que possibilitam a sugestão da promoção. Se não houver essas sequências para a promoção, esse atributo não será incluído na tag. |
sequência de pagamento | lista de números | As seqüências do tipo de meio de pagamento que possibilitam a sugestão da promoção. Se não houver essas sequências para a promoção, esse atributo não será incluído na tag. |
seq cliente | lista de números | As sequências do tipo cliente que possibilitam a sugestão da promoção. Se não houver essas sequências para a promoção, esse atributo não será incluído na tag. |
evento-seq | lista de números | As sequências do tipo de evento que possibilitam a sugestão da promoção. Se não houver essas sequências para a promoção, esse atributo não será incluído na tag. |
cupom seq | lista de números | As sequências de tipo de cupom que possibilitam a sugestão da promoção. Se não houver essas sequências para a promoção, esse atributo não será incluído na tag. |
cartão de fidelidade-seq | Lista de itens de fidelidade de fidelidade | Sequências de elementos de fidelização do tipo fidelização que permitem sugerir a promoção. Se não houver essas sequências para a promoção, esse atributo não será incluído na tag. |
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <sugestões> <promo id="Promoção de Natal" descriptor="trazendo uma árvore de natal damos as guirlandas" item-seq="1,2,3"/> <promo id="2x1 promoção em brinquedos" item-seq="1,2" cupom-seq="2" payment-seq="1"/> </sugestões> </mensagem> <message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <opcional> … promoções que compõem a opção … </opcional> <sugestões> <promo id="Promoção de Natal" descriptor="trazendo uma árvore de natal damos as guirlandas" item-seq="1,2,3"/> <promo id="2x1 promoção em brinquedos" item-seq="1,2" cupom-seq="2" payment-seq="1"/> </sugestões> </mensagem> <message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <sugestões> <promo id="Promoção de Natal" descriptor="trazendo uma árvore de Natal damos-lhe as guirlandas" /> <promo id="promoção 2x1 em brinquedos"/> </sugestões> </mensagem>
Sugestões sujeitas a stock
As promoções podem ser sugeridas aos clientes, com base no estoque existente.
Para isso, carrega-se o documento .txt com o SKU dos produtos em estoque:
O arquivo de estoque, será encontrado na raiz do mecanismo (ou pasta configurada), será texto simples no formato de 1 SKU por linha. Por exemplo: o arquivo de texto stock.txt mostra que cada uma das linhas contém um SKU:
O motor, na presença de uma promoção com sugestão de controle de estoque, irá:
- Pesquise se existe o arquivo de estoque configurado, caso não exista a promoção não será sugerida.
- Se o arquivo de estoque existir, se nenhum produto do conjunto de aplicativos (SKUs) tiver estoque (aparece no arquivo), não será sugerido.
O arquivo de estoque será atualizado toda vez que os mapas forem lidos (padrão de 10 min).
Fidelidade
Novos status em <Loyalty>
Historicamente, o valor da propriedade Status era de uso livre e sem restrições. A partir do PROMO 5, existem valores específicos e reservados para a propriedade "status" que indicarão ao motor determinadas ações a serem realizadas com o Console Central do PROMO.
Essas ações são:
Validação de Lealdade
Verifique o status de cupons, clientes e elementos de fidelidade para 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" avalia="true" map-version="9" sugere="false"> <loyaltycard-add seq="2" id=" 2220000000001" /> <coupon-add seq="1" qty="1" id=" 002001001413" /> <customer-add seq="1" id="6666"/> </mensagem>
Existem duas funções opcionais (a serem habilitadas) em relação à validação do cliente: (desde 6.5.2)
- Criação de cliente: Caso sejam enviadas informações completas do cliente (ou seja, e-mail ou identificador) e o cliente não exista no Promo, ele será automaticamente cadastrado.
- Atualização do cliente: Caso sejam recebidas informações completas do cliente e o cliente exista, então considera-se que a validação não é uma mera consulta de dados, mas ao enviar dados como "nome do cliente" é necessário atualizá-los.
(Consulte também, Resposta do mecanismo - LoyaltyValidation )
Essa ação não requer uma terceira mensagem (commit ou rollback) e cancela o elemento de fidelidade que está sendo relatado.
Ativação de Fidelidade
Realiza a ativação de um elemento de fidelidade.
Para ativar um elemento de fidelidade que está em estado inativo, pode ser enviada uma mensagem com Status="loyaltyActivation".
Deve ser enviado com o formato e atributos mostrados nos exemplos a seguir.
<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" avalia="true" map-version="9" sugere="false"> <loyaltycard-add seq="1" id="3330000000000"/> </mensagem>
Você também pode desativar um elemento de fidelidade ativo com LoyaltyAvtivation, adicionando o status="DISABLED" à tag <loyaltycard-add/>.
<mensagem 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" /> </mensagem>
(Consulte também Resposta do mecanismo – LoyaltyActivation )
Essa ação não requer uma terceira mensagem (commit ou rollback) e cancela o elemento de fidelidade relatado.
Criar itens de fidelidade
O status "loyaltyActivation" é um valor para a propriedade status do elementoloytcard, um valor CREATE para indicar que você deseja criar o elemento.
Se um cvv for especificado, ele será registrado e associado ao elemento de fidelidade que foi criado.
A figura a seguir mostra um tipo de exemplo chamado tn1
Procedemos à criação gratuita do primeiro elemento de fidelização:
<mensagem 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" avalia="false" offline="false"> <loyaltycard-add seq="1" id="10011" type="t1" status="CREATE" /> </mensagem>
A resposta é: (Ack =0 está correto)
<?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"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes/> </lealdade> </mensagem>
Além disso, se você deseja fazer uma cobrança inicial, pode adicionar a propriedade " chargeAmount " do elemento FidelityCard. Dessa forma, além de criá-lo, esse saldo será cobrado inicialmente.
Em seguida, passamos a criar um segundo com equilíbrio:
<mensagem 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" avalia="false" offline="false"> <loyaltycard-add seq="1" id="10012" type="t1" status="CREATE" chargeAmount="105.00" /> </mensagem>
Responder
<?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"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes/> </lealdade> </mensagem>
Se olharmos o detalhe de qualquer um deles:
Alteração e reinicialização do CVV de um elemento de fidelidade (CVVCHANGE e CVVRESET)
(a partir da promoção 6.5)
Habilita-se a possibilidade de efetuar a alteração ou reposição do CVV de um elemento de fidelização.
É necessário que o tipo de elemento a que pertence o elemento de fidelização ao qual se pretende alterar ou repor o CVV tenha a opção "CVV Obrigatório" assinalada.
As ações de alteração e reinicialização do cvv de um elemento de fidelidade podem ser realizadas tanto com elementos em estado ativo quanto inativo.
Transferência de Fidelidade
Transfira o saldo de um elemento de fidelização para outro do mesmo tipo.
Para realizar uma transferência de saldo, tanto o elemento de origem (aquele que dá saldo) quanto o elemento de destino (aquele que recebe saldo) devem ser do mesmo tipo.
No seq=1 enviado pelo PDV, será informado o cartão de origem, ou seja, de quem serão descontados os pontos, dinheiro, milhas, etc.
No seq=2 enviado pelo PDV, será informado o cartão de destino, ou seja, aquele que receberá os pontos, dinheiro, milhas, etc.
(Veja também o Manual do Usuário, "Conceitos do Cartão Fidelidade" para mais detalhes sobre os diferentes tipos de transferências possíveis)
<mensagem 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" /> </mensagem>
(Consulte também Resposta do mecanismo - LoyaltyTransfer ) COMMIT ou ROLLBACK
é necessário para confirmar ou reverter a transação.
LealdadeVazio
Este estatuto servirá para anular elementos de fidelização que iam ser emitidos ou concedidos, mas onde a transacção em curso que os emitiu não prosperou.
Os cupons cancelados através desta mensagem permanecerão com o status "Rejeitado".
<message companyId="sts" store="00001" terminal="010" date-time="2017-03-27 14:57" messageId="0010" void-trx="false" response="true" init- tck="verdadeiro" avalia="true" status="loyaltyVoid" msg-version="2.0" map-version="1"> <coupon-add seq="1" qty="1" id="1000010105299" type="C-Print"/> <loyaltycard-add seq="2" id="6665000008801" type="red" /> </mensagem>
(Consulte também Resposta do mecanismo – Anulação de fidelidade )
Esta ação não requer uma terceira mensagem (confirmação ou reversão) e cancela o elemento de fidelidade relatado.
LoyaltyAssign
O status "LoyaltyAssign" permitirá que o PDV, ou qualquer canal, informe a qual cliente um item está associado. Será validado que o elemento não foi previamente associado a um cliente, que o tipo de elemento existe e que requer associação via "Canal de Vendas".
<message companyId="sts" store="00001" terminal="010" date-time="2017-03-27 14:57" messageId="0010" void-trx="false" response="true" init- tck="verdadeiro" avalia="true" status="loyaltyAssign" msg-version="2.0" map-version="1"> <loyaltycard-add seq="2" id="6665000008801" type="red" /> <customer-add seq="1" id="6666"/> </mensagem>
(Consulte também Resposta do mecanismo – Anulação de lealdade ) COMMIT ou ROLLBACK
é necessário para confirmar ou reverter a transação.
TERMINAR
Indica o processamento do boleto na 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" avalia="true" status="finish" msg-version="2.0" map-version="15" sugere="true" sugere-seq="3"> .. Corpo da mensagem ... </mensagem>
Outra opção disponível para ativar um elemento de fidelidade é enviando o atributo "status" na tag <LoyaltyCard-ADD> quando um "Finish" é enviado, onde deve ser indicado o status HABILITADO para que o elemento incluído na transação seja ativado
<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" avalia="true" map-version="1" sugere="true"> <loyaltycard-add seq="2" id="3330000000002" type="3" status="ENABLED" /> </mensagem>
(Veja também Resposta do Motor - Ativação ao Concluir )
COMPROMETER-SE
Confirme a transação em andamento.
<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" sugerir="true" sugerir-seq="3"> ... Corpo da mensagem ... </mensagem>
REVERSÃO
Reverte a transação atual.
<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" sugerir="true" sugerir-seq="3">... corpo da mensagem ... </mensagem>
Solicitação de transação
Consulte as informações de uma determinada transação PROMO. (A transação a ser consultada deve ser informada no 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" sugerem="true" sugerir-seq="3"> </mensagem>
RetornoFinalizar
Registre todos os elementos de uma transação de devolução no PROMO e marque para o processo de segundo plano os elementos de fidelidade participantes da devolução a serem processados e revertidos, se aplicável. O campo OriginalTransaction deve ser informado junto com o ReturnFinish para que a operação seja realizada corretamente. COMMIT ou ROLLBACK
é necessário para confirmar ou reverter a transação.
<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" avalia="true" " status="returnFinish" originalTransaction="001_025_20161212134555" map-version="15" sugerem="true" sugerir-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"/> </mensagem>
Se não for especificado mais do que o cabeçalho da transação, este retorno será total: Todos os elementos que fizeram parte da venda serão revertidos.
Ex: O item especificado na sequência 1 e 2 está invertido, pois a venda original tinha o id: napse_2_1_20220503100000.
<?xml versão="1.0" codificação="UTF-8"?> <message store="2" terminal="1" date-time="2022-05-03 10:00:00" init-tck="true" messageId="1" void-trx="false" response=" true" status="finishEx" avalia="true" map-version="4" sugere="true" companyId="napse" originalTransaction="napse_2_1_20220503100000"> <item-add seq="1" qty="1" code="1234" magnitude="0" xprice="1" unitprice="1"/> <item-add seq="2" qty="1" code="2222" magnitude="0" xprice="2 unitprice="2"/> </mensagem>
Ex: do id da venda: napse_2_1_20220503100001 todos os seus itens são devolvidos
<?xml versão="1.0" codificação="UTF-8"?> <message store="2" terminal="1" date-time="2022-05-03 10:00:00" init-tck="true" messageId="1" void-trx="false" response=" true" status="finishEx" avalia="true" map-version="4" sugere="true" companyId="napse" originalTransaction="napse_2_1_20220503100001"> </mensagem>
Reembolso total
A partir desta versão, a funcionalidade Full Refund está disponível; evita que o operador tenha que escanear todos os produtos para fazer o reembolso total da compra.
A devolução total existente, onde o operador escaneia todos os itens, continuará disponível sem alterações.
Ele é implementado levando em consideração que <mensagem> não possui nós filhos. Por exemplo:
<?xml versão="1.0" codificação="UTF-8"?> <message store="2" terminal="1" date-time="2022-05-17 11:09:00" init-tck="true" messageId="1" void-trx="true" response=" true" status="returnFinish" originalTransaction="napse_2_1_20220517110500" avalia="true" map-version="2" sugere="true" companyId="napse"> </mensagem>
Este retorno total só funcionará quando não houver retornos parciais anteriores processados (commit) ou pendentes de processamento (commit pendente). Se existirem, um novo código de confirmação 9008 (ERR_InTotalReturnPartialReturnFound) será obtido.
Em transactionflatten você deve armazenar um campo (implementado como isEmptyReturnTransaction) que determina se foi um retorno completo ou não. Isso para que seja apresentado no relatório da transação que é um retorno total.
Ex:
<?xml versão="1.0" codificação="UTF-8"?> <message store="napse" terminal="1" date-time="2022-08-23 13:00:00" init-tck="true" messageId="1" void-trx="false" response=" true" status="returnFinish" originalTransaction="napse_napse_1_20220823123500" avalia="true" map-version="93" sugere="true" companyId="napse"> </mensagem>
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="7.2.0#226" mapversion="93" messageId="1" store= "napse" terminal="1" transaction="napse_napse_1_20220823130000"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes/> <redeemTable/> </lealdade> </mensagem>
Nota
O detalhe da devolução pode ser consultado na consola, Módulo Relatórios, Transacções, Detalhe da Transacção.
Validação de Resgate de Catálogo
Com base nos itens informados na solicitação e levando em consideração a loja da qual a transação é feita, ele informará os produtos existentes na tabela de Resgate de Pontos do Catálogo (explicada mais adiante neste documento).
É importante entender que para que um resgate de Pontos do Catálogo seja aplicado, esta mensagem deve ser enviada previamente.
No exemplo a seguir, uma mensagem deste tipo é enviada informando 5 códigos de Produtos diferentes:
<message companyId="napse" store="b320" terminal="1" date-time="2020-04-12 19:09" messageId="5" void-trx="false"uggest="true" response= "true" init-tck="true" avalia="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" /> </mensagem>
Como resposta à anterior, será recebida a tabela correspondente, por exemplo:
<message ack="0" companyId="napse" engine="6.5.1" mapversion="5555" messageId="5" store="b320" terminal="1" transaction="napse_b320_1_20200411190900"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes/> <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> </lealdade>
Veja as definições dos elementos nas tabelas correspondentes deste documento.
Fidelidade: resposta do motor
Cada um dos elementos de fidelização informados na resposta a um "acabamento" conterá dados sobre os benefícios obtidos com a aplicação de um benefício.
Dentro da tag <loyalty>, um ou mais dos seguintes elementos podem ser relatados:
- <cupom/>
- <cartões de fidelidade/>
- <erro/>
- <clientes/>
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <lealdade> <cupom/> <cartões de fidelidade/> <erro/> <clientes/> </lealdade> </mensagem>
As propriedades para o cabeçalho da resposta de fidelidade serão as mesmas informadas na resposta de qualquer outro elemento PROMO (Ver capítulo 3.1 Cabeçalho ),
Resposta - Validação de Lealdade
Em resposta a uma consulta de um ou mais elementos de fidelidade
<?xml versão="1.0" codificação="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530151500"> <lealdade> <cartões de fidelidade> <cartão de fidelidade ack="0" amount="0.0" customer="" id="2220000000001" seq="2" type="2"/> </cartões de fidelidade> <cupom> <cupom ack="0" amount="10.0" barcode="002001001413" cupomId="2" seq="1"/> </cupom> <erro/> <clientes> <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" cupomId="2" useTotalAmount="true" /> <coupon ack="0" amount="" barcode="003090033000000002147483647" cupomId="3"/> <cartão de fidelidade ack="0" amount="0.0" id="555000000222" type="5"/> </cliente> </clientes> </lealdade> </mensagem>
A propriedade useTotalAmount é retornada somente se o cupom for do tipo calculado e o tipo não foi enviado na consulta. Esta propriedade indicará se ela está totalmente (true) ou parcialmente (false) utilizada. De referir ainda que a utilização parcial implica o cancelamento total do cupão mas por valor inferior ao seu valor. Ou seja, se eu tiver um cupom no valor de R$ 100, parcialmente utilizado e na transação consumir apenas R$ 5 desse cupom, ele será marcado como utilizado, perdendo neste caso os R$ 95 restantes.
A propriedade amountChargeLimit é um dado de elemento de fidelidade que é fornecido na resposta de lealdadeValidação e é "o limite de cobrança que este elemento definiu".
Saída – Não OK (Ver capítulo 3.1.1 Valores do atributo "ack" )
<?xml versão="1.0" codificação="UTF-8"?> <message ack="0" engine="2.6" mapversion="9" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170529165306"> <lealdade> <cartões de fidelidade/> <cupom/> <erro> <error ack="9501" amount="0.0" cardType="3" info="3330000000002" seq="2" type="loyaltycard-redeem"/> </error> <clientes/> </lealdade> </mensagem>
(v7.1) No caso do Tag "erros" , a resposta dependerá do elemento de fidelidade informado. No caso particular dos Elementos Fidelidade, as propriedades amount, cardType, id, customer, contract, amountChargeLimit, nextExpDate, nextExpValue e usePartial serão informadas juntamente com as propriedades comuns apenas nos casos em que esta informação estiver disponível (ou seja, pode recuperar o tipo de elemento de fidelidade por exemplo) como ocorre no caso de resposta sem erros (ack=0).
Observação: Quando o item fidelidade consultado estiver inativo, o saldo do item fidelidade no momento da consulta será informado no atributo "valor" e o tipo de item em "cardType".
(consulte também Solicitação do mecanismo – lealdadeValidação )
Resposta - Cupons
Os cupons que foram concedidos como resultado dos benefícios de uma promoção são adicionados à mensagem de resposta. Vale esclarecer que esse é o detalhamento dos cupons concedidos, ou seja, se como resultado da avaliação de uma promoção foi concedido X número de cupons de algum tipo, então a resposta de fidelidade conterá o detalhamento desses X cupons concedidos .
<message companyId="sts" ack="0" engine="2.6" mapversion="1" messageId="1" store="1" terminal="1" transaction="1_1_20170515152511"> <lealdade> <cartões de fidelidade/> <cupom> <coupon ack="0" barcode="1000010019411" BenefitNro="58d2a8f8ef5a63133c3ca31d" couponId="TC_IM" format="PRINTED"" encoding="EAN13" promotionName="C-printed issue" promotionNro="58d2acdaef5a63133c3ca346">*< ! \[CDATA\[.....\]\]>* </cupom> </cupom> <erro/> <clientes/> </lealdade> </mensagem>
Como mencionamos, para cada um dos cupons gerados teremos um elemento cupom, conforme exemplo a seguir para 3 cupons:
<message companyId="sts" ack="0" engine="2.6" mapversion="1" messageId="1" store="1" terminal="1" transaction="1_1_20170515152511"> <lealdade> <cartões de fidelidade/> <cupom> <coupon ack="0" barcode="1234567890123" format="IMPRESSO" BenefitNro="58d2a8f8ef5a63133c3ca31d" cupomId="TC_IM" format="IMPRESSO"" encoding="EAN13" promotionName="C-printed issue" promotionNro="58d2acdaef5a63133c3ca 346 "><!CDATA\[ … dados livres …. \]\]> </cupom> <coupon ack="0" barcode="1234567890133" BenefitNro="58d2a8f8ef5a63133c3ca31d" couponId="TC_IM" format="PRINTED"" encoding="EAN13" promotionName="C-printed issue" promotionNro="58d2acdaef5a63133c3ca346"> <!CDATA\[ … dados livres …. \]\]> </cupom> <coupon ack="0" amount="10.0" barcode="1000010015888" BenefitNro="5900e18ea846390de08a7afd" couponId="1" encoding="EAN13" format="PRINTED" promotionName="calculated print issue" promotionNro="5900e173a846390de08a 7af7" > <!\[CDATA\[ … dados gratuitos… \]\]> </cupom> </cupom> <erro/> </lealdade> </mensagem>
As propriedades de cada elemento de cupom serão:
Propriedade | Tipo de dados | Descrição |
código de barras | alfanumérico | Código de barras do cupom, ou o que é o mesmo, seu identificador único. |
ack | todo | Código de retorno |
cupomId | alfanumérico | Identificador do tipo de cupom. |
formatar | alfanumérico | Formato de cupom. Os valores possíveis são: PRINTED, ELECTRONIC, THIRD_PARTY, EXTERNAL, PRE_PRINTED. |
codificação | alfanumérico | Formato em que o código de barras deve ser impresso (EAN13 - UPCA – CODE128) |
nome da promoção | alfanumérico | É o nome dado à promoção que aplica o benefício |
promoçãoNro | alfanumérico | Identifica a promoção que aplica o benefício. |
benefícioNro | alfanumérico | Identifica o benefício que aplica a promoção |
quantia | inteiro positivo | Indicará o valor associado a um cupom cujo valor foi calculado |
Enmascarar ID del cliente
Ao confirmar uma transação em que seja aplicado um benefício de emissão de cupom ou emissão de cupom calculado, os dados de @customerid e @customerin mascarados com asteriscos ( * ) devem ser informados de acordo com a configuração que foi aplicada.
<?xml version="1.0" encoding="UTF-8"?><message companyId="napse" date-time="2022-07-14 16:55:00" avalia="true" format="H" init-tck="false" map-version="160" status="finish" store="Store1"> <item-add seq="1" qty="1" code="111" magnitude="0" xprice="1000" unitprice="1000"/> <item-add seq="2" qty="2" code="211" magnitude="0" xprice="600" unitprice="300"/> <customer-add customerType="0" email="[email protected]" code="1" identifier="12345" identifierType="dni" name="john" seq="1" status="1" type= "2"/></mensagem>
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="7.2.3-SNAPSHOT#195" mapversion="160" messageId="0" store="Store1" terminal="0" transaction="napse_Store1__20220714165500"> <lealdade> <cartões de fidelidade/> <cupom> <cupom ack="0" amount="0.00" barcode="4550004836472" BenefitNro="62b44d46f36a17a8f47ca932" cupomId="cuimp7" encoding="EAN13" format="PRINTED" promotionName="Promoemitcup" promotionNro="62b44c70f36a17a 8f47ca92b">< ! [CDATA[@cuponid - *2.3.4.5 Cupom válido a partir de: 14/07/2022 00:00 Válido até: 14/08/2022 23:59 ]]></cupom> </cupom> <erro/> <clientes/> <redeemTable/> </lealdade> </mensagem>
Resposta - Elementos de Lealdade
Na resposta do motor, são adicionados à mensagem os dados dos elementos de fidelização que foram beneficiados em resultado da aplicação de benefícios.
Vale esclarecer que se trata do detalhamento de pontos, dinheiro, milhas, etc. premiado, ou seja, se como resultado da avaliação de uma promoção, X quantidade de pontos, dinheiro, milhas, etc. foram concedidos ou resgatados, então a resposta de fidelidade conterá o detalhe para esse elemento.
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <lealdade> <cartões de fidelidade>… detalhes do cartão de fidelidade … <cartões de fidelidade/> <cupom/> <erro/> <clientes/> </lealdade> </mensagem>
Como mencionamos, para cada um dos elementos de fidelização teremos um elemento, como no exemplo a seguir:
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <lealdade> <cartões de fidelidade> <loyaltycard ack="0" amount="10.0" id="3335999932200" seq="1" type="silver"/> <loyaltycard ack="0" amount="500.0" id="5550000000444" seq="2" type="gold"/> </cartões de fidelidade> <cupom/> <erro/> <clientes/> </lealdade> </mensagem
As propriedades de cada elemento de lealdade serão:
Propriedade | Tipo de dados | Descrição |
ir | alfanumérico | Número de identificação do elemento de fidelidade |
tipo | alfanumérico | Identificador de tipo de elemento de fidelidade. |
ack | todo | Código de retorno |
quantia | número positivo | Equilíbrio com o qual permaneceria o elemento fidelização |
tipo de carta | alfanumérico | Informa o tipo do elemento fidelidade (será informado apenas na tag <errors/> quando o ACK for 9501 – cartão inativo) |
Resposta - Ativação do elemento de fidelidade (em LoyaltyActivation)
Resposta OK ( ACK="0" nenhum dado é informado na etiqueta do cartão de fidelidade)
<?xml versão="1.0" codificação="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530124002"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes/> </lealdade> </mensagem
Resposta – Não OK (Ver capítulo 3.1.1 Valores do atributo "ack" )
<?xml versão="1.0" codificação="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530124222"> <lealdade> <cartões de fidelidade/> <cupom/> <erro> <error ack="9500" info="333000000000" seq="1" type="loyaltycard-activation"/> </error> <clientes/> </lealdade> </mensagem>
(Consulte também Solicitação do mecanismo - LoyaltyActivation )
Resposta - Ativação do elemento de fidelidade (em acabamento)
Resposta OK (ACK="0" e os dados do elemento de fidelidade que está sendo ativado são informados")
<?xml versão="1.0" codificação="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170530124539"> <lealdade> <cartões de fidelidade> <cartão de fidelidade ack="0" amount="0.0" id="3330000000002" seq="2" type="3"/> </cartões de fidelidade> <cupom/> <erro/> <clientes/> </lealdade> </mensagem>
Saída – Não OK (Ver capítulo 3.1.1 Valores do atributo "ack" )
<?xml versão="1.0" codificação="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170530124833"> <lealdade> <cartões de fidelidade/> <cupom/> <erro> <error ack="9500" info="33300000002" seq="2" type="loyaltycard-consume"/> </error> <clientes/> </lealdade> </mensagem>
(Consulte também Solicitação do mecanismo - FINALIZAR )
Resposta - Transferência de Fidelidade
Resposta OK
Na mensagem de resposta, cada uma das seqs informa o saldo final e a situação com que os elementos de fidelização ficarão após a transação de transferência.
<?xml versão="1.0" codificação="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530130305"> <lealdade> <cartões de fidelidade> <cartão de fidelidade ack="0" amount="296.0" id="2220000000000" seq="1" type="2"/> <cartão de fidelidade ack="0" amount="4.0" id="2220000000001" seq="2" type="2"/> </cartões de fidelidade> <cupom/> <erro/> <clientes/> </lealdade> </mensagem>
Resposta– Não OK (Ver capítulo 3.1.1 Valores do atributo "ack" )
<?xml versão="1.0" codificação="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530131342"> <lealdade> <cartões de fidelidade/> <cupom/> <erro> <error ack="9500" info="22200000001" seq="2" type="loyaltycard-transfer"/> </error> <clientes/> </lealdade> </mensagem>
(Consulte também Solicitação de mecanismo - LoyaltyTransfer )
Resposta - LoyaltyVoid
Resposta OK – Cupom e Itens de Fidelidade
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <lealdade> <erro/> </lealdade> </mensagem>
(Consulte também Solicitação do mecanismo – LoyaltyVoid )
Atribuição de saldos em elementos de fidelização
<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" avalia="false" status="concluir" msg-version="9" map-version="1"> <loyaltycard-add seq="2" type="2" id="2220000000001" chargeAmount="10" /> </mensagem>
<?xml versão="1.0" codificação="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530132245"> <lealdade> <cartões de fidelidade> <cartão de fidelidade ack="0" amount="10.0" id="2220000000001" seq="2" type="2"/> </cartões de fidelidade> <cupom/> <erro/> <clientes/> </lealdade> </mensagem>
Resposta– Não OK (Ver capítulo 3.1.1 Valores do atributo "ack" )
<?xml versão="1.0" codificação="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530132536"> <lealdade> <cartões de fidelidade/> <cupom/> <erro> <error ack="9500" info="22200000001" seq="2" type="loyaltycard-recharge"/> </error> <clientes/> </lealdade> </mensagem>
Desconto de saldo no elemento de fidelidade
<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" avalia="false" status="concluir" msg-version="2.0" map-version="1"> <loyaltycard-add seq="2" type="gold" id="2220000000002" consumaAmount="6" /> </mensagem>
<?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"> <lealdade> <cartões de fidelidade> <loyaltycard ack="0" amount="18.0" id="2220000000002" seq="2" type="gold"/> </cartões de fidelidade> <cupom/> <erro/> </lealdade> </mensagem>
Resposta – Não OK (Ver capítulo 3.1.1 Valores do 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"> <lealdade> <cartões de fidelidade/> <cupom/> <erro> <error ack="9500" info="4445000002200" seq="2" type="loyaltycard-recharge"/> </error> </lealdade> </mensagem>
Elementos de fidelidade: processo de atualização de saldo
Ao status "loyaltyActivation" foi adicionado um valor para a propriedade status do elemento loyaltcard, um valor CONFIRM para indicar que você deseja confirmar os pontos usados em uma transação anterior referenciada no atributo: "confirmationReference".
Faça uma compra com vencimento em 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" avalia="true" offline="false"> <loyaltycard-add seq="1" id="10012" type="t1" amount="1000" consumaAmount="10" confirmDate="201811141400" /> <item-add seq="2" code="2" unitprice="20" xprice="10000" qty="500" discountable="true" tax="2100" /> <item-add seq="3" code="3" unitprice="10" xprice="10000" qty="1000" discountable="true" tax="2100" /> </mensagem>
Responder:
<message ack="0" companyId="test" engine="6.1.4" mapversion="0" messageId="1" store="1" terminal="10" transaction="test_1_10_20181116163505"> <lealdade> <cartões de fidelidade> <loyaltycard ack="0" amount="35.0" id="10012" seq="1" type="t1"/> </cartões de fidelidade> <cupom/> <erro/> <clientes/> </lealdade> </mensagem>
Confirmamos a transação com o 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" avalia="true" offline="false"></mensagem>
Responder:
<?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"/>
A tela a seguir mostra o consumo de pontos no cartão:
Como próximo passo do exemplo, deixamos passar o dia 14-11 para observar a reversão do consumo já que não foi confirmado antes dessa data:
Agora vamos fazer outro mas confirmando o consumo:
Primeiro como fizemos antes, geramos um consumo com maturidade 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" avalia="true" offline="false"><loyaltycard-add seq="1" id="10012" type="t1" amount="1000" consumaAmount=" 10" confirmDate="201811181400" /> <item-add seq="2" code="2" unitprice="20" xprice="10000" qty="500" discountable="true" tax="2100" /> <item-add seq="3" code="3" unitprice="10" xprice="10000" qty="1000" discountable="true" tax="2100" /> </mensagem>
Responder
<?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"> <lealdade> <cartões de fidelidade> <loyaltycard ack="0" amount="35.0" id="10012" seq="1" type="t1"/> </cartões de fidelidade> <cupom/> <erro/> <clientes/> </lealdade> </mensagem>
Confirmamos a transação:
<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" avalia="true" offline="false"><loyaltycard-add seq="1" id="10012" type="t1" quantidade="1000" consumirAmount=" 10" confirmDate="201811181400" /> <item-add seq="2" code="2" unitprice="20" xprice="10000" qty="500" discountable="true" tax="2100" /> <item-add seq="3" code="3" unitprice="10" xprice="10000" qty="1000" discountable="true" tax="2100" /> </mensagem>
Responder
<?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"/>
No detalhe da movimentação do elemento fidelidade observa-se o consumo e que o identificador da transação foi “test_1_10_20181116165337 ”:
Agora enviamos a confirmação
<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" avalia="false" offline="false"> <loyaltycard-add seq="1" id="10012" type="t1" status="CONFIRM" confirmReference="test_1_10_20181116165337" /> </mensagem>
Responder
<?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"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes/> </lealdade> </mensagem>
Através desta operação então o consumo foi confirmado e após 11-18 não será revertido.
Resposta do mecanismo: erros de tag
Além de cupons e elementos de fidelidade, um bloco de relatório de bug pode ser adicionado ao elemento de fidelidade de resposta. Nele serão reportados erros no processamento de determinados cupões e/ou elementos de fidelização, tanto na sua emissão como no seu resgate.
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <lealdade> <cartões de fidelidade/> <erro> <error ack="9505" id="4445901938700" info="4445901938700" amount= "" seq="1" type="loyaltycard-activation"/> </error> </lealdade> </mensagem>
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <lealdade> <cupom/> <cartões de fidelidade/> <erro> <error ack="9501" id="5550010012948" info="5550010012948" amount= "100" seq="1" type="loyaltycard-validation"/> </error> </lealdade> </mensagem>
As propriedades dos elementos informados no Tag <Errors/> são:
Propriedade | Tipo de dados | Descrição |
tipo | alfanumérico | Informa o tipo de transação associada. Os valores atuais são: "cupom-create", "cupom-redeem", "loyalty-redeem", "loyalty-sale", "loyalty-activation" |
ack | alfanumérico | O valor do código de erro conforme descrito nos valores de propriedade ACK anteriormente neste documento. Consulte o capítulo 3.1.1 Valores do atributo "ACK" |
eu ia | alfanumérico | No caso de Cupons e Elementos de Fidelidade, o id/código de barras dos mesmos é informado aqui |
informação | alfanumérico | Informações adicionais que dependem do valor do campo "tipo". Por exemplo, pode ser o valor do tipo de cupom a ser gerado, o valor do código de barras informado para seu resgate, etc. |
descrição | alfanumérico | É um atributo extra para dar uma melhor leitura do erro ocorrido. No caso dos elementos de fidelização é possível identificar o nome das promoções + o número do benefício onde ocorreu o erro |
quantia | Numérico | Opcional – Este atributo só será exibido quando um erro estiver sendo reportado para a consulta de validação (loyaltyValidation) |
eu sei que | inteiro positivo | Número que identifica o elemento dentro da transação à qual o benefício é aplicado. |
Lealdade: status estendidos
Para atender necessidades especiais, como comércio eletrônico, versões estendidas foram adicionadas a alguns dos valores de status já conhecidos.
VALIDAÇÃO DE LEALDADE EX
Este valor de status unifica em uma mesma mensagem o que já é conhecido no FidelityValidation mais uma avaliação de Promoções ( vendas ). Se a validação retornar erros, as promoções não serão avaliadas e a resposta será a resposta tradicional de lealdadeValidação. Se não houver erros, a resposta incluirá os resultados da validação mais a resposta da avaliação das promoções.
Caso: A seguinte mensagem é enviada para validar e avaliar
<message companyId="test" store="test" terminal="001" date-time="2020-12-28 11:25" messageId="0011" void-trx="false" response="true" init- tck="true" avalia="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" /> </mensagem>
Resposta 1: Tudo acontece corretamente
<message ack="0" companyId="test" engine="2.6" mapversion="2" messageId="0014" store="test" terminal="001" transaction="test_test_001_20201228112802"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes/> <redeemTable/> </lealdade> <opcional> <promo code="TEST" id="TEST" nro="5fe9e7d1abe76823b4bd151d"> <benefit TLOGMessage="TEST" account="" applicationMethod="resume" baseAmount="5000.00" name="5fe9e7d1abe76823b4bd151d" nro="5fe9e84fabe76823b4bd1529" order="1" printerMessage="TEST" prorationMethod="PROPORCIONAL" unit="qty"> <aplicar> <item magnitude="0.000" qty="1.000" seq="1" value="500.00" valueWithTaxes="500.00" xprice="5000.00"/> </aplicar> </benefício> </promo> </opcional> </mensagem>
Resposta 2: Existem erros na validação
message ack="8296" companyId="test" engine="2.6" mapversion="2" messageId="0011" store="test" terminal="001" transaction="test_test_001_20201228112501"> <lealdade> <cartões de fidelidade/> <cupom/> <erro> <error ack="9101" id="1010BCup10000x" info="1010BCup10000x" seq="1" type="coupon-redeem"/> </error> <clientes> <customer code="123456" email="[email protected]" identifier="1" lastName="perez" limitedBenefits="" name="jorge" segment="" seq="1" type=" teste"/> </clientes> <redeemTable/> </lealdade> </mensagem>
Inyeccion automaticamente Segmentos en Clientes (loyaltyValidationex)
(desde v6.5.25)
Inclui-se a funcionalidade de adicionar automaticamente, na validação do cliente, os segmentos a que pertence, utilizando a funcionalidade de lealdadeValidationex.
IMPORTANTE
Os segmentos podem ser registrados a partir do console ( Business/Segments ) ou via serviço REST. Para obter mais informações sobre como associar clientes a Segmentos Promo via REST, consulte " Serviço de importação de segmentos " no Manual de Integração Promo-Serviços .
Quando uma consulta do tipo FidelityValidationex for recebida em Promo e um cliente for informado, os segmentos aos quais este cliente pertence serão incluídos na mensagem de resposta junto com o resultado da avaliação de promoções com o mapa atual.
FINISHEX
Consiste em uma mensagem que unifica ou executa o que é conhecido em Finish e, dependendo de sua avaliação, um commit automático (resposta de finalização bem-sucedida) ou rollback (finalização relata um erro).
Caso: A seguinte mensagem é enviada para encerrar a transação
<message companyId="test" store="test" terminal="001" date-time="2020-12-28 11:25" messageId="0011" void-trx="false" response="true" init- tck="true" avalia="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" /> </mensagem>
Resposta 1: Tudo acontece corretamente (Finish+commit com sucesso)
<message ack="0" companyId="test" engine="2.6" mapversion="2" messageId="0014" store="test" terminal="001" transaction="test_test_001_20201228112802"> <lealdade><cartões de fidelidade/> <cupom/> <erro/> <clientes/> <redeemTable/> </lealdade> </mensagem>
Resposta 2: Existem erros na validação (Finish+rollback foram executados)
<message ack="8296" companyId="test" engine="2.6" mapversion="2" messageId="0011" store="test" terminal="001" transaction="test_test_001_20201228112501"> <lealdade> <cartões de fidelidade/> <cupom/> <erro> <error ack="9101" id="1010BCup10000x" info="1010BCup10000x" seq="1" type="coupon-redeem"/> </error> <clientes> <customer code="123456" email="[email protected]" identifier="1" lastName="perez" limitedBenefits="" name="jorge" segment="" seq="1" type=" teste"/> </clientes> <redeemTable/> </lealdade> </mensagem>
Ferramenta de métricas de fidelidade
(Do Promo 7.2) Para medir os tempos de processamento dos elementos de fidelidade, foram incorporadas métricas no log do aplicativo.
A atualização é implementada no log a nível INFO, tanto na consola como no lado do motor, das seguintes operações:
- Validação de Lealdade
- Ativação de Fidelidade
- Transferência de Fidelidade
- LealdadeVazio
- LoyaltyAssign
- TERMINAR
- COMPROMETER-SE
- REVERSÃO
- Solicitação de transação
- RetornoFinalizar
- Validação de Resgate de Catálogo
VALIDAÇÃO DE LEALDADE EX
- FINISHEX
- preços
- voidTotal
- lista negra
Para habilitar as alterações realizadas, foram adicionadas as seguintes propriedades aos arquivos correspondentes ao registro, tanto no lado do console quanto no lado do motor:
Habilite o log do console, vá para: ..\synthesis\promo\appserver\modules\system\layers\base\com\synthesis\configuration\main \ log4j.xml
Valor padrão ERROR , passe para INFO para habilitar a funcionalidade.
log4j.xml (console)
Ative o registro do mecanismo, vá para: ...\synthesis\promo\engine\conf \ logging.properties
O padrão é SEVERE , passe para INFO para habilitar a funcionalidade.
logging.properties (mecanismo)
Além disso, assim que o valor da propriedade engine.operation.level for atualizado , o nível de log das seguintes propriedades será alterado de SEVERE para INFO:
- java.util.logging.FileHandler.level = INFORMAÇÕES
- java.util.logging.ConsoleHandler.level = INFORMAÇÕES
Resultado da alteração:
server.log
server.log 15,52,20,949 INFO [sts.console.api.ApiService@http-nio-8080-exec-2] -->loyaltyTransfer 15,52,20,974 INFO [sts.console.api.ApiService@http-nio-8080-exec-2] <--loyaltyTransfer 0,025 segundos 15,52,23,334 INFO [sts.console.api.ApiService@Actor Thread 5] ApiService.status.mapActives Iniciando processamento em sex jul 23 15:52:23 ART 2021 15,52,23,335 INFO [sts.console.api.ApiService@Actor Thread 3] ApiService.status.mapActives processados Terminar em sex 23 de julho 15:52:23 ART 2021 15,52,23,357 INFO [sts.console.api.ApiService@http-nio-8080-exec-8] -->processEngineRequest: verificando no tipo de console:DYNAMIC_ATTRIBUTES ... 15,52,23,380 INFO [sts.console.api.ApiService@http-nio-8080-exec-1] -->processEngineRequest: verificando se o console tem alguma pendência a ser processada no mecanismo... 15,52,29,749 INFO [sts.console.api.ApiService@http-nio-8080-exec-2] -->commit 15,52,29,752 INFO [sts.console.api.ApiService@http-nio-8080-exec-2] <--commit 0,003 segundos |
gerador.log
INFO: -->OperationFinish:remoteEvaluation 23 de julho de 2021 15h54min52s engine.operation.Operation loggerTimeStop INFO: <--OperationFinish:remoteEvaluation 0.913 segundos -><?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="7.1.4-SNAPSHOT" mapversion="44" messageId="1" store="napse" terminal="1" transaction="napse_napse_1_20210723100025"> <lealdade> <cartões de fidelidade> <cartão de fidelidade ack="0" amount="1800.00" id="550003" seq="1" type="tdf_001"/> </cartões de fidelidade> <cupom/> <erro/> <clientes/> <redeemTable/> </lealdade> </mensagem> 23 de julho de 2021 15h55min04s engine.operation.Operation loggerTimeStart INFO: -->OperationCommit:remoteEvaluation 23 de julho de 2021 15h55min04s engine.operation.Operation loggerTimeStop INFO: <--OperationCommit:remoteEvaluation 0,053 segundos 23 de julho de 2021 16h13min57s engine.operation.Operation loggerTimeStart INFO: -->OperationLoyaltyValidation:remoteEvaluation 23 de julho de 2021 16:13:57 mecanismo.operação.OperaçãoValidação de validação de lealdade INFORMAÇÃO: É validado que o corpo da mensagem não está vazio em LoyaltyValidation 23 de julho de 2021 16h13min57s engine.operation.Operation loggerTimeStop INFO: <--OperationLoyaltyValidation:remoteEvaluation 0,373 segundos
Fluxos de itens de fidelidade
Nesta secção serão expostos os fluxos desenvolvidos para elementos de fidelização, onde será possível observar as diferentes mensagens que podem ser trocadas entre o POS, o motor e a consola PROMO.
Registro de elemento de fidelidade
O registo de um elemento será feito na consola PROMO Central
Nota: O campo CVV tem um comprimento máximo de 5 posições .
Consulta de Elemento de Lealdade
Ativação do elemento (loyaltyActivation)
Ativação do elemento (FINISH)
transferência entre elementos
Alocação ou desconto de saldo fora de uma transação
Destinação ou desconto de saldo decorrente da aplicação de benefício.
Resposta do mecanismo: ReturnFinish
A avaliação do retorno é feita usando o motor de simulação no console. Este é um processo em Background, onde o PDV envia a transação para a PROMO com STATUS="returnfinish" informando o número da transação original e os itens devolvidos.
Online, apenas será validado que o número da transação original existe no banco de dados do cliente e que a mensagem está corretamente formada.
No processo de segundo plano, o PROMO recuperará a transação original, removerá os itens devolvidos do contexto e reavaliará as promoções com o novo contexto da transação com o número do mapa com o qual a venda foi avaliada, os benefícios NÃO relatados nesta avaliação (comparado com os benefícios informados na venda), serão os benefícios a serem cancelados da transação original.
No caso de transação de troca, o item devolvido será tratado como devolução, realizando-se as etapas e avaliações descritas acima. Os elementos que forem reportados ao motor serão da responsabilidade do pos.
<?xml version="1.0" encoding="UTF-8"?><message ack="0" engine="2.6" mapversion="2" messageId="1" companyId="sts" store="1" terminal ="1" transação="1_1_20170829162054"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes/> </lealdade> </mensagem>
Resposta – ERRO (Consulte o capítulo 3.1.1 Valores do 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" transação="1_1_20170829162239"/>
Clientes
Os dados correspondentes ao cliente consultado e os elementos de fidelização associados são adicionados à mensagem de resposta a "LoyaltyValidation". Vale esclarecer que caso o cliente possua um elemento de fidelidade inativo, esses elementos não retornarão na resposta de validação de fidelidade do cliente. Apenas os elementos de fidelidade ativos associados a eles serão relatados.
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes> <customer code="6666" email="[email protected]" identifier="3055881" lastName="" name="Rojo Marcos" seq="1"> <cartão de fidelidade ack="0" amount="100.0" id="3330000000001" type="1"/> <cupom ack="0" amount="0.0" barcode="1000010012948" cupomId="1" seq="1"/> </cliente> </clientes> </lealdade> </mensagem>
(Consulte também Solicitação de mecanismo - LoyaltyValidation )
Operação com Segmentos
Imaginemos que temos uma Promoção que beneficia os clientes do segmento "ABC1". A Operação para trabalhar com a referida Promoção seria:
- Realizamos uma operação LoyaltyValidation (Ver Engine Request - LoyaltyValidation ) para saber a que segmentos pertence o 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" avalia="true" " status="loyaltyValidation" map-version="15" sugerir="true" sugerir-seq="3"> <customer-add seq="1" id="9991"/> </mensagem>
2. Em resposta ao pedido anterior, a Promo irá informar-nos os segmentos a que aquele cliente pertence como uma das propriedades: Como podemos ver no exemplo, o cliente pertence aos segmentos ABC1, D18 e K1
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes> <customer code="9991" email="[email protected]" identifier="3055881" lastName="" name="Rojo Marcos" seq="1" segment="ABC1,D18,K1"> <cartão de fidelidade ack="0" amount="100.0" id="3330000000001" type="1"/> <cupom ack="0" amount="0.0" barcode="1000010012948" cupomId="1" seq="1"/> </cliente> </clientes> </lealdade> </mensagem>
3. Finalmente realizamos a transação de venda com o cliente enviando seus dados completos:
<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" avalia="true" status="Concluir" map-version="15" sugerir="true" sugerir-seq="3"> <customer-add seq="1" id="9991" segment="ABC1,D18,K1" /> </mensagem>
Desta forma será avaliada a transação e sendo cliente pertencente ao segmento ABC1, a Promoção será concedida.
Criar Clientes (Nota: Somente se a operação sem clientes pré-existentes estiver habilitada)
Há casos em que é necessário criar clientes no momento, por exemplo, para poder enviar cupons eletrônicos por e-mail. Para isso, foi incorporada a possibilidade de enviar a definição do cliente (dados mínimos necessários) desde o serviço de mensageria Promo.
Os clientes serão criados usando o status "loyaltyValidation" se os dados mínimos forem enviados e ao mesmo tempo o Promo detectar que o cliente não existe. Os dados mínimos citados, por exemplo, seriam aqueles marcados em negrito no exemplo a seguir:
<customer-add seq=
"1"
id=
"10090504"
identifier=
"10090504"
type=
"test"
name=
"pepe"
lastName=
"rodrigues"
identifierType=
"cpf"
email=
"mimail@test.com"
/>
Importante
Para que os clientes sejam cadastrados no momento do processamento de uma transação, o seguinte atributo deve estar habilitado no arquivo de configuração do Promo Console (“promoplus.properties”) :
# Ativar o registro do cliente imediatamente
promo.allowNonExistingCustomers = true
Depois de atualizado, o Wildfly deve ser reiniciado para que as alterações sejam feitas corretamente.
Agora vamos ver um exemplo de troca dessas mensagens:
Fazemos um pedido com o FidelityValidation e o cliente não 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" avalia="true" offline="false" > <customer-add seq="1" id="10090504" type="test" limitedBenefits="5b7044246491fa1604a6d15b:200.00;" /> </mensagem>
A resposta fornece valores padrão:
Response<message ack="0" companyId="napse" engine="6.4.6" mapversion="1" messageId="1" store="1" terminal="10" transaction="napse_1_10_20180809105150"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes> <customer code="10090504" email="-" identifier="-" lastName="-" limitedBenefits="" name="-" segment="" seq="1"/> </clientes> </lealdade> </mensagem>
Neste caso enviamos os dados do cliente mas não preenchemos todos os campos necessários:
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" avalia="true" offline="false" > <customer-add seq="1" id="10090504" identifier="10090504" type="test" limitedBenefits="5b7044246491fa1604a6d15b:200.00;" name="pepe" lastName="rodrigues" identifierType="cpf" /> </mensagem>
A resposta ainda contém dados padrão:
Response<message ack="0" companyId="napse" engine="6.4.6" mapversion="1" messageId="1" store="1" terminal="10" transaction="napse_1_10_20180809105150"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes> <customer code="10090504" email="-" identifier="10090504" lastName="rodrigues" limitedBenefits="" name="pepe" segment="" seq="1"/> </clientes> </loyalty></mensagem>
Agora enviamos TODOS os dados obrigatórios para o cliente a ser criado
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" avalia="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]" /> </mensagem>
A resposta é:
Code<?xml versão="1.0" codificação="UTF-8"?> <message ack="0" companyId="napse" engine="6.4.6" mapversion="1" messageId="1" store="1" terminal="10" transaction="napse_1_10_20180809105150"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes> <customer code="10090504" email="[email protected]" identifier="10090504" lastName="rodrigues" limitedBenefits="" name="pepe" segment="" seq="1"/> </clientes> </lealdade> </mensagem>
Agora vamos enviar a mensagem que enviamos no ponto 1, que possui apenas os dados básicos do cliente e para a qual no ponto 1 retornou valores padrão (o cliente não era conhecido) enquanto agora teria que retornar todos eles. os dados que já conhecemos e criamos no ponto 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" avalia="true" offline="false" > <customer-add seq="1" id="10090504" type="test" limitedBenefits="" /> </mensagem>
A resposta é na verdade:
Code<?xml versão="1.0" codificação="UTF-8"?> <message ack="0" companyId="napse" engine="6.4.6" mapversion="1" messageId="1" store="1" terminal="10" transaction="napse_1_10_20180809105150"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes> <customer code="10090504" email="[email protected]" identifier="10090504" lastName="rodrigues" limitedBenefits="" name="pepe" segment="" seq="1"/> </clientes> </lealdade> </mensagem>
Operação (com base em cenários possíveis):
Operativo | Cartão Presente | Bolsa | cartão de pontos | Presente - Uso Único |
Cadastro de cartão | Por arquivoINACTIVE | Por Arquivo/ManualInativo ou Ativo | Por arquivoINACTIVE | Por arquivoINACTIVE |
Consulta de Cartão | O Valor - Tipo será informado na tag Erros (por estar inativo) | Será informado na tag Erros se estiver inativo ou na tag Cartão Fidelidade se estiver ativo Tipo - Valor | Será informado na tag Erros (porque está inativo) Valor –Tipo-Cliente | Será informado na tag Erros (por estar inativo) Valor - Tipo |
Ativação do cartão | Deve ser ativado através da mensagem "Loyaltyactivation" ou "Finish" Validar CVV | Pode ser ativado pela mensagem "Ativação do Loyalty", "Finish" ou quando for feita a sua primeira recarga | Pode ser ativado pela mensagem "Ativação do Fidelidade", "concluir" ou quando for feita a primeira recarga. Caso seja enviado, o Cliente o validará | Pode ser acionado pela mensagem "Ativação do Loyalty", "concluir" ou quando for feita sua primeira recarga. CVV válido |
Transferir | Admite apenas transferências de saldo total - Uma vez transferido o saldo total do cartão, este é cancelado. CVV válido | Suporta transferências parciais sem alterar o estado do item. | Não admite transferência de qualquer tipo. | Não admite transferência de qualquer tipo. |
Alocação de Saldo | Não admite recarga de saldo. | Admite recargas até um valor máximo. | Suporta recargas ilimitadas. Se o cliente for enviado, ele será validado. | Suporta recargas ilimitadas. CVV válido. |
Saldo Consumo | Permite consumir o saldo em mais de uma transação sem alterar o estado do cartão. CVV válido | Permite consumir o saldo em mais de uma transação sem alterar o estado do cartão | Permite consumir o saldo em mais de uma transação sem alterar o estado do cartão Se o cliente for enviado, será validado | Permite apenas um único consumo de saldo, total ou parcial, após esse único consumo o elemento fidelização fica INATIVO. CVV válido |
Saldos por acordos
Quando o benefício tiver limites de saldos por convênios e por clientes, o funcionamento do motor deverá ser o seguinte:
Para poder operar com limites de saldo por convênios, a primeira mensagem enviada desde o PDV deve ser um status de validação de fidelidade com o elemento cliente, para poder carregar os limites do cliente antes de realizar a transação.
Caso haja limites aos benefícios do convênio; estes virão no atributo limitedBenefits, Os limites de clientes não conveniados, o console informa apenas o motor.
Importante: Para carregar o limite de clientes na engine, deve ser feito um FidelityValidation com init-tck="true" com o elemento customer , deve ser a primeira mensagem a operar.
Ejemplo para los mensajes de Limites
Aqui está como 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" avalia="false" sugere="true"> <customer-add seq="1" id="2" type="test" /> <item-add seq="2" qty="1" code="1" magnitude="0" xprice="200" unitprice="200"/> </mensagem>
<?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"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes> <customer code="2" email="[email protected]" identifier="25456742" lastName="Perez" limitedBenefits="5c73fa11a8b0ea2f888130c0:300.00;" nome="João" seq="1"> <loyaltycard ack="0" amount="2088.00" id="1110000000" status="Active" type="test"/> <limit amount="300.00" id="5c73fa11a8b0ea2f888130c0" promotionDescription="promoLimite" promotionName="promoLimite"/> </cliente> </clientes> </lealdade> </mensagem>
Na resposta podemos ver a informação do cliente com os Benefícios limitados que indica o limite por cliente do benefício do convênio. Ou seja, nesta promoção podemos utilizar 3 vezes por cliente, desde que o benefício seja no valor de 100 por benefício e o limite monetário é 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="vendas" avalia="true" sugere="true"> <customer-add seq="1" id="2" type="test" /> <item-add seq="2" qty="1" code="1" magnitude="0" xprice="200" unitprice="200"/> </mensagem>
Limites de cliente sem acordo, o console reporta apenas ao mecanismo.
<?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"> <opcional> <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="5c73fa1 1a8b0ea2f888130c0 " order="1" printerMessage="promoLimite" prorationMethod="PROPORCIONAL" unit="qty"> <aplicar> <item magnitude="0.000" qty="1.000" seq="2" value="100.00" valueWithTaxes="100.00" xprice="200.00"/> </aplicar> </benefício> </promo> </opcional> </mensagem>
Então nós fazemos o acabamento do status
<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="concluir" avalia="true" sugere="true"> <customer-add seq="1" id="2" type="test" /> <item-add seq="2" qty="1" code="1" magnitude="0" xprice="200" unitprice="200"/> </mensagem>
<?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"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes/> </lealdade> </mensagem>
Finalmente o 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" avalia="true" sugere="true"> <customer-add seq="1" id="2" type="test" /> <item-add seq="2" qty="1" code="1" magnitude="0" xprice="200" unitprice="200"/> </mensagem>
<?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"/>
Fazendo novamente o FidelityValidation veremos que consumimos 100 do limite, pois a promoção concedeu um benefício de 100 para cada transação.
<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" avalia="false" sugere="true"> <customer-add seq="1" id="2" type="test" /> </mensagem>
<?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"> <lealdade> <cartões de fidelidade/> <cupom/> <erro/> <clientes> <customer code="2" email="[email protected]" identifier="25456742" lastName="Perez" limitedBenefits="5c73fa11a8b0ea2f888130c0:200.00;" nome="João" seq="1"> <loyaltycard ack="0" amount="2088.00" id="1110000000" status="Active" type="test"/> <limit amount="200.00" id="5c73fa11a8b0ea2f888130c0" promotionDescription="promoLimite" promotionName="promoLimite"/> </cliente> </clientes> </lealdade> </mensagem>
Se você fizer mais 2 transações, a promoção não será mais válida por ter excedido o limite.
Gestão de Limites a partir da versão 7.0
O controle de limites através da lista negra gerada no console implica que a referida lista negra seja atualizada a partir da transação finalizada, portanto, no motor, o limite pode ser excedido durante a transação. Para evitar isso e para que o limite seja avaliado durante a transação, foram necessárias alterações no console e na engine.
Por um lado, o console continua calculando e armazenando os valores máximos e atuais dos limites de lucro ao processar o commit de uma transação, mas em vez de enviar ao mecanismo apenas a lista dos limites que foram atingidos ou excedidos (lista negra) , envia O estado destes limites também é enviado ao motor (esse estado é armazenado na tabela limitStatus). Na verdade, é o motor no início de um ticket que solicita várias informações do console -através de uma solicitação http-, incluindo limites, agora a informação sobre o status dos limites é adicionada para os benefícios e o cliente (se for um ticket que envolve cliente) do mapa a ser processado.
Por outro lado, o motor, ao receber os registros de limitStatus além da lista negra, os armazena em um cache para ser consultado durante a evolução do ticket, caso o valor atual seja igual ou superior ao valor máximo definido para o benefício, o limite é marcado como alcançado para otimizar os tempos e não reavaliá-lo.
Durante as diferentes operações no desenvolvimento do ticket, o motor avalia antes de entrar no cálculo de um benefício se o limite já foi atingido (ou seja, se está na lista negra), se sim, não procede ao cálculo do benefício. Caso não esteja na lista negra, o benefício é calculado e o limitStatus é consultado se o valor a ser concedido está dentro do limite e procede-se a aplicá-lo, caso contrário o benefício não é concedido.
CONSOLE
1-OBTER O ESTADO DE LIMITES
Conforme mencionado anteriormente, o console envia as informações do limite de benefício para a engine através dos registros da tabela limitStatus. No entanto, devido a detalhes de implementação, este registro em limitStatus só existe no caso de um benefício que possui limites ter sido operado em uma transação, portanto no momento de iniciar um ticket é possível que o referido registro não exista, caso em que é gerada a informação equivalente ao limitStatus a partir dos limites definidos para os benefícios das promoções contidos no mapa pelo qual o ticket é avaliado.
A geração e envio da lista negra continua em vigor,
O processamento da requisição da engine continua no console, sendo realizado no apiService, no método blacklist(), em cuja resposta é adicionado o limitStatus para quando a requisição vem de uma engine 7.0 ou superior. A console recebe através da API , no método "blacklist", uma requisição da engine com um json que indica a loja, cliente, mapa, entre outros valores.
MOTOR
1-TRATAMENTO DOS REGISTROS DE ESTADO LIMITE RECEBIDOS DO CONSOLE
Os registros de limite que foram atingidos continuam sendo recebidos como nas versões anteriores na resposta do console json como blackList, e são salvos em um cache: CacheDataManager.limits. Na resposta do console, existe outra lista "whiteList" que corresponde aos limites que foram editados e elevados ao seu valor máximo e, portanto, devem ser removidos da lista negra. No caso de receber um elemento na whiteList, o mecanismo simplesmente remove o elemento da blackList
Uma vez recebidos pelo motor, os registros de limitStatus, cujos conteúdos são os identificadores de limite, benefício, promoção, valor máximo, valor atual, tipo de limite e escopo, são armazenados no cache de limitStatus, tendo como chave o BenefitId. Na verdade, sob a chave BenefitId, é armazenado um mapa do correspondente limitStatus, sendo limitId a chave desse mapa, pois podem existir vários limites (por valor, por número de aplicações, por número de itens, etc.) beneficiar.
2-AVALIAÇÃO DOS LIMITES ANTES DE APLICAR O BENEFÍCIO
Como era feito na versão anterior do Promo, antes de inserir o cálculo do lucro, é consultado se o limite já foi atingido na lista negra.
3-AVALIAÇÃO DOS LIMITES COM O VALOR A SER APLICADO AO LUCRO
Tendo em vista que, dependendo do benefício, o valor a ser concedido pode ser de tipo diferente (pontos, valor da aplicação, valor, etc.), não poderia ser localizado em um ponto comum para todos os benefícios, a avaliação se a aplicação de um benefício está dentro de um limite. Portanto, uma nova avaliação de limite teve que ser adicionada para avaliar se o valor atual do limite, somado ao valor do benefício a ser concedido, está dentro do valor máximo do limite ou o excede, para fins de aplicação do benefício ou não.
Para os limites que são de número de aplicações, número de cupons entregues ou número de brindes entregues, a avaliação deste tipo de limites é realizada no final do processo de benefício, pois se aplicam a todo o benefício.
Para cada item do ticket passível de ser beneficiado, é feito um cálculo parcial passando pelos limites do benefício, sendo avaliados apenas aqueles que não são do tipo contagem (por exemplo, número de aplicações, etc.), e colocando uma marca no benefício que há limites desse tipo.
Então, ao final do processo de benefício, são avaliados apenas os limites do tipo contagem, que caso o saldo não seja suficiente, acaba descartando a aplicação do benefício.
Quanto à avaliação se o limite é suficiente para a concessão do benefício, existe a possibilidade de configurar que caso o saldo de um limite não cubra a totalidade do benefício, a referida concessão seja cancelada, ou seja concedido o saldo disponível. Ver ponto 5-CONFIGURAÇÃO DO COMPORTAMENTO
4-INFORMAR SALDO DE LIMITES AO POS
Quando forem aplicados limites, é importante informar ao sistema que a Promo utiliza , por exemplo um Ponto de Venda (PDV), os saldos dos limites, para que o PDV possa tomar alguma providência com base no referido saldo.
Como esta nova informação pode não ser necessária em todos os sistemas que utilizam Promo, optou-se por adicionar um atributo 'limitBalances' do tipo boolean no cabeçalho da mensagem do PDV ao motor, indicando quando ele entra em 'true' que é gerado e retornou na resposta os saldos limite.
Exemplo de mensagem do PDV para o motor com o atributo limitBalances="true" no tag de mensagem indicando que o saldo limite é informado:
Solicitação ao motor indicando que o saldo limite é necessário
<message companyId="napse" store="napse" terminal="1" date-time="2020-04-17 15:57:20" init-tck="false" messageId="4524" void-trx=" false" response="true" status="commit" map-version="65" avalia="true" tckpath="Y" sugere="true" limitBalances="true"> <item-add seq="1" código="315" qty="3" magnitude="0" marca="1" preço unitário="100" xpreço="300" fornecedor="1" descontoble="true"/ > <loyaltycard-add seq="1" id="880000000012" peso="5" type="tarfd" /> <customer-add seq="1" id="2222" type="na" age="41" sex="feminino" /> </mensagem> |
No método BenefitBase.process() foi adicionada uma chamada a CacheDataManager.prepareInfoLimitsByBenefit() onde os saldos dos limites de benefícios são coletados e armazenados em um mapa no Ticket.
Então, ao final da avaliação do ticket, ao construir a resposta para o PDV em EngineResponse.toXml(), createLimitsResponse() é chamado para gerar a lista de saldos limite e inseri-la na resposta.
Exemplo de resposta do motor com equilíbrio de limites:
Resposta do motor com equilíbrio de limites
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT" mapversion="65" messageId="4524" store="napse" terminal="1"> <opcional> <promo code="march27c" id="march27c" nro="5e7e04b78fc4c24a14491daa"> <benefit TLOGMessage="March27c" account=""applicationMethod="resume" baseAmount="300.00" 05588fc4c24a14491db1 " order="1" printerMessage="mar27c" prorationMethod="PROPORCIONAL" unit="qty"> <aplicar> <item magnitude="0.000" qty="3.000" seq="1" value="45.00" valueWithTaxes="45.00" xprice="300.00"/> </aplicar> </benefício> </promo> </opcional> <limitBalances> <limit amount="22.00" id="5e7e0e878fc4c2219049697e" max="25000.00" promotionName="march27c"/> <limit amount="4369.00" id="5e7e0f9b8fc4c22190496980" max="12000.00" promotionName="march27c"/> <limit amount="1681.00" id="5e8251f2b85cf77dbc714f32" max="50000.00" promotionName="march27c"/> </limitBalances> </mensagem> |
5-CONFIGURAÇÃO DO COMPORTAMENTO
O processo de novos limites, no comportamento padrão, deixa de conceder um benefício caso o saldo não seja suficiente. Esse comportamento pode ser modificado para que entregue o benefício com o saldo disponível mesmo que não cubra a totalidade do benefício.
Configuração do mecanismo para benefícios de saldo de limite: config.xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <configuração> <geral> ... <!--Concessão de benefício com limites: true concede o saldo (padrão), false não concede benefício se a aplicação exceder o saldo --> <useExactLimitValue>true</useExactLimitValue> </geral> ... </configuração> |
Tanto no caso de nenhum benefício ser entregue se o saldo não for suficiente, quanto quando o saldo disponível for entregue menor do que deveria ser concedido, é informado no atributo "limitApplied" da etiqueta de benefício da resposta ao PDV, com valor "true". ", se não houver limites aplicados, o atributo não estará presente.
Exemplo de resposta em que foi retornado como benefício apenas o saldo disponível, informando o atributo limitApplied na tag do benefício, e o saldo informado como zero, pois o que estava disponível foi utilizado para conceder o benefício: Resposta do motor com saldo
limite
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT" mapversion="65" messageId="4524" store="napse" terminal="1"> <opcional> <promo code="march27c" id="march27c" nro="5e7e04b78fc4c24a14491daa"> <benefit TLOGMessage="March27c" account=""applicationMethod="resume" baseAmount="300.00" para " nro="5e7e05588fc4c24a14491db1" order="1" printerMessage="mar27c" prorationMethod="PROPORCIONAL" unit="qty"> <aplicar> <item magnitude="0.000" qty="3.000" seq="1" value="22.00" valueWithTaxes="22.00" xprice="300.00"/> </aplicar> </benefício> </promo> </opcional> <limitBalances> <limit amount="0.00" id="5e7e0e878fc4c2219049697e" max="25000.00" promotionName="march27c"/> <limit amount="4366.00" id="5e7e0f9b8fc4c22190496980" max="12000.00" promotionName="march27c"/> <limit amount="1680.00" id="5e8251f2b85cf77dbc714f32" max="50000.00" promotionName="march27c"/> </limitBalances> </mensagem> |
Preços
Foi adicionado ao motor de mensagens um novo estado chamado preços , este estado irá informar-nos dos preços dos artigos a consultar, para consultar o preço, devem ser informados os artigos com o atributo preço unitário=0 , este novo estado irá avaliar o ticket da mensagem enviada e responderá os preços solicitados de acordo com a avaliação da tabela de preços, no caso de adicionar ou remover elementos para modificar as informações do ticket, utilize as operações add e void dos elementos (para ver mais detalhes dos preços , consulte o manual do usuário).
As listas de preços estão associadas a lojas, portanto, o campo da loja é fundamental para encontrar preços.
Nota: Para que a funcionalidade de precificação esteja disponível, o mecanismo deverá ter o atributo: <disablePrices>false</disablePrices> no arquivo de configuração (config.xml) na tag geral.
<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="preços" avalia="true" sugere="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"/> </mensagem>
resposta 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="02/19/2019 13:18:06" priceListId="napse_LP0_test" qty="2.00" seq= "1" fornecedorFinancial="PR3" fornecedorFinancialAmount="16070.00" fornecedorItem="PR1" fornecedorItemAmount="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" fornecedorFinancial="PR1" fornecedorFinancialAmount="32340.00" fornecedorItem="PR3" fornecedorItemAmount="24791.00" unitprice="73921.00" xprice="73921.00"/> </preços> </mensagem>
As propriedades dos elementos informados na Tag <Prices/> são:
Propriedade | Tipo de dados | Descrição |
última atualização | data com hora | Informa a data da última atualização de preço (o console se comunicou com a engine para informar os preços). |
com desconto | boleano | Determinar se o artigo admite desconto |
desconto manual | boleano | Determina se o item suporta desconto manual |
preçoÚltimaAtualização | alfanumérico | Data em que o preço do item foi atualizado |
priceListId | alfanumérico | É a empresa mais o código da tabela de preços a partir da qual o preço foi calculado <codigoEmpresa>_<codigo ListaDePrecios> |
quantidade | inteiro positivo | Número que identifica a Quantidade do item |
eu sei que | inteiro positivo | Número que identifica o elemento dentro da transação |
financeiro fornecedor | alfanumérico | Opcional. É o código do provedor financeiro do item |
fornecedorFinancialAmount | Numérico | Opcional. É o valor que o provedor financeiro reconhece |
item do fornecedor | alfanumérico | Opcional. É o código do fornecedor do item |
fornecedorItemAmount | Numérico | Opcional. É o valor que o provedor reconhece |
preço unitário | Numérico | É o preço do item consultado ao motor |
xpreço | Numérico | É o preço do item multiplicado pelo atributo qty |
Você também pode calcular os preços em outros status enviando o item com preço unitário = 0
Neste caso enviamos um status vendas com 2 itens com preço unitário=0 e um com preço
<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="vendas" avalia="true" sugere="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"/> </mensagem>
Na resposta vemos que o benefício da promoção de 10% em cada item é aplicado aos 3 itens, para os dois com item com preço unitário= 0 o preço foi calculado e aplicado 10%, abaixo você pode ver o bloco de preços de onde foram retirados os preços.
<?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"> <opcional> <promo code="teste" id="teste" nro="5c59964c47452a7b3c22724a"> <benefit TLOGMessage="test" account="" applicationMethod="resume" baseAmount="180991.92" BenefitType="PercentageDiscount" discountPercentage="10.00" displayMessage="test" name="5c59964c47452a7b3c22724a" nro="5c670e1ea8b0ea 296089de8f" order=" 1 " printerMessage="test" prorationMethod="PROPORCIONAL" unit="qty"> <aplicar> <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"/> </aplicar> </benefício> </promo> </opcional> <prices lastUpdate="19/02/2019 15:52:56"> <item code="00-1114298" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="02/19/2019 13:18:06" priceListId="napse_LP0_test" qty="2.00" seq= "1" fornecedorFinancial="PR3" fornecedorFinancialAmount="16070.00" fornecedorItem="PR1" fornecedorItemAmount="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" fornecedorFinancial="PR1" fornecedorFinancialAmount="32340.00" fornecedorItem="PR3" fornecedorItemAmount="24791.00" unitprice="73921.00" xprice="73921.00"/> </preços> </mensagem>
Novo atributo de cabeçalho tenderGroupCode
Para determinar se os precificadores aplicam o preço de crédito ou o preço de venda regular da lista de preços, um atributo foi adicionado ao cabeçalho, o tenderGroupCode .
Quando a mensagem possuir tenderGroupCode e seu valor for "cr" , o motor aplicará o preço de crédito, caso não possua o atributo ou possua outro valor, o preço a ser aplicado será o preço de venda .
Exemplo de mensagem com 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="vendas" avalia="true" sugere="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"/> </mensagem>
<?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"> <opcional> <promo code="teste" id="teste" nro="5c59964c47452a7b3c22724a"> <benefit TLOGMessage="test" account=""applicationMethod="resume" baseAmount="144668.20" 1 " printerMessage="test" prorationMethod="PROPORCIONAL" unit="qty"> <aplicar> <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"/> </aplicar> </benefício> </promo> </opcional> <prices lastUpdate="19/02/2019 16:11:13"> <item code="00-1114298" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="02/19/2019 13:18:06" priceListId="napse_LP0_test" qty="2.00" seq= "1" fornecedorFinancial="PR3" fornecedorFinancialAmount="16070.00" fornecedorItem="PR1" fornecedorItemAmount="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" fornecedorFinancial="PR1" fornecedorFinancialAmount="32340.00" fornecedorItem="PR3" fornecedorItemAmount="24791.00" unitprice="72446.20" xprice="72446.20"/> </preços> </mensagem>
Exemplo de mensagem SEM 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="vendas" avalia="true" sugere="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"/> </mensagem>
<?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"> <opcional> <promo code="teste" id="teste" nro="5c59964c47452a7b3c22724a"> <benefit TLOGMessage="test" account="" applicationMethod="resume" baseAmount="180991.92" BenefitType="PercentageDiscount" discountPercentage="10.00" displayMessage="test" name="5c59964c47452a7b3c22724a" nro="5c670e1ea8b0ea 296089de8f" order=" 1 " printerMessage="test" prorationMethod="PROPORCIONAL" unit="qty"> <aplicar> <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"/> </aplicar> </benefício> </promo> </opcional> <prices lastUpdate="19/02/2019 16:15:14"> <item code="00-1114298" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="02/19/2019 13:18:06" priceListId="napse_LP0_test" qty="2.00" seq= "1" fornecedorFinancial="PR3" fornecedorFinancialAmount="16070.00" fornecedorItem="PR1" fornecedorItemAmount="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" fornecedorFinancial="PR1" fornecedorFinancialAmount="32340.00" fornecedorItem="PR3" fornecedorItemAmount="24791.00" unitprice="73921.00" xprice="73921.00"/> </preços> </mensagem>
Dadas as solicitações anteriores com e sem tenderGroupCode , os preços variam, um é o preço de crédito e o outro é o preço de venda normal.
- Pode-se observar que com o tenderGroupCode o valor que o motor respondeu é o seguinte:
<item magnitude="0.000" qty="1.000" seq="2" value="7244.62" valueWithTaxes="0.00" xprice="72446.20"/>
- Vê-se que SEM o tenderGroupCode o valor que o motor respondeu é o seguinte:
<item magnitude="0.000" qty="1.000" seq="2" value="7392.10" valueWithTaxes="0.00" xprice="73921.00"/>
dicas práticas
Interação com o Motor de Promoções
Embora o motor de promoções possa ser utilizado de várias formas, recomenda-se fazer um único envio que contenha todos os elementos da transação, solicitando em seu cabeçalho a abertura de uma nova sessão, a avaliação do ticket enviado e o envio de uma resposta para aquela avaliação.
Isso permitirá um uso mais eficiente dos recursos, tanto de processamento quanto de memória, bem como do canal de comunicação.
Se por algum motivo (limitações técnicas, normas, etc.) não for possível enviar uma única mensagem, como segunda opção é possível enviar os elementos em mais de uma mensagem (podendo utilizar até uma mensagem para cada elemento a ser adicionado), solicitando a abertura de uma nova sessão no primeiro envio de mensagem correspondente à transação, e solicitando a avaliação do ticket ao final da mesma. Para garantir o envio bem-sucedido de cada elemento, é possível solicitar uma mensagem de confirmação (usando resposta no cabeçalho), mas sem solicitar a avaliação.
Esta última forma de interação é um pouco menos eficiente que a anterior, pois requer mais tempo para utilizar o canal de comunicação e a memória onde está rodando o Motor de Promoções.
Também pode expirar a sessão aberta no Engine, forçando um reenvio do ticket conforme indicado em ". Envio de mensagem única Conforme mencionado acima
, a política de envio recomendada é usar uma única mensagem contendo todos os itens. A Abaixo está uma etapa- enumeração passo a passo da submissão e avaliação em uma única mensagem.
- Crie uma única mensagem contendo
- o cabeçalho
- Configure que uma resposta é esperada (usando o atributo response ).
- Configure que o Mecanismo deve calcular as promoções (usando o atributo de avaliação ).
- Configure se um novo ticket for iniciado (limpe o contexto associado à sessão, usando o atributo init-tck )
- o corpo
- todos os itens da transação, de acordo com o formato estabelecido.
- todos os eventos da transação, de acordo com o formato estabelecido.
- todos os clientes da transação, de acordo com o formato estabelecido.
- todos os meios de pagamento da transação, de acordo com o formato estabelecido.
- todos os cupons da transação, de acordo com o formato estabelecido.
- o cabeçalho
- Envie a mensagem usando o protocolo de comunicação correspondente.
- Receber a resposta ao pedido efetuado. A referida resposta terá todas as promoções com seus respectivos benefícios, conforme descrito em " Resposta do Motor ". Caso o atributo ACK do cabeçalho da resposta seja diferente de 0, vá em "ACK" Valores do Atributo e execute a ação recomendada.
gerenciamento de sessão
Conforme mencionado anteriormente, o Promotions Engine é capaz de lidar com múltiplas sessões, o que permite atender diversas transações em paralelo. Cada sessão utiliza uma determinada quantidade de memória física do computador, portanto não seria conveniente criar muitas sessões a não ser que o Engine esteja atendendo a vários terminais e rodando em um computador com as características adequadas (ver Manual de Instalação).
Desta forma, se apenas um terminal estiver interagindo continuamente com o motor, seria conveniente usar sempre a mesma sessão e toda vez que for necessário deletar todo o conteúdo da sessão, faça-o através do atributo init-tck do cabeçalho .
Por outro lado, e devido à natureza humana da interação entre a entrada dos artigos no ponto de venda, se o ticket estiver a ser enviado para o Motor de Promoções em várias mensagens, o tempo de expiração da sessão pode passar. Conforme descrito em "Sessões", se isso acontecer, o Motor de Promoções irá eliminar a sessão juntamente com todos os elementos que contém e a pedido do terminal onde a transação é realizada, informará que a sessão dessa transação expirou ( usando o atributo ack do cabeçalho da mensagem de resposta). Nestes casos, deve-se lembrar de abrir uma nova sessão utilizando o atributo init-tck do cabeçalho das submissões e reenviar todos os elementos que foram inseridos até o momento. Então será possível continuar com a operação normal.
Implementação de itens aplicados
Esta seção fornecerá algumas orientações úteis a serem consideradas ao interpretar os itens aplicados dependendo do benefício a que pertencem.
Itens aplicados em benefícios monetários
Os itens aplicados a um benefício monetário são os itens nos quais o desconto informado pelo Motor de Promoções deve ser feito. Assim, a implementação mais simples é descontar diretamente o valor reportado pelo atributo value ao item reportado por seq . O atributo qty de cada elemento indicará o valor total a ser descontado, portanto será necessário distribuir (a critério do implementador) o valor atribuído ao valor entre a quantidade de itens informados em qty . Se uma magnitude for informada ( atributo magnitude ), o valor será descontado dessa magnitude.
Itens aplicados em benefícios não monetários
No caso particular dos benefícios não pecuniários, os artigos a eles aplicados poderão ser interpretados como apropriados por quem se encarregue da integração entre o ponto de venda e o Motor de Promoções. Por exemplo, os itens aplicados de um benefício de plano de pagamento ( PaymentPlanBenefit ) podem ser interpretados como os itens nos quais o plano de pagamento relatado é permitido.
No caso particular do FactorLoyaltyBenefit com integrações anteriores ao PROMO 5.2 (onde a gestão de saldos está incluída na consola), a implementação recomendada é multiplicar o fator ( atributo factor ) informado pela soma dos valores ( atributo preço unitário) dos itens aplicados, cada um deles multiplicado pelo valor informado pela quantidade :
Pt = fator x Σ(Preço unitário x quantidade)
Onde Pt é a quantidade total de pontos, dinheiro, milhas, etc. conceder e Σ(unitPrice x qty) a soma dos preços unitários dos elementos aplicados, multiplicado pela quantidade correspondente informada em < aplicar >.
Caso não sejam declarados aplicados (algo que é possível para benefícios não monetários), poderão ser aplicados pontos, dinheiro, milhas, etc. ao bilhete inteiro.
Para os demais benefícios não monetários, os elementos aplicados podem ser considerados meramente informativos.
ANEXO I - Benefício - ResgatarComOpçõesBenefício
A partir da Promo 7.0-EP2 há um novo benefício Monetário da classe "Câmbio com Opções"
Devem ser definidas as promoções pertinentes que possuem este novo tipo de benefício, uma vez distribuído o mapa com as ditas promoções, o motor poderá avaliar este novo tipo de benefício.
Basicamente, esse benefício, como o próprio nome indica, possui opções, que podem ser aplicadas linha por linha a cada artigo.
Cada sequência do elemento item poderá selecionar uma opção, esta opção contém pontos que o cliente terá que resgatar para poder aplicar o benefício da opção.
O benefício a ser aplicado é calculado com o tipo de benefício (atributo tipo-benefício da opção), a unidade de medida a ser aplicada no cálculo (atributo unidade da opção) e o valor a ser aplicado ((atributo valor da opção).
Bloco de opções de resgate
Quando a engine receber um status vendas com a avaliação ativada, ela disponibilizará as opções do benefício a ser aplicado em um novo bloco denominado reedemOptions, que é composto por uma lista de elementos option, que representam as opções de resgate do cliente pontos.
<opções de resgate> <option BenefitType="percentageDiscount" cardPoints="200.0" cardType="089" id="5e567f0506773d1c14528761_0" requiredPoints="100.0" unit="qty" value="10.0"/> <option BenefitType="percentageDiscount" cardPoints="1000.0" cardType="089" id="5e567f0506773d1c14528761_2" requiredPoints="0.0" unit="qty" value="20.0"/> <option BenefitType="percentageDiscount" cardPoints="0.0" cardType="-" id="5e567f0506773d1c14528761_3" requiredPoints="500.0" unit="qty" value="20.0"/> </redeemOptions>
ELEMENTO OPCIONAL
As opções disponíveis têm os seguintes atributos
atributo | cara | Descrição |
---|---|---|
eu ia | alfanumérico | Identificador de opção** |
Pontos necessários | Numérico | Pontos necessários para resgatar para aplicar o benefício |
tipo de carta | alfanumérico | Tipo de elemento para o qual os pontos do elemento podem ser resgatados (cardPoints) |
cardPoints | Numérico | Pontos do elemento de fidelidade necessários para serem resgatados para aplicar o benefício |
tipo de benefício | alfanumérico | Tipo de cálculo a aplicar ( fixedDiscount / percentDiscount / newPrice ) |
unidade | alfanumérico | Unidade de medida a aplicar no cálculo (quantidade / magnitude) |
valor | Numérico | Valor aplicado no cálculo de acordo com o tipo de benefício ( fixedDiscount: FixedDiscount, percentDiscount: percentual, newPrice: newPrice ) por sua vez, esse valor será subtraído dos valuePoints do item-apply |
Id del elemento Option
Id del elemento Option
As opções podem ser resgatadas por pontos do cliente ou pontos do cartão, ou ambos (conforme configurado no benefício)
- Se for trocado por pontos de cliente, não é necessário o elemento cartão fidelidade com tipo e valor
- Se forem trocados pontos de cartão, o elemento cartão de fidelidade deve existir com o mesmo tipo que o definido em cardType e com uma quantidade suficiente
- Se for trocado por pontos cliente, deve ter pontos disponíveis no elemento cliente e deve haver o elemento cartão fidelidade com tipo e valor
As opções disponíveis possuem 3 tipos de cálculos a serem aplicados ao lucro dos itens.
Esses cálculos são:
- Preço Fixo (cálculo pré-existente no benefício de desconto fixo)
- Desconto percentual (cálculo pré-existente no benefício de desconto percentual)
Novo preço (cálculo pré-existente no novo benefício de desconto de preço)
Uma vez disponíveis as opções, o TPV poderá atribuir as opções pretendidas a cada seq de artigo (item de elemento), e o motor aplicará a vantagem de cumprir as seguintes validações :
Validações que permitem o cálculo correto do benefício.
Selecionando uma opção válida , o id da opção ( resgateOption ) sugerida no bloco resgateOptions (opções disponíveis) deve ser adicionado ao elemento item-add .
A mensagem deve conter o elemento customer customer-add
O elemento cliente deve ter o atributo pontos com pontos suficientes para poder resgatar os pontos necessários para a opção selecionada.
O elemento cliente deve ter o novo atributo resgatePointsPriceFactor ( o fator de conversão permite calcular o valor do item em pontos)
Os pontos para um item são calculados da seguinte forma ptosItem= xprice/redeempointsPriceFactor
A pontuação do item (xprice/redeemPointsPriceFactor) deve ser maior que a pontuação necessária da opção selecionada ( requiredPoints ).
Novos atributos no item se aplicam
As opções disponíveis têm os seguintes atributos
atributo | cara | Descrição |
---|---|---|
opção de resgate | alfanumérico | Identificador da opção selecionada (Quando não quiser selecionar nenhuma opção, o valor deve ser "0") | |
pontos usados | Numérico | Pontos resgatados para aplicar o benefício (xprice*requiredPoints) |
tipo de carta | alfanumérico | Tipo de item para o qual os pontos foram resgatados |
cardUsedPoints | Numérico | Pontos de itens de fidelidade resgatados |
BenefícioTipoOpção | alfanumérico | Tipo de cálculo a aplicar ( fixedDiscount / percentDiscount / newPrice ) |
BenefícioUnitOption | alfanumérico | Unidade de medida a aplicar no cálculo (quantidade / magnitude) |
valuePoints | Numérico | Equivalente em pesos de pontos resgatados ( usedPoints * resgatePointsPriceFactor) |
preçoInPoints | Numérico | Valor do item em pontos (xprice/redeemPointsPriceFactor) |
desconto nominal | Numérico | É o Desconto Nominal (valor +valuePoints) |
porcentagemDesconto | Numérico | Valor a aplicar no desconto quando o BenefitTypeOption = percentDiscount) |
desconto fixo | Numérico | Valor a aplicar no desconto quando o BenefitTypeOption =fixedDiscount |
novo preço | Numérico | Valor a aplicar no desconto quando o BenefitTypeOption =newPrice |
Calculo del Value
O cálculo do valor dependerá do BenefitTypeOption( percentDiscount/ fixedDiscount/ newPrice ) e valuePoints serão subtraídos desse cálculo
EXEMPLO DE OPÇÕES DE SOLICITAÇÃO/RESPOSTA
Dada a seguinte mensagem de solicitação
<message store="1" terminal="001" date-time="2020-03-11 10:21" init-tck="true" messageId="1" void-trx="false" response="true" status="venda" avaliar="true" sugerir="true" map-version="5208" companyId="napse"> <customer-add seq="1" id="1" points="40000" resgatePointsPriceFactor="1" /> <loyaltycard-add seq="1" id="999999001" type="089" amount="5000"/> <item-add seq="1" qty="1" code="111" magnitude="0" xprice="5000" unitprice="5000" /> </mensagem>
O motor responderá ao benefício com suas opções:
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT" mapversion="5208" messageId="1" store="1" terminal="001"> <opcional> <promo code="24330" id="promo-24330" nro="5e567ea506773d1c1452875d"> <benefit RecoveryPercentage="0" RecoveryValue="0" Recovery="no" TLOGMessage="promo" account="" applicationMethod="lineByLine" baseAmount="5000.00" d " nro="5e567f0506773d1c14528761" order="1" printerMessage="promo" prorationMethod="PROPORCIONAL" usedPoints="0.00"> <aplicar> <item magnitude="0.000" qty="1.000" seq="1" value="0.00" valueWithTaxes="0.00" xprice="5000.00"/> </aplicar> <opções de resgate> <option BenefitType="percentageDiscount" cardPoints="200.0" cardType="089" id="5e567f0506773d1c14528761_0" requiredPoints="100.0" unit="qty" value="10.0"/> <option BenefitType="percentageDiscount" cardPoints="1000.0" cardType="089" id="5e567f0506773d1c14528761_2" requiredPoints="0.0" unit="qty" value="20.0"/> <option BenefitType="percentageDiscount" cardPoints="0.0" cardType="-" id="5e567f0506773d1c14528761_3" requiredPoints="500.0" unit="qty" value="20.0"/> </redeemOptions> </benefício> </promo> </opcional> </mensagem>
Atendendo a seguinte mensagem de solicitação, mensagem com o item (seq="1") selecionando a opção "5e567f0506773d1c14528761_0" (redeemOption)
<message store="1" terminal="001" date-time="2020-03-11 10:23" init-tck="true" messageId="3" void-trx="false" response="true" status="venda" avaliar="true" sugerir="true" map-version="5208" companyId="napse"> <customer-add seq="1" id="1" points="40000" resgatePointsPriceFactor="1" /> <loyaltycard-add seq="1" id="999999001" type="089" amount="5000"/> <item-add seq="1" qty="1" code="111" magnitude="0" xprice="5000" unitprice="5000" resgateOption="5e567f0506773d1c14528761_0" /> </mensagem>
redeemOption
Cada item pertencente ao aplicativo de benefício pode ter apenas uma opção selecionada (um único id da opção " redesemOption ")
Teremos como resposta:
<message ack="0" engine="2.6" mapversion="5208" messageId="3" store="1" terminal="001"> <opcional> <promo code="24330" id="promo-24330" nro="5e567ea506773d1c1452875d"> <benefit RecoveryPercentage="0" RecoveryValue="0" Recovery="no" TLOGMessage="promo" account="" applicationMethod="lineByLine" baseAmount="5000.00" d " nro="5e567f0506773d1c14528761" order="1" printerMessage="promo" prorationMethod="PROPORCIONAL" usedPoints="100.00"> <aplicar> <item BenefitTypeOption="percentageDiscount" BenefitUnitOption="qty" cardType="089" cardUsedPoints="200.00" magnitude="0.000" nominalDiscount="500.00" percentDiscount="10.00" priceinPoints="5000.00" qty="1.000" Redemption=" 5e567f0506773d1c14528761_0" seq="1" usedPoints="100.00" value="400.00" valuePoints="100.00" valueWithTaxes="400.00" xprice="5000.00"/> </aplicar> </benefício> </promo> </opcional> </mensagem>
Neste caso vemos que o item que possui a opção selecionada foi modificado, os atributos do cálculo do benefício foram adicionados ao item aplicável.
Bloque redeemOptions
O bloco resgateOptions estará sempre visível desde que não haja itens a selecionar e também o bilhete tenha pontos suficientes ou cumpra o tipo de cartão pretendido e os seus pontos (se, por exemplo, a opção tiver um tipo de cartão e o bilhete não não, essa opção não estará disponível, ou se você não tiver pontos, seja de um cliente ou de algum tipo de cartão, essa opção não será mostrada), uma vez que todos os itens aplicáveis tenham seu RedempOption, ele deixará de informar ( também deixará de estar disponível se os itens que não deseja aplicar nenhuma opção for colocado resgateOption="0" )
Mensagem com os itens aplicáveis, cada um selecionando uma opção de resgate
<message store="1" terminal="1" date-time="2019-10-30 09:26" init-tck="true" messageId="1" void-trx="false" response="true" status="venda" avalia="true" sugere="true" companyId="napse" map-version="5200" > <customer-add seq="1" id="1" points="300" resgatePointsPriceFactor="2" /> <item-add seq="1" qty="1" code="111" magnitude="0" xprice="2300" unitprice="2300" resgateOption="5db9b4afa171f2314ce5704e_1"/> <item-add seq="2" qty="1" code="222" magnitude="0" xprice="5000" unitprice="5000" resgateOption="5db9b4afa171f2314ce5704e_0" /> </mensagem>
<message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT" mapversion="5200" messageId="1" store="1" terminal="1"> <opcional> <promo code="17048" id="Promo 002" nro="5db9b41fa171f2314ce57042"> <benefit TLOGMessage="Promo 002" account="" applicationMethod="resume" baseAmount="7300.00" BenefitType="RedeemWithOptionsBenefit" displayMessage="Promo 002" name="5db9b41fa171f2314ce57042" nro="5db9b4afa171f23 14ce5704e" order="1" impressora Mensagem = "Promo 002" prorationMethod="PROPORCIONAL" usedPoints="200.00"> <aplicar> <item BenefitOption="percentageDiscount" BenefitUnitOption="qty" cardType="-" cardUsedPoints="0" magnitude="0.000" nominalDiscount="0.00" percentDiscount="10.00" priceinPoints="0.00" qty="1.000" RedemptionOption=" 5db9b4afa171f2314ce5704e_1" seq="1" usedPoints="0" value="0.00" valuePoints="0.00" valueWithTaxes="0.00" xprice="2300.00" /> <tem 5db9b4afa171f2314ce5704e_0" seq="2" usedPoints="200.00" value="-300.00" valuePoints="400.00" valueWithTaxes="-300.00" xprice="5000.00" /> </aplicar> </benefício> </promo> </opcional> </mensagem>
Mensagem com os itens que se aplicam, selecionando cada um uma opção de resgate, mas o cliente não tem pontos suficientes.
<message store="1" terminal="1" date-time="2019-10-30 09:26" init-tck="true" messageId="1" void-trx="false" response="true" status="venda" avalia="true" sugere="true" companyId="napse"> <customer-add seq="1" id="1" points="300" resgatePointsPriceFactor="2" /> <item-add seq="1" qty="1" code="111" magnitude="0" xprice="2300" unitprice="2300" resgateOption="5db9b4afa171f2314ce5704e_1"/> <item-add seq="2" qty="1" code="222" magnitude="0" xprice="5000" unitprice="5000" resgateOption="5db9b4afa171f2314ce5704e_2" /> </mensagem>
Neste caso, vemos como a engine responde ao apply do item com seq 2 com benefício 0, pois os pontos do cliente atingiram apenas a opção seq=1 do item.
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT" mapversion="5200" messageId="1" store="1" terminal="1"> <opcional> <promo code="17048" id="Promo 002" nro="5db9b41fa171f2314ce57042"> <benefit TLOGMessage="Promo 002" account="" applicationMethod="resume" baseAmount="7300.00" BenefitType="RedeemWithOptionsBenefit" displayMessage="Promo 002" name="5db9b41fa171f2314ce57042" nro="5db9b4afa171f23 14ce5704e" order="1" impressora Mensagem = "Promo 002" prorationMethod="PROPORCIONAL" usedPoints="0.00"> <aplicar> <item BenefitOption="PercentageDiscount" BenefitUnitOption="qty" magnitude="0.000" nominalDiscount="0.00" percentDiscount="10.00" priceinPoints="0.00" qty="1.000" RedemptionOption="5db9b4afa171f2314ce5704e_1" seq="1" usedPoints =" 0" value="0.00" valuePoints="0.00" valueWithTaxes="0.00" xprice="2300.00"/> <item Benefittypeoption = "newprice" Benefitunitotation = "Qty" magnitude = "0,000" newprice = "500,00" nominaldiscount = "0,00" Priceinpoints = "0,00" qty = "1.000" resgate = "5db9b4afa171f2314ce5704e_2" seq "usedpoints =" 0" valor ="0.00" valuePoints="0.00" valueWithTaxes="0.00" xprice="5000.00"/> </aplicar> </benefício> </promo> </opcional> </mensagem>
<message store="1" terminal="1" date-time="2019-10-30 09:26" init-tck="true" messageId="1" void-trx="false" response="true" status="venda" avalia="true" sugere="true" companyId="napse" map-version="5200"> <customer-add seq="1" id="1" points="300" resgatePointsPriceFactor="2" /> <item-add seq="1" qty="1" code="111" magnitude="0" xprice="2300" unitprice="2300" resgateOption="5db9b4afa171f2314ce5704e_1"/> <item-add seq="2" qty="1" code="222" magnitude="0" xprice="5000" unitprice="5000" resgateOption="0" /> </mensagem>
Quando você não quiser ver o bloco resgateOptions, redemOption="0" deve ser selecionado em cada item
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT" mapversion="5200" messageId="1" store="1" terminal="1"> <opcional> <promo code="17048" id="Promo 002" nro="5db9b41fa171f2314ce57042"> <benefit TLOGMessage="Promo 002" account="" applicationMethod="resume" baseAmount="7300.00" BenefitType="RedeemWithOptionsBenefit" displayMessage="Promo 002" name="5db9b41fa171f2314ce57042" nro="5db9b4afa171f23 14ce5704e" order="1" impressora Mensagem = "Promo 002" prorationMethod="PROPORCIONAL" usedPoints="0.00"> <aplicar> <item BenefitOption="percentageDiscount" BenefitUnitOption="qty" cardType="-" cardUsedPoints="0" magnitude="0.000" nominalDiscount="0.00" percentDiscount="10.00" priceinPoints="0.00" qty="1.000" RedemptionOption=" 5db9b4afa171f2314ce5704e_1" seq="1" usedPoints="0" value="0.00" valuePoints="0.00" valueWithTaxes="0.00" xprice="2300.00"/> <item magnitude="0.000" qty="1.000" seq="2" value="0.00" valueWithTaxes="0.00" xprice="5000.00"/> </aplicar> </benefício> </promo> </opcional> </mensagem>
limitações
Seleccion de Opciones
Existe a limitação de que um item só pode selecionar uma única opção.
Id del elemento Option
Id del elemento Option
Quando a opção de benefício for por quantidade, os pontos necessários serão os definidos na opção pela quantidade do item.
Esclarecimento, pode ser que pela quantidade os pontos não sejam suficientes, mas se vários itens forem feitos com quantidade 1, talvez alguns se apliquem,
Um exemplo seria se um cliente tiver 200 pontos, e a opção exigir 100 pontos, se o item tiver quantidade 3 não se aplica porque os pontos são insuficientes, mas se forem geradas 3 linhas por item com quantidade 1 da pós, o aplicar-se-iam as duas primeiras linhas e a 3 não porque os pontos não o atingiriam.
Devoluciones Automaticas RETURNFINISH
- Esse benefício, por ser um caso muito raro, o retorno automático não foi implementado (é difícil igualar o retorno dos itens e os aplicativos), ou seja, não suporta o returnFinish .
- Para devolver os pontos do elemento de fidelidade resgatados, um valor de cobrança deve ser feito no correio para poder devolvê-los.
Validaciones no cumplidas