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:

Ejemplo

<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.

Importante: Deve-se levar em conta que se no ticket forem encontrados caracteres que não pertençam ao alfabeto inglês ou caracteres reservados XML (como '>', '<', '"'), isso não garante que esses são corretamente interpretados pelo Motor de Promoções.

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 você sai total pagamento Existem valores específicos para este imóvel que serão apresentados na seção Fidelidade	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.

Request

<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:

Request

<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.

Request

<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) HABILITADO para habilitar um elemento de fidelidade (válido apenas no status FINISH)	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
	*e-mail*	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 no mecanismo para lidar com pagamentos parciais.	*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), obtém-se que o valor dos itens a serem pagos (PIA) é calculado como PIA = PA / (1 - % de redução) ou PIA = PA / (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. desc: aplica o desconto no item. Valor padrão. porc: porcentagem de desconto	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

Observação: O número de sequência deve ser único para cada tipo de elemento, podendo haver, por exemplo, um cliente e um item na mesma sequência; mas nunca dois elementos com o mesmo número de sequência.

Importante: Se um elemento for adicionado ao contexto com um número de sequência já utilizado por um elemento do mesmo tipo, o último enviado substituirá o anterior.

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:

Request

<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>

Response

<?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”.

Pos Inyecta Balances

<?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>

Response

<?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) transaction="1_1_20170321152000" (pega os dados data-time da solicitação para construir o número da transação na central PROMO)

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: O cvv é obrigatório e não foi reportado ou está errado. O tipo de elemento de fidelização é nomeado com atribuição desde ficheiro e tenta-se atribuir desde o ponto de venda (motor). O elemento de fidelidade expirou ou foi cancelado. O item de fidelidade não é nomeado e é feita uma tentativa de atribuição de um cliente.
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. Este erro será reportado quando o tipo de elemento de fidelização exigir o consumo total do valor numa única transacção e estiver a ser enviado um valor com um valor inferior. Este erro será reportado quando o tipo de elemento de fidelização exigir a transferência total do mount para outro elemento do mesmo tipo de elemento e um chargeAmount com valor menor está sendo enviado.
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.

Ejemplo de Respuesta correcta pero sin elementos informados

<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)
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.

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

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.

Ejemplo

<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

Ejemplo

<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.

Ejemplo

<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: " lineByLine " (o benefício deve ser exibido após cada item do benefício) " currículo " (o benefício deve ser mostrado no final do ticket)
*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:
1. Desconto Fixo
  - É um desconto fixo que é feito em um conjunto de itens.
2. PercentualDesconto
  - Representa uma porcentagem de desconto em um conjunto de itens.
3. Novo preço
  - Atribua um novo preço a um ou mais itens.
4. 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.
5. 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.
6. Cupom CalculadoBenefício do Aplicativo
  - O valor informado por um cupom calculado é aplicado como desconto
7. ContratoPercentagemDescontoBenefício
  - Desconto percentual aplicado a um determinado Contrato e limitado por um saldo associado a ele
8. 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
9. 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.

Não monetário
1. Plano de PagamentoBenefício
  - Conceda um plano de pagamento específico para uma série de itens ou para a compra.
2. CupomBenefício
  - Dê um certo número de cupons específicos para o cliente.
3. Presente Benefício
  - Dê ao cliente um ou mais presentes específicos.
4. GeralBenefício
  - Oferece ao cliente um ou mais benefícios gerais.
5. 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.
6. FatorLealdadeBenefício
  - Representa a atribuição de pontos, dinheiro, milhas, etc. de fidelidade em relação a um dado fator.
7. 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.
8. BenefícioCupomCalculado
  - Representa a atribuição de um cupão cujo valor do desconto a conceder é definido por uma percentagem dos participantes.

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: " qty " (o desconto é aplicado a cada unidade de quantidade) " magnitude " (o desconto é aplicado a cada unidade de quantidade) Caso não seja informada a unidade (atributo vazio), a aplicação recai sobre todo o conjunto de aplicado (vide " Elementos aplicados ").
	*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: padrão _ _ " proporcional " (proporciona o benefício proporcionalmente ao preço) " mais caro primeiro " (aplica o benefício ao item mais caro) " mais barato primeiro " (aplica o benefício ao item mais barato)
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 :

FixedDiscount

<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>

PercentageDiscount

<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>

TenderDiscountBenefit

<?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>

RedeemPointsBenefit

<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">

calculatedcouponaplicationbenefit

<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>

PaymentPlanBenefit

<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>

CouponBenefit

<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>

GiftBenefit

<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>

LoyaltyBenefit

<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

FactorLoyaltyBenefit

<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>

PercentLoyaltyBenefit

