PROMO - Manual de Integração 6.5
Sobre o manual
Objetivo e escopo
O objetivo deste manual é treinar usuários que desejam integrar seus aplicativos de vendas ao Motor de Promoção.
É fornecida uma descrição detalhada das mensagens que devem ser enviadas a ele e como interpretar as mensagens de resposta que serão fornecidas mediante solicitação.
Documentação PROMO
A PROMO fornece a seguinte documentação:
- Manual de usuário:
Este documento destina-se a treinar o usuário que deseja usar o console de administração de promoções da PROMO.
- Manual de instalação:
Este documento descreve os procedimentos para instalar os componentes do mecanismo e do console, a criação e a inicialização do banco de dados e os requisitos necessários para a operação correta desses componentes.
- Manual de integração:
Este documento descreve em detalhes as mensagens que devem ser enviadas ao Mecanismo de Promoção e como interpretar as mensagens de resposta que serão fornecidas quando solicitadas.
Nota: Antes de continuar com a leitura deste manual, é recomendável ler os capítulos 2 e 3 do Manual do Usuário.
Introdução à integração
O Motor do Promo é o componente PROMO encarregado de receber solicitações do ponto de venda e, em seguida, responder a elas. Essa interação será realizada através de uma série de mensagens no formato XML que seguem um protocolo de comunicação definido. Nesse sentido, o mecanismo de promoções pode funcionar como um servidor TCP / IP ou como um servidor REST, dependendo das necessidades, preferências e requisitos tecnológicos do ponto de venda.
Por outro lado, há casos em que a interação com os bancos de dados pertencentes ao console é necessária, como consultas diretas a itens de fidelidade existentes (exemplo: cupons e cartões existentes). Para esses casos, o console do Promo é responsável por expor uma série de serviços para expor ou fornecer essas informações a sistemas externos. Essa forma de integração, como você notará, na verdade tem objetivos muito diferentes do primeiro e é abordada em uma seção especial neste documento.
A seguir, descreveremos as duas opções de integração com o mecanismo de promoção mencionado acima.
Comunicação com o mecanismo de promoções
Como mencionado anteriormente, a maneira de comunicar com o Motor de Promoção é através do sistema de mensagens XML apresentado posteriormente neste documento. Essas mensagens usam duas formas de comunicação como transporte:
SERVIDOR TCP / IP
Um dos protocolos mais comuns hoje. Permite roteamento e remessa 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:
- Cabeçalho : 6 bytes que indicam o número de bytes que o corpo da mensagem enviada ao mecanismo de promoção terá.
- Mensagem : mensagem enviada ao Mecanismo de Promoção no formato XML descrito neste documento.
SERVIDOR REST
REST (Representational State Transfer) é um estilo de arquitetura usado em aplicativos de rede distribuídos. Ele é baseado em protocolos stateless cliente-servidor e, como no caso do PROMO, é implementado principalmente usando o protocolo HTTP. A idéia é uma alternativa simples ao uso de mecanismos mais complexos, como CORBA, RPC ou SOAP.
O mecanismo de promoção é apresentado aqui como um servidor HTTP aguardando conexões em uma determinada porta TCP / IP.
Para usar essa forma de comunicação, o aplicativo cliente deve enviar solicitações HTTP e aguardar as respostas correspondentes. O formato de chamada ou uso é: (pode ser feito em um navegador como FireFox, Chrome etc.)
http: // servidor: port / engine / assessment? Request = message
Onde:
- http: // server: port : é o URL para acessar o servidor em que o mecanismo PROMO está em execução.
- message : é a mensagem correspondente a ser avaliada pelo mecanismo, conforme especificado neste documento.
Apresentaremos vários exemplos aqui usando dois clientes: o navegador Firefox e o aplicativo "curl" de domínio público ( https://curl.haxx.se/ ). Portanto, assumimos que precisamos enviar a seguinte mensagem para ser avaliada pelo mecanismo:
<message companyId="sts" store="9905" terminal="001" date-time="2016-11-20 23:01" messageId="0001" void-trx="false" suggest="true" response="true" init-tck="true" evaluate="true" msg-version="2.4" status="init" ><item-add seq="1" unitprice="1" xprice="1" qty="1" magnitude="1" code="P001" discountable="true"/><font></font> </message>
Ao mesmo tempo, o servidor em que o mecanismo PROMO está disponível é http://demoserver.net e porta 3625.
No Firefox, o 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" suggest="true" response="true" init-tck="true" evaluate="true" msg-version="2.4" status="init" ><item-add seq="1" unitprice="1" xprice="1" qty="1" magnitude="1" code="P001" discountable="true"/><font></font> </message>
Isso em uma única linha, como visto na figura a seguir. De acordo com os resultados da avaliação do mapa, você verá uma resposta no navegador como: Da mesma forma, outro exemplo é fazer a mesma coisa, mas usando curl. Nesse caso, o comando é enviado pela linha de comando da seguinte maneira:
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, o que, no caso do Firefox, o navegador cuida dessa conversão automaticamente.
A figura a seguir mostra o exemplo completo com a solicitação e a resposta. Alguns dados relacionados ao servidor em que ele foi executado foram apagados, pois não seguem o exemplo.
Sessões
Antes de começar com a descrição da mensagem usada para enviar solicitações ao Mecanismo de Promoções, é necessário apresentar ao leitor o tratamento das sessões que ele realiza.
Uma sessão é um espaço reservado no mecanismo de promoções para o tratamento de informações relacionadas a uma transação. Dessa maneira, é capaz de lidar com várias transações simultaneamente, tendo uma sessão para cada uma delas. Podemos assimilar esse conceito com a abertura de uma transação que começou a ser realizada no ponto de venda e que incorporará elementos até o seu fechamento.
A sessão é identificada pela concatenação dos seguintes campos contidos no cabeçalho da mensagem (explicado na próxima seção):
SessionId = CompanyId + Store + Terminal
Ao iniciar uma nova sessão, os dados correspondentes da transação ficarão vazios e poderão ser concluídos conforme indicado abaixo, ou seja, apenas uma transação sem elementos será reservada, mas com os dados do cabeçalho, como o data e hora do mesmo, mais a loja e o terminal onde ocorre.
Da mesma forma, a sessão terá um tempo limite configurável (tempo de expiração) que, uma vez decorrido sem que nenhuma recepção de mensagem seja gravada, fará com que a sessão seja excluída automaticamente, tornando necessário abrir um novo e, se você continuar com a transação, o encaminhamento dos dados que a sessão expirada continha. Consulte o manual de instalação e configuração para obter mais detalhes.
Deve-se observar pelo que foi visto até agora, que ambos optam por comunicações com o mecanismo de promoção em seu servidor TCP / IP e REST, ambos usam o mesmo sistema de mensagens que será apresentado neste documento e que foi chamado de "MENSAGEM" em ambos. casos.
Motor: solicitação do motor
Mencionamos anteriormente que o mecanismo de promoções é o componente PROMO encarregado de receber solicitações do ponto de venda e, em seguida, responder a elas. Essa interação ocorrerá através de uma série de mensagens no formato XML que seguirão uma série de regras definidas.
Importante: Observe que se caracteres que não pertencem ao alfabeto inglês ou caracteres XML reservados (como '>', '<', '"') são encontrados no ticket, não é garantido que eles sejam interpretados corretamente por o mecanismo de promoções.
<message ... propiedades del encabezado ...><font></font> <font></font> ... elementos del cuerpo del mensaje ...<font></font> <font></font> </message><font></font> <font></font>
Cabeçalho
Como mencionado acima, as mensagens enviadas ao Mecanismo de Promoção estarão em XML. O elemento raiz dessa mensagem XML deve ser a tag <message>, sendo chamada de cabeçalho, e conterá uma série de atributos que serão usados pelo Mecanismo de Promoção para saber a hora e o local da transação, se deve ou não iniciar uma nova sessão, etc. Contidos nesta tag, estarão os comandos que você deseja executar no mecanismo, que formarão o corpo da mensagem, um tópico desenvolvido na seção a seguir.
Os atributos que o cabeçalho pode ter são:
Propriedade | Tipo de dados | Descrição do produto | Obrigatório | Valor na ausência |
companyId | Alfanumérico | Identifique a empresa que envia a mensagem | Sim | |
loja | Alfanumérico | Identifica o local que envia a mensagem. | Sim | |
terminal | Numérico | Identifique o terminal emissor | Sim | |
data e hora | AAAA-MM-DD HH: MM: SS | Data e hora da mensagem. ( date-time = "2017-03-21 15:20:26" ) | Sim | |
messageId | Numérico positivo | Identifica cada uma das mensagens enviadas pelo terminal, esse número sendo usado pelo Motor de Promoção como um identificador ao enviar uma resposta. | Sim | |
void-trx | Booleano | Indica se a transação é um retorno. | Não | "false" |
resposta | Booleano | Indica se você deseja que o mecanismo responda à mensagem enviada. | Não | "false" |
init-tck | Booleano | Indica se uma nova sessão deve ser iniciada com esta mensagem. | Não | "false" |
avaliar | Booleano | Instrui o mecanismo a calcular promoções usando os elementos inseridos até o momento. | Não | "false" |
status | Alfanumérico | Indica o estado do ponto de venda
| Não | "" |
msg-version | Alfanumérico | Indica a versão da mensagem em questão | Não | "" |
versão do mapa | Número inteiro positivo | Diz ao mecanismo qual mapa usar. Só fará sentido se o valor de "void-trx" for verdadeiro. | Não | "" |
sugerir | Booleano | Diz ao mecanismo se deve ou não sugerir promoções. Se sugestão-seq e tipo-seq-tipo não estiverem presentes, todo o contexto será usado para fazer a sugestão. | Não | "false" |
Suggest-seq | Numérico | Indica o número de sequência no qual o mecanismo fará a sugestão, caso o atributo sugira = "true". Este atributo será acompanhado pelo tipo de sugestão-seq, que, se não for especificado, será assumido como sugestão-seq-type = "item" | Não | "1" ou nulo |
tipo de sugestão-seq | Alfabética | Indica o tipo de linha na qual a sugestão deve ser feita, caso o atributo sugere = "verdadeiro". Este atributo será acompanhado pela sugestão-seq, que se não for especificada, será assumida sugget-seq = "1". Os valores que esse atributo pode receber são: item, cupom, pagamento, evento, cliente. | Não | "item" ou nulo |
sugerir por tipo | Booleano | Ele informa ao mecanismo se eles devem sugerir promoções, levando em consideração o tipo de conjunto que participa da 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 sugerem, tipo sugestão-seq e tipo sugestão-seq serão ignorados. | Não | "false" |
tipo de filtro sugerido | Alfabética | Indica o tipo de conjunto de promoções que deve ser considerado para a sugestão se o atributo sugerir por tipo = "true". Os valores que esse atributo pode receber são: item, cupom, pagamento, evento, cliente. Se não estiver presente, todos os tipos definidos serão assumidos. | Não | "nulo" |
sugestão estendida | Booleano | Ele informa ao mecanismo se deve exibir as informações de benefícios para cada promoção sugerida. Se sugestão for falsa, o valor desse campo é irrelevante. | Não | "false" |
offline | Booleano | Indica ao mecanismo que a transação será processada no modo offline, ou seja, no caso de uma contingência de comunicação com a PROMO Central, ela será armazenada para remessa subsequente. | Não | "false" |
originalTransaction | Alfabética | No caso de um valor de status = requestTransaction, essa propriedade indicará a transação que deve ser consultada | Não | "" |
| selectedOption | Positividade de número inteiro | Caso o resultado da avaliação tenha resultado em uma série de opções (vários blocos "opcionais"), esse atributo permite que o sistema externo informe o mecanismo Promo, qual dessas opções foi a que foi finalmente aplicada ou concedida ao cliente. O valor é baseado em 0, ou seja, a primeira opção é o número 0, a seguir é o número 1 e assim por diante. | Não | 0 0 |
| tenderGroupCode | Alfabética | Ao usar avaliadores, se o valor "cr" for enviado, o preço será devolvido a crédito, no caso de outro valor ou se não for enviado, o preço de venda será retornado. | Não | "" |
| canal | Alfabética | Armazene o canal de onde a operação é realizada. | Não | "" |
| storeChain | Alfabética | Cadeia de lojas. | Não | "" |
| formato | Alfabética | Formato da loja | Não | "" |
| zona | Alfabética | Área à qual a loja pertence | Não | "" |
| subzona | Alfabética | Subzona à qual a loja pertence | Nã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" evaluate="true" status="payment" msg-version="2.0" map-version="15"><font></font> <font></font> ... cuerpo del mensaje ...<font></font> <font></font> </message><font></font>
<message companyId="sts" store="00001" terminal="010" date-time="2017-12-04 12:30:50:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="payment" msg-version="2.0" map-version="15" suggest="true" suggest-seq="3" suggest-seq-type="payment"><font></font> <font></font> ... cuerpo del mensaje ...<font></font> <font></font> </message><font></font> <font></font>
<message companyId="sts" store="00001" terminal="010" date-time="2017-12-04 12:30:50:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="payment" msg-version="2.0" map-version="15" suggest-per-type="true" suggest-filter-type="coupon"><font></font> <font></font> ... cuerpo del mensaje ...<font></font> <font></font> </message><font></font> <font></font>
<message companyId="sts" store="00001" terminal="010" date-time="2017-12-04 12:30:50:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="payment" msg-version="2.0" map-version="15" suggest="true" suggest-extended="true"><font></font> <font></font> ... cuerpo del mensaje ...<font></font> <font></font> </message><font></font> <font></font>
Corpo
O corpo da mensagem enviada ao Mecanismo de Promoção será composto pelos comandos que você deseja executar. Basicamente, os comandos podem ser de dois tipos:
Acção | Descrição do produto |
adicionar | Adicione o item à sessão. |
vazio | Exclua o item da sessão. O item é identificado pelo número de sequência. |
Esses 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 do produto |
item | Identifique os artigos. |
cupom | Identifique os cupons. |
cartão de fidelidade | Identifique cartões de fidelidade. |
pagamento | Identifique os meios de pagamento. |
evento | Identifique eventos ou outros elementos não representados pelos outros tipos. |
cliente | Identifique clientes. |
A maneira de executar um comando é usar uma tag no formato < command-element >.
Dessa forma, se você quiser, por exemplo, adicionar um novo artigo à sessão, o comando a ser usado será < item-add >, se você desejar cancelar um cupom adicionado anteriormente, será enviado um comando do tipo <coupon-void> etc.
No 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.
Você também pode enviar uma mensagem sem comandos, por exemplo, solicitando a avaliação de um ticket.
ATRIBUTOS DE COMANDO
Cada um dos comandos enviados ao Mecanismo de Promoção possui atributos diferentes, que identificam o elemento que está sendo enviado e definem várias propriedades que eles possuem. Ambos suplemento , como vazio irá possuir um número sequencial que identifica univocamente cada elemento:
Propriedade | Tipo de dados | Descrição do produto | Obrigatório |
seq | Número 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 removido.
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 acima). Dependendo do elemento em questão, os atributos serão os seguintes:
Elemento | Propriedade | Tipo de dados | Descrição do produto | Obrigatório | Valor na ausência |
Item | preço unitário | Numérico positivo | Preço unitário do item em questão. | Sim | |
xprice | Numérico positivo | Preço estendido do item em questão. É igual à quantidade vezes o preço unitário. | Sim | ||
qtde | Número inteiro positivo | Quantidade de artigos na linha. | Sim | ||
magnitude | Numérico positivo | Se o item for mensurável por outra unidade que não a quantidade, ele deverá ser expresso nesta propriedade. | Não | 0 0 | |
código | Alfanumérico | Código do artigo. | Não | "-" | |
marca | Alfanumérico | Marca do item. | Não | "-" | |
fornecedor | Alfanumérico | Fornecedor ao qual o item pertence. | Não | "-" | |
com desconto | Alfanumérico | Se o item for, você pode receber descontos ou não. | Não | "-" | |
level1 | Alfanumérico | Nível 1 de categorização do artigo. Anteriormente, esse nível era conhecido como Departamento. | Não | "-" | |
level2 | Alfanumérico | Nível 2 de categorização do artigo. Esse nível era conhecido anteriormente como a família de itens. | Não | "-" | |
level3 | Alfanumérico | Nível 3 de categorização do artigo. Esse nível era conhecido anteriormente como Categoria de Item. | Não | "-" | |
level4 | Alfanumérico | Nível 4 da categorização do artigo. Esse nível era conhecido anteriormente como subcategoria do artigo. | Não | "-" | |
| descontínuo | booleano | Determinar se o produto é descontínuo | Não | falsa | |
| lowTurnover | booleano | Determinar se o produto é de baixa rotatividade | Não | falsa | |
| keyProduct | booleano | Determinar se o produto é um produto estrela | Não | falsa | |
Cupon | quantidade | Numérico positivo | É usado para indicar o valor monetário do cupom. Se não tiver, não será usado. | Não | 0 0 |
tipo | Alfanumérico | Tipo de cupom. | Não | "-" | |
qtde | Número inteiro positivo | Quantidade | Não | 1 | |
vai | Alfanumérico | Identificador de cupom. | Não | "-" | |
LoyaltyCard | tipo | Alfanumérico | Tipo de cartão de fidelidade | Não | "-" |
vai | Alfanumérico | Identificador de cartão de fidelidade | Sim | "-" | |
quantidade | Numérico positivo | Saldo do cartão de fidelidade | Não | 0 0 | |
chargeAmount | Numérico positivo | Saldo a ser creditado em um cartão de fidelidade | Não | 0 0 | |
consumeAmount | Numérico positivo | Saldo para debitar um cartão de fidelidade | Não | 0 0 | |
status | Alfanumérico | ATIVADO ou DESATIVADO para ativar ou desativar um cartão de fidelidade (válido apenas no status LoyatyActivation) | Não | " ATIVADO " | |
Cliente | tipo | Alfanumérico | Tipo de cliente. | Não | "-" |
vai | Alfanumérico | Identificador do cliente. | Não | "-" | |
remanescente | Numérico positivo | Propriedade que pode ser usada para indicar o saldo a favor ou contra o cliente em questão. (compatibilidade com o PROMO 4 e versões anteriores) | Não | 0 0 | |
pontos | Número inteiro positivo | Equilibre o cliente possui. (compatibilidade com o PROMO 4 e versões anteriores) | Não | 0 0 | |
Alfanumérico | Atributo incluído para consulta do cliente | Não | "" | ||
nome | Alfanumérico | Atributo incluído para consulta do cliente | Não | "" | |
lastName | Alfanumérico | Atributo incluído para consulta do cliente | Não | "" | |
Identificador | Numérico positivo | Atributo incluído para consulta do cliente | Não | "" | |
cardNumber | Numérico positivo | Atributo incluído para consulta do cliente | Não | "" | |
creditCampaignCode | Alfanumérico | Código da campanha de crédito | Não | "" | |
profileCode | Alfanumérico | Código do perfil do cliente | Não | "" | |
| segmento | Alfanumérico | Lista de códigos de segmento aos quais o cliente pertence, separados por; | Não | "" | |
remanescente | Numérico positivo | Propriedade que pode ser usada para indicar o saldo a favor ou contra o cliente em questão. (compatibilidade com o PROMO 4 e versões anteriores) | Não | 0 0 | |
| quantidade | Numérico positivo | Propriedade que pode ser usada para indicar o saldo correspondente a um cliente | Não | 0 0 | |
"Pagamento Os atributos valor e itemamount são exclusivos e seu uso depende da versão da promoção codificada | tipo | Alfanumérico | Tipo de método de pagamento. | Não | "-" |
vai | Alfanumérico | Identificador de pagamento. | Não | "-" | |
planejar | Alfanumérico | Plano de método de pagamento. | Não | "-" | |
quantidade | Numérico positivo | Dinheiro usado com esse meio de pagamento. Como o valor do pagamento (PA) é calculado como PA = PIA (1% de desconto) ou PA = PIA * (sobretaxa de 1 +%) *, | Não | 0 0 | |
banco | Alfanumérico | Banco relacionado aos meios de pagamento. | Não | "-" | |
itemamount | Numérico positivo | Dinheiro que representa a quantidade de itens que você deseja pagar. | Não | 0 0 | |
balançado | Booleano | Indica se o saldo da transação é cancelado com este método de pagamento.Se o valor for verdadeiro, não será necessário enviar o valor ou o valor. | Não | falsa | |
Evento | tipo | Alfanumérico | Tipo de evento. | Não | "-" |
vai | Alfanumérico | Identificador de evento. | Não | "-" | |
valor | Alfanumérico | Valor que representa o evento. | Não | "-" | |
seqItem | Alfanumérico | Número de sequência dos itens aos quais o desconto deve ser aplicado. Se o atributo não vier ou ficar vazio, presume-se que seja para o ticket inteiro. No caso de ter várias seqüências, elas devem ser separadas por vírgulas. Se qualquer sequência tiver mais de uma quantidade, ela deverá ser concatenada com um =. Exemplo: 1 = 2,2,3 = 3 (indica que o desconto é aplicado a dois elementos da sequência um, um da sequência dois e três da sequência 3 | Não |
Nota: O número da sequência deve ser exclusivo para cada tipo de elemento, por exemplo, um cliente e um item podem ter a 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á usado por um elemento do mesmo tipo, o último enviado substituirá o anterior.
Exemplo:
A seguir, é apresentado um exemplo de mensagem que adiciona um item e uma forma de pagamento (ambos com a sequência " 1 ") à sessão do Mecanismo de Promoção e remove um cupom (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" evaluate="true" status="payment" msg-version="2.0" map-version="15"><font></font> <item-add seq="1" code="0001" discountable="true" unitaryPrice="25.0" qty="1.0" level1="MEN" level2="CASUAL" supplier="" brand="LEVIS" xPrice="25.0" magnitude="1.0" /><font></font> <payment-add seq="1" type="CreditCard" amount="" id="000009" planId="10"/><font></font> <coupon-void seq="2" /><font></font> <loyaltycard-add seq="5" id="3330000000222" type="puntos" /><font></font> </message><font></font>
Resposta do mecanismo
Esta seção descreverá a estrutura e a interpretação da mensagem de resposta que o Motor de Promoção entregará.
Como mencionado anteriormente, assim como a mensagem de solicitação, a mensagem de resposta que o Mecanismo de Promoção oferece terá um formato XML e consistirá em um cabeçalho e um corpo. O cabeçalho conterá informações sobre o terminal ao qual está respondendo, erros que possam ter ocorrido e a versão do mecanismo.
No corpo da mensagem, você encontrará as promoções a serem aplicadas ou sugeridas, os artigos a serem beneficiados etc. Caso não haja promoções a serem aplicadas ou sugeridas ou que a avaliação ou sugestão não tenha sido solicitada, a mensagem de resposta consistirá apenas no cabeçalho.
Cabeçalho
Como na mensagem de solicitação, o elemento raiz da resposta será a tag < message > , também chamada de cabeçalho de resposta. Ele conterá atributos que indicam a loja e o terminal ao qual é endereçado, identificação da mensagem, versão do mapa e o Mecanismo com o qual a avaliação foi realizada, e código de retorno ( reconhecimento ); todos eles sendo enviados com obrigação:
Propriedade | Tipo de dados | Descrição do produto |
mapversion | Alfanumérico | Versão do mapa usado para avaliar promoções. |
companyId | 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 | Inteiro | O mesmo que foi enviado na mensagem de solicitação. |
messageId | Inteiro | O mesmo que foi enviado na mensagem de solicitação. |
motor | Alfanumérico | Versão do mecanismo de promoção que realizou a avaliação. |
ack | inteiro | Código de retorno (consulte a próxima seção). |
transação | Alfanumérico | Código que identifica a transação na PROMO central (relatada apenas com a resposta a um status de lealdade) |
VALORES DO ATRIBUTO "ACK"
Atributo confirmado Em inglês, ack é um atributo no 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, esse atributo terá um valor específico:
Valor de confirmação | Descrição do produto | Ação recomendada |
0 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, volte a validar seu formato. |
2 | A sessão não foi inicializada ou não existe. | Faça o login conforme as instruções em " Gerenciamento de sessão " . |
3 | Erro de validação na mensagem. | Revalide o formato da mensagem. O arquivo de log do mecanismo também pode ser consultado para estabelecer com mais precisão qual foi o erro. |
2001 | Erro de avaliação. | Entre em contato com o administrador do mecanismo de promoções para que o erro seja estabelecido por meio do arquivo de log. |
2002 | Não existe um mapa válido para calcular o ticket ou a 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 novamente a remessa. |
2004 | Erro de instanciação da sessão geral. | Entre em contato com o administrador do Motor de promoções para monitorar o equipamento em que o mecanismo está em execução. |
2005 | Tempo limite da sessão. A sessão expirou. | Se, durante a avaliação da sessão, ela terminar com o tempo limite, uma mensagem será enviada com o reconhecimento de 2005. Aguarde e tente enviar novamente. |
4001 | A avaliação da sugestão falhou. | Entre em contato com o administrador do mecanismo de promoção para que o erro seja estabelecido por meio do arquivo de log. Geralmente, esse erro pode estar relacionado a um tipo de sugestão-seq ou sugestão-seq-inválido ou algum outro erro na avaliação de sugestões. |
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 recuperar a transação original, mas não enviar o que é. | Revise a conformação da mensagem enviada da pos para a PROMO Central para verificar a existência do atributo originalTransaction. |
8299 | Erro genérico no envio para o PROMO central. | Entre em contato com o administrador da PROMO para monitorar o equipamento em que o console da PROMO está operando. |
A partir do PROMO 5, foram adicionadas as séries de erros 9xxx que se aplicam aos erros produzidos no processamento do PROMO Central Console.
Esses erros são:
| 1 | Valor de confirmação | Descrição do produto | Ação recomendada |
| 2 | 9000 | A mensagem não possui um ticket associado. | Reenvie a mensagem e, se o erro persistir, volte a validar seu formato. Verifique a sequência em que as mensagens estão sendo 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 = confirmação / reversão deve ser enviada para finalizar a transação anterior. |
| 4 | 9002 | Não há transação pendente. Uma mensagem com status = confirmação ou reversão foi recebida, mas não havia transação anterior pendente. | Revise as mensagens que estão sendo enviadas para o mecanismo, principalmente em sua sequência lógica. |
| 5 | 9003 | As informações de uma transação anterior foram solicitadas, mas o identificador da mesma não foi relatado. | Verifique se a propriedade originalTransaction tem um valor e é válido. |
| 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 loyaltyTransfer, se o console estiver no modo offline, essa operação não poderá ser executada. Entre em contato com o administrador da PROMO para verificar o computador em que o console da PROMO está sendo executado. |
| 8 | 9006 | Trabalho de conclusão de 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 | 9101 | Cupom não encontrado | Verifique os dados solicitados |
| 11 | 9102 | Cupom consumido | Verifique se o cupom não foi usado |
| 12 | 9103 | Cupom inativo | Verifique se o cupom solicitado está ativo. |
| 13 | 9104 | Tipo de cupom não encontrado | Verifique o valor relatado na mensagem. |
| 14 | 9105 | O cupom expirou. | A data de vencimento do cupom foi atingida, verificando essa situação. |
| 15 | 9106 | O número máximo de usos foi atingido | Verifique esta situação |
| 16 | 9107 | O cupom foi indicado e nenhum cliente foi relatado | Verifique esta situação |
| 17 | 9108 | O tipo de cupom não está ativo | Verifique o tipo de cupom |
| 18 | 9109 | O valor enviado não corresponde ao valor do cupom | Verificar o valor do cupom |
| 19 | 9110 | Cupom não usado | O cupom inserido na transação não participou de nenhuma promoção. |
| 20 | 9201 | Cabeçalho da transação não encontrado. | Geralmente devido a um erro interno, verifique com o administrador do sistema. |
| 21 | 9500 | Cartão de fidelidade não encontrado | Verifique os dados solicitados |
| 22 | 9501 | Cartão de fidelidade desativado | Verifique os dados solicitados. Para algumas ações, apenas os cartões de fidelidade ativados podem ser processados |
| 23 | 9502 | Cartão de fidelidade cancelado | Verifique os dados solicitados. Não foi possível interagir com os cartões de fidelidade cancelados |
| 24 | 9503 | Tipo de cartão de fidelidade não encontrado | Verifique os dados solicitados |
| 25 | 9504 | Tipo de cartão não ativo | Verifique os dados solicitados. Não é possível interagir com tipos de cartão inativos |
| 26 | 9505 | Tipo de cartão não recarregável | Verifique os dados solicitados. Para opções de carga ou recarga, o tipo de cartão deve ser recarregável |
| 27 | 9506 | O cartão já tem um cliente associado | Verifique se o cartão na ativação que o cliente enviou. |
| 28. | 9507 | O status do cartão enviado não existe. | Verifique se um status válido do cartão foi enviado, após a ativação, (ATIVADO, DESATIVADO) - Capitalizado - |
| 29 | 9508 | O cartão não se aplica ao benefício | Verifique se o tipo de cartão é recarregável ou se o cartão está ativado. Outro erro pode ser que o tipo de cartão com o qual o benefício foi armado esteja inativo ou não exista na transação. |
| 30 | 9509 | O cartão requer um cliente | Verifique se o tipo de cartão é necessário, pelo menos um cliente deve viajar na transação. |
| 31 | 9510 | Cartão não autorizado | Isso ocorre se o tipo de cartão requer CVV e não foi enviado ou inserido incorretamente |
| 32. | 9511 | Montante inválido | Quando você tenta descontar um valor maior que o total do valor do cartão, essa mensagem será exibida. Verifique se o valor é menor que o total. |
| 33 | 9512 | São necessários pelo menos dois cartões | Esta mensagem é usada para transferências. Dois cartões são necessários na mensagem. A origem em Seq = "1" e o destino em Seq = "2" |
| 34 | 9513 | O cartão não suporta transferência. | Verifique se o cartão de origem suporta transferência. Parcial ou total. |
| 35 | 9514 | O cartão de destino está ativo | Verifique se o cartão de destino está inativo para fazer uma transferência total. |
| 36. | 9515 | Os tipos de cartão não são os mesmos | Verifique se os tipos de cartão são iguais, ou seja, iguais. |
| 37. | 9516 | O saldo inserido é maior que o limite do saldo | Verifique se o valor inserido para carregar um cartão não é maior que o Limite de saldo do tipo de cartão. |
| 38. | 9603 | Cliente inexistente | Verificar dados do cliente inseridos na transação |
| 39. | 9610 | identificador de cliente vazio | Verificar dados do cliente inseridos na transação |
| 40. | 9611 | Nome do cliente vazio | Verificar dados do cliente inseridos na transação |
| 41. | 9612 | Sobrenome do cliente vazio | Verificar dados do cliente inseridos na transação |
| 42. | 9613 | ID do cliente vazio | Verificar dados do cliente inseridos na transação |
| 43 | 9614 | Nenhum parâmetro de cliente recebido | Verificar dados do cliente inseridos na transação |
| 44 | 9620 | Cliente existente | Verificar dados do cliente inseridos na transação |
| 45 | 9629 | Cliente inativo | Verificar dados do cliente inseridos na transação |
| 46. | 9901 | Erro de cupom inesperado. | Qualquer erro relacionado ao processamento de cupons não tipificado nos códigos anteriores. Consulte o administrador do sistema. |
| 47 | 9999 | Erro inesperado | Qualquer erro no processamento do PROMO Central que não é tipificado nos casos anteriores. |
Importante: Si se produce un error en la evaluación de las sugerencias y durante la evaluación de las promociones, existen una o más promociones que fueron aplicadas satisfactoriamente, entonces, éstas son informadas con un ack 4001
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="4001"><font></font> <optional><font></font> <font></font> … promociones que componen la opción …<font></font> <font></font> </optional><font></font> <optional><font></font> <font></font> … promociones que componen la opción …<font></font> <font></font> </optional><font></font> </message><font></font> <font></font>
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"><font></font> <loyalty><font></font> <loyaltycards/><font></font> <coupons/><font></font> <errors/><font></font> </loyalty><font></font> </message><font></font>
Corpo
O corpo da mensagem de resposta fornecida pelo Mecanismo de Promoção 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 de uma ou mais promoções
- Cada promoção conterá participantes com condição (podem não ser informados)
- Cada promoção será composta de um ou mais benefícios
- Cada benefício conterá participantes do combo (pode estar vazio)
- Cada benefício também conterá os elementos do item aplicado (pode estar vazio)
- Cada opção será composta de uma ou mais promoções
- Um conjunto de sugestões (esta parte do conteúdo pode não estar presente)
- As sugestões são compostas por uma ou mais promoções
- Descrição, nome, sequências e tipos de sequência que deram origem à sugestão serão relatados para cada promoção.
- As sugestões são compostas por uma ou mais promoções
No caso de avaliações a serem realizadas na PROMO Central, a composição da resposta será:
- Um elemento de fidelidade
- Cada elemento de fidelidade pode ser composto de um ou mais elementos de fidelidade (cupons e / ou cartões)
- Cada cupom conterá os detalhes para emissão (opcional, essas informações podem não existir)
- Cada cartão conterá os detalhes do cartão
- Cada elemento de fidelidade também pode ser composto de erros
- Cada elemento de fidelidade pode ser composto de um ou mais elementos de fidelidade (cupons e / ou cartões)
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á reporta as combinações possíveis. As opções são representadas com a tag < opcional >. Se não houver opções, o corpo da mensagem de resposta consistirá em uma única opção, ou seja, haverá apenas uma tag < opcional > que conterá as promoções a serem aplicadas. Esta tag não possui atributos.
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <font></font> … promociones que componen la opción …<font></font> <font></font> </optional><font></font> <optional><font></font> <font></font> … promociones que componen la opción …<font></font> <font></font> </optional><font></font> </message><font></font> <font></font>
PROMOÇÕES
Como mencionado acima, cada opção conterá uma ou mais promoções .
Estes serão identificados pelo nome, sendo este o seu único atributo.
As promoções serão representadas com a tag < promo >, com o atributo id representando seu nome:
Propriedade | Tipo de dados | Descrição do produto |
vai | Alfanumérico | Nome da promoção. |
não | Alfanumérico | Identificador de banco de dados de promoção |
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <promo id="Promoción navideña" nro="1"><font></font> <font></font> … participantes de condición …<font></font> <font></font> … beneficios …<font></font> <font></font> </promo><font></font> <promo id="Promoción 2x1 en juguetes" nro="2"><font></font> <font></font> … participantes de condición …<font></font> <font></font> … beneficios …<font></font> <font></font> </promo><font></font> </optional><font></font> </message><font></font>
Por sua vez, cada promoção pode relatar uma série de condições de participação e elementos de benefícios, detalhados nas seções a seguir.
CONDICIONAR PARTICIPANTES
Os participantes da condição são um componente opcional que indica os elementos que influenciaram a condição (consulte o Manual do Usuário) que causou a concessão do benefício. Esses elementos serão agrupados em uma tag do tipo < conditionParticipants >. Os elementos participantes da condição serão representados pelo rótulo que corresponde ao tipo de elemento, agrupado conforme já descrito em <conditionParticipants> . Os elementos participantes terão os atributos relatados ao adicioná-los à sessão.
Os participantes da condição são completamente opcionais e podem não ser informados se isso estiver configurado no arquivo de definição de promoções (mapa) ou se não houver participantes da condição. Nesse caso, a tag <conditionParticipants> não fará parte da promoção. Esta tag não possui atributos.
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <promo id="Promoción navideña" nro="1"><font></font> <conditionParticipants><font></font> <item code="0056" brand="PANASONIC" xprice="99.0" magnitude="0.0" family="TV" type="qty" dept="ELECTRONIC" qty="1.0" seq="2"/><font></font> <customer seq="2" id="000004" type="preferred" /><font></font> <coupon seq="1" id="0001" amount="" qty="1.0" type="A" /><font></font> </conditionParticipants><font></font> <font></font> … beneficios …<font></font> <font></font> </promo><font></font> </optional><font></font> </message><font></font> <font></font>
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) a ser dada ao cliente, correspondente à promoção a que pertencem. Eles serão definidos através da tag < benefício >.
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 < benefício > que o representa variarão . No entanto, existem alguns atributos comuns a todos eles:
Propriedade | Tipo de dados | Descrição do produto |
ordem | Número inteiro positivo | Um número que identifica exclusivamente o benefício na mensagem de resposta. Seu valor decorre da ordem em que sua aplicação foi feita na realização da avaliação. |
beneficiarTipo | Alfanumérico | Tipo de benefício envolvido. |
displayMessage | Alfanumérico | Mensagem a ser exibida no ponto de venda. |
printerMessage | Alfanumérico | Mensagem para imprimir na cédula ou no bilhete no final da compra. |
applicationMethod | Alfanumérico | Maneira de mostrar o benefício. Pode ter dois valores:
|
baseAmount | Real positivo | Indica o valor total em que o benefício em questão foi calculado. |
TLOGMessage | Alfanumérico | Mensagem para salvar no TLOG |
conta | Alfanumérico | Conta contábil à qual o lucro será atribuído. |
não | Alfanumérico | Identificador do banco de dados de benefícios. |
nome | Alfanumérico | Identificador do banco de dados da promoção que contém o benefício. |
Independentemente do tipo de benefício, eles podem ter aplicado elementos e combinado os participantes . 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. Benefícios monetários são aqueles que oferecem uma vantagem econômica ao cliente, enquanto benefícios não monetários não.
Os tipos de benefícios será dado pelo valor do atributo benefitType o < benefício >, e são os seguintes:
- Monetário:
- FixedDiscount
- É um desconto fixo que é feito em um conjunto de artigos.
- PercentageDiscount
- Representa uma porcentagem de desconto em um conjunto de artigos.
- NewPrice
- Atribua um novo preço a um ou mais itens.
- TenderDiscountBenefit
- Representa um desconto ou sobretaxa de% em um conjunto de artigos. As informações para calcular esse percentual são obtidas dos planos de pagamento (PaymentPlanBenefit) aplicados.
- RedeemPointsBenefit
- Faça a conversão do saldo em dinheiro e relate um valor de desconto a ser aplicado com base no valor relatado.
- CalculatedCouponApplicationBenefit
- Aplique como desconto o valor informado por um cupom calculado
- FixedDiscount
- Não monetário
- PaymentPlanBenefit
- Fornece um plano de pagamento específico para uma série de itens ou para compra.
- CouponBenefit
- Dê uma certa quantidade de cupons específicos para o cliente.
- GiftBenefit
- Dê ao cliente um ou mais presentes específicos.
- LoyaltyBenefit
- Beneficie o cliente com uma certa quantia de saldo de fidelidade (milhas, pontos de carteira, dinheiro, etc.). A partir da versão 2.8.0, esse benefício calcula a quantidade de saldo para cada item do aplicativo e a quantidade total de saldo que você concede.
- FactorLoyaltyBenefit
- Representa a concessão de pontos, dinheiro, milhas, etc. fidelidade em relação a um dado fator.
- PercentLoyaltyBenefit
- Representa a concessão de pontos, dinheiro, milhas, etc. lealdade em relação a uma determinada porcentagem. Este benefício calcula a quantidade de pontos, dinheiro, milhas, etc. para cada elemento do aplicativo e a quantidade de pontos, dinheiro, milhas, etc. no total, concede.
- CalculatedCouponBenefit
- Representa a concessão de um cupom cujo valor de desconto a ser concedido é definido por uma porcentagem dos participantes.
- PaymentPlanBenefit
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 ele pertence (indicado no BenefícioTipo ). A tabela a seguir lista esses atributos e a coluna "Necessário" indica se o atributo sempre estará presente na resposta ("Sim") ou se dependerá do valor a ser incluído ou não ("Não")
Benefício | Propriedade | Tipo de dados | Obrigatório | Descrição do produto |
FixedDiscount | unidade | Alfanumérico | Não | O valor de "unidade" indicará se o desconto será aplicado a todo o conjunto ou a cada unidade da propriedade selecionada. Os valores possíveis são:
|
discountAmount | Real positivo | Sim | Desconto a ser feito nos elementos aplicados. O valor para descontar cada item varia de acordo com a unidade de aplicação. | |
prorationMethod | Alfanumérico | Sim | Método que será usado para ratear o benefício entre os elementos aplicados, que podem ser:
| |
PercentageDiscount | unidade | Alfanumérico | Não | Indica se a porcentagem de desconto deve ser aplicada a cada unidade ou ao total. Os valores que ele pode ter são os indicados acima. |
discountPercentage | Real positivo | Sim | Porcentagem de desconto a ser feito nos elementos participantes. O valor para descontar cada item varia de acordo com a unidade de aplicação. | |
nome | Alfanumérico | Não | Nome da promoção que gerou o benefício. | |
prorationMethod | Alfanumérico | Sim | Método que será usado para ratear o benefício entre os elementos aplicados. Os valores a serem tomados são os mesmos indicados acima. | |
NewPrice | unidade | Alfanumérico | Não | Ele indicará se o novo preço deve ser aplicado a cada unidade ou ao total. Os valores que ele pode ter são os indicados acima. |
newPrice | Real positivo | Sim | Desconto fixo a ser feito nos elementos participantes. O valor para descontar cada item varia de acordo com a unidade de aplicação. | |
prorationMethod | Alfanumérico | Sim | Método que será usado para ratear o benefício entre os elementos aplicados. Os valores que ele pode assumir são os mesmos que os indicados acima. | |
TenderDiscountBenefit | concurso | Alfanumérico | Sim | Formas de pagamento que podem ser usadas. Pode ser uma lista separada por vírgula. |
limite | Real positivo | Não | Indica o valor máximo que pode ser pago com a forma de pagamento. Esse limite será útil apenas no ponto de venda sem afetar os cálculos do mecanismo de promoção. Se esse valor estiver vazio, significa que a quantidade é ilimitada. | |
planídeo | Alfanumérico | Sim | Identificador do plano que está sendo concedido. | |
Tipo | Alfanumérico | Não | Tipo de método de pagamento. | |
Banco | Alfanumérico | Não | Banco associado ao método de pagamento. | |
Porcentagem | Real positivo | Sim | Porcentagem de desconto ou sobretaxa a ser feita nos elementos participantes. | |
percenttype | Alfanumérico | Não | Indica se a porcentagem é um desconto (valor = desconto) ou sobretaxa (valor = sobretaxa). | |
deitar | Número inteiro positivo | Sim | Número identificador exclusivo do elemento médio do pado (pagamento) dentro da transação. | |
quantidade | Real positivo | Sim | Dinheiro usado com esse meio de pagamento | |
itemamount | Real positivo | Sim | Dinheiro que representa a quantidade de itens que você deseja pagar. | |
paymentAmount | Real positivo | Sim | Indica o valor total em que o benefício em questão foi calculado. | |
prestações | Real positivo | Não | Indica o valor das taxas associadas ao plano de pagamento | |
benefitedamount | Real positivo | Sim | Desconto a ser feito nos elementos aplicados. | |
RedeemPointsBenefit | Tipo | Alfanumérico | Sim | Indica o tipo de cartão ao qual o benefício será aplicado |
fator | Real positivo | Sim | Indica o fator de conversão para calcular o desconto com base no valor relatado no valor | |
usedPoints | Real positivo | Sim | Indica a quantidade de saldo (ponto, dinheiro, etc.) que será usado para a aplicação do referido benefício | |
discountAmount | Real positivo | Sim | Desconto a ser feito nos elementos aplicados. O valor para descontar cada item varia de acordo com a unidade de aplicação. | |
prorationMethod | Alfanumérico | Sim | Método que será usado para ratear o benefício entre os elementos aplicados. Os valores que ele pode assumir são os mesmos que os 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 ele pode ter são os indicados acima. | |
CalculatedCouponApplicationBenefit | discountAmount | Real positivo | Sim | Desconto a ser feito nos elementos aplicados. O valor para descontar cada item varia de acordo com a unidade de aplicação. |
couponId | Alfanumérico | Sim | Identificador do cupom a ser resgatado. | |
PaymentPlanBenefit | concurso | Alfanumérico | Sim | Formas de pagamento que podem ser usadas. Pode ser uma lista separada por vírgula. |
limitAmount | Real positivo | Não | Indica o valor máximo que pode ser pago com a forma de pagamento. Esse limite será útil apenas no ponto de venda sem afetar os cálculos do mecanismo de promoção. Se esse valor estiver vazio, significa que a quantidade é ilimitada. | |
planejar | Alfanumérico | Sim | Identificador do plano que está sendo concedido. | |
tipo | Alfanumérico | Não | Tipo de método de pagamento. | |
banco | Alfanumérico | Sim | Banco associado ao método de pagamento. | |
por cento | Real positivo | Não | Porcentagem de desconto ou sobretaxa a ser feita nos elementos participantes. O desconto ou sobretaxa será relatado como um benefício TenderDiscountBenefit | |
percenttype | Alfanumérico | Não | Indica se a porcentagem é um desconto (valor = desconto) ou sobretaxa (valor = sobretaxa). | |
prestações | Real positivo | Não | Indica o valor das taxas associadas ao plano de pagamento | |
paymentAmount | Real positivo | Sim | Indica o valor total em que o benefício em questão foi calculado. | |
| NominalAnnualRate | Real positivo | Não | TNA: Taxa Nominal Anual. É um valor informativo especificado na Promoção. | |
| effectiveMonthlyRate | Real positivo | Não | TEM: Taxa Efetiva Mensal. É um valor informativo especificado na Promoção. | |
| totalFinancialCostAssumed | Real positivo | Não | CFT Assumed: Custo Financeiro Total Assumido. É um valor informativo especificado na Promoção. | |
| BankRefundBenefit | Consulte PaymentPlanBenefit, pois possui as mesmas propriedades. | |||
CouponBenefit | couponId | Alfanumérico | Sim | Identificador do cupom a ser concedido. |
quantidade | Sim | Indique o valor associado a um cupom cujo valor foi calculado | ||
qtde | Número inteiro positivo | Sim | Quantidade de cupons a serem concedidos. | |
GiftBenefit | giftid | Alfanumérico | Sim | Identificador do presente a ser entregue. Caso seja um produto em estoque, pode representar o código do item a ser distribuído. |
giftType | Alfanumérico | Sim | Tipo de presente para entregar. Pode estar vazio. | |
qtde | Número inteiro positivo | Sim | Número de presentes com o identificador indicado. | |
LoyaltyBenefit | tipo | Alfanumérico | Sim | Tipo de valor de lealdade (pontos, dinheiro, milhas, etc.) sendo concedido. |
quantidade | Número 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. para cada unidade ou para o total. Os valores que ele pode ter são os indicados acima. | |
pontos totais | Real positivo | Sim | Indica a quantidade total de pontos, dinheiro, milhas, etc. que concede o benefício após o cálculo. | |
FactorLoyaltyBenefit | tipo | Alfanumérico | Sim | Tipo de pontos, dinheiro, milhas, etc. de fidelidade que estão sendo concedidas. |
fator | Real positivo | Sim | Fator multiplicador a ser usado para calcular pontos, dinheiro, milhas, etc. | |
PercentLoyaltyBenefit | 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., aplicada no xprice ou no XPrice original para calcular o número de pontos, dinheiro, milhas, etc. que correspondem à concessão. | |
pontos totais | Real positivo | Sim | Indica a quantidade total de pontos, dinheiro, milhas, etc. que concede o benefício após o cálculo. | |
CalculatedCouponBenefit | couponId | Alfanumérico | Sim | Identificador do cupom a ser concedido. |
quantidade | Número inteiro positivo | Sim | Indique 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 | |
qtde | Número inteiro positivo | Sim | Quantidade de cupons a serem concedidos. |
Exemplo:
<message companiId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <promo id="Promoción navideña" nro="1"><font></font> <conditionParticipants><font></font> <item code="0056" brand="PANASONIC" xprice="99.0" magnitude="0.0" family="TV" type="qty" dept="ELECTRONIC" qty="1.0" seq="2"/><font></font> <customer seq="2" id="000004" type="preferred" /><font></font> <coupon seq="1" id="0001" amount="" qty="1.0" type="A" /><font></font> </conditionParticipants><font></font> <benefit order="1" benefitType="FixedAmount" displayMessage="" printerMessage="" unit="qty" prorationMethod="PROPORTIONAL" applicationMethod="lineByLine" nro="3" amount="20.00" baseAmount="165.00"><font></font> <font></font> … participantes de combo y/o elementos aplicados …<font></font> <font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message><font></font> <font></font>
<message companiId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <promo id="Promoción navideña" nro="1"><font></font> <benefit order="1" benefitType="PercentageDiscount" displayMessage="" printerMessage="" unit="" prorationMethod="PROPORTIONAL" applicationMethod="lineByLine" nro="3" Percentage="20.00" baseAmount="165.00"><font></font> <font></font> … participantes de combo y/o elementos aplicados …<font></font> <font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message><font></font> <font></font>
<message companiId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <promo id="Promoción navideña" nro="1"><font></font> <benefit order="1" benefitType="TenderDiscountBenefit" displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" tender="VISA" planId="0A3" limitAmount="200.00" baseAmount="165.00" bank="HSBC" percent="5.000" percenttype="discount" amount="2375.000" itemamount="2500.000" paymentAmount="2500.000" benefitedamount="125.000" tenderseq="1" ><font></font> <font></font> … participantes de combo y/o elementos aplicados …<font></font> <font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message><font></font> <font></font>
<message ack="0" engine="2.6" mapversion="2" messageId="1" companiId="sts" store="1" terminal="1"><font></font>
<optional><font></font>
<promo id="redime puntos" nro="58ff57be6772781234e7915e"><font></font>
<benefit TLOGMessage="redime puntos" account="" applicationMethod="resume" baseAmount="100.00"<font></font>
benefitType="RedeemPointsBenefit" discountAmount="100.00" displayMessage="redime puntos" factor="1"<font></font>
name="58ff57be6772781234e7915e" nro="58ff57e76772781234e79164" order="1" printerMessage="redime puntos"<font></font>
prorationMethod="PROPORTIONAL" unit="" usedPoints="100.0"><font></font>
<apply><font></font>
<item magnitude="0.000" qty="1.000" seq="2" value="100.00" xprice="100.00"/><font></font>
</apply><font></font>
</benefit><font></font>
</promo><font></font>
</optional><font></font>
</message"><font></font>
<font></font>
<message ack="0" engine="2.6" mapversion="2" messageId="1" companiId="sts" store="1" terminal="1"><font></font> <optional><font></font> <promo id="redime impreso calculado" nro="5900e1a6a846390de08a7afe"><font></font> <benefit TLOGMessage="redime impreso calculado" account="" applicationMethod="resume" baseAmount="100.00" benefitType="CalculatedCouponApplicationBenefit" couponId="1" discountAmount="10.00" displayMessage="redime impreso calculado" name="5900e1a6a846390de08a7afe" nro="5900e1bca846390de08a7b04" order="1" printerMessage="redime impreso calculado" prorationMethod="PROPORTIONAL" unit=""><font></font> <apply><font></font> <item magnitude="0.000" qty="1.000" seq="2" value="10.00" xprice="100.00"/><font></font> </apply><font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message>
<message companiId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <promo id="Promoción navideña" nro="1"><font></font> <benefit order="1" benefitType="PaymentPlanBenefit" displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" tender="VISA" planId="A3" limitAmount="200.00" baseAmount="165.00" bank="HSBC" percent="5.000" percenttype="discount" paymentAmount="2500.00"><font></font> <font></font> … participantes de combo y/o elementos aplicados …<font></font> <font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message><font></font> <font></font>
<?xml version="1.0" encoding="UTF-8" standalone="no"?><font></font>
<message ack="0" companyId="napse" engine="2.6" mapversion="3" messageId="1" store="1" terminal="1"><font></font>
<optional><font></font>
<promo id="Reintegro bancario" nro="1"><font></font>
<benefit TLOGMessage="Reintegro bancario" account="" amount="90.00" applicationMethod="resume" baseAmount="100.00" benefitType="BankRefundBenefit" benefitedamount="10.00" displayMessage="Reintegro bancario" installments="1" itemamount="100.00" order="2" paymentAmount="100.00" percent="10" planId="1" printerMessage="Reintegro bancario" tender="1" tenderseq="1" type="1"><font></font>
<apply><font></font>
<item magnitude="0.000" qty="1.000" seq="2" value="1.00" valueWithTaxes="0.00" xprice="10.00"/><font></font>
<item magnitude="0.000" qty="1.000" seq="4" value="2.00" valueWithTaxes="0.00" xprice="20.00"/><font></font>
<item magnitude="0.000" qty="1.000" seq="6" value="3.00" valueWithTaxes="0.00" xprice="30.00"/><font></font>
<item magnitude="0.000" qty="1.000" seq="8" value="4.00" valueWithTaxes="0.00" xprice="40.00"/><font></font>
</apply><font></font>
</benefit><font></font>
</promo><font></font>
</optional><font></font>
</message><font></font>
<font></font>
<message companiId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <promo id="Promoción navideña" nro="1"><font></font> <conditionParticipants><font></font> <item code="0056" brand="PANASONIC" xprice="99.0" magnitude="0.0" family="TV" type="qty" dept="ELECTRONIC" qty="1.0" seq="2"/><font></font> <customer seq="2" id="000004" type="preferred" /><font></font> <coupon seq="1" id="0001" amount="" qty="1.0" type="A" /><font></font> </conditionParticipants><font></font> <benefit order="1" benefitType="CouponBenefit" displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" couponId="C0032" qty="2" baseAmount="165.00"><font></font> <font></font> … participantes de combo y/o elementos aplicados …<font></font> <font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message><font></font> <font></font>
<message companiId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <promo id="Promoción navideña" nro="1"><font></font> <benefit order="1" benefitType="GiftBenefit" displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" qty="2" giftType="A" giftId="00452" baseAmount="165.00"><font></font> <font></font> … participantes de combo y/o elementos aplicados …<font></font> <font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message><font></font> <font></font>
<message companiId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <promo id="Promoción navideña" nro="1"><font></font> <conditionParticipants><font></font> <item code="0056" brand="PANASONIC" xprice="99.0" magnitude="0.0" family="TV" type="qty" dept="ELECTRONIC" qty="1.0" seq="2"/><font></font> <customer seq="2" id="000004" type="preferred" /><font></font> <coupon seq="1" id="0001" amount="" qty="1.0" type="A" /><font></font> </conditionParticipants><font></font> <benefit order="1" benefitType="LoyaltyBenefit" displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" value="1000" type="points" baseAmount="99.00" totalpoints="1000.00" ><font></font> <font></font> … participantes de combo y/o elementos aplicados …<font></font> <font></font> <item value="0.000" seq="2" qty="1.000" points="1000.00" xprice="99.00"/><font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message><font></font> <message companiId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <promo id="Promoción navideña" nro="1"><font></font> <conditionParticipants><font></font> <item code="0056" brand="PANASONIC" xprice="99.0" magnitude="0.0" family="TV" type="qty" dept="ELECTRONIC" qty="2.0" seq="2"/><font></font> <customer seq="2" id="000004" type="preferred" /><font></font> <coupon seq="1" id="0001" amount="" qty="1.0" type="A" /><font></font> </conditionParticipants><font></font> <benefit order="1" benefitType="LoyaltyBenefit" displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" value="1000" type="points" baseAmount="99.00" unit="qty" totalpoints="2000.00" ><font></font> <font></font> … participantes de combo y/o elementos aplicados …<font></font> <font></font> <font></font> <font></font> <item value="0.000" seq="2" qty="2.000" points="2000.00" xprice="99.00"/><font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message>
<message companiId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <promo id="Promoción navideña" nro="1"><font></font> <benefit order="1" benefitType="FactorLoyaltyBenefit " displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" factor="2" type="points" baseAmount="165.00"><font></font> <font></font> … participantes de combo y/o elementos aplicados …<font></font> <font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message><font></font> <font></font>
<message companiId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <message companiId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <promo id="Promoción navideña" nro="1"><font></font> <conditionParticipants><font></font> <item code="0056" brand="PANASONIC" xprice="99.0" magnitude="0.0" family="TV" type="qty" dept="ELECTRONIC" qty="1.0" seq="2"/><font></font> <customer seq="2" id="000004" type="preferred" /><font></font> <coupon seq="1" id="0001" amount="" qty="1.0" type="A" /><font></font> </conditionParticipants><font></font> <benefit order="1" benefitType="PercentLoyaltyBenefit" displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" percent="10.0" type="points" baseAmount="165.00" totalpoints="16.50" ><font></font> <font></font> … participantes de combo y/o elementos aplicados …<font></font> <font></font> <font></font> <item value="0.000" seq="2" qty="1.000" points="16.50" xprice="99.00"/><font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message><font></font> <font></font>
<message ack="0" engine="2.6" mapversion="2" messageId="1" companiId="sts" store="1" terminal="1"><font></font> <optional><font></font> <promo id="emite impreso calculado" nro="5900e173a846390de08a7af7"><font></font> <benefit TLOGMessage="emite impreso calculado" account="" amount="10.00" applicationMethod="resume" baseAmount="100.00" benefitType="CalculatedCouponBenefit" couponId="1" displayMessage="emite impreso calculado" name="5900e173a846390de08a7af7" nro="5900e18ea846390de08a7afd" order="1" percentage="10" printerMessage="emite impreso calculado" qty="1.000"><font></font> <apply><font></font> <item magnitude="0.000" qty="1.000" seq="2" value="0.00" xprice="100.00"/><font></font> </apply><font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message><font></font>
PARTICIPANTES COMBO
Caso a promoção contenha um conjunto finito associado de elementos. Para mais detalhes, é recomendável consultar o Manual do Usuário "condição por composição". Os benefícios da promoção que se aplicam a este combo associado conterão uma tag chamada < comboParticipants >. Dentro dele, os elementos que compõem o combo ao qual o benefício ao qual eles pertencem serão listados, chamados participantes do combo , da mesma forma que condicionam os participantes e possuem os mesmos atributos.
Se a promoção não for definida por combos ou o cálculo do participante não for necessário no arquivo de definição (mapa), < comboParticipants > não estará presente. Esta tag não possui atributos.
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <promo id="Promoción navideña" nro="1"><font></font> <benefit order="1" benefitType="FactorLoyaltyBenefit " displayMessage="" printerMessage="" applicationMethod="lineByLine" nro="3" factor="2" type="points" baseAmount="165.00"><font></font> <comboParticipants><font></font> <item seq="1" code="0010" qty="2.0" magnitude="1.0" xPrice="90.0" unitPrice="50.0" /><font></font> <item seq="2" code="0011" qty="2.0" magnitude="1.0" xPrice="72.0" unitPrice="40.0" /><font></font> </comboParticipants><font></font> <font></font> … elementos aplicados …<font></font> <font></font> <font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message><font></font> <font></font> <font></font>
ELEMENTOS APLICADOS
Os benefícios são sempre aplicados aos artigos . Para representar isso, o Mecanismo de Promoção ao relatar benefícios usa a tag < apply >, que lista os itens nos quais o benefício deve ser aplicado. Como os benefícios só podem ser aplicados aos artigos, os elementos contidos em < apply > sempre serão < item >.
Ao contrário dos elementos relatados nos participantes (sejam eles condição ou combinação), os elementos < item > que serão encontrados em < apply > terão os seguintes atributos:
Propriedade | Tipo de dados | Descrição do produto |
seq | Número inteiro positivo | Número que identifica o elemento na transação à qual o benefício se aplica. |
valor | Número No caso de um item receber um novo preço maior que o preço de venda informado, esse valor pode assumir um valor negativo. Por esse motivo, as rotinas devem ser implementadas para gerenciar esses tipos de valores. | Valor total a ser descontado no elemento indicado pelo atributo seq . |
qtde | Número inteiro positivo | Quantidade de itens afetados entre os quais o desconto expresso em valor deve ser distribuído . |
magnitude | Real positivo | Valor afetado no qual o desconto expresso em valor deve ser aplicado . Se uma magnitude não foi definida para o item, ela será relatada como " 0,0 ". Ao calcular pontos, dinheiro, milhas, etc., se esse valor for " 0,0 ", ele não será relatado. |
pontos | Real positivo | Quantidade total de pontos, dinheiro, milhas, etc. que concede a sequência identificada por seq . Aparece sempre que o elemento do aplicativo faz parte de um benefício LoyaltyBenefit ou PercentLoyaltyBenefit para o qual são calculados pontos, dinheiro, milhas, etc. |
xprice | Real positivo | Xprice ou preço original da sequência no momento em que o lucro foi calculado. Qual é o xprice ou o preço original dependerá de como o benefício está configurado e de qual desses dois valores se aplica (da versão 2.8.0). |
Os benefícios da taxa monetária sempre reportarão itens aplicados, enquanto os benefícios não monetários podem não. Por outro lado, dentro dos artigos aplicados de benefícios não monetários, o atributo de valor desses artigos sempre será " 0,0 ", uma vez que não há desconto a ser realizado.
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"><font></font> <optional><font></font> <promo id="Promoción navideña" nro="1"><font></font> <benefit order="1" benefitType="PercentageDiscount" displayMessage="" printerMessage="" unit="" prorationMethod="PROPORTIONAL" applicationMethod="lineByLine" nro="3" Percentage="20.00" baseAmount="162.00"><font></font> <comboParticipants><font></font> <item seq="1" code="0010" qty="2.0" magnitude="1.0" xPrice="90.0" unitPrice="50.0" /><font></font> <item seq="2" code="0011" qty="2.0" magnitude="1.5" xPrice="72.0" unitPrice="40.0" /><font></font> </comboParticipants><font></font> <apply><font></font> <item seq="1" value="18.00" magnitude="0.0" qty="1.0" xprice="90.00"/><font></font> <item seq="2" value="14.40" magnitude="1.5" qty="1.0" xprice="72.00" /><font></font> </apply><font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message><font></font>
ELEMENTOS NÃO APLICADOS
Nos benefícios externos (ExternalBenefit), pode haver itens que não são aplicados porque não estão presentes no contexto. Para representar isso, o Mecanismo de promoções ao relatar benefícios usa a tag < notApply >, que lista os artigos nos quais o benefício não pôde ser aplicado. Como os benefícios só podem ser aplicados aos artigos, os elementos contidos em < notApply > sempre serão < item >.
Diferentemente dos elementos relatados nos participantes (sejam eles de condição ou de combinação), os elementos < item > que serão encontrados em < notApply > terão os seguintes atributos:
Propriedade | Tipo de dados | Descrição do produto |
seq | Número inteiro positivo | Número que identifica o elemento na transação à qual o benefício se aplica. |
valor | Número No caso de um item receber um novo preço maior que o preço de venda informado, esse valor pode assumir um valor negativo. Por esse motivo, as rotinas devem ser implementadas para gerenciar esses tipos de valores. | Valor total que não pôde ser descontado no elemento indicado pelo atributo seq . |
qtde | Número inteiro positivo | Número de itens que não foram afetados. |
magnitude | Real positivo | Magnitude que não foi afetada |
xprice | Real positivo | Sempre vá para zero. |
<message engine="2.6" companyId="sts" store="0236" terminal="004" mapversion="114" ack="0" messageId="3777"><font></font> <optional><font></font> <promo id="Desc5" nro="3"><font></font> <conditionParticipants><font></font> <benefit benefitType="desc" amount="100.00" seqItem="2=2,3=2,5" type="MktExc" seq="1" id="1234"/><font></font> </conditionParticipants><font></font> <benefit benefitType="ExternalBenefit" discountAmount="60.00" type="MktExc" TLOGMessage="" account="" applicationMethod="" displayMessage="" order="1" prorationMethod="PROPORTIONAL" nro="3" baseAmount="3000.00" printerMessage=""><font></font> <apply><font></font> <item value="20.00" magnitude="0.000" xprice="1000.00" seq="2" qty="1.000"/><font></font> <item value="40.00" magnitude="0.000" xprice="2000.00" seq="3" qty="2.000"/><font></font> </apply><font></font> <notApply><font></font> <item value="20.000" magnitude="0.000" xprice="0.000" seq="2" qty="1.000"/><font></font> <item value="20.000" magnitude="0.000" xprice="0.000" seq="5" qty="1.000"/><font></font> </notApply><font></font> </benefit><font></font> </promo><font></font> </optional><font></font> </message><font></font>
SUGESTÕES
As sugestões adicionam à mensagem de resposta as promoções que não foram concedidas, porque a condição da promoção 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 usadas pelo vendedor para oferecer as condições necessárias para a promoção ser aplicada antes de prosseguir com o fechamento da venda. As sugestões são representadas pela tag < sugestões > que aparecerá após a última tag <opcional> . Se não houver sugestões, a tag < sugestões > não aparecerá na mensagem de resposta. Esta tag não possui atributos.
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> … promociones que componen la opción … </optional> <optional> … promociones que componen la opción … </optional> <suggestions> … promociones que pueden ser sugeridas … </suggestions> </message>
PROMOÇÕES SUGERIDAS
Como 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 >, com o atributo id representando seu nome.
Propriedade | Tipo de dados | Descrição do produto |
vai | 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 tiver sido especificado para a promoção sugerida. |
item-seq | Lista de números | As sequências do tipo de item que possibilitam a sugestão da promoção. Se não houver essas seqüências para a promoção, esse atributo não será incluído na tag. |
pagamento-seq | Lista de números | As sequências do método de pagamento que permitem sugerir a promoção. Se não houver essas seqüências para a promoção, esse atributo não será incluído na tag. |
customer-seq | Lista de números | As seqüências do tipo cliente que permitem sugerir a promoção. Se não houver essas seqüências para a promoção, esse atributo não será incluído na tag. |
event-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 seqüências para a promoção, esse atributo não será incluído na tag. |
cupom-seq | Lista de números | Sequências do tipo cupom que possibilitam a sugestão da promoção. Se não houver essas seqüências para a promoção, esse atributo não será incluído na tag. |
loyaltycard-seq | Lista de cartões de fidelidade | As sequências do tipo cartão de fidelidade que permitem sugerir a promoção. Se não houver essas seqüências para a promoção, esse atributo não será incluído na tag. |
<message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <suggestions> <promo id="Promoción navideña" descriptor="llevando un árbol de navidad te regalamos las guirnaldas" item-seq="1,2,3"/> <promo id="Promoción 2x1 en juguetes" item-seq="1,2" coupon-seq="2" payment-seq="1"/> </suggestions> </message> <message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <optional> … promociones que componen la opción … </optional> <suggestions> <promo id="Promoción navideña" descriptor="llevando un árbol de navidad te regalamos las guirnaldas" item-seq="1,2,3"/> <promo id="Promoción 2x1 en juguetes" item-seq="1,2" coupon-seq="2" payment-seq="1"/> </suggestions> </message> <message companyId="sts" store="MX" mapversion="3241" messageId="160" terminal="100" engine="2.6" ack="0"> <suggestions> <promo id="Promoción navideña" descriptor="llevando un árbol de navidad te regalamos las guirnaldas" /> <promo id="Promoción 2x1 en juguetes"/> </suggestions> </message>
Fidelidade
Novo status em <Lealdade>
Historicamente, o valor da propriedade Status estava disponível gratuitamente e sem restrições. A partir do PROMO 5, existem valores específicos e reservados para a propriedade "status" que indicarão ao mecanismo determinadas ações a serem executadas com o Console Central do PROMO.
Essas ações são:
VALIDAÇÃO DE LEALDADE
Verifique o status dos cupons, clientes e cartões na central da PROMO.
<message companyId="sts" store="1" terminal="1" date-time="2017-12-29 16:49:16" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyvalidation" evaluate="true" map-version="9" suggest="false"> <loyaltycard-add seq="2" id=" 2220000000001" /> <coupon-add seq="1" qty="1" id=" 002001001413" /> <customer-add seq="1" id="6666"/> </message>
(Consulte também Resposta do mecanismo - LoyaltyValidation )
Esta ação não requer uma terceira mensagem (confirmação ou reversão) e cancela o elemento de fidelidade relatado.
LOYALTYACTIVATION
Ative um cartão de fidelidade.
Para ativar um cartão que está inativo, uma mensagem pode ser enviada com Status = "loyaltyActivation".
Ele deve ser enviado no formato e atributos mostrados nos exemplos a seguir.
<message companyId="sts" store="1" terminal="1" date-time="2017-12-29 16:49:16" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyactivation" evaluate="true" map-version="9" suggest="false"> <loyaltycard-add seq="1" id="3330000000000"/> </message>
Você também pode desativar um cartão ativo com a LoyaltyAvtivation, adicionando na tag <loyaltycard-add /> o status = "DISABLED".
<message companyId="sts" store="1" terminal="1" date-time="2017-12-29 16:49:16" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyactivation" msg-version="9" map-version="1"> <loyaltycard-add seq="1" id="3330000000000" status="DISABLED" /> </message>
(Consulte também Resposta do mecanismo - LoyaltyActivation )
Esta ação não requer uma terceira mensagem (confirmação ou reversão) e cancela o elemento de fidelidade relatado.
A figura a seguir mostra um tipo de exemplo chamado t1
Prosseguimos para a criação sem carga do primeiro cartão:
<message companyId="test" store="1" terminal="10" date-time="2018-10-10 09:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyActivation" evaluate="false" offline="false"> <loyaltycard-add seq="1" id="10011" type="t1" status="CREATE" /> </message>
A resposta é: (Aceitar = 0 está correto)
<?xml version="1.0" encoding="UTF-8"?><message ack="0"
companyId="test" engine="6.1.3" mapversion="0" messageId="1" store="1"
terminal="10" transaction="test_1_10_20181025125336">
<loyalty>
<loyaltycards/>
<coupons/>
<errors/>
<customers/>
</loyalty>
</message>
Além disso, se você desejar efetuar uma cobrança inicial, poderá adicionar a propriedade "chargeAmount" do elemento loyaltyCard. Dessa forma, além de criá-lo, esse saldo será cobrado inicialmente.
Depois, criamos um segundo com saldo:
<message companyId="test" store="1" terminal="10" date-time="2018-10-10 09:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyActivation" evaluate="false" offline="false"> <loyaltycard-add seq="1" id="10012" type="t1" status="CREATE" chargeAmount="105.00" /> </message>
Resposta
<?xml version="1.0" encoding="UTF-8"?><message ack="0"
companyId="test" engine="6.1.3" mapversion="0" messageId="1" store="1"
terminal="10" transaction="test_1_10_20181025125336">
<loyalty>
<loyaltycards/>
<coupons/>
<errors/>
<customers/>
</loyalty>
</message>
Se olharmos para os detalhes de qualquer um deles:
LOYALTYTRANSFER
Faça a transferência do saldo de um cartão de fidelidade para outro do mesmo tipo.
Para realizar uma transferência de saldo, o cartão de origem (o que dá saldo) e o cartão de destino (o que recebe saldo) devem ser do mesmo tipo.
No seq = 1 enviado pelo PDV, o cartão de origem será informado, ou seja, para quem os pontos, dinheiro, milhas etc. serão descontados.
No seq = 2 enviado pelo PDV, o cartão de destino será informado, ou seja, aquele que receberá os pontos, dinheiro, milhas, etc.
(Consulte também o Manual do usuário, "Conceitos do cartão de fidelidade" para obter mais detalhes sobre os diferentes tipos de transferência possíveis)
<message companyId="sts" store="1" terminal="1" date-time="2017-12-29 16:49:16" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyTransfer" msg-version="9" map-version="1"> <loyaltycard-add seq="1" type="2" id="2220000000000"/> <loyaltycard-add seq="2" type="2" id="2220000000001" chargeAmount="4" /> </message>
(Consulte também Resposta do mecanismo - LoyaltyTransfer ) COMMIT ou ROLLBACK
é necessário para confirmar ou reverter a transação.
LOYALTYVOID
Esse status será usado para cancelar elementos de fidelidade que deveriam ser emitidos ou concedidos, mas onde a transação atual que os emitiu não prosperou.
Os cupons removidos por meio desta mensagem permanecerão no estado "Rejeitado" (rejeitado).
<message companyId="sts" store="00001" terminal="010" date-time="2017-03-27 14:57" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="loyaltyVoid" msg-version="2.0" map-version="1"> <coupon-add seq="1" qty="1" id="1000010105299" type="C-Impreso"/> <loyaltycard-add seq="2" id="6665000008801" type="roja" /> </message>
(Consulte também Resposta do mecanismo - Cancelamento de lealdade )
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 POS, ou qualquer canal, informe a qual cliente um cartão está associado. Será validado que o cartão não possui um cliente associado anteriormente, que o cliente e o cartão existem, que o tipo de cartão requer associação via "Canal de Vendas" e que o cartão está inativo.
<message companyId="sts" store="00001" terminal="010" date-time="2017-03-27 14:57" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="loyaltyAssign" msg-version="2.0" map-version="1"> <loyaltycard-add seq="2" id="6665000008801" type="roja" /> <customer-add seq="1" id="6666"/> </message>
(Consulte também Resposta do mecanismo - Loyalty Void ) COMMIT ou ROLLBACK
é necessário para confirmar ou reverter a transação.
FINISH
Indica o processamento do ticket na PROMO Central.
<message companyId="sts" store="00001" terminal="010" date-time="2017-01-04 12:30:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="finish" msg-version="2.0" map-version="15" suggest="true" suggest-seq="3"> .. cuerpo del mensaje ... </message>
Outra opção disponível para ativar um cartão de fidelidade é enviar o atributo "status" na tag <LoyaltyCard-ADD> ao enviar um "Concluir", onde o status ATIVADO deve ser indicado para que o cartão incluído na transação é ativado
<message companyId="sts" store="1" terminal="1" date-time="2017-05-30 12:06:10" init-tck="true" messageId="1" void-trx="false" response="true" status="finish" evaluate="true" map-version="1" suggest="true"> <loyaltycard-add seq="2" id="3330000000002" type="3" status="ENABLED" /> </message>
(Veja também Resposta do mecanismo - Ativação no acabamento )
COMMIT
Confirme a transação atual.
<message companyId="sts" store="1" terminal="1" date-time="2017-05-30 12:06:10" init-tck="true" messageId="1" void-trx="false" response="true" status="commit" msg-version="2.0" map-version="15" suggest="true" suggest-seq="3"> ... cuerpo del mensaje ... </message>
ROLLBACK
Inverta a transação atual.
<message companyId="sts" store="1" terminal="1" date-time="2017-05-30 12:06:10" init-tck="true" messageId="1" void-trx="false" response="true" status="rollback" msg-version="2.0" map-version="15" suggest="true" suggest-seq="3">... cuerpo del mensaje ... </message>
TRANSACTIONREQUEST
Verifique as informações sobre uma transação PROMO específica. (A transação a ser consultada deve ser relatada no atributo "OriginalTransaction")
<message companyId="sts" store="1" terminal="1" date-time="2017-05-30 12:06:10" init-tck="true" messageId="1" void-trx="false" response="true" status="transactionrequest" originalTransaction ="001_025_20161212134555" map-version="15" suggest="true" suggest-seq="3"> </message>
RETURNFINISH
Registre todos os elementos de uma transação de devolução no PROMO e marque para o processo em segundo plano os elementos de fidelidade que participam da devolução a serem processados e revertidos, se aplicável. A alteração OriginalTransaction deve ser relatada juntamente com o ReturnFinish para que a operação seja realizada corretamente. COMMIT ou ROLLBACK
é necessário para confirmar ou reverter a transação.
<message companyId="sts" store="00001" terminal="010" date-time="2017-06-04 12:30:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" " status="returnFinish" originalTransaction="001_025_20161212134555" map-version="15" suggest="true" suggest-seq="3"> <item-add seq="2" qty="1" code="1" magnitude="0" xprice="100" unitprice="100"/> <payment-add seq="1" type="CreditCard" amount="100" id="000009" planId="10"/> <loyaltycard-add seq="5" id="3330000000133" /> <coupon-add seq="1" qty="1" id="xxxxxxxxxx" type="yyy" /> <customer-add seq="1" id="1"/> </message>
Lealdade: Resposta do Motor
Cada um dos elementos de lealdade relatados na resposta a um "acabamento" conterá os dados dos benefícios obtidos pela aplicação de um benefício.
Na tag <loyalty>, um ou mais dos seguintes elementos podem ser relatados:
- <cupons />
- <cartões de fidelidade />
- <erros />
- <clientes />
<<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <coupons/> <loyaltycards/> <errors/> <customers/> </loyalty> </message>
As propriedades do cabeçalho de resposta de fidelidade serão as mesmas que as relatadas na resposta de qualquer outro elemento PROMO (consulte o capítulo 3.1 Cabeçalho ),
RESPONSE - LOYALTYVALIDATION
Em resposta a uma consulta de um ou mais elementos de fidelidade
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530151500"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="0.0" customer="" id="2220000000001" seq="2" type="2"/> </loyaltycards> <coupons> <coupon ack="0" amount="10.0" barcode="002001001413" couponId="2" seq="1"/> </coupons> <errors/> <customers> <customer code="6666" email="[email protected]" identifier="30112255881" lastName="" name="Rojo Marcos" seq="1" segment="A1;B6;C11"> <coupon ack="0" amount="60.0" barcode="002009005475" couponId="2"/> <coupon ack="0" amount="" barcode="003090033000000002147483647" couponId="3"/> <loyaltycard ack="0" amount="0.0" id="5550000000222" type="5"/> </customer> </customers> </loyalty> </message>
Saída - Não OK (consulte o capítulo 3.1.1 Valores de atributo "ack" )
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="9" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170529165306"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9501" amount="0.0" cardType="3" info="3330000000002" seq="2" type="loyaltycard-redeem"/> </errors> <customers/> </loyalty> </message>
Nota: Quando o cartão consultado está inativo, o saldo do cartão no momento da consulta e o tipo de cartão em "cardType" serão relatados no atributo "quantidade".
(consulte também Solicitação de mecanismo - loyaltyValidation )
RESPOSTA - CUPONS
Cupons que foram concedidos como resultado dos benefícios de uma promoção são adicionados à mensagem de resposta. Vale esclarecer que este é o detalhe dos cupons concedidos, ou seja, se como resultado da avaliação de um número X de promoção de algum tipo tiver sido concedido, a resposta de fidelidade conterá os detalhes desses X cupons concedidos.
<message companyId="sts" ack="0" engine="2.6" mapversion="1" messageId="1" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards/> <coupons> <coupon ack="0" barcode="1000010019411" benefitNro="58d2a8f8ef5a63133c3ca31d" couponId="TC_IM" format="PRINTED"" encoding="EAN13" promotionName="Emisión C-impreso" promotionNro="58d2acdaef5a63133c3ca346">*<!\[CDATA\[.....\]\]>* </coupon> </coupons> <errors/> <customers/> </loyalty> </message>
Como mencionamos para cada um dos cupons gerados, teremos um elemento de cupom, conforme mostrado no exemplo a seguir para 3 cupons:
<message companyId="sts" ack="0" engine="2.6" mapversion="1" messageId="1" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards/> <coupons> <coupon ack="0" barcode="1234567890123" format="PRINTED" benefitNro="58d2a8f8ef5a63133c3ca31d" couponId="TC_IM" format="PRINTED"" encoding="EAN13" promotionName="Emisión C-impreso" promotionNro="58d2acdaef5a63133c3ca346"><!CDATA\[ … datos libres …. \]\]> </coupon> <coupon ack="0" barcode="1234567890133" benefitNro="58d2a8f8ef5a63133c3ca31d" couponId="TC_IM" format="PRINTED"" encoding="EAN13" promotionName="Emisión C-impreso" promotionNro="58d2acdaef5a63133c3ca346"> <!CDATA\[ … datos libres …. \]\]> </coupon> <coupon ack="0" amount="10.0" barcode="1000010015888" benefitNro="5900e18ea846390de08a7afd" couponId="1" encoding="EAN13" format="PRINTED" promotionName="emite impreso calculado" promotionNro="5900e173a846390de08a7af7"><!\[CDATA\[ … datos libres… \]\]> </coupon> </coupons> <errors/> </loyalty> </message>
As propriedades de cada elemento do cupom serão:
Propriedade | Tipo de dados | Descrição do produto |
código de barras | Alfanumérico | Código de barras do cupom, ou o que é o mesmo, o identificador exclusivo dele. |
ack | inteiro | Código de retorno |
couponId | Alfanumérico | Identificador do tipo de cupom. |
formato | Alfanumérico | Formato de cupom. Os valores possíveis são: IMPRESSO (impresso), ELETRÔNICO (Eletrônico), TERCEIRO (PARTE 3), EXTERNO (Externo), PRE_PRINTED (Pré-impresso). |
codificação | Alfanumérico | Formato em que o código de barras deve ser impresso (EAN13 - UPCA - CODE128) |
promotionName | Alfanumérico | É o nome dado à promoção que aplica o benefício |
promotionNro | Alfanumérico | Identifique a promoção que aplica o benefício. |
beneficiarNro | Alfanumérico | Identifique o benefício que a promoção se aplica |
quantidade | Número inteiro positivo | Indique o valor associado a um cupom cujo valor foi calculado |
RESPONSE - CARTÕES DE FIDELIDADE
Na resposta do mecanismo, os dados do cartão ou cartões que foram beneficiados como resultado da aplicação de benefícios são adicionados à mensagem.
Vale esclarecer que são os detalhes dos pontos, dinheiro, milhas, etc. concedido, ou seja, se um número X de pontos, dinheiro, milhas etc. tiver sido concedido ou resgatado como resultado da avaliação de uma promoção, a resposta de lealdade conterá os detalhes desse cartão.
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards>… detalle de la tarjeta fidelidad … <loyaltycards/> <coupons/> <errors/> <customers/> </loyalty> </message>
Como mencionamos para cada uma das cartas, teremos um elemento, como no exemplo a seguir:
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="10.0" id="3335999932200" seq="1" type="plata"/> <loyaltycard ack="0" amount="500.0" id="5550000000444" seq="2" type="gold"/> </loyaltycards> <coupons/> <errors/> <customers/> </loyalty> </message
As propriedades de cada elemento do cartão serão:
Propriedade | Tipo de dados | Descrição do produto |
Go | Alfanumérico | Número de identificação do cartão de fidelidade |
Tipo | Alfanumérico | Identificador do tipo de cartão. |
ack | inteiro | Código de retorno |
quantidade | Número positivo | Saldo com o qual o cartão permaneceria |
cardType | Alfanumérico | Informa o tipo de cartão (ele será relatado apenas na tag <errors /> quando o ACK estiver 9501 - cartão inativo) |
RESPOSTA - ATIVAÇÃO DO CARTÃO (EM LOYALTYACTIVATION)
Resposta OK ( ACK = "0" nenhum dado é relatado na tag de cartões de fidelidade)
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530124002"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers/> </loyalty> </message
Resposta - Não OK (consulte o capítulo 3.1.1 Valores de atributo "ack" )
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530124222"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9500" info="333000000000" seq="1" type="loyaltycard-activation"/> </errors> <customers/> </loyalty> </message>
(Consulte também Solicitação de mecanismo - LoyaltyActivation )
RESPOSTA - ATIVAÇÃO DO CARTÃO (EM CONCLUIR)
Resposta OK (ACK = "0" e os dados do cartão que está sendo ativado são relatados ")
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170530124539"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="0.0" id="3330000000002" seq="2" type="3"/> </loyaltycards> <coupons/> <errors/> <customers/> </loyalty> </message>
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170530124833"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9500" info="33300000002" seq="2" type="loyaltycard-consume"/> </errors> <customers/> </loyalty> </message>
(Veja também Solicitação de Motor - FINISH )
RESPONSE - LOYALTYTRANSFER
Resposta OK
Na mensagem de resposta, o saldo final e o status dos cartões após a transação de transferência são relatados em cada um dos seqs.
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530130305"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="296.0" id="2220000000000" seq="1" type="2"/> <loyaltycard ack="0" amount="4.0" id="2220000000001" seq="2" type="2"/> </loyaltycards> <coupons/> <errors/> <customers/> </loyalty> </message>
Nota: Uma mensagem com o status " Confirmar " deve ser enviada para que os saldos sejam imputados.
Resposta - Não OK (consulte o capítulo 3.1.1 Valores de atributo "ack" )
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530131342"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9500" info="22200000001" seq="2" type="loyaltycard-transfer"/> </errors> <customers/> </loyalty> </message>
(Veja também Solicitação de mecanismo - LoyaltyTransfer )
RESPONSE - LOYALTYVOID
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <errors/> </loyalty> </message>
Resposta OK - Cupom e cartões
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <errors/> </loyalty> </message>
(Veja também Solicitação de mecanismo - LoyaltyVoid )
IMPUTAÇÃO DE SALDOS DE CARTÕES
<message companyId="sts" store="00001" terminal="010" date-time="2017-05-30 12:35:58" messageId="11" void-trx="false" response="true" init-tck="false" evaluate="false" status="finish" msg-version="9" map-version="1"> <loyaltycard-add seq="2" type="2" id="2220000000001" chargeAmount="10" /> </message>
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530132245"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="10.0" id="2220000000001" seq="2" type="2"/> </loyaltycards> <coupons/> <errors/> <customers/> </loyalty> </message>
Nota: Uma mensagem com o status " Confirmar " deve ser enviada para que os saldos sejam imputados.
Nota 2: No atributo "quantidade", o saldo com o qual o cartão permanecerá após a confirmação será relatado.
Resposta - Não OK (consulte o capítulo 3.1.1 Valores de atributo "ack" )
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" engine="2.6" mapversion="1" messageId="11" companyId="sts" store="00001" terminal="010" transaction="00001_010_20170530132536"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9500" info="22200000001" seq="2" type="loyaltycard-recharge"/> </errors> <customers/> </loyalty> </message>
DESCONTO NO SALDO DO CARTÃO
<message companyId="sts" store="00001" terminal="010" date-time="2005-01-04 12:35:28" messageId="11" void-trx="false" response="true" init-tck="false" evaluate="false" status="finish" msg-version="2.0" map-version="1"> <loyaltycard-add seq="2" type="gold" id="2220000000002" consumeAmount="6" /> </message>
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="18.0" id="2220000000002" seq="2" type="gold"/> </loyaltycards> <coupons/> <errors/> </loyalty> </message>
Nota: Uma mensagem com o status " Confirmar " deve ser enviada para que os saldos sejam imputados.
Nota 2: No atributo "quantidade", o saldo com o qual o cartão permanecerá após a confirmação será relatado.
Resposta - Não OK (consulte o capítulo 3.1.1 Valores de atributo "ack" )
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards/> <coupons/> <errors> <error ack="9500" info="4445000002200" seq="2" type="loyaltycard-recharge"/> </errors> </loyalty> </message>
Cartões de fidelidade: processo de atualização do saldo
Um valor foi adicionado ao status "loyaltyActivation" para a propriedade status do elemento loyaltcard, um valor CONFIRMAR para indicar que você deseja confirmar os pontos usados em uma transação anterior referenciada no atributo: "confirmReference".
Faça um consumo com vencimento em 14/11:
<message companyId="test" store="1" terminal="10" date-time="2018-11-09 10:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="finish" evaluate="true" offline="false"> <loyaltycard-add seq="1" id="10012" type="t1" amount="1000" consumeAmount="10" confirmationDate="201811141400" /> <item-add seq="2" code="2" unitprice="20" xprice="10000" qty="500" discountable="true" taxes="2100" /> <item-add seq="3" code="3" unitprice="10" xprice="10000" qty="1000" discountable="true" taxes="2100" /> </message>
Resposta:
<message ack="0" companyId="test" engine="6.1.4" mapversion="0" messageId="1" store="1" terminal="10" transaction="test_1_10_20181116163505">
<loyalty>
<loyaltycards>
<loyaltycard ack="0" amount="35.0" id="10012" seq="1" type="t1"/>
</loyaltycards>
<coupons/>
<errors/>
<customers/>
</loyalty>
</message>
Confirmamos a transação com o Commit:
<message companyId="test" store="1" terminal="10" date-time="2018-11-09 10:51:50" init-tck="false" messageId="1" void-trx="false" response="true" status="commit" evaluate="true" offline="false"></message>
Resposta:
<?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 resultado:
Como próximo passo no exemplo, passamos o dia 14-11 para observar a reversão do consumo, uma vez que não foi confirmado antes dessa data:
Agora vamos fazer outro, mas confirmando o consumo:
Primeiro, como fizemos anteriormente, geramos um consumo com maturidade 18-11
<message companyId="test" store="1" terminal="10" date-time="2018-11-09 10:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="finish" evaluate="true" offline="false"><loyaltycard-add seq="1" id="10012" type="t1" amount="1000" consumeAmount="10" confirmationDate="201811181400" /> <item-add seq="2" code="2" unitprice="20" xprice="10000" qty="500" discountable="true" taxes="2100" /> <item-add seq="3" code="3" unitprice="10" xprice="10000" qty="1000" discountable="true" taxes="2100" /> </message>
Resposta:
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="test" engine="6.1.4" mapversion="0" messageId="1" store="1" terminal="10" transaction="test_1_10_20181116165337"> <loyalty> <loyaltycards> <loyaltycard ack="0" amount="35.0" id="10012" seq="1" type="t1"/> </loyaltycards> <coupons/> <errors/> <customers/> </loyalty> </message>
Confirmamos a transação:
<message companyId="test" store="1" terminal="10" date-time="2018-11-09 10:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="commit" evaluate="true" offline="false"><loyaltycard-add seq="1" id="10012" type="t1" amount="1000" consumeAmount="10" confirmationDate="201811181400" /> <item-add seq="2" code="2" unitprice="20" xprice="10000" qty="500" discountable="true" taxes="2100" /> <item-add seq="3" code="3" unitprice="10" xprice="10000" qty="1000" discountable="true" taxes="2100" /> </message>
Resposta:
<?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 do movimento do cartão, o consumo é observado e o identificador da transação foi "test_1_10_20181116165337 ":
Agora enviamos a confirmação:
<message companyId="test" store="1" terminal="10" date-time="2018-11-09 09:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyActivation" evaluate="false" offline="false"> <loyaltycard-add seq="1" id="10012" type="t1" status="CONFIRM" confirmationReference="test_1_10_20181116165337" /> </message>
Resposta:
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="test" engine="6.1.4" mapversion="0" messageId="1" store="1" terminal="10" transaction="test_1_10_20181116165603"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers/> </loyalty> </message>
Através desta operação, o consumo foi confirmado e após 18-11 não será revertido.
RESPOSTA DO MECANISMO: ERROS DE TAGS
Além de cupons e cartões, um bloco de relatório de erros pode ser adicionado ao elemento de fidelidade da resposta. Dentro dele, serão relatados erros no processamento de determinados cupons e / ou cartões, tanto na emissão quanto no resgate.
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards/> <errors> <error ack="9505" info="4445901938700" amount= "" seq="1" type="loyaltycard-activation"/> </errors> </loyalty> </message>
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <coupons/> <loyaltycards/> <errors> <error ack="9501" info="5550010012948" amount= "100" seq="1" type="loyaltycard-validation"/> </errors> </loyalty> </message>
As propriedades dos elementos relatados na tag <Erros /> são:
Propriedade | Tipo de dados | Descrição do produto |
tipo | Alfanumérico | Informa o tipo de transação associado. Os valores atuais são: "criação de cupom", "resgate de cupom", "resgate de lealdade", "venda de lealdade", "ativação de lealdade" |
ack | Alfanumérico | O valor do código de erro, conforme descrito nos valores da propriedade ack, anteriormente neste documento. Consulte o capítulo 3.1.1. Valores dos atributos "ACK" |
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 da remessa relatada para resgate etc. |
descrição | Alfanumérico | É um atributo extra para fornecer uma melhor leitura do erro que ocorreu. No caso de cartões de fidelidade, você pode identificar o nome das promoções + o número do benefício em que ocorreu o erro |
quantidade | Numérico | Opcional - Este atributo será mostrado apenas quando um erro estiver sendo relatado para a consulta de validação (loyaltyValidation) |
seq | Número inteiro positivo | Número que identifica o elemento na transação à qual o benefício se aplica. |
Fluxos de cartões
Nesta seção, os fluxos desenvolvidos para cartões de fidelidade serão expostos, onde poderão ser observadas as diferentes mensagens que podem ser trocadas entre o POS, o mecanismo e o console do PROMO.
REGISTRO DE CARTÃO
O registro de um cartão será realizado no console central da PROMO. Nota: O campo CVV tem um comprimento máximo de 5 posições .
PEDIDO DE CARTÃO
ATIVAÇÃO DO CARTÃO (LOYALTYACTIVATION)
ATIVAÇÃO DO CARTÃO (FINISH)
TRANSFERÊNCIA ENTRE CARTÕES
ALOCAÇÃO OU DESCONTO DE SALDO FORA DE UMA TRANSAÇÃO
IMPUTAÇÃO OU DESCONTO DO SALDO ACUMULADO NA APLICAÇÃO DE UM BENEFÍCIO.
RESPOSTA DO MOTOR: RETURNFINISH
A avaliação do retorno é feita usando o mecanismo de simulação no console. Este é um processo em segundo plano, no qual o pos envia a transação para a PROMO com STATUS = "returnfinish" relatando o número da transação original e os itens retornados.
On-line, apenas será validado que o número da transação original exista na base de clientes e que a mensagem seja formada corretamente.
No processo em segundo plano, o PROMO recuperará a transação original, removerá os itens retornados 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 (comparada com os benefícios relatados na venda), serão os benefícios a serem cancelados da transação original.
No caso de uma transação de troca, o item devolvido será tratado como um retorno, executando as etapas e avaliações descritas acima. Os elementos relatados ao mecanismo serão de responsabilidade da pos.
<?xml version="1.0" encoding="UTF-8"?><message ack="0" engine="2.6" mapversion="2" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170829162054"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers/> </loyalty> </message>
Resposta - ERRO (consulte o capítulo 3.1.1 Valores de atributo "ack" )
<?xml version="1.0" encoding="UTF-8"?><message ack="9004" engine="2.6" mapversion="2" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170829162239"/>
Clientes
Os dados correspondentes ao cliente consultado e os elementos de lealdade associados a ele são adicionados à mensagem de resposta em "LoyaltyValidation". Vale esclarecer que, se o cliente tiver um cartão inativo, esses cartões não retornarão na resposta de validação de lealdade do cliente. Somente os elementos de lealdade ativos associados a eles serão relatados.
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="6666" email="[email protected]" identifier="3055881" lastName="" name="Rojo Marcos" seq="1"> <loyaltycard ack="0" amount="100.0" id="3330000000001" type="1"/> <coupon ack="0" amount="0.0" barcode="1000010012948" couponId="1" seq="1"/> </customer> </customers> </loyalty> </message>
(Consulte também Solicitação de mecanismo - LoyaltyValidation )
OPERAÇÃO POR SEGMENTO
Vamos imaginar que temos uma Promoção que beneficia os clientes com o segmento "ABC1". O Operativo para trabalhar com a referida Promoção seria:
- Realizamos uma operação LoyaltyValidation (consulte Solicitação de mecanismo - LoyaltyValidation ) para conhecer os segmentos aos quais o cliente 9991 pertence:
<message companyId="sts" store="00001" terminal="010" date-time="2017-06-04 12:30:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" " status="loyaltyValidation" map-version="15" suggest="true" suggest-seq="3"> <customer-add seq="1" id="9991"/> </message>
2. Em resposta à solicitação anterior, a Promo nos informará como uma das propriedades dos segmentos aos quais esse cliente pertence: Como vemos no exemplo, o cliente pertence aos segmentos ABC1, D18 e K1
<message ack="0" engine="2.6" mapversion="1" messageId="1" companyId="sts" store="1" terminal="1" transaction="1_1_20170515152511"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="9991" email="[email protected]" identifier="3055881" lastName="" name="Rojo Marcos" seq="1" segment="ABC1,D18,K1"> <loyaltycard ack="0" amount="100.0" id="3330000000001" type="1"/> <coupon ack="0" amount="0.0" barcode="1000010012948" couponId="1" seq="1"/> </customer> </customers> </loyalty> </message>
3. Por fim, realizamos a transação de venda com o cliente enviando suas informações completas:
<message companyId="sts" store="00001" terminal="010" date-time="2017-06-04 12:30:00" messageId="0010" void-trx="false" response="true" init-tck="true" evaluate="true" status="Finish" map-version="15" suggest="true" suggest-seq="3"> <customer-add seq="1" id="9991" segment="ABC1,D18,K1" /> </message>
Dessa forma, a transação será avaliada e, sendo um cliente que pertence ao segmento ABC1, a Promoção será premiada.
CRIAR CLIENTES (NOTA: SOMENTE SE A OPERAÇÃO SEM CLIENTES PRÉ-EXISTENTES TIVER SIDO ATIVADA)
Há casos em que você precisa criar clientes no momento, por exemplo, para poder enviar cupons eletrônicos por email. Para esse fim, foi incorporada a possibilidade de enviar a definição do cliente (dados mínimos necessários) do correio promocional.
Os clientes serão criados usando o status "loyaltyValidation" no caso de enviar os dados mínimos e, ao mesmo tempo, o Promo detectar que o cliente não existe. Os dados mínimos mencionados, por exemplo, seriam os marcados em negrito e o seguinte exemplo:
<customer-add seq="1" id="10090504" identifier="10090504" type="test" name="pepe" lastName="rodrigues" identifierType="cpf" email="mimail@test.com" />
Vamos agora ver um exemplo da troca dessas mensagens:
Fazemos uma solicitação com loyaltyValidation e o cliente não existe:
<message companyId="napse" store="1" terminal="10" date-time="2018-08-09 10:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyValidation" evaluate="true" offline="false" > <customer-add seq="1" id="10090504" type="test" limitedBenefits="5b7044246491fa1604a6d15b:200.00;" /> </message>
A resposta fornece valores padrão:
<message ack="0" companyId="napse" engine="6.4.6" mapversion="1" messageId="1" store="1" terminal="10" transaction="napse_1_10_20180809105150"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="10090504" email="-" identifier="-" lastName="-" limitedBenefits="" name="-" segment="" seq="1"/> </customers> </loyalty> </message>
2. Nesse caso, enviamos dados do cliente, mas não preenchemos todos os campos necessários:
<message companyId="napse" store="1" terminal="10" date-time="2018-08-09 10:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyValidation" evaluate="true" offline="false" > <customer-add seq="1" id="10090504" identifier="10090504" type="test" limitedBenefits="5b7044246491fa1604a6d15b:200.00;" name="pepe" lastName="rodrigues" identifierType="cpf" /> </message>
A resposta ainda contém dados padrão:
<message ack="0" companyId="napse" engine="6.4.6" mapversion="1" messageId="1" store="1" terminal="10" transaction="napse_1_10_20180809105150"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="10090504" email="-" identifier="10090504" lastName="rodrigues" limitedBenefits="" name="pepe" segment="" seq="1"/> </customers> </loyalty></message>
3. Agora enviamos TODOS os dados obrigatórios para o cliente a ser criado
<message companyId="napse" store="1" terminal="10" date-time="2018-08-09 10:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyValidation" evaluate="true" offline="false" > <customer-add seq="1" id="10090504" identifier="10090504" type="test" limitedBenefits="5b7044246491fa1604a6d15b:200.00;" name="pepe" lastName="rodrigues" identifierType="cpf" email="[email protected]" /> </message>
A resposta é:
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" companyId="napse" engine="6.4.6" mapversion="1" messageId="1" store="1" terminal="10" transaction="napse_1_10_20180809105150"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="10090504" email="[email protected]" identifier="10090504" lastName="rodrigues" limitedBenefits="" name="pepe" segment="" seq="1"/> </customers> </loyalty> </message>
4. Agora vamos enviar a mensagem que enviamos no ponto 1, que possui apenas os dados básicos do cliente e para os quais no ponto 1 ele retornou valores padrão (o cliente não era conhecido), enquanto agora teria que retornar todos os dados que já conhecemos e criamos no ponto 3.
<message companyId="napse" store="1" terminal="10" date-time="2018-08-09 10:51:50" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyValidation" evaluate="true" offline="false" > <customer-add seq="1" id="10090504" type="test" limitedBenefits="" /> </message>
A resposta é efetivamente:
<?xml version="1.0" encoding="UTF-8"?> <message ack="0" companyId="napse" engine="6.4.6" mapversion="1" messageId="1" store="1" terminal="10" transaction="napse_1_10_20180809105150"> <loyalty> <loyaltycards/> <coupons/> <errors/> <customers> <customer code="10090504" email="[email protected]" identifier="10090504" lastName="rodrigues" limitedBenefits="" name="pepe" segment="" seq="1"/> </customers> </loyalty> </message>
Operativo (com base em possíveis cenários):
Operativo | Giftcard | Bolsa | Cartão de Pontos | Presente - Uso Único |
Registro de cartão | Por arquivo INATIVO | Por arquivo / manual ativo ou ativo | Por arquivo INATIVO | Por arquivo INATIVO |
Consulta de Cartão | O valor - tipo será relatado na tag de erros (inativo) | Ele será relatado na tag Erros, se estiver inativo, ou na tag LoyaltyCard, se estiver ativo. Tipo - Valor | Será relatado na tag de erros (por estar inativo) Valor - tipo de cliente | Será relatado na tag de erros (por estar inativo) Valor - Tipo |
Ativação do cartão | Deve ser ativado por meio da mensagem "Loyaltyativation" ou "finish" Valida CVV | Pode ser ativado pela mensagem "Loyaltyativation", "finish" ou quando é recarregado pela primeira vez | Pode ser ativado pela mensagem "Ativação de fidelidade", "concluir" ou quando a primeira recarga for efetuada.Se for enviado, o Cliente validará. | Pode ser ativado pela mensagem "Ativação de fidelidade", "finalizar" ou quando é recarregado pela primeira vez. CVV válido |
Transferir | Suporta apenas transferência total de saldo - Depois que o saldo total do cartão foi transferido, o cartão é cancelado. CVV válido | Ele suporta transferências parciais sem alterar o status do cartão. | Não admite transferência de nenhum tipo. | Não admite transferência de nenhum tipo. |
Imputação de saldo | Não suporta recarga de balança. | Suporta recargas até um valor máximo. | Suporta recargas de recarga. Se um cliente for enviado, ele será validado. | Suporta recargas de recarga. CVV válido. |
Equilíbrio de consumo | Ele suporta consumir o saldo em mais de uma transação sem alterar o estado do cartão. CVV válido | Suporta consumir o saldo em mais de uma transação sem alterar o status do cartão | Ele admite consumir o saldo em mais de uma transação sem alterar o status do cartão.Se um cliente for enviado, ele será validado. | Ele permite apenas um saldo único ou consumo total ou parcial; após esse consumo único, o cartão fica INATIVO. CVV válido |
Limites por clientes
Quando o benefício é limitado pelos clientes, a operação do mecanismo deve ser a seguinte:
Para operar com os limites do cliente, a primeira mensagem enviada da posição deve ser uma validação de status loyaltyValidation com o elemento customer, para carregar os limites do cliente antes de fazer a transação.
O mecanismo relatará os limites consumidos no elemento customer no atributo limitedBenefits.
Importante: Para carregar o limite do cliente no mecanismo, uma loyaltyValidation deve ser feitacom init-tck = "true" com o elemento customer , ela deve ser a primeira mensagem a operar.
Exemplo para mensagens de limites
Nota: Neste exemplo, uma promoção foi definida com um benefício monetário fixo de 100 e com um limite monetário de 300 por cliente, ou seja, neste caso, se o cliente fizer mais de 3 transações, nas 4, não será mais aplicável porque elas passaram o limite configurado na promoção.
Abaixo está como operar:
<message companyId="napse" store="1" terminal="1" date-time="2019-02-25 12:02" init-tck="true" messageId="20" void-trx="false" response="true" status="loyaltyValidation" evaluate="false" suggest="true">
<customer-add seq="1" id="2" type="test" />
<item-add seq="2" qty="1" code="1" magnitude="0" xprice="200" unitprice="200"/>
</message>
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="6.4.0" mapversion="25" messageId="20" store="1" terminal="1" transaction="napse_1_1_20190225125106">
<loyalty>
<loyaltycards/>
<coupons/>
<errors/>
<customers>
<customer code="2" email="[email protected]" identifier="25456742" lastName="Perez" limitedBenefits="5c73fa11a8b0ea2f888130c0:300.00;" name="Juan" seq="1">
<loyaltycard ack="0" amount="2088.00" id="1110000000" status="Activa" type="test"/>
<limit amount="300.00" id="5c73fa11a8b0ea2f888130c0" promotionDescription="promoLimite" promotionName="promoLimite"/>
</customer>
</customers>
</loyalty>
</message>
Na resposta, podemos ver as informações do cliente com os benefícios limitados que indicam o limite por cliente do benefício. Em outras palavras, nesta promoção, podemos usá-lo três vezes por cliente, pois o benefício é de 100 por benefício e o limite monetário é de 300.
<message companyId="napse" store="1" terminal="1" date-time="2019-02-25 12:02" init-tck="false" messageId="20" void-trx="false" response="true" status="sales" evaluate="true" suggest="true">
<customer-add seq="1" id="2" type="test" />
<item-add seq="2" qty="1" code="1" magnitude="0" xprice="200" unitprice="200"/>
</message>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<message ack="0" companyId="napse" engine="6.4.0" mapversion="25" messageId="20" store="1" terminal="1">
<optional>
<promo code="promoLimite" id="promoLimite" nro="5c73f81fa8b0ea2f888130ab">
<benefit TLOGMessage="promoLimite" account="" applicationMethod="resume" baseAmount="200.00" benefitType="FixedDiscount" discountAmount="100.00" displayMessage="promoLimite" hasLimit="true" name="5c73f81fa8b0ea2f888130ab" nro="5c73fa11a8b0ea2f888130c0" order="1" printerMessage="promoLimite" prorationMethod="PROPORTIONAL" unit="qty">
<apply>
<item magnitude="0.000" qty="1.000" seq="2" value="100.00" valueWithTaxes="100.00" xprice="200.00"/>
</apply>
</benefit>
</promo>
</optional>
</message>
Então fazemos o status finish
<message companyId="napse" store="1" terminal="1" date-time="2019-02-25 12:02" init-tck="false" messageId="20" void-trx="false" response="true" status="finish" evaluate="true" suggest="true">
<customer-add seq="1" id="2" type="test" />
<item-add seq="2" qty="1" code="1" magnitude="0" xprice="200" unitprice="200"/>
</message>
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="6.4.0" mapversion="25" messageId="20" store="1" terminal="1" transaction="napse_1_1_20190225125233">
<loyalty>
<loyaltycards/>
<coupons/>
<errors/>
<customers/>
</loyalty>
</message>
Finalmente o commit
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="6.4.0" mapversion="25" messageId="20" store="1" terminal="1" transaction="napse_1_1_20190225125233">
<loyalty>
<loyaltycards/>
<coupons/>
<errors/>
<customers/>
</loyalty>
</message>
<?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 a loyalty validation novamente , veremos que consumimos 100 do limite, pois a promoção deu um benefício de 100 para cada transação.
<message companyId="napse" store="1" terminal="1" date-time="2019-02-25 12:05" init-tck="true" messageId="21" void-trx="false" response="true" status="loyaltyValidation" evaluate="false" suggest="true"> <customer-add seq="1" id="2" type="test" /> </message>
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="6.4.0" mapversion="25" messageId="21" store="1" terminal="1" transaction="napse_1_1_20190225125107">
<loyalty>
<loyaltycards/>
<coupons/>
<errors/>
<customers>
<customer code="2" email="[email protected]" identifier="25456742" lastName="Perez" limitedBenefits="5c73fa11a8b0ea2f888130c0:200.00;" name="Juan" seq="1">
<loyaltycard ack="0" amount="2088.00" id="1110000000" status="Activa" type="test"/>
<limit amount="200.00" id="5c73fa11a8b0ea2f888130c0" promotionDescription="promoLimite" promotionName="promoLimite"/>
</customer>
</customers>
</loyalty>
</message>
Se você fizer mais 2 transações, a promoção não será mais aplicada porque você excedeu o limite.
Preços
Um novo status chamado de preços foi adicionado ao sistema de mensagens do mecanismo , esse estado nos informará sobre os preços dos itens a serem consultados, para verificar o preço em que os itens devem ser relatados com o atributo unitprice = 0, esse novo status avaliará o ticket da mensagem enviada e ele responderá aos preços solicitados de acordo com a avaliação da lista de preços, no caso de adicionar ou remover elementos para modificar as informações do ticket, use as operações de adição e cancelamento de elementos (para ver mais detalhes sobre preço, consulte o manual do usuário).
As listas de preços estão associadas às lojas, portanto, o campo da loja é essencial para encontrar preços.
Nota: Para que a funcionalidade de preço esteja disponível, o mecanismo precisará ter no arquivo de configuração (config.xml) na tag geral o atributo: <disablePrices> false </disablePrices>
<message companyId="napse" store="test" terminal="1" date-time="2018-02-19 12:35" init-tck="true" messageId="1" void-trx="false" response="true" status="prices" evaluate="true" suggest="true"> <item-add seq="1" qty="2" code="00-1114298" magnitude="0" xprice="200" unitprice="0"/> <item-add seq="2" qty="1" code="768-76-8409" magnitude="0" xprice="0" unitprice="0"/> </message>
Resposta esperada
<message ack="0" companyId="napse" engine="6.4.0" mapversion="0" messageId="1" store="test" terminal="1">
<prices lastUpdate="19/02/2019 13:22:08">
<item code="00-1114298" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:06" priceListId="napse_LP0_test" qty="2.00" seq="1" supplierFinancial="PR3" supplierFinancialAmount="16070.00" supplierItem="PR1" supplierItemAmount="65988.00" unitprice="48535.46" xprice="97070.92"/>
<item code="768-76-8409" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:00" priceListId="napse_LP0_test" qty="1.00" seq="2" supplierFinancial="PR1" supplierFinancialAmount="32340.00" supplierItem="PR3" supplierItemAmount="24791.00" unitprice="73921.00" xprice="73921.00"/>
</prices>
</message>
As propriedades dos elementos relatados na tag <Prices /> são:
Propriedade | Tipo de dados | Descrição do produto |
lastupdate | Data com hora | Relate a data da última atualização de preço (o console entrou em contato com o mecanismo para informar preços). |
com desconto | Booleano | Determinar se o item suporta descontos |
manualDiscount | Booleano | Determina se o item suporta desconto manual |
priceLastUpdate | Alfanumérico | Data em que o preço do item foi atualizado |
priceListId | Alfanumérico | É a empresa mais o código da lista de preços a partir do qual o preço <código da empresa> _ <código da lista de preços> |
| qtde | Número inteiro positivo | Número que identifica a quantidade do item |
seq | Número inteiro positivo | Número que identifica o elemento dentro da transação |
| supplierFinancial | Alfanumérico | Opcional. É o código do provedor financeiro do item |
| supplierFinancialAmount | Numérico | Opcional. É a quantia que o provedor financeiro reconhece |
| supplierItem | Alfanumérico | Opcional. É o código do fornecedor do item |
| supplierItemAmount | Numérico | Opcional. É a quantia que o provedor reconhece |
| preço unitário | Numérico | É o preço do item consultado para o motor |
| xprice | Numérico | É o preço do item multiplicado pelo atributo qty |
Os preços também podem ser calculados em outros status, enviando o item com unitprice = 0
Nesse caso, enviamos um status de vendas com 2 itens com preço unitário = 0 e um com preço
<message companyId="napse" store="test" terminal="1" date-time="2019-02-19 14:35" init-tck="false" messageId="13" void-trx="false" response="true" status="sales" evaluate="true" suggest="true"> <item-add seq="1" qty="2" code="00-1114298" magnitude="0" xprice="200" unitprice="0"/> <item-add seq="2" qty="1" code="768-76-8409" magnitude="0" xprice="0" unitprice="0"/> <item-add seq="3" qty="1" code="769-51-6063" magnitude="0" xprice="10000" unitprice="10000"/> </message>
Na resposta, vemos que o benefício da promoção de 10% em cada item é aplicado para os 3 itens, para os dois com um item com preço unitário = 0 o preço foi calculado e 10% foi aplicado, abaixo está o bloco de preços de onde os preços foram obtidos.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<message ack="0" companyId="napse" engine="6.4.0" mapversion="5" messageId="13" store="test" terminal="1">
<optional>
<promo code="test" id="test" nro="5c59964c47452a7b3c22724a">
<benefit TLOGMessage="test" account="" applicationMethod="resume" baseAmount="180991.92" benefitType="PercentageDiscount" discountPercentage="10.00" displayMessage="test" name="5c59964c47452a7b3c22724a" nro="5c670e1ea8b0ea296089de8f" order="1" printerMessage="test" prorationMethod="PROPORTIONAL" unit="qty">
<apply>
<item magnitude="0.000" qty="2.000" seq="1" value="9707.09" valueWithTaxes="20.00" xprice="97070.92"/>
<item magnitude="0.000" qty="1.000" seq="2" value="7392.10" valueWithTaxes="0.00" xprice="73921.00"/>
<item magnitude="0.000" qty="1.000" seq="3" value="1000.00" valueWithTaxes="1000.00" xprice="10000.00"/>
</apply>
</benefit>
</promo>
</optional>
<prices lastUpdate="19/02/2019 15:52:56">
<item code="00-1114298" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:06" priceListId="napse_LP0_test" qty="2.00" seq="1" supplierFinancial="PR3" supplierFinancialAmount="16070.00" supplierItem="PR1" supplierItemAmount="65988.00" unitprice="48535.46" xprice="97070.92"/>
<item code="768-76-8409" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:00" priceListId="napse_LP0_test" qty="1.00" seq="2" supplierFinancial="PR1" supplierFinancialAmount="32340.00" supplierItem="PR3" supplierItemAmount="24791.00" unitprice="73921.00" xprice="73921.00"/>
</prices>
</message>
Novo atributo do cabeçalho tenderGroupCode
Para determinar se os avaliadores aplicam preço de crédito ou preço de venda regular a partir da lista de preços , um atributo foi adicionado ao cabeçalho tenderGroupCode .
Quando a mensagem tiver tenderGroupCode e seu valor for "cr", o motor aplicará o preço do crédito, caso não possua o atributo ou tenha outro valor, o preço a aplicar será o preço de venda .
Exemplo de mensagem com tenderGroupCode :
<message companyId="napse" store="test" terminal="1" date-time="2019-02-19 14:35" init-tck="false" messageId="14" void-trx="false" response="true" status="sales" evaluate="true" suggest="true" tenderGroupCode="cr"> <item-add seq="1" qty="2" code="00-1114298" magnitude="0" xprice="200" unitprice="0"/> <item-add seq="2" qty="1" code="768-76-8409" magnitude="0" xprice="0" unitprice="0"/> <item-add seq="3" qty="1" code="769-51-6063" magnitude="0" xprice="10000" unitprice="10000"/> </message>
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <message ack="0" companyId="napse" engine="6.4.0" mapversion="5" messageId="14" store="test" terminal="1" tenderGroupCode="cr"> <optional> <promo code="test" id="test" nro="5c59964c47452a7b3c22724a"> <benefit TLOGMessage="test" account="" applicationMethod="resume" baseAmount="144668.20" benefitType="PercentageDiscount" discountPercentage="10.00" displayMessage="test" name="5c59964c47452a7b3c22724a" nro="5c670e1ea8b0ea296089de8f" order="1" printerMessage="test" prorationMethod="PROPORTIONAL" unit="qty"> <apply> <item magnitude="0.000" qty="2.000" seq="1" value="6222.20" valueWithTaxes="20.00" xprice="62222.00"/> <item magnitude="0.000" qty="1.000" seq="2" value="7244.62" valueWithTaxes="0.00" xprice="72446.20"/> <item magnitude="0.000" qty="1.000" seq="3" value="1000.00" valueWithTaxes="1000.00" xprice="10000.00"/> </apply> </benefit> </promo> </optional> <prices lastUpdate="19/02/2019 16:11:13"> <item code="00-1114298" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:06" priceListId="napse_LP0_test" qty="2.00" seq="1" supplierFinancial="PR3" supplierFinancialAmount="16070.00" supplierItem="PR1" supplierItemAmount="65988.00" unitprice="31111.00" xprice="62222.00"/> <item code="768-76-8409" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:00" priceListId="napse_LP0_test" qty="1.00" seq="2" supplierFinancial="PR1" supplierFinancialAmount="32340.00" supplierItem="PR3" supplierItemAmount="24791.00" unitprice="72446.20" xprice="72446.20"/> </prices> </message>
Mensagem de amostra SEM tenderGroupCode
<message companyId="napse" store="test" terminal="1" date-time="2019-02-19 14:36" init-tck="true" messageId="15" void-trx="false" response="true" status="sales" evaluate="true" suggest="true"> <item-add seq="1" qty="2" code="00-1114298" magnitude="0" xprice="200" unitprice="0"/> <item-add seq="2" qty="1" code="768-76-8409" magnitude="0" xprice="0" unitprice="0"/> <item-add seq="3" qty="1" code="769-51-6063" magnitude="0" xprice="10000" unitprice="10000"/> </message>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<message ack="0" companyId="napse" engine="6.4.0" mapversion="5" messageId="15" store="test" terminal="1">
<optional>
<promo code="test" id="test" nro="5c59964c47452a7b3c22724a">
<benefit TLOGMessage="test" account="" applicationMethod="resume" baseAmount="180991.92" benefitType="PercentageDiscount" discountPercentage="10.00" displayMessage="test" name="5c59964c47452a7b3c22724a" nro="5c670e1ea8b0ea296089de8f" order="1" printerMessage="test" prorationMethod="PROPORTIONAL" unit="qty">
<apply>
<item magnitude="0.000" qty="2.000" seq="1" value="9707.09" valueWithTaxes="20.00" xprice="97070.92"/>
<item magnitude="0.000" qty="1.000" seq="2" value="7392.10" valueWithTaxes="0.00" xprice="73921.00"/>
<item magnitude="0.000" qty="1.000" seq="3" value="1000.00" valueWithTaxes="1000.00" xprice="10000.00"/>
</apply>
</benefit>
</promo>
</optional>
<prices lastUpdate="19/02/2019 16:15:14">
<item code="00-1114298" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:06" priceListId="napse_LP0_test" qty="2.00" seq="1" supplierFinancial="PR3" supplierFinancialAmount="16070.00" supplierItem="PR1" supplierItemAmount="65988.00" unitprice="48535.46" xprice="97070.92"/>
<item code="768-76-8409" discountable="true" magnitude="0.00" manualDiscount="true" priceLastUpdate="19/02/2019 13:18:00" priceListId="napse_LP0_test" qty="1.00" seq="2" supplierFinancial="PR1" supplierFinancialAmount="32340.00" supplierItem="PR3" supplierItemAmount="24791.00" unitprice="73921.00" xprice="73921.00"/>
</prices>
</message>
Dados os pedidos anteriores com e sem tenderGroupCode, os preços variam, um é o preço de crédito e o outro é o preço de venda regular.
- Observa-se que com o tenderGroupCode o valor que o motor respondeu é o seguinte:
<magnitude do item = "0,000" qty = "1,000" seq = "2" value = "7244,62" valueWithTaxes = "0,00" xprice = "72446.20" />
- Observa-se que SEM o tenderGroupCode o valor que o motor respondeu é o seguinte:
<magnitude do item = "0,000" qty = "1,000" seq = "2" value = "7392,10" valueWithTaxes = "0,00" xprice = "73921,00" />
Console: Serviços REST
SERVIÇOS REST - CONSULTA AO CLIENTE
A PROMO exibe um serviço que permite que os cartões sejam consultados no banco de dados usando o ID do cliente.
Juntamente com os campos do cliente, uma lista de cartões e cupons, itens de fidelidade também é retornada.
Se você não possui elementos de lealdade, os cartões ou cupons vazios serão devolvidos.O
código da consulta deve ser exato e somente um resultado será retornado, se o cliente existir.
O formato em que é respondido está em JSON.
Para os exemplos, foram feitas consultas de clientes usando a ferramenta "PostMan" do Chrome. O acesso ao acesso
deve ser solicitado primeiro usando o APP cUrl ( https://curl.haxx.se/ ) com o seguinte comando:
curl –v –X POST –u meu cliente: -d "tipo_de_venção = senha" –d "nome de usuário = remetente" –d "senha = companheiro" –d "escopo = leitura" {*} http: // localhost: 8080 / promo / oauth / token * |
(O usuário e os dados de passagem devem ser aqueles que correspondem ao usuário de comunicação Motor / Console. A URL de acesso deve se referir ao IP e à porta em que o console PROMO está sendo executado) Obtido o token, a consulta pode ser realizada (postMan ): (curl -X GET -H "Autorização: portador 8c014b30-a674-456e-bc18-29a072a7a1f8" -H "Tipo de conteúdo: application / json" -H "Aceitar: application / json" "http: // localhost: 8080 / promo / api / rest / customer? Code = 1 ") Obtendo a seguinte resposta:
{
"_id": "59a992cacaec3625e8447663",
"code": "1",
"creationDate": "2017-09-01T17:03:06Z",
"email": "gala @sts.com",
"identificationType": "DNI",
"identifier": "54333222",
"isActive": true,
"lastName": "Higgins",
"name": "GALA",
"version": 0,
*"cards": \[*
{
"_id": "59a99439caec3625e84476f8",
"amount": 254,
"code": "2220000000001",
"created": "2017-09-01T17:09:13Z",
"isConsumed": false,
"status": "ENABLED",
"storeCode": "BLC",
"terminalCode": "2",
"transactionId": "BLC_201709011409677",
"type": "2",
"validFrom": "2017-09-01T03:00:00Z",
"validTo": "2018-09-01T03:00:00Z",
"version": 2,
"customerId": "1"
}
],
*"coupons": \[\]*
}
Caso o cliente não exista na base, a resposta será retornada vazia.
SERVIÇOS REST - CONSULTA DE CUPONS
A PROMO exibe um serviço que permite que os cupons sejam consultados no banco de dados usando apenas o número do cupom e, em resposta, são obtidos os movimentos associados ao referido cupom
(v6.5.10) Você também pode fazer perguntas sobre o histórico de movimentos de cupons.
Los parámetros de entrada de la consulta son:
Propiedad | Tipo de dato | Descripción |
| companyId | Alfanumérico | Código a empresa |
| barcode | Alfanumérico | Código do cupon |
limit | Numérico | Quantidade de registros de movimento a serem retornados (padrão: 5) com um máximo de 100.000 por consulta. |
dateFrom | Numérico | (a partir de 6.5.10) Data de início no formato AAAAMMDD. Se o código não foi especificado. |
dateTo | Numérico | (a partir 6.5.10) Data de Final no formato AAAAMMDD. Se o código não foi especificado. |
couponAction | Alfanumérico | (a partir 6.5.10) Código de operação que deseja consultar. Se código. Por padrão, são todas as operações. Os valores disponíveis são: CREATE, REDEEM, VOID |
EXEMPLO 1: os dados do cupom 1020000000007 são solicitados
(curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8" -H "Content-type: application/json" -H "Accept: application/json" http://localhost:8080/promo/api/rest/coupon?barcode=1020000000007)
Obtenção da seguinte resposta:
{
"_id": "59a993d6caec3625e84476e1",
"barcode": "1020000000007",
"consumed": false,
"couponFormat": "PRE_PRINTED",
"couponStatus": "ACTIVE",
"couponType": "2",
"issuedDate": "2017-09-01T17:07:34Z",
"maxUsageTimes": 1,
"storeCode": "BC",
"terminalCode": "2",
"transactionId": "BC_201709011407171",
"usedTimes": 0,
"validFrom": "2017-09-01T17:07:34Z",
"validTo": "2117-08-08T17:07:34Z",
"version": 0,
*"couponHistory": \[*
{
"couponAction": "CREATE",
"date": "2017-09-01T17:07:34Z",
"storeCode": "BC"
}
]
}
Caso o cliente não exista na base, a resposta será retornada vazia.
EXEMPLO 2: Todos os cupons criados no período 01/06 / 2020-01 / 07/2020 são solicitados para a caducidade da empresa no limite de 100.000 inscrições.
(curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8" -H "Content-type: application/json" -H "Accept: application/json"http://localhost:8080/promo/api/rest/coupon?dateFrom=20200601&dateTo=20200701&companyId=napse&limit=100000&couponAction=CREATE')
Com resposta:
{
"couponHistory": [
{
"transactionId": "napse_1_10_20200608105150",
"date": "2020-06-05T18:11:00Z",
"coupon": "1010010106479",
"couponAction": "CREATE",
"storeCode": "1",
"terminalCode": "10"
},
{
"transactionId": "napse_1_10_20200608105150",
"date": "2020-06-05T18:11:00Z",
"coupon": "1010010102945",
"couponAction": "CREATE",
"storeCode": "1",
"terminalCode": "10"
},
{
"transactionId": "napse_1_10_20200608105150",
"date": "2020-06-05T18:11:00Z",
"coupon": "1010010109418",
"couponAction": "CREATE",
"storeCode": "1",
"terminalCode": "10"
},
{
"transactionId": "napse_1_10_20200608105250",
"date": "2020-06-05T18:21:30Z",
"coupon": "1010010102891",
"couponAction": "CREATE",
"storeCode": "1",
"terminalCode": "10"
}
]
}
SERVIÇOS REST - CONSULTA DE CARTÕES
A PROMO exibe um serviço que permite que os cartões sejam consultados no BBDD usando apenas o número do cartão e, em resposta, são obtidos os movimentos associados ao referido cartão. Os dados retornados são: tipo de operação, quantidade, armazenamento.
O código da consulta deve ser exato e somente um resultado será retornado, se o cartão existir. O formato no qual é respondido está em JSON e retorna apenas as informações dos cartões ativados. Para os exemplos, as consultas do cartão foram feitas usando a ferramenta "PostMan" do Chrome. É necessário obter um novo Tocken (cUrl) e, em seguida, a consulta do cartão (PostMan) pode ser executada.
(enrolar -X GET -H "Autorização: portador 8c014b30-a674-456e-bc18-29a072a7a1f8 -H" Tipo de conteúdo: application / json "-H" Aceitar: application / json "" http: // localhost: 8080 / promo / api / rest / card? code = 2220000000001 ")
{
"_id": "59a99439caec3625e84476f8",
"amount": 254,
"code": "2220000000001",
"created": "2017-09-01T17:09:13Z",
"isConsumed": false,
"status": "ENABLED",
"storeCode": "BLC",
"terminalCode": "2",
"transactionId": "BLC_201709011409677",
"type": "2",
"validFrom": "2017-09-01T03:00:00Z",
"validTo": "2018-09-01T03:00:00Z",
"version": 2,
"customerId": "1",
*"cardHistory": \[*
{
"amount": "254.0",
"cardAction": "AMOUNT_UPDATE",
"date": "2017-09-01T17:09:52Z"
},
{
"amount": "0",
"cardAction": "ASSIGN_CUSTOMER",
"date": "2017-09-01T17:09:44Z"
}
]
}
Caso o cliente não exista na base, a resposta será retornada vazia.
SERVIÇOS REST - CONSULTA DO MAP
O PROMO expõe um serviço que permite consultar mapas usando apenas o número do mapa e, em resposta, você obtém o xml do mapa da mesma maneira que obtém da opção "download". Como no caso dos serviços REST descritos anteriormente, é necessária autorização via OAuth2. A figura a seguir mostra o conteúdo da solicitação de exemplo:
Onde:
Operação: valor getMaps para obter o mapa solicitado.
companyId: identificação ou empresa que faz a solicitação.
mapNumber: número do mapa solicitado.
A resposta é do tipo:
<?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
<ack>0</ack>
<message>OK</message>
<maps>
<map version:="5">
<?xml version="1.0" encoding="iso-8859-1"?>
<promo-engine start-date="15/01/2019 00:00" end-date="22/01/2084 23:59" validity-after-void="365" map-version="5" suggest="conditional">
<parameter key="Logging" value="true" />
<parameter key="LogConfigurationFile" value="logrsca.xml" />
<parameter key="LogConfigurationCategory" value="com.synthesis.promo" />
<parameter key="Descriptors" value="descriptor.properties" />
<parameter key="DAOConfigurationFeatures" value="com.synthesis.promo.engine.dao.ConfigurationFeatures" />
<parameter key="EvaluationAlgorithmClass" value="com.synthesis.promo.engine.evaluation.InStepsAlgorithm" />
<promotions>
<promotion nro="5c3df6e0f7a021227ca8f7d4" name="Promociòn 10% de Descuento SKU 1" code="Promociòn 10% de Descuento SKU 1" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="not" descriptor="Promociòn 10% de Descuento SKU 1">
<sets>
<set name="5c3df6f6f7a021227ca8f7d8" type="item" attribute="code" comparator="Into" value="1" />
</sets>
<condition type="basic" name="Exists">
<parameter key="use-set" value="5c3df6f6f7a021227ca8f7d8" />
</condition>
<benefits>
<benefit instance="PercentageDiscount" nro="5c3df748f7a021227ca8f7dc">
<parameter key="displayMessage" value="Promociòn 10% de Descuento SKU 1" />
<parameter key="printerMessage" value="Promociòn 10% de Descuento SKU 1" />
<parameter key="TLOGMessage" value="Promociòn 10% de Descuento SKU 1" />
<parameter key="applicationMethod" value="lineByLine" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="5c3df6e0f7a021227ca8f7d4" />
<parameter key="percent" value="10" />
<parameter key="unit" value="qty" />
<applied-elements>
<use-set name="5c3df6f6f7a021227ca8f7d8" />
</applied-elements>
</benefit>
</benefits>
</promotion>
<promotion nro="5c3dfcd5f7a021227ca8f807" name="Promocion 3x2 en SKU 2" code="Promocion 3x2 en SKU 2" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="always" descriptor="Con 3 items del SKU 2 obtendra Promocion 3x2 en SKU 2">
<sets>
<set name="5c3dfd00f7a021227ca8f80c" type="item" attribute="code" comparator="Into" value="2" />
</sets>
<combo>
<combo-component min="3" max="3" attribute="qty" use-set="5c3dfd00f7a021227ca8f80c" />
</combo>
<benefits>
<benefit instance="PercentageDiscount" nro="5c3dfd52f7a021227ca8f80e">
<parameter key="displayMessage" value="Promocion 3x1 en SKU 2" />
<parameter key="printerMessage" value="Promocion 3x1 en SKU 2" />
<parameter key="TLOGMessage" value="Promocion 3x1 en SKU 2" />
<parameter key="applicationMethod" value="resume" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="5c3dfcd5f7a021227ca8f807" />
<parameter key="percent" value="100" />
<parameter key="unit" value="qty" />
<applied-elements>
<use-set name="5c3dfd00f7a021227ca8f80c" max="1.0" attribute="qty" />
</applied-elements>
</benefit>
</benefits>
</promotion>
<promotion nro="5c3dffd1f7a021227ca8f82e" name="Promocion Cupon de Regalo en SKU 3" code="Promocion Cupon de Regalo en SKU 3" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="not">
<sets>
<set name="5c3e0041f7a021227ca8f835" type="item" attribute="code" comparator="Into" value="3" />
</sets>
<condition type="basic" name="Exists">
<parameter key="use-set" value="5c3e0041f7a021227ca8f835" />
</condition>
<benefits>
<benefit instance="CouponBenefit" nro="5c3e0001f7a021227ca8f832">
<parameter key="displayMessage" value="Promocion Cupon de Regalo en SKU 3" />
<parameter key="printerMessage" value="Promocion Cupon de Regalo en SKU 3" />
<parameter key="TLOGMessage" value="Promocion Cupon de Regalo en SKU 3" />
<parameter key="applicationMethod" value="resume" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="5c3dffd1f7a021227ca8f82e" />
<parameter key="qty" value="1" />
<parameter key="couponid" value="tc01" />
<applied-elements>
<use-set name="5c3e0041f7a021227ca8f835" max="1.0" attribute="qty" />
</applied-elements>
</benefit>
</benefits>
</promotion>
</promotions>
<evaluation-algorithm>
<step>
<function name="ALL">
<function name="SIMPLE">
<promotion-usage name="Promociòn 10% de Descuento SKU 1" />
</function>
<function name="SIMPLE">
<promotion-usage name="Promocion 3x2 en SKU 2" />
</function>
<function name="SIMPLE">
<promotion-usage name="Promocion Cupon de Regalo en SKU 3" />
</function>
</function>
</step>
</evaluation-algorithm>
</promo-engine>
</map>
</maps>
</promoCoreResponse>
Onde é observado:
ack: resultado da solicitação, em que 0 é o processamento correto. (Consulte os códigos de resposta ack anteriormente neste documento).
message: é a mensagem de erro resultante.
maps: tag geral que contém os elementos do mapa retornados na resposta. Cada elemento do mapa contém todos os elementos e tags que um mapa contém, como quando é baixado para um arquivo.
SERVIÇOS REST - PREÇOS: SERVIÇO DE FRETE COM LISTA ZERO
Foi criado um Serviço de Descanso que permite o carregamento de produtos de uma lista zero, que recebe as informações e será processado de forma assíncrona, ou seja, recebe as informações e será processado.
Lista Zero é a lista base na qual todos os preços dos produtos serão encontrados, tem a menor prioridade das listas (o mecanismo ao consultar os preços avalia as listas de prioridades existentes da mais alta para a mais baixa).
A Lista Zero será enviada de um sistema externo para promoção, o processo cria e atualiza os preços enviados.
No console, a tela Monitoramento de Importação foi adicionada. na seção de suporte, nessa tela, você poderá ver o resultado da importação, ver as informações enviadas na importação (menu Contexto Conteúdo), os detalhes da importação mostrarão o total de registros que foram processados corretamente e os que apresentaram erros , o último, se existir, será visto na página ou poderá ser baixado em um arquivo de texto. O monitor também permite reprocessamento de importações.
O Serviço restante deve ter o token oauth obtido de
curl -v -X POST -u my-client: -d "grant_type=password" -d "username=sender" -d "password=mate" -d "scope=read" <promo>/oauth/token
Onde <promo> é, por exemplo, http: // localhost: 8080 / promo
O método é um POST para o seguinte endereço: <promo> / api / rest / priceList com o seguinte corpo:
{
"companyId": "napse",
"store": "napse",
"items": [
{
"sku": "0527-1537",
"salePrice": 69406.77,
"costPrice": 50942.13,
"saleCreditPrice": 119716.68,
"magnitudePrice": 829,
"measuredUnit": "cm3",
"supplierItem": "PR3",
"supplierFinancial": "PR2",
"supplierItemAmount": 52471,
"supplierFinancialAmount": 53604,
"saleWholesalePrice": 31858,
"saleWholesaleLimit": 6081,
"limit": 794,
"enabledDate": "2018-12-25T10:42:25Z"
"discountable":true,
"manualDiscount":false
},
{
"sku": "66897-001",
"salePrice": 39123.0,
"costPrice": 10452.59,
"saleCreditPrice": 42433.6,
"magnitudePrice": 371,
"measuredUnit": "kg",
"supplierItem": "PR2",
"supplierFinancial": "PR2",
"supplierItemAmount": 52551,
"supplierFinancialAmount": 21423,
"saleWholesalePrice": 78603,
"saleWholesaleLimit": 9691,
"limit": 2982,
"enabledDate": "2019-01-20T10:41:55Z"
}
]
}
A resposta do mesmo será no caso de Ok (Http.status = 200)
{
"status": "Informacion Recibida OK",
"description": "La lista de precios será procesada"
}
Em caso de erro: (Http.status = 400)
{
"status": "companyId is Required",
"description": "Debe enviar el campo companyId"
}
{
"status": "companyId is Invalid",
"description": "Debe enviar el campo companyId valido"
}
Nota: A empresa enviada no restante deve ter o módulo de preços ativado para que o serviço seja ativado
Propriedade | Tipo de dados | Descrição do produto |
| companyId | Alfanumérico | Código da empresa |
| loja | Alfanumérico | Código da loja promocional |
sku | Alfanumérico | Código do produto |
salePrice | Numérico | Preço de venda |
costPrice | Numérico | Opcional. Preço de custo |
saleCreditPrice | Numérico | Preço do crédito |
magnitudePrice | Numérico | Opcional. Preço por magnitude (quilo, litro, embalagem, etc.) |
| measureUnit | Alfanumérico | Opcional. unidade de medida |
supplierItem | Alfanumérico | Opcional.É o código do fornecedor do item |
| supplierItemAmount | Numérico | Opcional. É a quantia que o provedor reconhece (quantia de recuperação) |
| supplierFinancial | Alfanumérico | Opcional. É o código do provedor financeiro do item |
| supplierFinancialAmount | Numérico | Opcional. É a quantia que o provedor financeiro reconhece (quantia de recuperação) |
| saleWholesalePrice | Numérico | Preço de atacado opcional |
| saleWholesaleLimit | Numérico | Opcional. Quantidade à qual se aplica o preço de atacado |
| limite | Numérico | Opcional (limite de unidades que podem ser vendidas a esse preço) |
| enabledDate | Data | Data que indica quando o preço é válido (ISO 8601 (UTC) FORMAT) |
com desconto | Booleano | Opcional. determina se o item pode ser descontado (se omitir esse campo por padrão, será verdadeiro) |
manualDiscount | Booleano | Opcional. determina se o item pode ser aplicado Desconto manual. (se omitir esse campo por padrão, será verdadeiro) |
O processo de importação da lista zero inserirá / atualizará o produto na lista zero da loja, no caso de o campo enable_date com uma data futura, esse preço será ativado no momento em que for a enable_date.
O processo de atualização de preço para uma lista zero, bloqueia enquanto a atualização está sendo processada, no caso de um erro inesperado e está bloqueado, existem dados de configuração que determinam o tempo em minutos para aguardar um bloqueio de atualização que é o seguinte (após esse período, o processo pode ser executado novamente para essa lista zero).
ConfigurationData.readAsInteger(companyId, "prices", "priceList.lockForUpate",15)
SERVIÇOS REST - NÚMERO DO PRÓXIMO CARTÃO
A PROMO exibe um serviço que permite a consulta, para um determinado tipo de cartão, que é o próximo número de cartão inativo e nenhum cliente associado.
Para os exemplos, as consultas do cartão foram feitas usando a ferramenta "PostMan" do Chrome. Um novo Tocken (cUrl) deve ser obtido e, em seguida, o próximo número de cartões (PostMan) pode ser consultado.
O único método aceito para fazer esse pedido é o POST.
Como qualquer serviço de descanso no console, para executar qualquer operação, será necessário usar um token de acesso. Ele deve ser incluído no cabeçalho da autorização http, por exemplo.
Portador de autorização fb489bee-ff9f-4a4b-905c-28c6969ef180 Não se esqueça do portador (espaço)
curl -v -X POST -u my-client: -d "grant_type=password" -d "username=sender" -d "password=mate" -d "scope=read" http://localhost:8080/promo/oauth/token
O corpo da mensagem deve ser um xml. Os possíveis pedidos e suas respostas envolvidas serão detalhados abaixo.
<promoCoreRequest>
<operation>NextCardNumber</operation>
<params>
<type>nominada</type>
</params>
</promoCoreRequest>
<promoCoreResponse>
<ack>0</ack>
<message>
<id>2345000000002</id>
</message>
</promoCoreResponse>
SERVIÇOS REST - CATÁLOGOS DE IMPORTAÇÃO
O PROMO expõe esse novo serviço para oferecer uma alternativa no carregamento / recebimento de catálogos que, até a versão atual, só podiam ser feitos via arquivos. Para entender esta seção, é recomendável consultar o manuseio de catálogos no manual do usuário.
O esquema de autenticação é o mesmo que nos outros serviços REST apresentados aqui (veja acima).
Depois que o token de acesso é obtido, o serviço pode ser chamado usando o método POST, a partir da URL: <promo> / api / rest / catalogs
O formato geral da solicitação é:
{
"companyId": "myCompanyId",
"catalog":"CatalogId",
"params":[
"param1":"param1value",
"paramN":"paramNvalue"
],
"items": [
{.... primer item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
]
}
onde
Campo | Descrição do produto | Tipo de dados |
|---|---|---|
companyId |
| alfanumérico |
catálogo | identificador de catálogo | alfanumérico |
| params | Parâmetros que dependerão do catálogo | Lista de objetos do tipo chave, valor |
| itens | Registros a serem importados | Coleção de objetos dependentes de cada catálogo |
A resposta será do tipo:
{
"status": "200",
"description": "CatalogCountry",
"detail": {
"result": "ok",
"detail": "Info adicional"
}
}
onde:
Campo | Descrição do produto | Tipo de dados | Valores possíveis |
|---|---|---|---|
status | Código de resposta | alfanumérico | 200 (válido), 400 (erros de validação ou sintaxe json), 500 (erro genérico) |
descrição | identificador de catálogo | alfanumérico | Cada um dos nomes dos catálogos pode ser importado pelo resto da mensagem ou uma sequência vazia, se não for possível obtê-los (por exemplo, devido a um erro de sintaxe json). |
| detalhe | Informação adicional | Object | Resultado principal, com os possíveis resultados, ou seja, ok ou erro. Chave de detalhes, com valor correspondente à mensagem informativa de validação, erro ou processamento válido. |
Considerações
- O número de registros por pacote (solicitação) será limitado a 1000 itens para não afetar o desempenho e as respostas podem ser processadas.
- Em caso de erro, os registros errados serão relatados, mas os que estiverem corretos serão incorporados. Os resultados podem ser visualizados no console na tela Import Monitor.
- Em todos os casos, o número total de linhas com erro e as corretas serão relatadas. Os resultados podem ser visualizados no console na tela Import Monitor.
- O processo usa semáforos para evitar a simultaneidade de clientes que pretendem processar em paralelo, pois implica na possibilidade de erros nas validações.
SERVIÇOS REST - CATÁLOGOS DE IMPORTAÇÃO: DESIGNAÇÃO DE CARTÕES
Esta operação é equivalente à função de atribuição / atualização do cartão, além da importação de novos clientes (consulte o processo atual para atribuição de contratos). Nesse caso, os campos serão:
{
"companyId": "napse",
"catalog": "CatalogCardAssign",
"params": [
{
"cardType": "tipo1"
},
{
"contract": "convenio1"
}
],
"items": [
{
"operation": "I",
"id": "1111000000030",
"customer": "codCliente1",
"amount": "90.37",
"name": "Juan",
"surname": "Perez",
"gender": "hom",
"birthDate": "19900506",
"idType": "dni",
"identifier": "33334444",
"idDate": "21001005",
"nacionality": "Argentina",
"email": "[email protected]",
"customerType": "gold",
"address": "Urquiza 20",
"country": "ar",
"state": "bsas",
"city": "tig",
"postalCode": "7669",
"phone": "2222-4444"
}
,{otro item.......}
,{otro item.......}
,{otro item.......}
,{otro item.......}
,{otro item.......}
,{otro item.......}
]
}
Os campos em negrito são obrigatórios.
Campo | Descrição do produto |
|---|---|
| params | cardType: tipo de cartão a ser importado que será validado. contrato: código do contrato ao qual esses cartões / clientes pertencem. |
operação | I: Inserção / U: Atualização / R: Excluir |
vai |
|
cliente |
|
quantidade |
|
nome | Nome do cliente. Cadeia livre. |
sobrenome | Sobrenome. Cadeia livre. |
sexo | Sexo. (veja valores por catálogo). Depende dos valores carregados no catálogo para essa finalidade. |
birthDate | Data de nascimento. String no formato "aaaaMMdd". Mais informações sobre o formato |
idType | Tipo de identificação (consulte os valores por catálogo). Depende dos valores carregados no catálogo para essa finalidade. |
identificador | Número de Identificação do Cliente |
idDate | Data de validade da identificação. String no formato "aaaaMMdd". Mais informações sobre o formato |
nacionalidade | Nacionalidade. Cadeia Livre. |
Endereço de email. Cadeia livre. | |
customerType | Tipo de cliente (consulte os valores por catálogo). Depende dos valores carregados no catálogo para essa finalidade. |
endereço | Endereço. Cadeia livre |
país | País. (veja valores por catálogo). Depende dos valores carregados no catálogo para essa finalidade. |
estado | Estado / Província (consulte os valores por catálogo). Depende dos valores carregados no catálogo para essa finalidade. |
cidade | Cidade (ver valores por catálogo). Depende dos valores carregados no catálogo para essa finalidade. |
postalCode | Código postal |
telefone | Telefone |
Conselhos práticos
Interação com o mecanismo de promoções
Embora o mecanismo de promoção possa ser usado de várias maneiras, é recomendável fazer uma remessa única que contenha todos os elementos da transação, solicitando no cabeçalho a abertura de uma nova sessão, a avaliação do ticket enviado e que ele envie uma resposta para essa avaliação.
Isso permitirá um uso mais eficiente dos recursos, processamento e memória, e o canal de comunicação.
Se, por algum motivo (limitações técnicas, padrões, etc.), uma única mensagem não puder ser enviada, como segunda opção, é possível enviar os elementos em mais de uma mensagem (podendo usar até uma mensagem para cada elemento a ser adicionado) , solicitando a abertura de uma nova sessão na primeira mensagem de envio correspondente à transação e solicitando a avaliação do ticket no final dela. Para garantir a entrega bem-sucedida de cada item, é possível solicitar uma mensagem de confirmação (usando resposta no cabeçalho), mas sem solicitar avaliação.
Essa última maneira de interagir é um pouco menos eficiente que a anterior, pois requer mais tempo para usar o canal de comunicação e a memória em que o Motor de Promoção está operando.
A sessão aberta no mecanismo também pode expirar, forçando o reenvio do ticket, conforme indicado em ". Envio de mensagem única
Como mencionado acima, a política de envio recomendada é usar uma mensagem única que contenha todos os itens. Abaixo está uma lista passo a passo da remessa e avaliação em uma única mensagem.
- Crie uma mensagem exclusiva que contenha
- o cabeçalho
- Configure qual resposta é esperada (usando o atributo de resposta ).
- Configure que o mecanismo calcule promoções (usando o atributo de avaliação ).
- Configure se um novo ticket for iniciado (exclua o contexto associado à sessão, usando o atributo init-tck )
- o corpo
- todos os itens da transação, de acordo com o formato estabelecido.
- todos os eventos da transação, de acordo com o formato estabelecido.
- todos os clientes da transação, de acordo com o formato estabelecido.
- todos os meios de pagamento da transação, de acordo com o formato estabelecido.
- todos os cupons da transação, de acordo com o formato estabelecido.
- o cabeçalho
- Envie a mensagem usando o protocolo de comunicação correspondente.
- Receba a resposta à solicitação feita. A referida resposta terá todas as promoções com seus respectivos benefícios, conforme descrito em " Resposta do mecanismo ". Caso o atributo ack do cabeçalho da resposta seja diferente de 0, vá para Valores do Atributo "ACK" e execute a ação recomendada.
Gerenciamento de sessão
Como mencionado anteriormente, o Motor de Promoção é capaz de lidar com várias sessões, permitindo atender a várias transações em paralelo. Cada sessão usa uma certa quantidade de memória física do computador, portanto, não seria conveniente criar muitas sessões, a menos que o mecanismo esteja atendendo a vários terminais e esteja executando em um computador com os recursos apropriados (consulte o Manual de Instalação).
Dessa forma, se um único terminal estiver interagindo continuamente com o mecanismo, seria conveniente sempre usar a mesma sessão e sempre que for necessário excluir todo o conteúdo da sessão, faça-o usando o atributo init-tck do cabeçalho.
Por outro lado, e devido à natureza humana da interação da entrada de itens no ponto de venda, se o ticket estiver sendo enviado ao Mecanismo de Promoções em várias mensagens, o tempo de expiração da sessão poderá passar. Conforme descrito em "Sessões", se isso acontecer, o Mecanismo de Promoções excluirá a sessão juntamente com todos os elementos que ela contém e, mediante solicitação do terminal onde a transação é realizada, informará que a sessão dessa transação expirou (usando o atributo ack o cabeçalho da mensagem de resposta). Nesses casos, lembre-se de abrir uma nova sessão usando o atributo init-tck do cabeçalho de envio e reenviar todos os elementos que foram inseridos até o momento. Então será possível continuar a operação normal.
Implementação de itens aplicados
Nesta seção, algumas orientações úteis serão levadas em consideração ao interpretar os itens aplicados, dependendo do benefício a que pertencem.
ITENS APLICADOS EM BENEFÍCIOS MONETÁRIOS
Os itens solicitados para um benefício monetário são aqueles nos quais o desconto informado pelo Motor de Promoção deve ser feito. Portanto, a implementação mais simples é descontar diretamente o valor relatado pelo atributo value ao item relatado pela 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 o número de itens relatados no qty . Caso seja relatada uma magnitude ( magnitude do atributo ), o valor será descontado na referida magnitude.
ITENS APLICADOS A BENEFÍCIOS NÃO MONETÁRIOS
No caso particular de benefícios não monetários, os artigos aplicados podem ser interpretados como considerados adequados por quem estiver encarregado da integração entre o ponto de venda e o Motor de Promoções. Por exemplo, os itens aplicados de um benefício do plano de pagamento ( PaymentPlanBenefit ) podem ser interpretados como os itens nos quais o plano de pagamento informado é permitido.
No caso específico de FactorLoyaltyBenefit com integrações pré-PROMO 5.2 (onde o gerenciamento de saldo está incluído no console), a implementação recomendada é multiplicar o fator (atributo de fator ) relatado pela soma dos valores (atributo unitprice) Dos itens aplicadas, cada uma multiplicada pela quantidade relatada Quant :
Pt = x factor de Σ (UNITPRICE x Quant)
Ser Pt a quantidade total de pontos, dinheiro, milha, etc. para conceder y Σ (unitPrice x qty) a soma dos preços unitários dos elementos aplicados, multiplicada pela quantidade correspondente relatada em < apply >.
Se não tiver sido aplicado (algo que é possível para benefícios não monetários), pontos, dinheiro, milhas etc. podem ser aplicados. para todo o ticket.
Para o restante dos benefícios não monetários, os elementos aplicados podem ser considerados meramente informativos.