<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

CalculatedCouponBenefit

<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>

CatalogRedeemBenefit

<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>

GeneralBenefit - Request

<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>

GeneralBenefit - Response

<?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.

Ejemplo

<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.

Ejemplo

<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.

Ejemplo

<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:

RedeemOptions

<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.

Ejemplo

<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.

Ejemplo

<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á:

1. Pesquise se existe o arquivo de estoque configurado, caso não exista a promoção não será sugerida.
2. 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.

Request

<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.

Request

<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/>.

Request

<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:

Request

<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)

Request

<?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:

Request

<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

Request

<?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.

CVVCHANGE

Para alterar o CVV, o status "CVVCHANGE" deve ser enviado na tag status="loyaltyActivation" <loyaltycard / >

Exemplo de envio de alteração CVV

Request

<message status="loyaltyActivation" companyId="napse" date-time="2021-04-11 16:44" avalia="true" init-tck="true" messageId="1" offline="false" response= "true" store="0043" terminal="001" void-trx="false">
<loyaltycard-add seq="1" id="4400000000000012" status="CVVCHANGE" cvv="1234" />
</mensagem>

Quando a operação for concluída satisfatoriamente, a seguinte resposta será obtida:

Response

<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="7.1.5-SNAPSHOT#132" mapversion="714" messageId="1" store="0043" terminal="001" transaction="napse_0043_001_20210806164400">
  <lealdade>
    <cartões de fidelidade>
      <cartão de fidelidade ack="0" id="4400000000000012" seq="1" type="-"/>
    </cartões de fidelidade>
    <cupom/>
    <erro/>
    <clientes/>
    <redeemTable/>
  </lealdade>
</mensagem>

Em caso de erro no processo de alteração do CVV, será retornada a seguinte resposta:

Response

<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="7.1.5-SNAPSHOT#132" mapversion="714" messageId="1" store="0043" terminal="001" transaction="napse_0043_001_20210806165500">
  <lealdade>
    <cartões de fidelidade/>
    <cupom/>
    <erro>
      <error ack="9500" id="440000000003300012" info="440000000003300012" seq="1" type="loyaltycard-activation"/>
    </error>
    <clientes/>
    <redeemTable/>
  </lealdade>
</mensagem>

Neste caso, informa-se que o elemento não existe na Base Promol.

Quando é feita uma alteração de CVV, o movimento pode ser observado no detalhe do elemento da seguinte forma:

CVVRESET

Para reset do CVV, o status " CVVRESET " deve ser enviado na tag status="loyaltyActivation" <loyaltycard/>

Exemplo de envio de redefinição de CVV:

Request

<message status="loyaltyActivation" companyId="napse" date-time="2021-04-11 16:20" avalia="true" init-tck="true" messageId="1" offline="false" response= "true" store="0043" terminal="001" void-trx="false">
<loyaltycard-add seq="1" id="4400000000000011" status="CVVRESET"/>
</mensagem>

Quando a operação for concluída satisfatoriamente, a seguinte resposta será obtida:

Response

<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="7.1.5-SNAPSHOT#132" mapversion="714" messageId="1" store="0043" terminal="001" transaction="napse_0043_001_20210411161000">
  <lealdade>
    <cartões de fidelidade>
      <cartão de fidelidade ack="0" id="4400000000000080" seq="1" type="-"/>
    </cartões de fidelidade>
    <cupom/>
    <erro/>
    <clientes/>
    <redeemTable/>
  </lealdade>
</mensagem>

Em caso de erro no processo de reset do CVV, será retornada a seguinte resposta:

Response

<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="7.1.5-SNAPSHOT#132" mapversion="714" messageId="1" store="0043" terminal="001" transaction="napse_0043_001_20210411161000">
  <lealdade>
    <cartões de fidelidade/>
    <cupom/>
    <erro>
      <error ack="9507" id="4400000000000080" info="4400000000000080" seq="1" type="loyaltycard-activation"/>
    </error>
    <clientes/>
    <redeemTable/>
  </lealdade>
</mensagem>

neste caso, é relatado que o estado enviado do elemento não existe. (erro de sintaxe na requisição )

Ao realizar um reset CVV, o movimento pode ser observado no detalhe do elemento da seguinte forma:

Ao zerar o CVV de um item de Fidelidade, o campo CVV do cartão será exibido no Banco de Dados da seguinte forma:

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)

Request

<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".

Request

<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".

Request

<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.

Request

<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

Request

<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.

Request

<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.

Request

<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")

Request

<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.

Request

<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:

Request Devolución Total

<?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>

Response Devolución Total

<?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:

Request

<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:

Request

<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/>

Request

<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

Response OK

<?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" )

Response

<?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 .

Request

<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:

Response

<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.

Input

<?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>

Output

<?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.

Request

<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:

Response

<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)

Response

<?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" )

Response

<?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")

Response

<?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" )

Response

<?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.

Response

<?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>

Obs.: Deverá ser enviada uma mensagem com status " Commit " para que os saldos sejam alocados.

Resposta– Não OK (Ver capítulo 3.1.1 Valores do atributo "ack" )

Response

<?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

Response

<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

Request

<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>

Response

<?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>

Obs.: Deverá ser enviada uma mensagem com status " Commit " para que os saldos sejam alocados.

Obs 2: O atributo "quantia" informará o saldo que o item fidelidade terá após a efetivação do commit.

Resposta– Não OK (Ver capítulo 3.1.1 Valores do atributo "ack" )

Response

<?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

Request

<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>

Response OK

<?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>

Obs.: Deverá ser enviada uma mensagem com status " Commit " para que os saldos sejam alocados.

Obs 2: O atributo "quantia" informará o saldo que o item fidelidade terá após a efetivação do commit.

Resposta – Não OK (Ver capítulo 3.1.1 Valores do atributo "ack" )

Response ERROR

<?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:

Ejemplo

<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:

Ejemplo

<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:

Ejemplo

<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:

Ejemplo

<?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

Ejemplo

<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

Ejemplo

<?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:

Ejemplo

<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

Ejemplo

<?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

Ejemplo

<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

Ejemplo

<?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.

Ejemplo

<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>

Ejemplo

<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. No caso de elementos de fidelidade, o valor será o id do elemento informado
*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

Request

<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

Request

<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

Request

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.

Ejemplo de Input

Input

<message companyId="napse" store="013" terminal="001" date-time="2021-08-06 01:30:00" messageId="0011" map-version="494" void-trx=" false" response="true" init-tck="true" avalia="true" status="loyaltyvalidationex">
<item-add seq="1" qty="1" code="112233" magnitude="0" xprice="5000" unitprice="5000" type="555"/>
<customer-add seq="1" id="c4" />
</mensagem>

Ejemplo de Output

Output

<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="6.5" mapversion="494" messageId="0011" store="013" terminal ="001" transação="napse_013_001_20210806013000">
  <lealdade>
    <cartões de fidelidade/>
    <cupom/>
    <erro/>
    <clientes>
      <customer code="c4" email="-" identifier="-" lastName="-" limitedBenefits="" name="-" segment="5500,555" type="EMPLOYEE" seq="1"/>
    </clientes>
    <redeemTable/>
    <lojas/>
  </lealdade>
  <opcional>
    <promo code="40705" id="segmento do cliente" nro="610cb87616f79a30b457e44c">
      <benefit TLOGMessage="segmento do cliente" account="" applicationMethod="resume" baseAmount="5000" BenefitType="PercentageDiscount" discountPercentage="50" displayMessage="segmento do cliente" name="610cb87616f79a30b457e44c" nro="610cb89b16f79a30 b457e456" pedido = "1" printerMessage="segmento do cliente" prorationMethod="PROPORCIONAL" unit="qty">
        <aplicar>
          <item magnitude="0.000" qty="1.000" seq="1" value="2500" valueWithTaxes="2500" xprice="5000"/>
        </aplicar>
      </benefício>
    </promo>
  </opcional>
</mensagem>

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

Request

<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)

Request

<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)

Request

<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

gengine.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.

Response OK

<?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" )

Response ERROR

<?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.

Ejemplo

<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:

Request

<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

Ejemplo

<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:

Request

<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

Obs: Neste exemplo foi definida uma promoção com benefício monetário fixo de 100, e com limite monetário de 300 por cliente, ou seja, neste caso, se o cliente fizer mais de 3 transações, na 4ª não não se aplicam por ter excedido o limite configurado na promoção.

Aqui está como operar:

Request LoyaltyValidation Limites por Clientes

<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>

Response LoyaltyValidation Limites por Clientes

<?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.

Request Sales Limites por Clientes

<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.

Response sales Limites por Clientes

<?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

Request finish Limites por Clientes

<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>

Response finish Limites por Clientes

<?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

Request commit Limites por Clientes

<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>

Response commit Limites por Clientes

<?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.

Request LoyaltyValidation Limites por Clientes

<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>

Response LoyaltyValidation Limites por Clientes

<?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.

Ejemplo de request de Prices

<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

Ejemplo de Response de Prices

<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

Request

<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.

Response

<?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 :

Request

<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>

Response

<?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

Request

<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>

Response

<?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
1. o cabeçalho
  1. Configure que uma resposta é esperada (usando o atributo response ).
  2. Configure que o Mecanismo deve calcular as promoções (usando o atributo de avaliação ).
  3. Configure se um novo ticket for iniciado (limpe o contexto associado à sessão, usando o atributo init-tck )
2. o corpo
  1. todos os itens da transação, de acordo com o formato estabelecido.
  2. todos os eventos da transação, de acordo com o formato estabelecido.
  3. todos os clientes da transação, de acordo com o formato estabelecido.
  4. todos os meios de pagamento da transação, de acordo com o formato estabelecido.
  5. todos os cupons da transação, de acordo com o formato estabelecido.
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.

RedeemOptions

<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

**O id do elemento opção é gerado a partir do motor com o id do benefício concatenado com "_" mais um índice (por exemplo " 5db9b4afa171f2314ce5704e_1 ", onde o código 5db9b4afa171f2314ce5704e é o identificador do benefício e o 1 representa a segunda opção do mesmo começa de 0), foi definido assim para evitar, que o item da mensagem seja aplicado a duas opções simultaneamente. Visto que na geração do código fonte do benefício na engine não existe um identificador por promoção que permita a unicidade de promotion_beneficio_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

Request SALE

<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:

Response SALE

<?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)

Request SALE con 1 opción Seleccionada

<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

Msg con 2 opciones Seleccionadas

<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>

Response Applies Seleccionados

<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.

Mensaje Seleccionando Opciones y Cliente con saldo insuficiente

<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.

Respuesta Puntos Insuficientes

<?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>

Mensaje Seleccionando Opciones con una seleccion 0

<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

Respuesta Puntos Insuficientes

<?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

O id identificador do elemento opção é gerado a partir do motor com o id do benefício concatenado com "_" mais um índice (por exemplo " 5db9b4afa171f2314ce5704e_1 ", onde o código 5db9b4afa171f2314ce5704e é o identificador do benefício e o 1 representa a segunda opção do próprio start de 0), foi definido assim para evitar que o item mensagem seja aplicado a duas opções simultaneamente. Visto que na geração do código fonte do benefício na engine não existe um identificador por promoção que permita a unicidade de promotion_beneficio_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

Se as 6 validações anteriores não forem atendidas, o cálculo do benefício será 0 para o referido item (valor="0")

Árvore de páginas

PROMO 7.2 - Manual de Integração - Motor PT

Sobre o manual

Finalidade e âmbito

Documentação da PROMOÇÃO

Introdução à Integração

Comunicação com o Motor de Promoções

servidor TCP/IP

servidor REST

modo GET

Modo POST

sessões

Mecanismo: solicitação do mecanismo

Cabeçalho

Corpo

atributos de comando

Desconto condicionado a uma cota

resposta do motor

Cabeçalho

Valores do atributo "ack"

Corpo

Opções

promoções

participantes da condição

Benefícios

tipos de benefícios

Promoções escalonadas

participantes do combo

elementos aplicados

itens não aplicados

Elemento de Resgate - Resgatar com Opções

Sugestões

promoções sugeridas

Sugestões sujeitas a stock

Fidelidade

Novos status em <Loyalty>

Validação de Lealdade

Ativação de Fidelidade

Criar itens de fidelidade

Alteração e reinicialização do CVV ​​de um elemento de fidelidade (CVVCHANGE e CVVRESET)

Transferência de Fidelidade

LealdadeVazio

LoyaltyAssign

TERMINAR

COMPROMETER-SE

REVERSÃO

Solicitação de transação

RetornoFinalizar

Reembolso total

Validação de Resgate de Catálogo

Fidelidade: resposta do motor

Resposta - Validação de Lealdade

Resposta - Cupons

Resposta - Elementos de Lealdade

Resposta - Ativação do elemento de fidelidade (em LoyaltyActivation)

Resposta - Ativação do elemento de fidelidade (em acabamento)

Resposta - Transferência de Fidelidade

Resposta - LoyaltyVoid

Atribuição de saldos em elementos de fidelização

Desconto de saldo no elemento de fidelidade

Elementos de fidelidade: processo de atualização de saldo

Resposta do mecanismo: erros de tag

Lealdade: status estendidos

VALIDAÇÃO DE LEALDADE EX

FINISHEX

Ferramenta de métricas de fidelidade

Fluxos de itens de fidelidade

Registro de elemento de fidelidade

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

Clientes

Operação com Segmentos

Criar Clientes (Nota: Somente se a operação sem clientes pré-existentes estiver habilitada)

Operação (com base em cenários possíveis):

Saldos por acordos

Alteração e reinicialização do CVV de um elemento de fidelidade (CVVCHANGE e CVVRESET)