Manual de Integração -
Serviços PROMO V7.2
Índice
Sobre o manual
Finalidade e âmbito
O objetivo deste manual é capacitar o usuário que deseja integrar seu aplicativo de vendas com os serviços que o Promo expõe.
É fornecida uma descrição detalhada das mensagens que lhe devem ser enviadas e como interpretar as mensagens de resposta que dará a um pedido.
Documentação do PROMO
PROMO fornece a seguinte documentação:
- Manual de usuário:
Este documento tem como objetivo treinar o usuário que deseja utilizar o console de Administração de Promoções PROMO.
- Manual de instalação:
Este documento descreve os procedimentos para instalar os componentes Engine e Console, a criação e inicialização do Banco de Dados e os requisitos necessários para o correto funcionamento dos referidos componentes.
- Manual de Integração - Motor
Este documento descreve detalhadamente as mensagens que devem ser enviadas ao Motor de Promoções e a forma de interpretação das mensagens de resposta que este dará a um pedido.
- Manual de Integração - Serviços:
Este documento descreve detalhadamente os serviços que o console Promo oferece e como enviar e receber informações com ele.
Nota: Antes de prosseguir com a leitura deste manual, recomenda-se a leitura dos capítulos 2 e 3 do Manual do Usuário.
Ferramentas utilizadas
No desenvolvimento deste manual serão utilizadas basicamente três ferramentas que são de domínio público para os exemplos:
- CURL (https://curl.haxx.se/) "command line tool and library for transferring data with URLs": É uma ferramenta de linha de comando para enviar/receber mensagens http.
- POSTMAN ( https://www.postman.com ) "The Collaboration Platform for API Development": Ferramenta gráfica para criar, enviar e receber mensagens.
- SOAPUI ( https://www.soapui.org/ ) "Accelerating API Quality Through Testing ": Outra ferramenta gráfica para definir, enviar e receber mensagens.
Segurança: Autenticação de Sistemas Externos com os Serviços
Antes de consumir um serviço prestado pelo Promo, deve ser realizado um Processo de Autenticação OAuth2. Consiste na obtenção de um TOKEN que deve ser enviado nas mensagens subsequentes.
Portanto, como primeiro passo para iniciar a comunicação com os serviços Promo, o sistema externo deve realizar o processo aqui descrito.
Primeiramente, deve-se solicitar o token de acesso, que usando CURL o comando ficaria:
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
Onde " http://localhost:8080/promo " deve ser alterado para a URL onde o console Promo está localizado.
A resposta de exemplo pode ser vista na seguinte janela:
Uma vez obtido o token, ele deve ser enviado nas requisições subsequentes. Por exemplo, realizamos um GET com a ferramenta CURL:
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/customer?code=1"
Da mesma forma, a mesma requisição mas feita no POSTMAN, ficaria:
Console: consultar serviços REST
Aqui estão os serviços prestados para consulta das informações contidas no PROMO.
Antes de consumir o serviço, deve-se obter o TOKEN de identificação conforme explicado em "Segurança: Autenticação de Sistemas Externos com os Serviços".
variável rabbitMq.date.UTC
Foi adicionada a nova variável rabbitMq.date.UTC para que todas as mensagens que sejam retornadas para qualquer uma das consultas via Rest disponíveis no Promo, sejam informadas com o formato de localidade configurado no servidor, que por padrão é GMT.
Serviços afetados :
- Clientes: http://localhost:8080/promo/api/rest/customer
- Status dos limites do cliente: http://localhost:8080/promo/api/rest/limit/limitStatus
- Cupons: http://localhost:8080/promo/api/rest/coupon
- Elementos de fidelidade: http://localhost:8080/promo/api/rest/card
- Mapas, promoções e promoções distribuídas: http://localhost:8080/promo/api/rest/promotions
- Número do próximo item de fidelidade: http://localhost:8080/promo/api/rest/nextCardNumber
- Relatório de promoções: http://localhost:8080/promo/api/rest/reports/transaction/promotion
Nota
Leve em consideração a configuração descrita em Informações de configuração
Consulta de Dados do Cliente
PROMO expõe um serviço que permite consultar elementos de fidelização e transações (vendas e devoluções) ao BBDD através do ID de cliente. Junto com os campos do cliente, também é retornada uma lista de Itens de Fidelidade e Cupons, e suas últimas transações N.
Se você não tiver itens de Fidelidade, Itens ou Cupons vazios serão devolvidos; Da mesma forma, caso não tenham transações, não trará dados sobre elas.
O código de consulta deve ser exato e apenas um resultado será retornado se o cliente existir.
O formato em que é respondido é em JSON.
Este método, acessível a partir de:
http://[SERVER]:[PORT]/promo/api/rest/customer
é responsável por devolver no formato JSON o cliente ou cliente solicitado através da ação GET.
Possui três parâmetros de entrada:
Nome | Valor |
|---|---|
companyId | O código da empresa. String. Obrigatório. |
code | O código do cliente. String. Não requerido. |
identificationType | O código do tipo de identificação do cliente (por exemplo, "dni"). String. Não requerido. |
identifier | O não. identificação do cliente (por exemplo, número de identificação). String. Não requerido. |
| lastSales | Com o valor configurado pelo cliente, é habilitada na resposta uma lista com as últimas transações do cliente. Não requerido |
Para buscar o cliente, deve-se enviar o parâmetro " code " ou o par de parâmetros identifier e identificationType. Se nenhum for enviado, ele retorna [] com uma mensagem de erro no log. Se enviarem código e o novo par de parâmetros mencionados, fará a busca por código já que tem prioridade de busca pelo campo anterior neste caso específico.
O código deve ser exato e apenas um resultado será retornado, caso o cliente exista.
O campo “lastSales” é numérico e indica o número de transações que um cliente possui. O usuário deve inserir o número de transações que deseja visualizar. Se x números passarem, essas últimas x transações serão retornadas . Se eles passarem 0, ou não passarem (vazio), essa informação não é retornada.
Exemplo, enviando para
http://{{SERVER}}:{{PORT}}/promo/api/rest/customer?companyId={{COMPANYID}}&identifier=12345&identificationType=dni
oi http://{{SERVER}}:{{PORT}}/promo/api/rest/customer?companyId={{COMPANYID}}&code=1
Ou, para consultar as últimas 10 transações associadas ao cliente, você deve enviar, por exemplo.http://URLPROMO:PUERTO/promo/api/rest/customer?code=0102909421&companyId=napse&lastSalesInfo=N
http://{server}:{port}/promo/api/rest/customer?code=12345&companyId={companyId}
você obteria um resultado como o seguinte:
{
"_id": "5f5f8d16b51f3b3160021dac",
"code": "1",
"name": "JUAN",
"lastName": "Perez",
"gender": "h",
"birthDate": "1900-01-10T04:16:48Z",
"identificationType": "dni",
"identifier": "12345",
"identificationExpiration": "2050-10-10T03:00:00Z",
"nacionality": "arg",
"email": "",
"customerType": "EMPLEADO",
"address": "calle 1",
"addressCountry": "arg",
"addressState": "bsas",
"addressCity": "tig",
"addressPostalCode": "1",
"phone": "1555555555",
"isActive": true,
"segments": "",
"companyId": "napse",
"creationDate": "2020-09-14T15:32:38Z",
"cards": [
{
"_id": "5f5fa94db51f3b5b0c2cedc9",
"amount": 0.0,
"code": "2222000000013",
"customerId": "1",
"validFrom": "2020-08-14T03:00:00Z",
"type": "tipo2",
"validTo": "2021-07-14T03:00:00Z",
"status": "DISABLED",
"companyId": "napse",
"created": "2020-09-14T17:33:01Z",
"isConsumed": false,
"version": 1,
"typeName": "tipo2"
},
{
"_id": "5f5f8d88b51f3b3160021db1",
"amount": 0.0,
"code": "1111000000010",
"customerId": "1",
"type": "tipo1",
"status": "ENABLED",
"companyId": "napse",
"created": "2020-09-14T15:34:32Z",
"isConsumed": false,
"version": 2,
"activation": "2020-09-14T15:34:33Z",
"typeName": "tipo1"
},
{
"_id": "5f5f8d88b51f3b3160021db2",
"amount": 0.0,
"code": "1111000000011",
"customerId": "1",
"type": "tipo1",
"status": "ENABLED",
"companyId": "napse",
"created": "2020-09-14T15:34:32Z",
"isConsumed": false,
"version": 2,
"activation": "2020-09-14T15:34:34Z",
"typeName": "tipo1"
},
{
"_id": "5f5f8e3ab51f3b3160021db8",
"amount": 0.0,
"code": "2222000000012",
"customerId": "1",
"validFrom": "2020-08-14T03:00:00Z",
"type": "tipo2",
"validTo": "2021-07-14T03:00:00Z",
"status": "ENABLED",
"companyId": "napse",
"created": "2020-09-14T15:37:30Z",
"isConsumed": false,
"version": 2,
"activation": "2020-09-14T15:37:30Z",
"typeName": "tipo2"
}
],
"coupons": []
}
Se o cliente não existir no banco de dados, a resposta será retornada vazia.-
A resposta para cada elemento incluído no atributo lastSales tem a seguinte estrutura (estes dados serão adicionados , se aplicável, aos dados já reportados para cartões e cupões associados ao cliente):
Atributo | Descrição |
|---|---|
transactionId | Código da transação |
ransactionType | Tipo de transação |
storeCode | código da loja |
terminalCode | código do terminal |
customerId | Código do cliente |
customerType | O código do tipo de cliente |
mapVersion | O não. do mapa avaliado ao fazer esta transação |
offline | Com valor true determina se foi originado offline, e false determina se foi originado online. |
date | Data da transação. Formato equivalente à data de criação do cliente ( campo creationDate ). Por exemplo 2021-06-24T20:34:39Z |
transactionStatus | O estado em que a transação está atualmente. |
itemsTotalQuantity | Número de unidades de produtos vendidos ao cliente. No caso de vendas por magnitude, ao não enviar a quantidade, acrescenta 1; por exemplo vender os seguintes itens resultaria em "itemsTotalQuantity" : 2.0 : <item-add code="1234" magnitude="1.5" seq="1" <outros atributos>/> <item-add code="2222" magnitude="5.5" seq="2" <outros atributos>/> |
summaryValues | Eles representam o resumo dos valores da transação. Objeto contendo quatro atributos. Detalhe abaixo. |
summaryValues.subtotal | Indica o subtotal da transação sem descontos ou sobretaxas |
summaryValues.discount | Indica a quantidade de descontos aplicados na transação |
summaryValues.surcharge | Indica o valor das sobretaxas aplicadas na transação |
summaryValues.total | Indica o total da transação com descontos e sobretaxas aplicadas |
payments | Eles representam os pagamentos apresentados na transação. É uma lista de objetos que contém três atributos. Detalhe abaixo. |
payments.type | O tipo de forma de pagamento |
O id do método de pagamento | |
payments.amount | O valor do pagamento feito com esse meio. |
loyaltyCards | Eles representam um detalhe dos elementos de fidelidade apresentados na transação. É uma lista de objetos que contém cinco atributos. Detalhe abaixo. |
O código do elemento de fidelidade | |
loyaltyCards.obtainedPoints | Pontos ganhos durante a transação |
loyaltyCards.benefitedByPromotion | verdadeiro no caso de ter obtido pontos. |
loyaltyCards.redeemedPoints | Pontos resgatados durante a transação |
loyaltyCards.redeemedByPromotion | verdadeiro se os pontos foram resgatados. |
coupons | Eles representam um detalhe do número de cupons emitidos e consumidos na transação. É um objeto que contém dois atributos. Detalhe abaixo. |
coupons.obtained | Número de cupons obtidos. |
coupons.redeemed | Número de cupons resgatados. |
Exemplo
{
"_id": "60824eeecff31c4138ebf73d",
"code": "0102909421",
"identifier": "0102909421",
"email": "-",
"name": "john promo",
"lastName": "-",
"identificationType": "c",
"customerType": "c",
"creationDate": "2021-04-23T04:37:02Z",
"isActive": true,
"companyId": "napse",
"cards": [],
"coupons": [],
"lastSales": [
{
"transactionId": "napse_1_1_20210624173439",
"transactionType": "SALE",
"storeCode": "1",
"terminalCode": "1",
"customerId": "0102909421",
"customerType": "c",
"mapVersion": 5,
"offline": false,
"date": "2021-06-24T20:34:39Z",
"transactionStatus": "COMMIT",
"itemsTotalQuantity": 33.0,
"summaryValues": {
"subtotal": 2217.0,
"discount": 353.0,
"surcharge": 0.0,
"total": 1864.0
},
"payments": [
{
"type": "1",
"id": "1",
"amount": 100.25
},
{
"type": "2",
"id": "2",
"amount": 200.5
}
],
"loyaltyCards": [
{
"id": "1111000000010",
"obtainedPoints": 100.0,
"benefitedByPromotion": true,
"redeemedPoints": 3.0,
"redeemedByPromotion": true
}
],
"coupons": {
"obtained": 10,
"redeemed": 2
}
}
]
}
Jobs a ejecutar
Observe que esse serviço rest, na seção lastSales, é alimentado pelas coleções transaction, transactionFlatten e viewCustomer. Para que as informações estejam disponíveis, é necessário que os jobs tenham sido processados: sts.console.job.LoyaltyJob (Conclusão de transações) e sts.console.job.TransactionFlattenJob (Achatamento de transações).
Se o cliente não existir no banco de dados, a resposta retornará vazia.
Consulta dos limites do Estado do Cliente
PROMO expõe um serviço que permite a um cliente consultar, quais são as promoções com limites que foram aplicadas às transações que ele conseguiu realizar, ao BBDD usando o ID do cliente.
Se o cliente consultado não tiver limites associados. o campo "limitsDetail" será retornado vazio.
O código de consulta deve ser exato e apenas um resultado será retornado se o cliente existir.
O formato em que é respondido é em JSON.
A requisição usando CURL será:
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/limit/limitStatus?companyId=napse&code=85001"
Obtendo a seguinte resposta:
Ejemplo {
"customerId": "85001",
"companyId": "napse",
"limitsDetail": [
{
"_id": "603a437c1082e83690817050",
"promotionId": "603a319c1082e83690816f95",
"benefitId": "603a31b81082e83690816f9c",
"promotionCode": "3",
"promotionName": "limite cliente",
"limitId": "603a31b61082e83690816f9b",
"scope": "CUSTOMER",
"period": "UNDEFINED",
"maxValue": 5.0,
"customerId": "85001",
"storeId": "-",
"numberDays": 0,
"nextReset": "2021-02-27T03:00:00+0000",
"lastReset": "2021-02-27T03:00:00+0000",
"companyId": "napse",
"limitTypeCode": "benefitApplicationCount",
"description": null,
"lastUpdate": "2021-02-27T13:05:00+0000",
"active": true,
"currentValue": 1.0
}
]
}
|
|---|
Se o cliente não existir no banco de dados, a resposta será " O cliente especificado não existe ".
Serviço de Consulta de Cupons
PROMO expõe um serviço que permite consultar bases de dados de cupões utilizando apenas o número do cupom e em resposta obtêm-se os movimentos associados ao dito cupom.
Também podem ser feitas consultas sobre o histórico de movimentações de cupons.
A URL é:
http://[SERVER]:[PORT]/promo/api/rest/coupon
Os parâmetros de entrada da consulta são:
Propriedade | Tipo de dados | Descrição |
| companyId | alfanumérico | Código da companhia |
| barcode | alfanumérico | Código do elemento de fidelização que pretende consultar |
limit | Numérico | Número de registros de movimento a serem retornados (padrão: 5) com um máximo de 100.000 por consulta. |
dateFrom | Numérico | Data de início no formato AAAAMMDD. Se código. |
dateTo | Numérico | Data final no formato AAAAMMDD. Se código. |
couponAction | alfanumérico | Código de operação a ser consultado. Se código. Por padrão, são todas operações. Os valores disponíveis são: CREATE, REDEEM, VOID |
| timeFrom | Numérico | (desde 7EP2) Hora de início no formato HHmm |
| timeTo | Numérico | (desde 7EP2) Hora final no formato HHmm |
| offset | Numérico | Permite navegar dentro do alcance. É usado em conjunto com o parâmetro limite. Por exemplo: Você deseja navegar pelos primeiros 10 registros, defina offset=1 e limit=10. Você deseja ver os próximos 10, defina offset=11 e limite 10. Quando não houver mais registros, ele ficará vazio. |
Aclaración
O dateFrom e o dateTo podem ser enviados sem carregar os dados timeFrom e timeTo , estes serão opcionais. Mas os parâmetros timeFrom e timeTo só serão usados se você tiver os parâmetros dateFrom e dateTo carregados , caso contrário, eles não serão usados.
EXEMPLO 1: são solicitados os dados do cupom 1050030016471
http://localhost:8072/promo/api/rest/coupon?barcode=1050030016471&companyID=napse
O mesmo, mas usando CURL:
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=1050030016471&companyId=napse
Obtendo a seguinte resposta:
Ejemplo {
"_id": "64a86490ab7b181240232917",
"companyId": "napse",
"transactionId": "2_3_1_20230707160000",
"couponType": "6",
"issuedDate": "2023-07-07T19:16:31Z",
"customerId": "1",
"couponStatus": "ACTIVE",
"validFrom": "2023-07-07T03:00:00Z",
"validTo": "2024-01-01T02:59:59Z",
"usedTimes": 0,
"consumed": false,
"couponFormat": "PRINTED",
"emitPromotion": "Promo Invierno",
"storeCode": "3",
"terminalCode": "1",
"maxUsageTimes": 1,
"barcode": "1050030016471",
"amount": 0.0,
"generatedHTML": "1050030016471\r\n\r\n07/07/2023 00:00\r\n\r\n31/12/2023 23:59",
"couponHistory": [
{
"date": "2023-07-07T19:17:00Z",
"couponAction": "CREATE",
"storeCode": "3"
}
]
}
|
Se o cliente não existir no banco de dados, a resposta será retornada vazia.
EXEMPLO 2: São solicitados todos os cupons gerados no período de 01/03/2023-07/07/2023, para o cadastro da empresa com limite de 100.000 registros.
http://localhost:8072/promo/api/rest/coupon?dateFrom=20230301&dateTo=20230707&companyId=napse&limit=100000&couponAction=CREATE
(curl -X GET -H "Authorization: Bearer f015554e-880e-4301-b83a-fe51ad7fb435" -H "Content-type: application/json" -H "Accept: application/json"http://localhost:8072/promo/api/rest/coupon?dateFrom=20230301&dateTo=20230707&companyId=napse&limit=100000&couponAction=CREATE')
A resposta será do tipo:
{
"couponHistory": [
{
"coupon": "1030BC0030007",
"couponAction": "CREATE",
"date": "2023-03-17T19:29:09Z",
"storeCode": "BC",
"terminalCode": "3",
"transactionId": "BC_202303171629177"
},
{
"coupon": "1030BC0036474",
"couponAction": "CREATE",
"date": "2023-03-17T19:29:09Z",
"storeCode": "BC",
"terminalCode": "3",
"transactionId": "BC_202303171629177"
},
{
"coupon": "1030BC0032940",
"couponAction": "CREATE",
"date": "2023-03-17T19:29:09Z",
"storeCode": "BC",
"terminalCode": "3",
"transactionId": "BC_202303171629177"
},
{
"coupon": "1030BC0039413",
"couponAction": "CREATE",
"date": "2023-03-17T19:29:09Z",
"storeCode": "BC",
"terminalCode": "3",
"transactionId": "BC_202303171629177"
},
{
"coupon": "1030BC0035880",
"couponAction": "CREATE",
"date": "2023-03-17T19:29:09Z",
"storeCode": "BC",
"terminalCode": "3",
"transactionId": "BC_202303171629177"
}
]
}
Serviço de consulta de status de cupom
PROMO expõe um serviço que permite à base de dados verificar o estado dos cupões tendo como parâmetros o ID do cliente, ID da empresa, o tipo de ação e o intervalo de datas (Date_from e Date_until) e como resposta os movimentos associados ao referido cupom.
A URL para acessar o serviço é:
http://[SERVER]:[PORT]/promo/api/rest/couponStatements
Os parâmetros de entrada da consulta são:
| Propriedade | Tipo de dados | Descrição |
|---|---|---|
| customerId | alfanumérico | identificador único de cliente |
| companyId | alfanumérico | Código da companhia |
| actionType | string | Tipo de operação a consultar. Se não especificado, o padrão é todas as operações. Os valores disponíveis são: CREATE, REDEEM, VOID |
| dateFrom | alfanumérico | Data de início no formato AAAAMMDD. |
| dateTo | alfanumérico | Data final no formato AAAAMMDD |
Ex: os cupons gerados para o cliente Id = 1
e como resposta obtêm-se os dados do cupom associado ao cliente e o seu estado.
Response:
[
{
"transactionId": "napse_napse_1_20220830120000",
"action": "Emisión",
"terminal": "1",
"couponType": "cimp",
"customerId": "1",
"amount": "-",
"store": "napse",
"datetime": "30/08/2022 11:08",
"couponCode": "116pse0018828"
},
{
"transactionId": "napse_napse_1_20220830120000",
"action": "Emisión",
"terminal": "1",
"couponType": "cimp",
"customerId": "1",
"amount": "-",
"store": "napse",
"datetime": "30/08/2022 11:08",
"couponCode": "116pse0015292"
}
]
Serviço de consulta de elementos de fidelidade
PROMO expõe um serviço que permite consultar os elementos de fidelização à base de dados utilizando apenas o seu número de elemento e como resposta obtêm-se os dados do elemento em questão e os movimentos associados a esse elemento. Os dados retornados são: data, id da transação, tipo de operação, valor, loja.
Para consumir este serviço, deve-se realizar uma solicitação do tipo GET com os parâmetros correspondentes à seguinte URL:
http://[SERVER]:[PORT]/promo/api/rest/card
Os parâmetros de entrada da consulta são:
Propriedade | Tipo de dados | Descrição |
| companyId | alfanumérico | Código da companhia |
| code | alfanumérico | Código do elemento a consultar |
limit | Numérico | Número de registros de movimento a serem retornados (padrão: 5) com um máximo de 100.000 por consulta. |
dateFrom | Numérico | Data de início no formato AAAAMMDD |
dateTo | Numérico | Data final no formato AAAAMMDD |
| requestTypes | boleano | (desde 7.EP2.1) Especificar o valor true retornará apenas os tipos de elementos definidos. *veja exemplo abaixo |
| cardAction | alfanumérico | Código de operação a ser consultado. Se código. Por padrão, são todas operações. Os valores disponíveis são: CHARGE, RECHARGE, AMOUNT_UPDATE, SALE, EXTENDED_POINTS |
| timeFrom | Numérico | Hora de início no formato HHmm |
| timeTo | Numérico | Hora de término no formato HHmm |
| offset | Numérico | Permite navegar dentro do alcance. É usado em conjunto com o parâmetro limite. Por exemplo: Você deseja navegar pelos primeiros 10 registros, defina offset=1 e limit=10. Você deseja ver os próximos 10, defina offset=11 e limite 10. Quando não houver mais registros, ele ficará vazio. |
Aclaración
O dateFrom e o dateTo podem ser enviados sem carregar os dados timeFrom e timeTo , estes serão opcionais. Mas os parâmetros timeFrom e timeTo só serão usados se você tiver os parâmetros dateFrom e dateTo carregados , caso contrário, eles não serão usados.
Se for especificado um elemento, serão devolvidos os dados e movimentos associados a esse elemento, com a possibilidade de especificar um intervalo de datas e um limite ao número de movimentos.
Caso o elemento não seja especificado, deverá ser especificado um intervalo de datas e serão retornadas todas as movimentações dos elementos desse intervalo, incluindo neste caso o número do elemento em questão.
No caso de informações do elemento, o Formato da Resposta será (JSON):
Propriedade | Tipo de dados | Descrição | ||||||
| _id* | alfanumérico | Uso interno | ||||||
| amount* | Numérico | Saldo atual do item. | ||||||
code* | alfanumérico | Número de item | ||||||
Created* | alfanumérico | Data de criação no formato ISODATE | ||||||
| customerId | alfanumérico | ID do cliente associado ao elemento | ||||||
| activation | Numérico | Data de ativação | ||||||
isConsumed* | boleano | Se foi consumido ou não | ||||||
| status* | alfanumérico | Estado atual do elemento | ||||||
| storeCode* | alfanumérico | Código da loja de geração (se aplicável) | ||||||
| terminalCode* | alfanumérico | Código do terminal de geração (se aplicável) | ||||||
| transactionId* | alfanumérico | Código da transação que o gerou (se aplicável) | ||||||
| lastPurchaseDate | Numérico | Data do último movimento | ||||||
| type* | alfanumérico | Tipo de elemento | ||||||
| typeName | alfanumérico | Nome do tipo de elemento | ||||||
| amountPrev | Numérico | valor anterior | ||||||
| version* | Numérico | Uso interno | ||||||
| cardHistory | Coleção | Conjunto de registos que correspondem a cada movimento do elemento, com:
Conjunto de registos que correspondem à promoção que se aplica à movimentação do elemento
|
- Esses dados são retornados apenas se um código de elemento específico for consultado.
Para o caso de tipos de elementos:
Propriedade | Tipo de dados | Descrição |
amountChargeLimit | Numérico | Limite de carga |
cardNumberLength | Numérico | Comprimento do número do elemento |
cardTypePrefixRange | variedade | definição de intervalos de prefixo para esse elemento. |
code | alfanumérico | digite o código |
customerValidation | alfanumérico | Se nomeado, o tipo de validação do cliente (NO, API, FILE) |
description | alfanumérico | descrição do tipo |
isActive | boleano | verdadeiro se ativo |
isCVVRequired | boleano | Verdadeiro se requer cvv |
isNominated | boleano | Verdadeiro se nomeado |
isRechargeable | boleano | Verdadeiro é recarregável |
name | alfanumérico | Digite o nome |
EXEMPLO 1: os dados do elemento 1000000000001 são solicitados para a empresa sem movimentação e com movimentações de 01/04/2020 a 31/04/2020 sem especificar limites, que serão as 5 últimas movimentações.
.
Por CURL
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/card?code=1000000000001&companyId=napse&dateFrom=20200401&dateTo=20200431
Que receberá uma resposta do tipo:
{
"_id": "6054129516f79ab3103ad3ac",
"companyId": "napse",
"code": "s_verdes3095535912",
"status": "ENABLED",
"type": "s_verdes",
"amount": 20.0,
"customerId": "3095535912",
"created": "2021-03-19T02:55:17Z",
"activation": "2021-03-19T02:55:17Z",
"transactionId": "napse_1_1_20210319203011",
"storeCode": "1",
"terminalCode": "1",
"isConsumed": false,
"version": 2,
"lastPurchaseDate": "2021-03-19T02:56:30Z",
"typeName": "Stickers Verdes",
"cardHistory": [
{
"date": "2021-03-19T23:30:15Z",
"createdAt": "2021-03-19T02:56:30Z",
"card": "-",
"cardAction": "SALE",
"storeCode": "1",
"terminalCode": "1",
"appliedPromotionDetails": [
{
"promotionName": "otorga Stickers Verdes-54",
"promotionCode": "54",
"conditionDateRangeDescription": null
}
],
"customerCode": "-",
"amount": "20.0",
"amountPrev": "0.0",
"transactionId": "napse_1_1_20210319203015",
"reasonName": null
},
{
"date": "2021-03-19T02:55:17Z",
"createdAt": "2021-03-19T02:55:17Z",
"card": "-",
"cardAction": "ACTIVATION",
"storeCode": "1",
"terminalCode": "1",
"customerCode": "3095535912",
"amount": "0.0",
"amountPrev": "0",
"appliedPromotionDetails": null,
"transactionId": null,
"reasonName": null
}
],
"amountPrev": 0
}
EXEMPLO 2: todos os movimentos são solicitados de 29/04/2020 a 29/04/2020 com um máximo de 100.000 movimentos.
Por CURL:
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/card?companyId=napse&dateFrom=20200429&dateTo=20200429&limit=100000"
Que receberá uma resposta do tipo:
{
"cardHistory": [
{
"amount": "10.0",
"card": "1000000000000",
"cardAction": "AMOUNT_UPDATE",
"date": "2020-04-29T12:42:18Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "300.0",
"card": "1000000000000",
"cardAction": "CHARGE",
"date": "2020-04-29T12:02:06Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "0",
"card": "1000000000000",
"cardAction": "ACTIVATION",
"date": "2020-04-29T12:02:06Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "20.0",
"card": "1000000000001",
"cardAction": "AMOUNT_UPDATE",
"date": "2020-04-29T12:42:26Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "300.0",
"card": "1000000000001",
"cardAction": "CHARGE",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "0",
"card": "1000000000001",
"cardAction": "ACTIVATION",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "300.0",
"card": "1000000000002",
"cardAction": "CHARGE",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "0",
"card": "1000000000002",
"cardAction": "ACTIVATION",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "300.0",
"card": "1000000000003",
"cardAction": "CHARGE",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "0",
"card": "1000000000003",
"cardAction": "ACTIVATION",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "300.0",
"card": "1000000000004",
"cardAction": "CHARGE",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "0",
"card": "1000000000004",
"cardAction": "ACTIVATION",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "300.0",
"card": "1000000000005",
"cardAction": "CHARGE",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "0",
"card": "1000000000005",
"cardAction": "ACTIVATION",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
}
]
}
Tipos de elementos
Quando o parâmetro "isTypes" é especificado, apenas os tipos de elementos definidos serão retornados.
EXEMPLO 3:
Por CURL
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/card?companyId=napse&isTypes=true"
Que receberá uma resposta do tipo:
{
"cardTypes": [
{
"amountChargeLimit": 0.0,
"cardNumberLength": 16,
"cardTypePrefixRange": [
{
"_id": "5f45547d830a697a4012df3c",
"creationAt": "2020-08-25T18:12:13Z",
"isSuggested": false,
"prefixEnd": 1000,
"prefixStart": 1
},
{
"_id": "5f45547d830a697a4012df3d",
"creationAt": "2020-08-25T18:12:13Z",
"isSuggested": false,
"prefixEnd": 2000,
"prefixStart": 1001
}
],
"code": "tc01",
"customerValidation": "NO",
"description": "TC01",
"isActive": true,
"isCVVRequired": false,
"isNominated": false,
"isRechargeable": true,
"name": "TC01"
},
{
"amountChargeLimit": 5000.0,
"cardNumberLength": 11,
"cardTypePrefixRange": [
{
"_id": "5f45575d830a697a4012df40",
"creationAt": "2020-08-25T18:24:29Z",
"isSuggested": false,
"prefixEnd": 3000,
"prefixStart": 3000
}
],
"code": "tc02",
"customerValidation": "FILE",
"description": "TC02",
"isActive": false,
"isCVVRequired": true,
"isNominated": true,
"isRechargeable": true,
"name": "TC02"
}
]
}
Status dos Pontos do Elemento de Fidelidade
PROMO expõe um serviço que permite consultar o estado dos pontos de um elemento de fidelização à base de dados utilizando apenas o seu número do elemento e como resposta, os dados do estado dos pontos do elemento em causa e os movimentos associados com o referido elemento são obtidos. Os dados retornados são: número e tipo de item fidelidade, ID da transação, ação realizada, loja, data da transação, número de pontos envolvidos na ação e código do cliente.
Para consumir este serviço, deve-se fazer uma requisição do tipo GET com os parâmetros correspondentes à seguinte URL: http://servidor:puerto/promo/api/rest/statementPoints
Os parâmetros de entrada da consulta são:
| Propriedade | Tipo de dados | Descrição |
|---|---|---|
| companyId | alfanumérico | Código da companhia |
toDate | Numérico | Data final no formato AAAAMMDD |
fromDate | Numérico | Data de início no formato AAAAMMDD |
customerCode | alfanumérico | identificador único de cliente |
isConsume | boleano | Se foi consumido ou não |
Todos esses dados são obrigatórios; quando faltar um deles, o aplicativo enviará uma mensagem como no exemplo:
O intervalo de datas não pode ser superior a um mês:
O formato da resposta será (JSON):
| Propriedade | Tipo de dados | Descrição |
|---|---|---|
| cardNumber | alfanumérico | Número do elemento de fidelidade associado ao cliente |
| cardTypeCode | alfanumérico | identificador exclusivo de tipo de item de fidelidade |
| transactionId | Numérico | Número da transação |
| action | alfanumérico | Ação realizada (doação, consumo) |
| storeCode | alfanumérico | Identificador único da Loja onde foi realizada a transação |
| date | Numérico | Data e hora da transação |
| amount | Numérico | Número de pontos participantes da transação |
| customerCode | alfanumérico | identificador único de cliente |
| terminalCode | alfanumérico | Terminal onde foi realizada a transação |
A resposta para Ex 1 é:
[
{
"cardNumber": "6000011014",
"cardTypeCode": "10",
"transactionId": "napse_napse_1_20220831120500",
"action": "Consumo",
"storeCode": "napse",
"date": "31/08/2022 12:05",
"amount": 200.0,
"customerCode": "1",
"terminalCode": "1"
}
]
Serviço de consulta de mapas
PROMO expõe um serviço que permite a consulta de mapas utilizando apenas o número do mapa e como resposta obtém-se o xml do mapa da mesma forma que se obtém pela opção "download".
Como no caso dos serviços REST descritos anteriormente, é necessária uma autorização via OAuth2.
A URL a ser usada é:
http://[SERVER]:[PORT]/promo/api/rest/promotions
A figura a seguir mostra o conteúdo da solicitação de exemplo:
Onde:
operation: valor getMaps para obter o mapa solicitado. Requerido
companyId : identificação ou código da 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 requisição, onde 0 é o processamento bem-sucedido. (Consulte os códigos de resposta ACK acima neste documento).
messagem: é 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 quando é baixado para um arquivo.
Serviço de Consulta de Promoções Distribuídas
O PROMO expõe um serviço que permite consultar as promoções distribuídas através de filtro por empresa (obrigatório) e parâmetros de filtro opcionais (loja/s, região/s, código/s) e como resposta obtém-se um xml com as promoções obtidas.
Como no caso dos serviços REST descritos anteriormente, é necessária uma autorização via OAuth2.
A figura a seguir mostra o conteúdo da solicitação de exemplo:
http://[SERVER]:[PORT]/promo/api/rest/promotions
<promoCoreRequest>
<operation>getPromotions</operation>
<companyId>2</companyId>
<params>
<promoCode>descuento</promoCode>
<store>1</store>
<region>1</region>
</params>
</promoCoreRequest>
Onde:
Operation (obrigatório): valor getPromotions para obter promoções.
companyId (obrigatório): identificação ou código da empresa que faz a solicitação.
store (opcional): Lojas a que pertence a(s) promoção(ões).
regiões (opcional): Zonas a que pertence a(s) promoção(ões).
promoCode (opcional): Código/os das promoções solicitadas
A resposta é do tipo:
<?xml version="1.0" encoding="iso-8859-1"?> <promoCoreResponse> <ack>0</ack> <message value="" /> <promotions> <promotion nro="64cd5282a62e431960edd5d5" name="Promo Descuentos" code="descuento" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not" promotionType="1" promotionSubType="1" promotionApplicationForm="1"> <sets> <set name="64cd5289a62e431960edd5d9" type="item" /> </sets> <condition type="basic" name="Exists"> <parameter key="use-set" value="64cd5289a62e431960edd5d9" /> </condition> <benefits> <benefit instance="PercentageDiscount" nro="64cd52b6a62e431960edd5dd"> <parameter key="displayMessage" value="Promo Descuentos" /> <parameter key="printerMessage" value="Promo Descuentos" /> <parameter key="TLOGMessage" value="Promo Descuentos" /> <parameter key="applicationMethod" value="resume" /> <parameter key="prorationMethod" value="proportional" /> <parameter key="applicationPriceType" value="benefited-price" /> <parameter key="hasLimit" value="true" /> <parameter key="name" value="64cd5282a62e431960edd5d5" /> <parameter key="percent" value="30" /> <parameter key="unit" value="qty" /> <parameter key="prorateBCP" value="false" /> <parameter key="recoveryValue" value="0" /> <parameter key="recoveryType" value="" /> <applied-elements> <use-set name="64cd5289a62e431960edd5d9" /> </applied-elements> </benefit> </benefits> </promotion> </promotions> </promoCoreResponse>
Onde é observado:
ack: resultado da requisição, onde 0 é o processamento bem-sucedido. (Consulte os códigos de resposta ACK acima neste documento).
message: é a mensagem de erro resultante.
promotions: tag geral que contém os elementos da promoção retornados na resposta. Cada elemento de promoção contém todos os elementos e tags que uma promoção contém.
Serviço de Consulta de Promoções Disponíveis
PROMO expõe um serviço que permite consultar as promoções disponíveis através de um filtro por empresa e versão do mapa (obrigatório) e o Código da promoção como parâmetro de filtro opcional.
Para utilizar este serviço, deve ser feita uma solicitação do tipo GET com os parâmetros correspondentes à seguinte URL:
http://servidor:puerto/promo/api/rest/promotionAvailable
A figura a seguir mostra o conteúdo da solicitação de exemplo:
Os parâmetros de entrada são:
| Propriedade | Tipo de dados | Descrição |
|---|---|---|
| mapVersion | alfanumérico | Versão do mapa que contém a promoção |
| companyId | alfanumérico | Identificador exclusivo da empresa |
| promotionCode | alfanumérico | código promocional que faz parte do mapa |
Os parâmetros de saída são:
| Propriedade | Tipo de dado | Descrição |
|---|---|---|
| mapVersion | Alfanumérico | Versão necessária do mapa |
| code | Alfanumérico | Código promocional contido no mapa |
| name | String | Nome da Promoção |
| conditionSimple | String | Condição simples da promoção |
| conditionCombo | String | Condição do Combo Promocional |
| conditionDate | Alfanumérico | Condição da Data da Promoção |
| benefitTypeDescription | String | Descrição do tipo de benefício da promoção |
| benefitClassDescription | String | Descrição da classe de benefício da promoção |
| benefit | String | Descrição do benefício da promoção |
| promotionType | String | Tipo ao qual a promoção pertence |
| promotionSubType | String | Subtipo ao qual a promoção pertence |
| promotionApplicationForm | String | Forma de aplicação da promoção |
a resposta é o Json:
[
{
"mapVersion": "90",
"code": "descuento",
"name": "Promo Descuentos",
"conditionSimple": "Productos con Aplica a TODOS",
"conditionCombo": "",
"conditionDate": "",
"benefitTypeDescription": "<p>1.- Monetario</p><br/>",
"benefitClassDescription": "<p>1.- Descuento porcentaje</p><br/>",
"benefit": "<p>1.- Productos con Aplica a TODOS. El siguiente porcentaje (%) 30. Por cada unidad de Cantidad. Prorratear entre Participantes No. Valor de Recupero 0. Tipo de Recupero -. Balance - Límites de aplicación Tipo de límite: Cliente Descripción: - Periodo a contabilizar: Indefinido Limitar por: Cantidad de dinero Valor: 5000 </p> ",
"promotionType": "1",
"promotionSubType": "1",
"promotionApplicationForm": "1"
}
]
Serviço de Consulta de Promoção
A PROMO expõe três serviços que permitem consultar uma promoção através de um filtro por empresa (obrigatório) e consultar por número da promoção ou código da promoção ou número do benefício da promoção e como resposta é obtido um xml com a promoção obtida.
Como no caso dos serviços REST descritos anteriormente, é necessária uma autorização via OAuth2.
O serviço pode ser acessado em:
http://[Server]:[Port]/promo/api/rest/promotions
As figuras a seguir mostram o conteúdo das solicitações mencionadas
Promoción por Numero <promoCoreRequest> <operation>getPromotionsByNro</operation> <companyId>2</companyId> <nro>64d140e6b29c1e1764334c1f</nro> </promoCoreRequest> Promoción por Numero <?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
<ack>0</ack>
<message value="" />
<promotions>
<promotion nro="64d140e6b29c1e1764334c1f" name="Promo Canje" code="canje"
className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not"
promotionType="1" promotionSubType="1" promotionApplicationForm="1">
<sets>
<set name="64d140ecb29c1e1764334c23" type="item" />
</sets>
<condition type="basic" name="Exists">
<parameter key="use-set" value="64d140ecb29c1e1764334c23" />
</condition>
<benefits>
<benefit instance="RedeemPointsBenefit" nro="64d14116b29c1e1764334c26">
<parameter key="displayMessage" value="Promo Canje" />
<parameter key="printerMessage" value="Promo Canje" />
<parameter key="TLOGMessage" value="Promo Canje" />
<parameter key="applicationMethod" value="resume" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="64d140e6b29c1e1764334c1f" />
<parameter key="type" value="5" />
<parameter key="factor" value="1" />
<parameter key="recoveryValue" value="0" />
<parameter key="recoveryType" value="" />
<parameter key="prorateBCP" value="false" />
<applied-elements>
<use-set name="64d140ecb29c1e1764334c23" />
</applied-elements>
</benefit>
</benefits>
</promotion>
</promotions>
</promoCoreResponse>
| Promocion por Codigo <promoCoreRequest> <operation>getPromotionsByCode</operation> <companyId>2</companyId> <promoCode>redes</promoCode> </promoCoreRequest> Promoción por Código <?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
<ack>0</ack>
<message value="" />
<promotions>
<promotion nro="64d0fb1db29c1e1764334bc6" name="Promo Redes" code="redes"
className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not"
promotionType="1" promotionSubType="1" promotionApplicationForm="1">
<sets />
<benefits />
</promotion>
</promotions>
</promoCoreResponse>
| Promocion por Numero de Beneficio <promoCoreRequest> <operation>getPromotionsByBenefitNro</operation> <companyId>2</companyId> <nro>6489c122a62e4343b821cc9d</nro> </promoCoreRequest> Promoción por Numero de Beneficio <?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
<ack>0</ack>
<message value="" />
<promotions>
<promotion nro="64cbfc85a62e430ec443b4d5" name="Promo Limites Clientes Cant. de aplicaciones" code=""
className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not"
promotionType="1" promotionSubType="1" promotionApplicationForm="1">
<sets>
<set name="64cbfc85a62e430ec443b4d2" type="item" />
</sets>
<condition type="basic" name="Exists">
<parameter key="use-set" value="64cbfc85a62e430ec443b4d2" />
</condition>
<benefits>
<benefit instance="PercentageDiscount" nro="64cbfc85a62e430ec443b4d4">
<parameter key="displayMessage" value="Promo Limites Clientes Cant. de aplicaciones" />
<parameter key="printerMessage" value="Promo Limites Clientes Cant. de aplicaciones" />
<parameter key="TLOGMessage" value="Promo Limites Clientes Cant. de aplicaciones" />
<parameter key="applicationMethod" value="resume" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="64cbfc85a62e430ec443b4d5" />
<parameter key="percent" value="50" />
<parameter key="unit" value="qty" />
<parameter key="prorateBCP" value="false" />
<parameter key="recoveryValue" value="0" />
<parameter key="recoveryType" value="" />
<applied-elements>
<use-set name="64cbfc85a62e430ec443b4d2" />
</applied-elements>
</benefit>
</benefits>
</promotion>
</promotions>
</promoCoreResponse>
| Promoción por Nombre <promoCoreRequest> <operation>getPromotionsByName</operation> <companyId>2</companyId> <promoName>Promo Limite Clientes Cant. de Dinero</promoName> </promoCoreRequest> Promocion por Nombre ?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
<ack>0</ack>
<message value="" />
<promotions>
<promotion nro="64cbfc85a62e430ec443b4d1" name="Promo Limite Clientes Cant. de Dinero" code=""
className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not"
promotionType="1" promotionSubType="1" promotionApplicationForm="1">
<sets>
<set name="64cbfc85a62e430ec443b4ce" type="item" />
</sets>
<condition type="basic" name="Exists">
<parameter key="use-set" value="64cbfc85a62e430ec443b4ce" />
</condition>
<benefits>
<benefit instance="PercentageDiscount" nro="64cbfc85a62e430ec443b4d0">
<parameter key="displayMessage" value="Promo Limite Clientes" />
<parameter key="printerMessage" value="Promo Limite Clientes" />
<parameter key="TLOGMessage" value="Promo Limite Clientes" />
<parameter key="applicationMethod" value="resume" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="hasLimit" value="true" />
<parameter key="name" value="64cbfc85a62e430ec443b4d1" />
<parameter key="percent" value="50" />
<parameter key="unit" value="qty" />
<parameter key="prorateBCP" value="false" />
<parameter key="recoveryValue" value="0" />
<parameter key="recoveryType" value="" />
<applied-elements>
<use-set name="64cbfc85a62e430ec443b4ce" />
</applied-elements>
</benefit>
</benefits>
</promotion>
</promotions>
</promoCoreResponse>
|
|---|
Onde:
Operação (obrigatório): valor getPromotionsByNro, getPromotionsByCode ou getPromotionsByBenefitNro.
companyId (obrigatório): identificação ou código da empresa que faz a solicitação.
nro (obrigatório): para busca pelo número da promoção ou pelo número do benefício da promoção.
promoCode (obrigatório): para uma pesquisa usando o código promocional
promoName(obligatorio): para uma pesquisa usando o nome da promoção.
Onde se observa:
ack: Resultado da solicitação, onde 0 é o processamento correto. (Consulte os códigos de resposta acima neste documento.)
message: é a mensagem de erro resultante.
promotions: Tag geral que contém os elementos de promoção retornados na resposta. Cada elemento de promoção, contém todos os elementos e tags que contém uma promoção
Se o código promocional não for exclusivo, A resposta detalhará a lista de todas as promoções que tenham esse código.
Caso contrário, a resposta mostrará as informações da promoção que correspondem a esse código.
Número do elemento de fidelidade do próximo serviço
PROMO expõe um serviço que permite consultar, para um determinado tipo de elemento, qual o próximo número de elemento disponível, inativo e sem cliente associado. Através deste serviço de consulta, o TPV poderá saber o número do “próximo elemento inativo e sem cliente associado ” a atribuir a um cliente da fila de caixa. Promo devolverá o número do elemento e o TPV associará ao cliente e reenviará (LoyaltyAssign) o número e tipo do elemento, mais os dados do cliente para que o elemento seja ativado e atribuído.
Quando não houver mais elementos inativos e nenhum cliente associado na base de dados para o tipo de elemento consultado, será retornada a mensagem de erro indicando que não há mais elementos disponíveis para serem associados.
Considere que o tipo de indicação que você irá utilizar é "Associação por Canal de Vendas" e os elementos devem ser cadastrados via .
No arquivo de registro massivo, apenas o número será informado. do elemento e o Tipo.
Quando os elementos forem registrados, eles permanecerão no estado INACTIVE.
A ativação do elemento e atribuição de cliente deve ser feita através do “Canal de Vendas”.
Para tal, uma vez registados os artigos em massa, a partir do TPA, quando se pretender registar um cliente e atribuir-lhe uma conta “pré-paga” (Wallet), será enviada a próxima mensagem de consulta de Artigo ( NextCardNumber ) . Promo informará nesta mensagem o número do próximo item inativo e não cliente disponível.
Em seguida o TPV enviará uma mensagem de associação ( LoyaltyAssign ) do cliente ao elemento, deixando este último ativo e com o cliente informado associado ao elemento.
Serviço REST
Para os exemplos, as consultas dos elementos foram feitas utilizando a ferramenta "PostMan" do Chrome. Um novo token (cUrl) deve ser obtido e, em seguida, a próxima consulta de número de elemento pode ser realizada
(Postman).
O único método aceito para fazer este pedido é o POST.
Autenticação :
Para acessar o serviço resto, deve-se solicitar um token de autorização que será utilizado posteriormente no cabeçalho da chamada ao serviço. As etapas para solicitar um token são as seguintes:
Depois que o comando curl estiver instalado, execute:
curl -v -X POST -u my-client: -d "grant_type=password" -d "username=<userName>" -d "password=<password>" -d "scope=read" http://<servername>:<port>/promo/oauth/token
Campo | Descrição |
<userName> | usuário (solicitado por Promo) |
<password> | senha (solicitada pela Promo) |
nome ou ip onde esta hospedado Promo | |
<port> | porta http onde o Promo está sendo executado. |
Por exemplo:
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 token de acesso a ser utilizado é representado pelo valor de access_token , que neste exemplo corresponde a dcb8a705-8b04-409f-98b7-3cd93fc7be3f . Esse token deve ser usado posteriormente no cabeçalho do serviço rest.
MENSAGEM DE CONSULTA
O corpo da mensagem deve ser um xml. As possíveis solicitações e suas respostas envolvidas serão detalhadas a seguir.
REQUEST
<promoCoreRequest>
<operation>NextCardNumber</operation>
<params>
<type="555">
</params>
</promoCoreRequest>
RESPONSE
<promoCoreResponse>
<ack>0</ack>
<message>Id:"555000002200002"</message>
</promoCoreResponse>
RESPONSE NO OK
<promoCoreResponse>
<ack>9503</ack>
<message>No se encontró el Tipo de tarjeta loyalty</message>
</promoCoreResponse>
Serviço de relatórios de promoções
(>v7.EP2.1)
PROMO expõe um serviço que permite consultar a mesma informação que se obtém no Relatório de Promoções do Console (consulte o referido relatório para informação sobre filtros e dados).
http://localhost:8080/promo/api/rest/reports/transaction/promotion?companyId=napse&limit=50000&offset=0&dateFrom=20210512&dateTo=20210519
Os parâmetros de entrada da consulta são:
Propriedade | Tipo de dados | Descrição |
| companyId | alfanumérico | Código da companhia |
limit | Numérico | Número de registros de movimento a serem retornados com um máximo de 50.000 por consulta. Padrão: 25 |
| offset | Numérico | Registro a partir do qual iniciar a contagem até o "limite" de registros. Padrão: 0 |
dateFrom | Numérico | Data de início no formato AAAAMMDD. |
dateTo | Numérico | Data final no formato AAAAMMDD. |
transactionType | alfanumérico | Opcionalmente, pode ser filtrado por tipo de Transação: VENDAS ou DEVOLUÇÃO. Padrão: '' (Todos) |
| store | alfanumérico | Código da loja pelo qual deseja filtrar. Padrão: '' (Todos) |
| pname | alfanumérico | O nome da Promoção pela qual você deseja filtrar. Padrão: '' (Todos) |
| pcode | alfanumérico | O código da Promoção que você deseja filtrar. Padrão: '' (Todos) |
Exemplo de parâmetros de entrada de consulta no Postman:
A Resposta será do tipo JSON com os seguintes parâmetros:
Propriedade | Tipo de dados | Descrição |
| Records | Vetor | Cada um dos registros que compõem o relatório |
Header | Vetor | Cabeçalho com informações adicionais |
{
"records:": "[{\"transactionId\":\"napse_Tienda1_1_20210519110000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Descuento porcentaje\",\"itemCode\":\"456\",\"discountApply\":500.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"19/05/2021 11:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo limite1\",\"store\":\"Tienda1\",\"subTotal\":500.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210519100000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Descuento porcentaje\",\"itemCode\":\"456\",\"discountApply\":500.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"19/05/2021 10:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo limite1\",\"store\":\"Tienda1\",\"subTotal\":500.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210519091000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Descuento porcentaje\",\"itemCode\":\"456\",\"discountApply\":500.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"19/05/2021 09:10\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo limite1\",\"store\":\"Tienda1\",\"subTotal\":500.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210517091000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"555\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"17/05/2021 09:10\",\"transactionType\":\"Devolución\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo EMITE CUPON Impreso\",\"store\":\"Tienda1\",\"subTotal\":1000.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210517090000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"555\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"17/05/2021 09:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo EMITE CUPON Impreso\",\"store\":\"Tienda1\",\"subTotal\":1000.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210513100000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"555\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"13/05/2021 10:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo EMITE CUPON Impreso\",\"store\":\"Tienda1\",\"subTotal\":1000.0,\"conditionTimeRange\":\"Indefinida\"}]",
"header": {
"total": 6,
"offset": 0,
"limit": 50000
}
}
Cada elemento Vector Records conterá os seguintes parâmetros correspondentes a cada uma das colunas do relatório:
Propriedade | Tipo de dados | Descrição |
| transactionId | alfanumérico | código de transação |
offline | boleano | Verdadeiro se a transação foi realizada no modo offline |
| unitPrice | Numérico | preço unitário do produto |
benefitClass | alfanumérico | classe de benefícios |
itemCode | alfanumérico | Código do produto |
discountApply | Numérico | Desconto Aplicado |
| deploymentChannels | alfanumérico | Canal de Publicação |
| date | alfanumérico | data da transação |
| transactionType | alfanumérico | Tipo de transação |
| campaign | alfanumérico | Campainha |
| quantity | Numérico | Quantidade de produto |
| promotionCode | alfanumérico | Código de promoção |
| promotionName | alfanumérico | Nome da promoção |
| store | alfanumérico | Loja |
| subTotal | Numérico | Subtotal da transação |
| conditionTimeRange | alfanumérico | Condição de data/hora, se aplicável. |
Cada elemento Vector Header conterá os seguintes parâmetros informativos:
Propriedade | Tipo de dados | Descrição |
| total | Numérico | Total de registros disponíveis |
offset | Numérico | compensação atualmente solicitada |
| limit | Numérico | limite atualmente solicitado |
Esta informação é utilizada para manter uma paginação tal como acontece na tela mas ao nível do serviço. Digamos:
Primeira consulta: offset: 0, limite: 25 → retorna a primeira página de 25 registros e relata um total de 500.
Segunda consulta: offset: 25, limite 25 → retorna a segunda página, ou seja, registros 26 a 50.
A partir de agora você pode solicitar páginas até atingir o deslocamento: 475, limite 25.
Você também pode paginar 100 registros por consulta, etc. (limite: 100).
EXEMPLO 1:
Solicitamos um relatório de Promoções para a empresa myCompany, entre 21/11/2020 e 04/12/2020, limitado a 25 registros a partir de 500 (isso equivale a página 21 da tela), para o código de Promoção 10549
Obtendo a seguinte resposta:
Ejemplo {
"records:": "[{\"transactionId\":\"xx_0621_002_20201202123540\",\"offline\":false,\"unitPrice\":10400.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"1580203\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"02/12/2020 04:35\",\"transactionType\":\"Venta\",\"campaign\":\"Mercadeo\",\"quantity\":1.0,\"promotionCode\":\"10549\",\"promotionName\":\"MY PROMO-10549\",\"store\":\"0621 - MY STORE \",\"subTotal\":10400.0,\"conditionTimeRange\":\"\r\nEntre las fechas con horario 26/11/2020 02:00-06/12/2020 01:59\r\n\"},{\"transactionId\":\"xx_0621_001_20201202112635\",\"offline\":false,\"unitPrice\":5600.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"720190\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"02/12/2020 03:26\",\"transactionType\":\"Venta\",\"campaign\":\"Mercadeo\",\"quantity\":1.0,\"promotionCode\":\"10549\",\"promotionName\":\"MY PROMOTION-10549\",\"store\":\"0621 - MY STORE\",\"subTotal\":5600.0,\"conditionTimeRange\":\"\r\nEntre las fechas con horario 26/11/2020 02:00-06/12/2020 01:59\r\n\"}]",
"header": {
"total": 504,
"offset": 500,
"limit": 25
}
}
|
Limite Transacional via REST
PROMO apresenta um serviço que permite a devolução de informações referentes ao transacional de limites para uma determinada empresa.
Para isso, é necessário enviar um GET para a seguinte URL: http://[SERVER]:[PORT]/promo/api/rest/limit/statements
Possui três parâmetros de ingresso:
| Nombre | Valor |
|---|---|
| companyId | O código da empresa. String. Requerido |
| mapVersion | n° de mapa. Requerido |
| promoCode | Código da promoção. String. Requerido |
Deve-se validar que o mapa consultado esteja ativo em algum dos motores conectados ao console.
Ex:
O seguinte resultado seria obtido:
Espera-se obter como resposta um Json que informe os movimentos de limites que as promoções com limites definidos no mapa consultado tenham tido. Os dados a serem informados devem ser:
| Nome | Valor |
|---|---|
| PromotionName | Nome da promoção que está envolvida na transação. |
| PromotionCode | Código da promoção que está envolvida na transação. |
| benefitType | Tipo de Benefício concedido pela promoção. |
| benefitClass | O tipo de benefício concedido pela transação. |
| limitScope | Tipo de Limite que tem o benefício da promoção |
| limitType | Indica o critério pelo qual o limite será aplicado. |
| store | ID da loja na qual o mapa onde a promoção está localizada foi distribuído |
| customer | O ID do cliente que realizou a transação. |
| limitOriginalValue | Valor-limite original |
| limitCurrentValue | Valor-limite atual |
| storeCode | Código da loja onde ocorreu a transação |
| date | Dia em que a transação ocorreu |
| transaction | ID da transação que aplicou essa promoção limitada |
| operation | Tipo de operação |
| store | ID da loja onde a transação ocorreu |
| terminal | Terminal onde ocorreu a transação. |
| customer | ID do cliente que realizou a transação |
| initialValue | Valor inicial da transação |
| transactionValue | Valor do limite aplicado na transação |
| finalValue | valor final do limite aplicado na transação. |
Ex. consulta com companyId e mapVersion::
[
{
"promotionName": "PromoLimite",
"promotionCode": null,
"benefitType": "Monetario",
"benefitClass": "Descuento porcentaje",
"limitScope": "General",
"limitType": "Cantidad de productos beneficiados",
"store": "",
"customer": "",
"limitOriginalValue": "3.00",
"limitCurrentValue": "1.00",
"storeCode": "-",
"detail": [
{
"date": "09/11/2022 10:37",
"transaction": "napse_napse_1_20221109120000",
"operation": "Venta",
"store": "napse",
"terminal": "1",
"customer": "",
"initialValue": "0.00",
"transactionValue": "1.00",
"finalValue": "1.00"
}
]
}
]
Exemplo com companyId inexistente:
Exemplo com um mapa invadido:
Outros erros:
Console: serviços REST de carga de dados
Aqui estão os serviços prestados para enviar ou fazer upload de informações no PROMO.
Antes de consumir o serviço, deve-se obter o TOKEN de identificação conforme explicado em "Segurança: Autenticação de Sistemas Externos com Serviços"
Preço: Serviço de Carga de Lista Zero
Foi criado um Rest Service que permite o carregamento de produtos de uma lista zero, ele recebe as informações e será processado de forma assíncrona, ou seja, recebe as informações e depois será processado.
A Lista Zero é a lista base onde serão encontrados todos os preços dos produtos, tem a menor prioridade das listas (Ao consultar os preços, o motor avalia as listas de prioridade existentes da maior para a menor).
A Lista Zero será enviada de um sistema externo para promo, o processo cria e atualiza os preços enviados.
A tela de monitoramento de importação foi adicionada ao console. na seção de suporte, nesta tela você pode ver o resultado da importação, ver as informações enviadas na importação (menu contextual de conteúdo), o detalhe da importação mostrará o número total de registros, os processados corretamente e os que tiveram errors , estes últimos, se existirem, serão vistos na tela paginada ou podem ser baixados em um arquivo de texto. O monitor também permite o reprocessamento das importações.
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"
}
]
}
Sua resposta será se 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"
}
Obs: A empresa enviada no restante deve ter o módulo de precificação habilitado para que o serviço seja habilitado
Propriedade | Tipo de dados | Descrição |
| companyId | alfanumérico | Código da companhia |
| store | alfanumérico | Código promocional da loja |
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 de crédito |
magnitudePrice | Opcional. Preço por grandeza (quilo, litro, embalagem, etc.) | |
| measuredUnit | alfanumérico | Opcional. unidade de medida |
supplierItem | Opcional. É o código do fornecedor do item | |
| supplierItemAmount | Opcional. É o valor que o provedor reconhece (valor de recuperação) | |
| supplierFinancial | alfanumérico | Opcional. É o código do provedor financeiro do item |
| supplierFinancialAmount | Opcional. É o valor que o provedor financeiro reconhece (valor da recuperação) | |
| saleWholesalePrice | Numérico | Opcional. Preço de Atacado |
| saleWholesaleLimit | Numérico | Opcional. Quantidade a partir da qual se aplica o preço de atacado |
| limit | Numérico | Opcional. (limite de unidades que podem ser vendidas a esse preço) |
| enabledDate | Data | Data que indica a partir de quando o preço é válido (ISO 8601 FORMAT (UTC)) |
discountable | boleano | Opcional. Determina se o item pode ser aplicado um desconto. (Omitir esse campo por padrão será verdadeiro) |
manualDiscount | boleano | Opcional. Determina se o item pode ser aplicado um desconto manual. (Omitir o referido campo por padrão será verdadeiro) |
O processo de importação da lista zero, irá inserir/atualizar o produto na lista zero da loja, caso tenha o campo enable_date com uma data futura, esse preço será habilitado no momento que for o enable_date.
O processo de atualização de preços para uma lista zero, trava enquanto a atualização está sendo processada, no caso de um erro inesperado não coberto e ela permaneça bloqueada, existe um dado de configuração que determina o tempo em minutos para aguardar um bloqueio de atualização que é da seguinte forma (depois desse tempo o processo pode ser executado novamente para essa lista zero).
ConfigurationData.readAsInteger(companyId, "prices", "priceList.lockForUpate",15)
Serviço de Importação de Catálogo
PROMO expõe este novo serviço para oferecer uma alternativa de upload/recebimento de catálogos que, até a presente versão, só era possível através de arquivos. Para entender esta seção, é recomendável consultar o gerenciamento de catálogo no manual do usuário.
O esquema de autenticação é o mesmo dos demais serviços REST apresentados aqui (veja acima).
Uma vez obtido o token de acesso, o serviço pode ser invocado 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 | Tipo de dados |
|---|---|---|
companyId |
| alfanumérico. Requerido |
catalog | identificador de catálogo | alfanumérico. Requerido |
| params | Parâmetros que vão depender do catálogo | Lista de objetos do tipo chave, valor. Cada catálogo pode ter seus parâmetros específicos, mas como valor genérico temos:
[...] "params": [ [...] Importante Não se aplica a cartões de fidelidade e cessão de convênios. |
| items | Registros a serem importados | Coleção de objetos dependentes de cada catálogo Atributos dinamicos. Para o Catálogo de Clientes (catalogCustomer.catalog) podem ser incorporados ao load os atributos dinâmicos dos itens que estão sendo cadastrados. Para isso, o nome dos atributos dinâmicos registrados pelo console deve ser especificado dentro da tag "itens": [
{.... primeiro item .......}]Os Atributos dinâmicos carregados via Serviço serão levados para a validação entre atributos do elemento Produto na definição das condições de uma promoção, quando esta funcionalidade estiver habilitada no console. (Consulte PROMO - Manual do Usuário Final - 7) Ejemplo de catalogItem con Atributos dinámicos. {
"companyId": "napse",
"catalog": "catalogCustomer",
"params": [],
"items": [{
"operation": "I",
"code":"949450",
"name":"John",
"lastName":"Promo",
"gender":"2",
"birthDate":"03-05-1959",
"identificationType":"01",
"identifier":"4688779900",
"identificationExpiration":"31-12-2030",
"nacionality":"Arg",
"email":"[email protected]",
"customerType":"111",
"address":"Av.Livertad 123",
"addressCountry":"100",
"addressState":"200",
"addressCity":"300",
"addressPostalCode":"9999",
"phone":"457896203",
"isActive":"true",
"prof":"Ingeniero"
}
]
}
No exemplo anterior, "prof" é o atributo dinâmico criado para importar as profissões dos clientes. |
Cada um dos itens vai depender do catálogo em seu formato, mas existe um campo comum a todos:
| Campo | Descrição | Tipo de dados |
|---|---|---|
operation | A operação a ser executada no elemento. Os valores possíveis são:
| Alfanumérico. Requerido |
A resposta será do tipo:
{
"status": "200",
"description": "CatalogCountry",
"detail": {
"result": "ok",
"detail": "Info adicional"
}
}
onde:
| Campo | Descrição | Tipo de dados | valores possíveis |
|---|---|---|---|
status | Código de resposta | alfanumérico | 200 (válido), 400 (validação ou erros de sintaxe json), 500 (erro genérico) |
description | identificador de catálogo | alfanumérico | Cada um dos nomes dos catálogos importáveis por mensagem rest, ou uma string vazia se não for possível obtê-los (por exemplo, devido a um erro de sintaxe json). |
| detail | Informação adicional | Objeto | A chave de resultado, com os resultados possíveis, ou seja, ok ou erro. Chave de detalhe, com valor correspondente à mensagem informativa de validação, erro ou processamento válido. |
Considerações
- O número de registros por pacote (request) será limitado a 1000 itens para não afetar o desempenho e para que as respostas possam ser processadas.
- Em caso de erro, os registros errados serão informados, mas os corretos serão incorporados. Os resultados podem ser visualizados no console na tela do monitor de importação.
- Em todos os casos, será informado o número total de linhas com erro e corretas. Os resultados podem ser visualizados no console na tela do monitor de importação.
- O processo utiliza semáforos para evitar a concorrência de clientes que pretendem processar em paralelo, pois implica na possibilidade de erros nas validações.
Os catálogos a serem importados são:
Excluindo atributos em catálogos no PROMO
A partir da versão 7.2.3 do Promo, a aplicação permite excluir em determinados catálogos, alguns atributos apenas enviando o id desse atributo no post, utilizando o serviço Rest.
Não é necessário enviar o id e a descrição. Apenas o código é suficiente para realizar a exclusão.
Os catálogos que atendem a esse critério são:
Catálogos dinâmicos.
"CatalogAdditionalField00", "CatalogAdditionalField01", "CatalogAdditionalField02", "CatalogAdditionalField03",
"CatalogAdditionalField04", "CatalogAdditionalField05", "CatalogAdditionalField06", "CatalogAdditionalField07",
"CatalogAdditionalField08", "CatalogAdditionalField09", "CatalogAdditionalField10", "CatalogAdditionalField11",
"CatalogAdditionalField12", "CatalogAdditionalField13", "CatalogAdditionalField14", "CatalogAdditionalField15",
"CatalogAdditionalField16", "CatalogAdditionalField17", "CatalogAdditionalField18", "CatalogAdditionalField19",
"CatalogBrand", "CatalogChannel", "CatalogCreditCampaignCode",
"CatalogCurrencyCode", "CatalogCustomerType", "CatalogDepartment", "CatalogEventTransaction",
"CatalogEventTransactionType", "CatalogFamily", "CatalogFormat",
"CatalogPaymentBank", "CatalogPaymentCode", "CatalogPaymentPrefix", "CatalogItem", "CatalogSubCategory",
"CatalogPaymentType", "CatalogPocket", "CatalogProductBarcode", "CatalogProductCode", "CatalogCustomer",
"CatalogProfileCode", "CatalogStoreChain", "CatalogStore", "CatalogSubZone", "CatalogSupplier", "CatalogZone",
"CatalogGender", "CatalogIdType", "CatalogContractPriceList", "CatalogCountry", "CatalogCategory",
Do exposto, estes não permitem a repetição de inscrições:
"CatalogGender", "CatalogIdType", "CatalogContractPriceList", "CatalogCountry",
"CatalogCustomerType", "CatalogItem", "CatalogCustomer"
"E estes não são nomes de código, mas ainda assim atenderão ao requisito porque sua chave primária inclui apenas companyId e code."
"CatalogItem", "CatalogCustomer", "CatalogSubCategory"
"CatalogCategory"
Estes catálogos não foram afetados:
"Card", "CatalogCity" ,"CatalogState", "CatalogInfoFinancial", "CatalogItemStock" (si bien tiene clave primaria companyId-code, no tiene un campo name), "CatalogExtendWarranty" (idem anterior), "CatalogRedeemBenefit"
Os seguintes casos podem ser apresentados:
A Url é:
http://{{SERVER}}:{{PORT}}/promo/api/rest/catalogs
- Apenas o código do produto é enviado:
A mensagem é enviada via Postman:
{
"companyId" = "napse",
"catalog" = "CatalogChannel",
"params":[],
"items": [
{
"code"= "1",
"operacion" = "D"
}
]
}
Após a execução do job de Importação de Entidades, o registro que correspondia ao código solicitado será removido no console.
2. Apenas o código e nome do produto são enviados.
{
"companyId" = "napse",
"catalog" = "CatalogChannel",
"params":[],
"items": [
{
"code"= "1",
"name"= "CATALOGCHANNEL2",
"operacion" = "D"
}
]
}
Depois de executar o job Importação de Entidades, o registro que correspondia ao código solicitado será excluído no console.
Console: Serviço REST de Exclusão de Dados do Cliente e seus dados de fidelidade
Este serviço rest permite excluir o cliente e todos os dados de fidelidade relacionados a ele, se desejado.
| Campo | Valor |
|---|---|
companyId | Id da empresa (obrigatório) |
| params | para torná-lo extensível, é uma lista vazia |
| code | Código do cliente (obrigatório) |
| operation | D: o apagamento parcial atribuirá um traço (-) aos dados do cliente (exceto o código, que continuará sendo exibido) ou R: apagamento total inclui fidelidade e também apaga o código do cliente. Requerido |
Dados para o pedido
Método | Url base |
|---|---|
| DELETE | http://URLPROMO:PUERTO/promo/api/rest/customer/delete Por ej. http://promo.com:8080/promo/api/rest/customer/delete |
Serviço REST para excluir totalmente ou parcialmente o cliente e, se desejado, seus dados de fidelidade.
{
"companyId": "<companyId>",
"params": [],
"items": [
{
"code": "<codigoCliente1>",
"operation": "D"
}
]
}
Você pode enviar vários clientes de uma só vez.
{
"status": "200",
"description": "Cliente (s) Eliminado (s)",
"detail": [
{
"result": "ok",
"detail": "Cliente (s) Eliminado (s)"
}
]
}
Exemplo:
Serviço de Importação em Massa de Promoções via REST
Este serviço permite importar promoções em massa para a console PROMO através de REST. O esquema de autenticação é o mesmo dos outros serviços REST apresentados aqui (ver acima). Depois de obter o token de acesso, o serviço pode ser invocado usando o método POST, na URL: <promo>/api/rest/import.
Dados para o request
Método | Url base |
|---|---|
| POST | http://URLPROMO:PUERTO/promo/api/rest/promotion/import Por ex. http://promo.com:8080/promo/api/rest/promotion/import |
É importante definir modelos específicos ao importar, isso facilitará muito a tarefa de montar o serviço. Por exemplo, se estivermos importando descontos percentuais, o mais importante é definir o modelo em JSON. A elaboração do modelo é um processo que deve ser realizado por alguém com conhecimento da plataforma.
Importante
As promoções devem estar no estado Completa para serem importadas através deste serviço. Promo limita a 3000 a quantidade de condições simples que podem ser adicionadas por promoção.
Um exemplo de criação, desativação ou atualização de um conjunto de promoções é o seguinte:
{
"companyId": "napse",
"promotions": [
{
"operation": "I",
"name": "promo import10",
"code": "promo import10",
"promotionType": "tipo 1",
"promotionSubType": "tipo 1",
"promotionApplicationForm": "tipo 1",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "631642d4cfaa7738300ff981",
"type": "item"
}
},
"condition": {
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "631642d4cfaa7738300ff981"
}
},
"benefits": {
"benefit": {
"instance": "PercentageDiscount",
"parameter": [
{
"key": "displayMessage",
"value": "promo import"
},
{
"key": "printerMessage",
"value": "promo import"
},
{
"key": "TLOGMessage",
"value": "promo import"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "631642c3cfaa7738300ff97e"
},
{
"key": "percent",
"value": "10"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "prorateBCP",
"value": "false"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {"name": "631642d4cfaa7738300ff981"}
}
}
}
}
]
}
Importante
Ao inserir uma promoção por serviço REST, será gerado um novo ID para o benefício e não será considerado o ID do benefício atribuído pelo usuário no JSON, para evitar a atribuição de IDs duplicados. Portanto, ao atualizar a promoção, o usuário deve levar em consideração o ID do benefício gerado e atualizá-lo no JSON antes de enviar a alteração. Caso contrário, o benefício será considerado como novo e inserido, resultando em duplicação do benefício. Isso ocorre porque, ao não encontrar o ID ao pesquisar os benefícios na promoção, ele será considerado como um novo benefício para a promoção.
- Para operações de inserção (I), um novo ID será gerado para o benefício.
- Portanto, para modificar a promoção U, deve-se indicar o número do novo ID gerado.
Parâmetros de entrada
| Campo | Descrição |
|---|---|
| companyId | Código da empresa. Necessário |
promotions | Conjunto de promoções a serem atualizadas, podendo ser novas, atualizações ou promoções que desejamos desativar. Requerido. |
| operation | I: Inserir / U: Atualizar / R: Cancelamento. Requerido |
| name | Nombre de la promoción. Requerido |
code | Nome da promoção. Obrigatório |
| sets | Refere-se aos conjuntos que definirão a condição e o benefício da promoção, por exemplo:
|
| conditions | Refere-se à combinação de conjuntos que fazem parte da condição para obter o benefício requerido. Exemplo: Conjunto 1 E conjunto 2. Produtos com Marca X e Família Y Exemplo 2: Conjunto 1 E Conjunto 3 Produtos com marca X e forma de pagamento VISA |
| benefits | Refere-se à combinação de conjuntos que fazem parte da condição para obter o benefício requerido. Los beneficios posibles son: NewPrice : Nuevo precioNewPrice : Novo preço |
Respuesta del servicio
Si la solicitud ha sido exitosa, se podrá visualizar la siguiente respuesta:
Request exitoso
{
"status": "Información Recibida OK",
"description": "La importación de promociones será procesada"
}
En el caso de indicar un código de compañía que no existe, visualizará la siguiente respuesta:
Error con compañía indicada
{
"status": "companyId is Invalid",
"description": "Debe enviar el campo companyId válido"
}
Para cancelar una promoción, a través del servicio Rest se debe informar:
- Nombre de la Promoción
{
"companyId": "1",
"promotions": [
{
"operations": "R",
"name": "Promo4"
}
]
}
La respuesta es:
{
"status": "Informacion Recibida OK",
"description": "La importación de promociones será procesada"
}
2. Código de la Promoción
{
"companyId": "1",
"promotions":[
{
"operation": "R",
"code": "Promo1"
}
]
}
La respuesta es:
{
"status": "Informacion Recibida OK",
"description": "La importación de promociones será procesada"
}
3. Código y Nombre de la Promoción
{
"companyId": "1",
"promotions":[
{
"operation": "R",
"code":"Promo7",
"name":"Promo7"
}
]
}
La respuesta es:
{
"status": "Informacion Recibida OK",
"description": "La importación de promociones será procesada"
}
Ejemplo 1: invocando el servicio de importación masiva de promociones via CURL:
Ejemplo
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/promotion/import"
Se enviará el siguiente request:
{
"companyId": "napse",
"promotions": [
{
"code": "P002",
"sets": {
"set": [
{
"name": "5feaf1324b10b84760e83f37",
"type": "item",
"attribute": "level1",
"comparator": "Into",
"value": "maderas"
},
{
"name": "5feaf13a4b10b84760e83f3a",
"type": "payment",
"attribute": "type",
"comparator": "Into",
"value": "card"
}
]
},
"condition": {
"type": "composite",
"name": "And",
"condition": [
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "5feaf1324b10b84760e83f37"
}
},
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "5feaf13a4b10b84760e83f3a"
}
}
]
},
"benefits": {
"benefit": {
"instance": "CouponBenefit",
"parameter": [
{
"key": "displayMessage",
"value": "Entrega de un cupon para proxima compra"
},
{
"key": "printerMessage",
"value": "Entrega de un cupon para proxima compra"
},
{
"key": "TLOGMessage",
"value": "Entrega de un cupon para proxima compra"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "5feaf1224b10b84760e83f34"
},
{
"key": "qty",
"value": "1"
},
{
"key": "couponid",
"value": "001"
},
{
"key": "infoPos",
"value": "0"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"name": "5feaf1324b10b84760e83f37"
}
}
}
}
},
{
"operation": "u",
"name": "Entrega de puntos llevando 2 furadeiras",
"code": "P003",
"sets": {
"set": {
"name": "5feaf18c4b10b84760e83f45",
"type": "item",
"attribute": "level3",
"comparator": "Into",
"value": "furadeiras"
}
},
"combo": {
"combo-component": {
"min": "2",
"max": "2",
"attribute": "qty",
"use-set": "5feaf18c4b10b84760e83f45"
}
},
"benefits": {
"benefit": {
"instance": "PercentLoyaltyBenefit",
"nro": "5feaf1cd4b10b84760e83f4a",
"parameter": [
{
"key": "displayMessage",
"value": "Entrega de puntos llevando 2 furadeiras"
},
{
"key": "printerMessage",
"value": "Entrega de puntos llevando 2 furadeiras"
},
{
"key": "TLOGMessage",
"value": "Entrega de puntos llevando 2 furadeiras"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "5feaf1794b10b84760e83f40"
},
{
"key": "percent",
"value": "50"
},
{
"key": "type",
"value": "3003"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"name": "5feaf18c4b10b84760e83f45"
}
}
}
}
}
]
}
El cual recibirá una respuesta del tipo:
{
"status": "Información Recibida OK",
"description": "La importación de promociones será procesada"
}
Importante
Si se desea cancelar y/o actualizar una promoción cuyo código se repite en otras promociones; se debe tener en cuenta informar el nombre de la que se desea cancelar y /o actualizar.
Importación de una promoción desde un mapa (.xml):
Pasos a seguir para convertir un mapa (.xml) en un json de entrada del servicio de Importación Masiva de Promociones vía REST:
Dado el siguiente mapa .xml:
<?xml version="1.0" encoding="UTF-8"?> <promo-engine start-date="19/05/2022 00:00" end-date="26/05/2022 23:59" map-version="1" suggest="not"> <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="62867033c9512b0184381178" name="Promos con limites 1" code="30" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not"> <sets> <set name="62867340c9512b01843811b5" type="item" attribute="code" comparator="Into" value="111"/> </sets> <condition type="composite" name="And"> <condition type="basic" name="Exists"> <parameter key="use-set" value="62867340c9512b01843811b5"/> </condition> <condition type="basic" name="Header"> <parameter key="attribute" value="store"/> <parameter key="value" value="napse,napse2"/> </condition> </condition> <benefits> <benefit instance="FixedDiscount" nro="628670c9c9512b018438117f"> <parameter key="displayMessage" value="Promos con limites 1"/> <parameter key="printerMessage" value="Promos con limites 1"/> <parameter key="TLOGMessage" value="Promos con limites 1"/> <parameter key="applicationMethod" value="resume"/> <parameter key="prorationMethod" value="proportional"/> <parameter key="applicationPriceType" value="benefited-price"/> <parameter key="hasLimit" value="true"/> <parameter key="name" value="62867033c9512b0184381178"/> <parameter key="amount" value="300"/> <parameter key="unit" value="qty"/> <parameter key="prorateBCP" value="false"/> <parameter key="recoveryValue" value="0"/> <parameter key="recoveryType" value=""/> <applied-elements> <use-set name="62867340c9512b01843811b5"/> </applied-elements> </benefit> </benefits> </promotion> </promotions> <evaluation-algorithm> <step> <function name="ALL"> <function name="SIMPLE"> <promotion-usage name="Promos con limites 1"/> </function> </function> </step> </evaluation-algorithm> </promo-engine>
- Se deberá tomar solo la sección del bloque <promotion ....>, tal como se ve en la siguiente imagen:
<promotion nro="62867033c9512b0184381178" name="Promos con limites 1" code="30" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not"> <sets> <set name="62867340c9512b01843811b5" type="item" attribute="code" comparator="Into" value="111"/> </sets> <condition type="composite" name="And"> <condition type="basic" name="Exists"> <parameter key="use-set" value="62867340c9512b01843811b5"/> </condition> <condition type="basic" name="Header"> <parameter key="attribute" value="store"/> <parameter key="value" value="napse,napse2"/> </condition> </condition> <benefits> <benefit instance="FixedDiscount" nro="628670c9c9512b018438117f"> <parameter key="displayMessage" value="Promos con limites 1"/> <parameter key="printerMessage" value="Promos con limites 1"/> <parameter key="TLOGMessage" value="Promos con limites 1"/> <parameter key="applicationMethod" value="resume"/> <parameter key="prorationMethod" value="proportional"/> <parameter key="applicationPriceType" value="benefited-price"/> <parameter key="hasLimit" value="true"/> <parameter key="name" value="62867033c9512b0184381178"/> <parameter key="amount" value="300"/> <parameter key="unit" value="qty"/> <parameter key="prorateBCP" value="false"/> <parameter key="recoveryValue" value="0"/> <parameter key="recoveryType" value=""/> <applied-elements> <use-set name="62867340c9512b01843811b5"/> </applied-elements> </benefit> </benefits> </promotion>
2. Luego, ir al sitio web https://www.oxygenxml.com/xml_json_converter.html, para convertir el xml a formato json.
3. Pegar el xml dentro del campo XML y generar el Json presionando el botón con la ->
4. Esto generará el siguiente resultado, del cual solo se deberá copiar lo que está dentro de "promotion": { marcado en azul, tal como se muestra en el siguiente ejemplo:
Ejemplo:
{
"promotion": {
"nro": "62867033c9512b0184381178",
"name": "Promos con limites 1",
"code": "30",
"className": "com.synthesis.promo.engine.promotion.ModularPromotion",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "62867340c9512b01843811b5",
"type": "item",
"attribute": "code",
"comparator": "Into",
"value": "111"
}
},
"condition": {
"type": "composite",
"name": "And",
"condition": [
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "62867340c9512b01843811b5"
}
},
{
"type": "basic",
"name": "Header",
"parameter": [
{
"key": "attribute",
"value": "store"
},
{
"key": "value",
"value": "napse,napse2"
}
]
}
]
},
"benefits": {
"benefit": {
"instance": "FixedDiscount",
"nro": "628670c9c9512b018438117f",
"parameter": [
{
"key": "displayMessage",
"value": "Promos con limites 1"
},
{
"key": "printerMessage",
"value": "Promos con limites 1"
},
{
"key": "TLOGMessage",
"value": "Promos con limites 1"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "hasLimit",
"value": "true"
},
{
"key": "name",
"value": "62867033c9512b0184381178"
},
{
"key": "amount",
"value": "300"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "prorateBCP",
"value": "false"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {"name": "62867340c9512b01843811b5"}
}
}
}
}
}
5. Una vez copiado todo el contenido marcado en azul, se deberá actualizar el formato estándar de importación de promociones. Por ejemplo:
Deberá pegar el contenido copiado dentro después de “operation”: I, tal como se ve en la siguiente imagen.
Esto da el siguiente resultado con el formato de importación ya completo y listo para usar desde POSTMAN (el contenido pegado está marcado en azul):
Resultado del JSON de importación de promoción:
{
"companyId": "napse",
"promotions": [
{
"operation": "I",
"nro": "62867033c9512b0184381178",
"name": "Promos con limites 1",
"code": "30",
"className": "com.synthesis.promo.engine.promotion.ModularPromotion",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "62867340c9512b01843811b5",
"type": "item",
"attribute": "code",
"comparator": "Into",
"value": "111"
}
},
"condition": {
"type": "composite",
"name": "And",
"condition": [
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "62867340c9512b01843811b5"
}
},
{
"type": "basic",
"name": "Header",
"parameter": [
{
"key": "attribute",
"value": "store"
},
{
"key": "value",
"value": "napse,napse2"
}
]
}
]
},
"benefits": {
"benefit": {
"instance": "FixedDiscount",
"nro": "628670c9c9512b018438117f",
"parameter": [
{
"key": "displayMessage",
"value": "Promos con limites 1"
},
{
"key": "printerMessage",
"value": "Promos con limites 1"
},
{
"key": "TLOGMessage",
"value": "Promos con limites 1"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "hasLimit",
"value": "true"
},
{
"key": "name",
"value": "62867033c9512b0184381178"
},
{
"key": "amount",
"value": "300"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "prorateBCP",
"value": "false"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {"name": "62867340c9512b01843811b5"}
}
}
}
}
]
}
6. Importación del json desde el servicio:
Resultado:
{
"status":"Informacion recibida OK",
"description":"La importacion de Promociones será procesada"
}
Al importar una promoción se debe tener en cuenta el workflow asociado al usuario que está llevando a cabo la importación.
- Si el usuario que realiza la importación tiene asignados todos los workflows definidos en la consola o ninguno de ellos, la promoción se importará con el workflow general por default.
- Si el usuario tiene asociado un workflow, la promoción se importará con el workflow asociado al usuario.
- Si el usuario tiene asociado más de un workflow, la promoción se importará con el primer workflow de la lista. Dicha lista está ordenada en forma alfabética; no por orden de creación.
Tipo, subtipo y Forma de Aplicación
Promo admite tanto por servicio Rest como por importación de promociones en xml, importar promociones con tipo, subtipo y forma de aplicación.
Ej:
Json:
{
"companyId": "napse",
"promotions": [{
"operation": "I",
"name": "Promo Import4",
"code": "Promo Import4",
"promotionType": "tipo 1",
"promotionSubType": "tipo 1",
"promotionApplicationForm": "tipo 1",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "6324b5f8be13d734e87ccc14",
"type": "item"
}
},
"condition": {
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "6324b5f8be13d734e87ccc14"
}
},
"benefits": {
"benefit": {
"instance": "PercentageDiscount",
"parameter": [{
"key": "displayMessage",
"value": "promo import"
},
{
"key": "printerMessage",
"value": "promo import"
},
{
"key": "TLOGMessage",
"value": "promo import"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "6324b5a1be13d734e87ccc0e"
},
{
"key": "percent",
"value": "10"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "prorateBCP",
"value": "false"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"name": "6324b5f8be13d734e87ccc14 "
}
}
}
}
}]
}
Desde el servicio Rest:
Request:
{
"status":"Informacion recibida OK",
"description":"La importacion de Promociones será procesada"
}
Al importar una promoción se debe tener en cuenta el workflow asociado al usuario que está llevando a cabo la importación.
- Si el usuario no tiene asociado un workflow (en la vista Administración de Usuarios/Asociación a workflows), la promoción se importará con el primer workflow de la lista de asociación.
- El usuario tiene asociado un workflow, la promoción se importará con el workflow asociado al usuario.
- El usuario tiene asociado más de un workflow, la promoción se importará con el primer workflow de la lista. Dicha lista está ordenada en forma alfabética; no por orden de creación.
Servicio de importación de promociones con los atributos de cabecera deshabilitados
Es posible insertar promociones, cuando se deshabiliten e inactiven los atributos de cabecera, en la consola (Módulo de Administración/Atributos de cabecera)::
EJ. Json:
{
"companyId": "napse",
"promotions": [
{
"nro": "",
"name": "promoIT1",
"code": "",
"className": "com.synthesis.promo.engine.promotion.ModularPromotion",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "627b93e926a51910c877b0e5",
"type": "item",
"attribute": "code",
"comparator": "Into",
"value": "1234"
}
},
"combo": {
"combo-component": {
"min": "1",
"max": "4",
"attribute": "qty",
"use-set": "627b93e926a51910c877b0e9"
}
},
"benefits": {
"benefit": {
"instance": "FixedDiscount",
"nro": "627b953326a51910c877b0f1",
"parameter": [
{
"key": "displayMessage",
"value": "Bug305863-Limite_71-47440-47573"
},
{
"key": "printerMessage",
"value": "Bug305863-Limite_71-47440-47573"
},
{
"key": "TLOGMessage",
"value": "Bug305863-Limite_71-47440-47573"
},
{
"key": "applicationMethod",
"value": "lineByLine"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "original-price"
},
{
"key": "hasLimit",
"value": "true"
},
{
"key": "name",
"value": "627b939926a51910c877b0e4"
},
{
"key": "amount",
"value": "1000"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "recoveryValue",
"value": "100"
},
{
"key": "recoveryType",
"value": "p"
},
{
"key": "margengasto",
"value": "1"
},
{
"key": "prorateBCP",
"value": "false"
}
],
"applied-elements": {
"use-set": {"name": "627b93e926a51910c877b0e9"}
},
"staggered": {
"unit": "qty",
"staggeredStep": [
{
"nro": "627b947426a51910c877b0ed",
"min": "1",
"max": "1",
"applyValue": "50000"
},
{
"nro": "627b949c26a51910c877b0f0",
"min": "4",
"max": "4",
"applyValue": "1000"
}
]
}
}
},
"operation":"I"
}
]
}
Desde Postman:
Servicio de Exclusión de Fechas para no ser ejecutada una promoción
Servicio que permite tener la posibilidad de configurar una exclusión de fechas determinadas durante todo el período de vigencia para NO ser ejecutada una promoción por sucursal. Esta opción va a permitir controlar que en determinadas fechas(que son días especiales) no se aplique las promociones que tienen productos que participan en estos días.
Este método accesible desde api/rest/catalogs es el encargado de devolver en formato JSON las fechas en que deben excluirse las promociones y en las tiendas informadas solicitado por medio de la acción POST.
http://{{SERVER}}:{{PORT}}/promo/api/rest/catalogs
Ej:
http://localhost:8072/promo/api/rest/catalogs
El formato para el servicio será:
| Campo | Ejemplos | Tipo de dato | Detalle |
| companyId | napse | Alfanumérico | Código de la compañía - Requerido |
| catalog | CatalogExclusionDates | string | Catálogo de Fechas de Exclusión - Requerido |
| params | [ ] | Listado | Parámetros adicionales - Requerido |
| storeCode | napse | Alfanumérico | Código de la tienda - Requerido |
| promotionNames | Promo test | Alfanumérico | Nombre de la promoción que será excluida para la tienda y fecha indicada. No obligatorio para la operación R, solo en los casos en que se quiera eliminar todas las exclusiones de días específicos, este campo podrá quedar como vacío es decir "", indicando que todas las exclusiones de promociones en las fechas indicadas serán removidas. |
| exclusionDates | ["2022-07-21", "2022-07-22"] | Listado de fechas | Fechas en las que será excluida la promoción, cada fecha deberá seguir el formato de "año-mes-día" - Requerido |
| operation | I | Alfanumérico | Identifica el tipo de operación a realizar por cada limite a procesar (requerido), dentro de las opciones disponibles están: (Requerido)
|
Ej:
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "3",
"promotionName": "Promo Puntos I",
"exclusionDates": ["2023-07-10","2023-07-11","2023-07-12", "2023-07-12"],
"operation": "U" //Tipo de operación asociada a I (insertar), U (actualizar) y R (remover)
},
{
"storeCode": "3",
"promotionName": "Promo Descuento por Convenio",
"exclusionDates": ["2023-07-10"],
"operation": "I"
},
{
"storeCode": "3",
"promotionName": "Promo Puntos III",
"exclusionDates": ["2023-07-11"],
"operation": "R"
}
]
}
{
"status": "200",
"description": "CatalogExclusionDates",
"detail": {
"result": "ok",
"detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
}
}
Formato de una exclusión con operación I
El siguiente json representa el formato para el registro de nuevas exclusiones de promociones por fecha para una tienda y promoción especifica.
- Tenga en cuenta que en el campo exclusionDates solo podrá indicar datos de la fecha con el formato "año-mes-día"
- Solo se crearan las exclusiones con las fechas que sean validas, es decir que tengan el formato del punto anterior y que no sean menor a la fecha actual.
- Si la promoción sobre la cual se procesaran las exclusiones tiene vigencia definida (Fecha inicio y fin), las fechas incluidas en el campo exclusionDates deberá estar dentro del rango de vigencia de la promo, de lo contrario las exclusiones fuera de la vigencia serán ignoradas, creando solo las exclusiones sobre las fechas que estén dentro de la vigencia.
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "3",
"promotionName": "Promo Emite Cupon II",
"exclusionDates": ["2023-07-10","2023-07-11","2023-07-12"],
"operation": "I"
}
]
}
{
"status": "200",
"description": "CatalogExclusionDates",
"detail": {
"result": "ok",
"detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
}
}
Formato de una exclusión con operación U
El proceso de actualización de la exclusión de promociones por fecha, considera los puntos indicados para la operación I, teniendo solo las siguientes particularidades:
- El proceso de actualización incorporara nuevos registros de fechas de exclusión para la promoción siempre y cuando ya no exista un registro previo sobre esa misma promoción, tienda y fecha.
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "napse",
"promotionName": "Promo Puntos III",
"exclusionDates": ["2023-07-10"],
"operation": "U"
}
]
}
Formato de limite con operación R
El proceso de remover exclusiones contempla dos casos:
1- Cuando se quiere remover la exclusión de una promoción en una fecha especifica, deberá indicar el siguiente formato.
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "napse",
"promotionName": "Promo Descuento por Convenio",
"exclusionDates": ["2023-07-10"],
"operation": "R"
}
]
}
Cuando se quiere remover la exclusión de todas las promociones en una fecha especifica, deberá indicar el siguiente formato.
- La diferencia con el formato anterior es que el valor del campo promotionName se deja como un string vacío igual a ""
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "napse",
"promotionName": "",
"exclusionDates": ["2023-07-10"],
"operation": "R"
}
]
}
Respuesta del servicio
Si la solicitud ha sido exitosa, se podrá visualizar la siguiente respuesta (Interfaz Rest):
{
"status": "200",
"description": "CatalogExclusionDates",
"detail": {
"result": "ok",
"detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
}
}
En el caso de indicar un código de compañía que no existe, visualizara la siguiente respuesta
{
"status": "400",
"description": "CatalogExclusionDates",
"detail": {
"result": "error",
"detail": "El código de compañía napse no pertenece a una compañía existente."
}
}
Servicio de Canje de Puntos por Catalogo
Como soporte al Nuevo beneficio de Canje de Puntos por Catalogo (ver mas arriba), se deben especificar la tabla de productos que poseen equivalente en puntos a través de un catalogo definido para tal uso.
Siguiendo el formato especificado anteriormente tendremos:
| Campo | Valor |
|---|---|
| companyId | El código de la compañía correspondiente. Requerido |
| catalog | "CatalogRedeemBenefit". No se debe modificar. Requerido |
params | Un listado vacío. No se debe modificar. Requerido |
| items | Un listado con cada ítem del catálogo de Canje de puntos. Requerido |
Dentro de ítems, el formato es:
| Campo | Valor |
|---|---|
store | Código de tienda. Requerido. Alfanumérico. Si se aplica a todas las tiendas, el código de la tienda debe ser "-". |
code | Código del producto. Requerido. Alfanumérico. |
points | Puntos requeridos. Numérico con decimales. |
discountValue | Valor descuento. Numérico con decimales. |
discountType | Tipo descuento. Acepta sólo los valores "perc" (porcentaje), "fix" (descuento fijo), o bien, "nprice" (nuevo precio) |
operation | La operación a realizar sobre el elemento. Ver tabla con valores posibles. |
Así tendremos que un ejemplo de request para insertar registros en este catálogo será:
{
"companyId": "napse",
"catalog": "CatalogRedeemBenefit",
"params": [],
"items": [
{
"store": "1",
"code": "10",
"points": "10.5",
"discountValue":"15" ,
"discountType": "perc",
"operation": "I"
},
{
"store": "1",
"code": "20",
"points": "20.5",
"discountValue":"20" ,
"discountType": "fix",
"operation": "I"
},
{
"store": "-",
"code": "30",
"points": "50",
"discountValue":"25" ,
"discountType": "nprice",
"operation": "I"
}
]
}
{
"status": "200",
"description": "CatalogRedeemBenefit",
"detail": {
"result": "ok",
"detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
}
}
Servicio de Asignación de Elementos de Fidelidad
Esta operación es el equivalente a la función de asignación/actualización de elementos, mas la importación de clientes nuevos (Ver proceso actual de asignación de convenios). En este caso los campos serán:.
Asignación a un elemento de fidelidad de un cliente, un convenio y su monto.
Esta operación realiza la asignación de tarjeta, cliente, convenio, y monto. Debe existir previamente la tarjeta (activa o inactiva), un convenio activo, y el cliente, en caso de no existir, se da de alta. En relación al monto, se le puede asignar o no un operador adelante del monto; especificando el operador + suma un valor al monto que la tarjeta tiene; especificando el operador - resta saldo al monto que la tarjeta tiene; si no se pone operador reemplaza el monto que la tarjeta tiene (ver más abajo el ejemplo del campo amount).
Un esquema de ejemplo es el siguiente:
{
"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.......}
]
}
Los campos en negrita son obligatorios.
| Campo | Descripción |
|---|---|
| params | cardType: Tipo de elemento de fidelidad a importar que será validado. contract: código de convenio al que pertenecen estos elementos/clientes. |
operation | I: Inserción / U: Actualización / R: Eliminación |
id |
|
customer |
|
amount |
|
name | Nombre del Cliente. Cadena libre. |
surname | Apellido. Cadena libre. |
gender | Género. (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin. |
birthDate | Fecha de nacimiento. Cadena en formato "yyyyMMdd". Más Información del formato |
idType | Tipo de identificación (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin. |
identifier | Numero de Identificación del Cliente |
idDate | Fecha de Expiración de la identificación. Cadena en formato "yyyyMMdd". Más Información del formato |
nacionality | Nacionalidad. Cadena Libre. |
Dirección de correo electrónico. Cadena libre. | |
customerType | Tipo de Cliente (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin. |
address | Dirección. Cadena libre |
country | País. (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin. |
state | Estado/Provincia (ver valores por Catálogo). Depende de los valores cargados en el catálogo a tal fin. |
city | Ciudad (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin. |
postalCode | Código Postal |
phone | Teléfono |
Asignación de ejemplo
Teniendo en cuenta que existe un convenio activo con código c1, y que hay un elemento existente, con código 1234000000000, y pertenece al tipo de elemento de código verano, se asigna al elemento el convenio mencionado, el monto de 100, y un nuevo cliente. Al no existir se da de alta en la base de datos.
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCardAssign",
"params": [
{"cardType": "verano"},
{"contract": "c1"}
],
"items": [{
"operation": "I",
"id": "1234000000000",
"customer": "emc",
"amount": "100",
"name": "Eugenia",
"surname": "Molina",
"gender": "M",
"birthDate": "19900101",
"idType": "dni",
"identifier": "77778888",
"idDate": "20500101",
"nacionality": "Argentina",
"email": "[email protected]",
"customerType": "vip",
"address": "Urquiza 5050",
"country": "ar",
"state": "bsas",
"city": "tig",
"postalCode": "4433",
"phone": "2222-9999"
}]
}
Incremento de saldo
Para incrementar el saldo al elemento se especifica un operador + con el valor a sumar. Siguiendo el ejemplo anterior, donde el elemento tenía un saldo de 100, se le suman 50 en este ejemplo. Después de esta operación el saldo resultante será de 150.
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCardAssign",
"params": [
{"cardType": "verano"},
{"contract": "c1"}
],
"items": [{
"operation": "I",
"id": "1234000000000",
"customer": "emc",
"amount": "+50",
"name": "Eugenia",
"surname": "Molina",
"gender": "M",
"birthDate": "19900101",
"idType": "dni",
"identifier": "77778888",
"idDate": "20500101",
"nacionality": "Argentina",
"email": "[email protected]",
"customerType": "vip",
"address": "Urquiza 5050",
"country": "ar",
"state": "bsas",
"city": "tig",
"postalCode": "4433",
"phone": "2222-9999"
}]
}
Decremento de saldo
Similar al incremento. Para restar saldo se usa el operador - y luego el valor del monto a restar. Si el elemento anteriormente tenía 150, al restar 20 queda en 130 de monto.
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCardAssign",
"params": [
{"cardType": "verano"},
{"contract": "c1"}
],
"items": [{
"operation": "I",
"id": "1234000000000",
"customer": "emc",
"amount": "-20",
"name": "Eugenia",
"surname": "Molina",
"gender": "M",
"birthDate": "19900101",
"idType": "dni",
"identifier": "77778888",
"idDate": "20500101",
"nacionality": "Argentina",
"email": "[email protected]",
"customerType": "vip",
"address": "Urquiza 5050",
"country": "ar",
"state": "bsas",
"city": "tig",
"postalCode": "4433",
"phone": "2222-9999"
}]
}
Alta del Elemento de Fidelidad asociada al cliente identificado en la transacción (al momento de aplicar el beneficio de acumulación)
Para la asignación y carga de un elemento de fidelidad que acumule puntos deberá considerarse la siguiente secuencia entre el pos y Promo:
- Pre-Requisitos:
Para que el alta de clientes pueda efectuarse al momento de procesarse una transacción, deberá de habilitarse en el archivo de configuraciones de la Consola de Promo (“promoplus.properties”) el siguiente atributo:
# Habilita el alta de clientes on the fly promo.allowNonExistingCustomers = true |
Una vez actualizado, deberá de reiniciarse el Wildfly para que los cambios sean tomados correctamente.
- Alta de Cliente
Los clientes serán creados utilizando el estado "loyaltyValidation" en el caso de enviarse los datos mínimos y al mismo tiempo Promo detecte que el cliente no existe. Los datos mínimos mencionados son (marcados en Rojo):
<customer-add seq="1" id="10090504" identifier="10090504" type="test" name="pepe" lastName="rodrigues" identifierType="cpf" email="mimail@test.com" />
Input
Input
|
En la respuesta al loyaltyValidation no se informarán tarjetas ya que el cliente esta recién ingresado en la consola de Promo.
Output
|
Ingreso de ítem
Input
|
Se devuelve la promoción que aplica puntos al tipo de elemento de fidelidad; en este caso "otorga Stickers A-3"
Output
|
CATÁLOGO DE CLIENTES
Exclusão de atributos nos catálogos PROMO
A partir desta versão, Promo permite eliminar determinados atributos de determinados catálogos, bastando para tal enviar o id do referido atributo que lhe é enviado no correio, através do serviço Rest.
Não é necessário enviar id e descrição. Enviando apenas o código, a exclusão pode ser realizada.
Os catálogos que atendem a esse critério são:
catálogos dinâmicos,
"CatalogAdditionalField00", "CatalogAdditionalField01", "CatalogAdditionalField02", "CatalogAdditionalField03", "CatalogAdditionalField04", "CatalogAdditionalField05", "CatalogAdditionalField06", "CatalogAdditionalField07", "CatalogAdditionalField
d08", "Catálogo CampoAdicional09" , "CampoAdicionalCatalog10"
, "CampoAdicionalCatalogo11",
" CatalogAdditionalField12 ", "CatalogAdditionalField13", "CatalogAdditionalField14", "CatalogAdditionalField15",
"CatalogAdditionalField16", "CatalogAdditionalField17", "CatalogAdditionalField18", "CatalogAdditionalField19",
"CatalogBrand", "CatalogChannel", "CatalogCreditCampaignCode",
"CatalogCurrencyCode", "CatalogCustomerType", "CatalogDepartment", "CatalogEventTransaction",
"CatalogEventTransactionType", "CatalogFamily", "CatalogFormat",
"CatalogPaymentBank", "CatalogPaymentCode", "CatalogPaymentPrefix", "CatalogItem", "CatalogSubCategory",
"CatalogPaymentType", "CatalogPocket", "CatalogProductBarcode", "CatalogProductCode", "CatalogCusto " sea ",
"CatalogProfileCode", "CatalogStoreChain", "CatalogStore", "CatalogSubZone", "CatalogSupplier", "CatalogZone", "CatalogGender", "CatalogIdType", " CatalogContractPriceList", "CatalogCountry", "CatalogCategory"
,
Dos itens acima, estes não suportam repetição de registro:
"CatalogGender", "CatalogIdType", "CatalogContractPriceList", "CatalogCountry",
"CatalogCustomerType", "CatalogItem", "CatalogCustomer"
E estes não são nomes de código, mas ainda atenderão ao requisito porque sua chave primária inclui apenas companyId e code
"CatalogItem", "CatalogCustomer", "CatalogSubCategory"
"CatalogCategory"
Estes catálogos não foram afetados:
"Card", "CatalogCity" ,"CatalogState", "CatalogInfoFinancial", "CatalogItemStock" (apesar de possuir uma chave primária companyId-code, não possui um campo de nome), "CatalogExtendWarranty" (o mesmo acima), "CatalogRedeemBenefit"
Podem ocorrer os seguintes casos:
A URL é:
http://{{SERVER}}:{{PORT}}/promo/api/rest/catalogs
- Apenas o código do produto é enviado:
Na consola:
A mensagem é enviada pelo carteiro:
{
"companyId" = "napse",
"catalog" = "CatalogChannel",
"params":[],
"itens": [
{
"code"= "1",
"operação" = "D"
}
]
}
Após a execução do job de Entity Import, observa-se que o primeiro registro que coincidia com o código solicitado foi eliminado no console:
2. É enviado apenas o código e o nome do produto:
{
"companyId" = "napse",
"catalog" = "CatalogChannel",
"params":[],
"itens": [
{
"code"= "1",
"name"= "CATALOGCHANNEL2",
"operação" = "D"
}
]
}
No console, observa-se que o registro com código e nome solicitados foi deletado:
Console: Serviço REST para Eliminação de Dados de Clientes e seus dados de fidelização
Este serviço de rest permite eliminar o cliente e todos os dados de fidelização relacionados com o mesmo, se assim o desejar.
| Campo | Valor |
|---|---|
ID da empresa | ID da empresa (obrigatório) |
| parâmetros | para torná-lo extensível, é uma lista vazia |
| código | Código do cliente (obrigatório) |
| cirurgia | D : a exclusão parcial atribuirá um traço (-) aos dados do cliente (exceto o código, que continuará sendo exibido) ou R : a exclusão total inclui a fidelidade e também exclui o código do cliente. |
Dados para o pedido
Método | url base |
|---|---|
| EXCLUIR | http://URLPROMO:PORT/promo /api/rest/customer/delete Por exemplo http://promo.com:8080/promo/api/rest/customer/delete _ _ |
Resto de serviço para eliminar total ou parcialmente o cliente e se desejar os seus dados de fidelização:
{
"companyId": "<companyId>",
"params": [],
"itens": [
{
"code": "<CustomerCode1>",
"operation": "D"
}
]
}
Vários clientes podem ser enviados de uma só vez.
{
"status": "200",
"description": "Cliente(s) Removido(s)",
"detalhe": [
{
"resultado": "ok",
"detalhe": "Cliente(s) Removido(s) ) )"
}
]
}
Exemplo:
Exemplo:
No console Promo, na tela "Gestão de clientes" antes de executar o serviço REST para remover os dados do cliente e seus dados de fidelidade, os clientes são exibidos da seguinte forma:
Depois de executar o serviço REST, ficará assim:
A exibição do log de auditoria detalhará a exclusão parcial:
e a remoção total:
Observar-se-á que o primeiro registro encontrado com os dados solicitados foi deletado no console:
Serviço de Importação em Massa de Promoções via REST
Este serviço permite importar promoções em massa por meio de REST para o console PROMO.
O esquema de autenticação é o mesmo dos demais serviços REST apresentados aqui (veja acima).
Uma vez obtido o token de acesso, o serviço pode ser invocado usando o método POST, a partir da URL:< promo >/ api / rest / import
Dados para o pedido
Método | url base |
|---|---|
| PUBLICAR | http://URLPROMO:PORT /promo /api/rest/promotion/import Por exemplo http://promo.com:8080/promo/api/rest/promotion/import_ _ |
É importante que na hora da importação sejam definidos templates específicos, isso facilitará muito a tarefa de montagem do serviço.
Exemplo: se vamos importar descontos por porcentagem, o mais importante é definir o template em JSON.
A montagem do gabarito é um processo que deve ser realizado por uma pessoa com conhecimento da plataforma.
Um exemplo de criação, inativação ou atualização de um conjunto de promoções é o seguinte:
{
"companyId": "napse",
"promotions": [
{
"operation": "I",
"name": "promo import10",
"code": "promo import10",
"promotionType": "type 1",
"promotionSubType": "type 1",
"promotionApplicationForm": "type 1",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "631642d4cfaa7738300ff981 ",
"tipo": "item"
}
},
"condição": {
"tipo": "básico",
"nome": "Existe",
"parâmetro": {
"chave": "conjunto de uso",
"value": "631642d4cfaa7738300ff981"
}
},
"benefits": { "
Benefit": {
"instance": "PercentageDiscount",
"parameter": [
{
"key": "displayMessage",
"value": "promo import"
},
{
"key": "printerMessage",
"value": "promo import"
},
{
"key": "TLOGMessage",
"value": "promo import"
},
{
"key": "applicationMethod",
"value": "currículo"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "preço-benefício"
},
{
"key": "name",
"value" : "631642c3cfaa7738300ff97e"
},
{
"chave": "porcentagem",
"valor": "10"
},
{
"chave": "unidade",
"valor": "qty"
},
{
"key": "prorateBCP",
"value": "false"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set" : {"nome": "631642d4cfaa7738300ff981"}
}
}
}
}
]
}
Importante
Ao inserir uma promoção por serviço REST, irá gerar um novo id para o Benefício, não irá considerar o id do benefício atribuído pelo usuário no json, isso para evitar atribuição de ids duplicados .
Portanto, ao atualizar novamente a promoção, o usuário deve levar em consideração o id do benefício gerado e atualizá-lo no json antes de enviar sua alteração, caso contrário aquele benefício será tomado como novo e inserido, gerando como consequência que seja duplicado .o benefício, pois ao não obter o id ao buscar os benefícios na promoção, o levará como um novo benefício para a promoção.
- Para as operações I (inserir) será gerado um novo id para o benefício.
- Portanto, para U (Modificar) a promoção, o número do novo id gerado deve ser indicado.
PARÂMETROS DE ENTRADA
| Campo | Descrição |
|---|---|
| ID da empresa | Código da companhia |
promoções | Conjunto de promoções a atualizar, podem ser novidades, atualizações ou promoções que queremos inativar. |
| cirurgia | I: Inserir / U: Atualizar / R: Cancelar |
| inhame | Nome da promoção |
código | Código promocional exclusivo |
| conjuntos | Refere-se aos conjuntos que definirão a condição e o benefício da promoção, por exemplo:
|
| condições | Refere-se à combinação de conjuntos que fazem parte da condição para obtenção do benefício. Exemplo: Conjunto 1 E conjunto 2. Produtos com Marca X e Família Y Exemplo 2: Conjunto 1 E conjunto 3 Produtos com marca X e forma de pagamento VISA |
| benefícios | Refere-se aos benefícios que serão concedidos se as condições forem atendidas Os possíveis benefícios são: NovoPreço: Novo Preço |
RESPOSTA DE SERVIÇO
Se a solicitação for bem-sucedida, a seguinte resposta pode ser exibida:
pedido bem sucedido
{
"status" : "Informações Recebidas OK" ,
"descrição" : "A importação das promoções será processada"
}
No caso de indicar uma empresa que não existe, será apresentada a seguinte resposta:
Erro com a empresa indicada
{
"status" : "companyId is Invalid" ,
"description" : "Você deve enviar um campo companyId válido"
}
Exemplo 1: invocando o serviço de importação de promoções em massa via CURL:
Ejemplo
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/promotion/import"
A seguinte solicitação será enviada:
{
"companyId": "napse",
"promotions": [
{
"code": "P002",
"sets": {
"set": [
{
"name": "5feaf1324b10b84760e83f37",
"type": "item",
"attribute": "level1",
"comparator": "Into",
"value": "woods"
},
{
"name": "5feaf13a4b10b84760e83f3a",
"tipo": "pagamento",
"atributo": "tipo",
"comparador": "Into",
"valor": "cartão"
}
]
},
"condição": {
"tipo": "composto",
"nome": "E",
"condição": [
{
"tipo": "básico",
"nome": "Existe",
"parâmetro": {
"chave": "conjunto de uso",
"valor": "5feaf1324b10b84760e83f37"
}
},
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "5feaf13a4b10b84760e83f3a"
}
}
]
},
"benefits": { "
benefício ": {
"instance": "CouponBenefit",
"parameter": [
{
"key": "displayMessage",
"value": "Entrega de cupom para próxima compra"
},
{
"key": "printerMessage",
"value": "Entrega de cupom para próxima compra"
},
{
"key": "TLOGMessage",
"value": "Entrega de cupom para próxima compra"
},
{
" key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proporcional"
},
{
"key": "applicationPriceType",
"value": "preço-benefício"
},
{
"key": "name",
"value": "5feaf1224b10b84760e83f34"
},
{
"key": "qty",
" valor": "1"
},
{
"chave": "cupomid",
"valor": "001"
},
{
"key": "infoPos",
"value": "0"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": " "
}
],
"elementos aplicados": {
"conjunto de uso":{
"nome": "5feaf1324b10b84760e83f37"
}
}
}
}
},
{
"operação": "u",
"nome": "Entrega de pontos com 2 furadeiras",
"código": "P003",
"conjuntos": {
"conjunto": {
"nome": " 5feaf18c4b10b84760e83f45",
"type": "item",
"attribute": "level3",
"comparator": "Into",
"value": "furadeiras"
}
},
"combo": {
"combo-componente": {
"min": "2",
"max": "2",
"attribute": "qty",
"use-set": "5feaf18c4b10b84760e83f45"
}
},
"benefits": { "
benefit": {
"instance": "PercentLoyaltyBenefit",
"nro": "5feaf1cd4b10b84760e83f4a",
"parameter": [
{
"key": "displayMessage",
"value": "Entrega de pontos portando 2 furadeiras"
},
{
"chave": "mensagem da impressora",
"value": "Atribuição de pontos por 2 furadeiras"
},
{
"key": "TLOGMessage",
"value": "Atribuição de pontos por 2 furadeiras"
},
{
"key": "applicationMethod",
"value": "resume "
},
{
"key": "prorationMethod",
"value": "proporcional"
},
{
"key": "applicationPriceType",
"value": "preço-benefício"
},
{
"key": "name",
"value": "5feaf1794b10b84760e83f40"
},
{
"key": "percent",
"value": "50"
},
{
"chave": "tipo",
"valor": "3003"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
" nome": "5feaf18c4b10b84760e83f45"
}
}
}
}
}
]
}
Que receberá uma resposta do tipo:
{
"status": "Informações recebidas OK",
"descrição": "A importação das promoções será processada"
}
IMPORTANDO UMA PROMOÇÃO DE UM MAPA (.xml):
Passos a seguir para converter um mapa (.xml) em uma entrada json para o serviço de Importação em Massa de Promoções via REST:
Dado o seguinte mapa .xml:
<?xml version="1.0" encoding="UTF-8"?> <promo-engine start-date="5/19/2022 00:00" end-date="5/26/2022 23:59" mapa -version="1" sugerir="not"> <parameter key="Logging" value="true"/> <parameter key="LogConfigurationFile" value="logrsca.xml"/> <parameter key="LogConfigurationCategory" valor ="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"/> <promoções> <promotion nro="62867033c9512b0184381178" name="Promoções com limites 1" code="30" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" sugerem="não"> <conjuntos> < set name="62867340c9512b01843811b5" type="item" attribute="code" comparator="Into" value="111"/> </sets> <condição tipo= " composto" name="E"> <condição tipo = " basic" name="Exists"> <parameter key="use-set" value="62867340c9512b01843811b5"/> </condition> <condição type="basic" name="Header"> <parameter key="attribute" value="store"/> <parameter key="value" value="napse,napse2"/> </condition> </condition> <benefícios> <benefit instance="FixedDiscount" nro="628670c9c9512b018438117f"> <parameter key="displayMessage" value="Promos com limites de 1"/> <parameter key="printerMessage" value="Promos com limites de 1"/> <chave de parâmetro ="TLOGMessage" value="Promos com limites 1"/> <parameter key="applicationMethod" value="resume"/> <parameter key="prorationMethod" value="proportional"/> <parameter key="applicationPriceType" valor ="preço-benefício"/> <parameter key="hasLimit" value="true"/> <parameter key="name" value="62867033c9512b0184381178"/> <parameter key="amount" value="300"/> <parameter key="unit" value="qty"/> <parameter key="prorateBCP" value="false"/> <parameter key="recoveryValue" value="0"/> <parameter key="recoveryType" value=""/> <applied-elements> <use-set name="62867340c9512b01843811b5"/> </applied-elements> < /benefit> </benefits> </promotion> </promotions> <evaluation-algorithm> <step> <function name="ALL"> <function name="SIMPLE"> <promotion-usage name="Promos com limites 1 "/> </function> </function> </step> </evaluation-algorithm> </promo-engine>
- Apenas a seção do bloco <promotion ....> deve ser tomada, conforme a imagem a seguir:
<promotion nro="62867033c9512b0184381178" name="Promoções com limites 1" code="30" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" sugerem="não"> <conjuntos> < set name="62867340c9512b01843811b5" type="item" attribute="code" comparator="Into" value="111"/> </sets> <condição tipo= " composto" name="E"> <condição tipo = " basic" name="Exists"> <parameter key="use-set" value="62867340c9512b01843811b5"/> </condition> <condition type="basic" name="Header"> <parameter key="attribute" value="store"/> <parameter key="value" value="napse,napse2"/> </condition> </condition> <benefícios> <benefit instance="FixedDiscount" nro="628670c9c9512b018438117f"> <parameter key="displayMessage" value="Promos com limites de 1"/> <parameter key="printerMessage" value="Promos com limites de 1"/> <chave de parâmetro ="TLOGMessage" value="Promos com limites 1"/> <parameter key="applicationMethod" value="resume"/> <parameter key="prorationMethod" value="proportional"/> <parameter key="applicationPriceType" valor ="preço-benefício"/> <parameter key="hasLimit" value="true"/> <parameter key="name" value="62867033c9512b0184381178"/> <parameter key="amount" value="300"/> <parameter key="unit" value="qty"/> <parameter key="prorateBCP" value="false"/> <parameter key="recoveryValue" value="0"/> <parameter key="recoveryType" value=""/> <applied-elements> <use-set name="62867340c9512b01843811b5"/> </applied-elements> < /benefício> </benefícios> </promoção>
2. Em seguida, acesse o site https://www.oxygenxml.com/xml_json_converter.html , para converter o formato xml para json.
3. Cole o xml dentro do campo XML e gere o Json pressionando o botão com a tecla ->
4. Isso produzirá a seguinte saída, da qual deve ser copiado apenas o que estiver dentro de "promoção": { marcado em azul , conforme mostrado no exemplo a seguir:
Ejemplo:
{
"promoção": {
"não": "62867033c9512b0184381178",
"name": "Promoções com limites 1",
"código": "30",
"className": "com.synthesis.promo.engine.promotion.ModularPromotion",
"relatórioParticipantes": "falso",
"sugerir": "não",
"conjuntos": {
"definir": {
"nome": "62867340c9512b01843811b5",
"tipo": "artigo",
"atributo": "código",
"comparador": "Into",
"valor": "111"
}
},
"doença": {
"tipo": "composto",
"nome e",
"doença": [
{
"tipo": "básico",
"nome": "Existe",
"parâmetro": {
"chave": "conjunto de uso",
"valor": "62867340c9512b01843811b5"
}
},
{
"tipo": "básico",
"nome": "Cabeçalho",
"parâmetro": [
{
"chave": "atributo",
"valor": "loja"
},
{
"valor chave",
"valor": "napse,napse2"
}
]
}
]
},
"benefícios": {
"benefício": {
"instance": "FixedDiscount",
"não": "628670c9c9512b018438117f",
"parâmetro": [
{
"chave": "displayMessage",
"value": "Promoções com limites 1"
},
{
"chave": "mensagem da impressora",
"value": "Promoções com limites 1"
},
{
"chave": "TLOGMessage",
"value": "Promoções com limites 1"
},
{
"chave": "método de aplicação",
"valor": "currículo"
},
{
"chave": "Método de rateio",
"valor": "proporcional"
},
{
"chave": "aplicativoPriceType",
"valor": "preço-benefício"
},
{
"chave": "hasLimit",
"valor": "verdadeiro"
},
{
"chave": "nome",
"valor": "62867033c9512b0184381178"
},
{
"chave": "quantia",
"valor": "300"
},
{
"chave": "unidade",
"valor": "quantidade"
},
{
"chave": "prorataBCP",
"valor": "falso"
},
{
"chave": "valor de recuperação",
"valor": "0"
},
{
"chave": "tipo de recuperação",
"valor": ""
}
],
"elementos aplicados": {
"use-set": {"nome": "62867340c9512b01843811b5"}
}
}
}
}
}
5. Depois de copiado todo o conteúdo marcado em azul, o formato padrão de importação da promoção deve ser atualizado. Por exemplo:
Você precisará colar o conteúdo copiado dentro após a “operação”: I, conforme a imagem a seguir.
Isso fornece a seguinte saída com o formato de importação já completo e pronto para uso do POSTMAN (o conteúdo colado é marcado em azul ):
Resultado del JSON de importación de promoción:
{
"companyId": "napse",
"promoções": [
{
"operação": "eu",
"não": "62867033c9512b0184381178",
"name": "Promoções com limites 1",
"código": "30",
"className": "com.synthesis.promo.engine.promotion.ModularPromotion",
"relatórioParticipantes": "falso",
"sugerir": "não",
"conjuntos": {
"definir": {
"nome": "62867340c9512b01843811b5",
"tipo": "artigo",
"atributo": "código",
"comparador": "Into",
"valor": "111"
}
},
"doença": {
"tipo": "composto",
"nome e",
"doença": [
{
"tipo": "básico",
"nome": "Existe",
"parâmetro": {
"chave": "conjunto de uso",
"valor": "62867340c9512b01843811b5"
}
},
{
"tipo": "básico",
"nome": "Cabeçalho",
"parâmetro": [
{
"chave": "atributo",
"valor": "loja"
},
{
"valor chave",
"valor": "napse,napse2"
}
]
}
]
},
"benefícios": {
"benefício": {
"instance": "FixedDiscount",
"não": "628670c9c9512b018438117f",
"parâmetro": [
{
"chave": "displayMessage",
"value": "Promoções com limites 1"
},
{
"chave": "mensagem da impressora",
"value": "Promoções com limites 1"
},
{
"chave": "TLOGMessage",
"value": "Promoções com limites 1"
},
{
"chave": "método de aplicação",
"valor": "currículo"
},
{
"chave": "Método de rateio",
"valor": "proporcional"
},
{
"chave": "aplicativoPriceType",
"valor": "preço-benefício"
},
{
"chave": "hasLimit",
"valor": "verdadeiro"
},
{
"chave": "nome",
"valor": "62867033c9512b0184381178"
},
{
"chave": "quantia",
"valor": "300"
},
{
"chave": "unidade",
"valor": "quantidade"
},
{
"chave": "prorataBCP",
"valor": "falso"
},
{
"chave": "valor de recuperação",
"valor": "0"
},
{
"chave": "tipo de recuperação",
"valor": ""
}
],
"elementos aplicados": {
"use-set": {"nome": "62867340c9512b01843811b5"}
}
}
}
}
]
}
6. Importando o json do POSTMAN:
Resultado:
Promoção importada e criada com sucesso:
Tipo, subtipo e Forma de Aplicação
O Promo suporta tanto pelo serviço Rest quanto pela importação de promoções em xml, importando promoções com tipo, subtipo e forma de aplicação.
Ex:
json:
{
"companyId": "napse",
"promotions": [{
"operation": "I",
"name": "Promo Import4",
"code": "Promo Import4",
"promotionType": "type 1",
"promotionSubType": "type 1",
"promotionApplicationForm": "type 1",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "6324b5f8be13d734e87ccc14 ",
"tipo": "item"
}
},
"condição":{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "6324b5f8be13d734e87ccc14"
}
},
"benefits": {
"benefit": {
"instance": "PercentageDiscount",
"parameter": [{
"key": "displayMessage",
"value": "promo import"
},
{
"key": "printerMessage" ,
"value": "promo import"
},
{
"key": "TLOGMessage",
"value": "promo import"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
" chave":"prorationMethod",
"value": "proporcional"
},
{
"key": "applicationPriceType",
"valor": "preço-benefício"
},
{
"chave": "nome",
"valor": "6324b5a1be13d734e87ccc0e"
},
{
"chave": "percent",
"valor": "10"
},
{
"chave ": "unit",
"value": "qty"
},
{
"key": "prorateBCP",
"value": "false"
},
{
"key": "recoveryValue",
"value": "0"
} ,
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"nome": "6324b5f8be13d734e87ccc14"
}
}
}
}
}]
}
Do carteiro:
Promoção importada e criada com sucesso:
Serviço de importação de promoção com atributos de cabeçalho desativados
É possível inserir promoções, quando os atributos do header estiverem desabilitados e inativos, no console:
POR EXEMPLO. json:
{
"companyId": "napse",
"promotions": [
{
"no": "",
"name": "promoIT1",
"code": "",
"className": "com.synthesis.promo.engine. promotion.ModularPromotion",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "627b93e926a51910c877b0e5",
"type": "item",
"attribute" : "código",
"comparador": "Into",
"value": "1234"
}
},
"combo": {
"combo-component": {
"min": "1",
"max": "4",
"attribute": "qty",
"use-set": "627b93e926a51910c877b0e9"
}
},
"benefits": {
"benefit": {
"instance": "FixedDiscount",
"nro": "627b953326a51910c877b0f1",
"parameter": [
{
"key": "displayMessage ",
"value": "Bug305863-Limite_71-47440-47573"
},
{
"key": "printerMessage",
"value": "Bug305863-Limite_71-47440-47573"
},
{
"key": "TLOGMessage",
"value": "Bug305863-Limite_71-47440-47573"
},
{
"key": "applicationMethod",
"value": "lineByLine"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "original -preço"
},
{
"chave": "hasLimit",
"valor": "verdadeiro"
},
{
"chave": "nome",
"valor": "627b939926a51910c877b0e4"
},
{
"chave": "quantia",
"valor": "1000"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "recoveryValue",
"value": "100"
},
{
"key": "recoveryType",
"value": " p"
},
{
"chave": "margem de gasto",
"valor": "1"
},
{
"chave": "prorateBCP",
"valor": "falso"
}
],
"applied-elements": {
"use-set": {"name": "627b93e926a51910c877b0e9"}
},
"escalonado": {
"unit": "qty",
"staggeredStep": [
{
"no": "627b947426a51910c877b0ed",
"min": "1",
"max": "1",
"applyValue": "50000"
},
{
"number": "627b949c26a51910c877b0f0",
"min": "4",
"max": "4",
"applyValue": "1000"
}
]
}
}
},
"operação":"eu"
}
]
}
Do carteiro:
Promoção importada e criada com sucesso:
Se os atributos de cabeçalho estiverem ativados e habilitados:
a promoção foi importada e criada corretamente:
Se os atributos do cabeçalho forem apenas obrigatórios, mas não ativos, a promoção é importada e criada corretamente:
Porém os atributos não serão mostrados na Promoção:
Finalmente, você pode importar promoções cujos atributos de cabeçalho estão ativos, mas não são obrigatórios:
importado e criado com sucesso:
Neste caso os campos serão criados vazios:
Serviço de Exclusão de Datas para não ser executada uma promoção
Serviço que permite configurar a exclusão de determinadas datas durante todo o período de vigência para que NÃO seja realizada uma promoção por agência. Esta opção permitirá controlar que em determinadas datas (que são dias especiais) não se apliquem as promoções que tenham produtos que participem nesses dias.
Este método, acessível a partir de api/rest/catalogs, é responsável por retornar em formato JSON as datas em que as promoções devem ser excluídas e nas lojas informadas solicitadas através da ação POST.
http:// {{SERVER}} : {{PORT}} /promo/api/rest/catalogs
Ex:
http://localhost:8080/promo/api/rest/catalogs
O formato do serviço será:
| Campo | exemplos | Tipo de dados | Detalhe |
| ID da empresa | cochilo | alfanumérico | Código da Empresa - Obrigatório |
| Catálogo | Lista | Lista de limites - Obrigatório | |
| parâmetros | [ ] | Lista | Parâmetros Adicionais - Obrigatório |
| storeCode | cochilo | alfanumérico | Código da Loja - Obrigatório |
| promoçãoNomes | teste promocional | alfanumérico | Nome da promoção que será excluída para a loja e data indicada. Não é obrigatório para a operação R , apenas nos casos em que você deseja eliminar todas as exclusões de dias específicos, este campo pode ser deixado em branco, ou seja "", indicando que todas as exclusões de promoções nas datas indicadas serão ser removido. |
| datas de exclusão | ["2022-07-21", "2022-07-22"] | lista de datas | Datas em que a promoção será excluída, cada data deve seguir o formato "ano-mês-dia" - Obrigatório |
| cirurgia | você | alfanumérico | Identifica o tipo de operação a realizar para cada limite a processar (obrigatório), entre as opções disponíveis encontram-se:
|
Ex:
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "napse",
"promotionName": "Promo 001",
"exclusionDates" : ["2022-07-25","2022-07-27","2022-07-29"],
"operação": "I" //Tipo de operação associada a I (inserir), U (atualizar) e R (remover)
},
{
"storeCode": "napse",
"promotionName": "Promo 002",
"exclusionDates":["2022-07-21"],
"operação": "U"
},
{
"storeCode": "napse",
"promotionName": "Promo 002",
"exclusionDates": ["2022-07-21"],
"operação": "R"
}
]
}
Formato de uma exclusão com operação I
O json a seguir representa o formato para registrar novas exclusões de promoção por data para uma loja e promoção específica.
- Observe que no campo excludeDates você só pode indicar dados de data no formato "ano-mês-dia"
- Só serão criadas as exclusões com as datas que forem válidas, ou seja que tenham o formato do ponto anterior e que não sejam inferiores à data atual.
- Caso a promoção para a qual serão processadas as exclusões tenha uma validade definida (Data Inicial e Data Final), as datas incluídas no campo excludeDates devem estar dentro da faixa de validade da promoção, caso contrário as exclusões fora da validade serão ignoradas, criando apenas as exclusões nas datas que estiverem dentro da validade.
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "napse",
"promotionName": "Promo 001",
"exclusionDates" : ["2022-07-25","2022-07-27","2022-07-29"],
"operação": "I"
}
]
}
Formato de uma exclusão com operação U
O processo de atualização da exclusão de promoções por data, considera os pontos indicados para a operação I, tendo apenas as seguintes particularidades:
- O processo de atualização incorporará novos cadastros de datas de exclusão da promoção desde que não haja mais cadastro anterior para aquela mesma promoção, loja e data.
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "napse",
"promotionName": "Promo 001",
"exclusionDates" : ["2022-07-25"],
"operação": "U"
}
]
}
Limite o formato com a operação R
O processo de remoção de exclusões contempla dois casos:
1- Quando desejar remover a exclusão de uma promoção em uma data específica , deverá indicar o seguinte formato.
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "napse",
"promotionName": "Promo 001",
"exclusionDates" : ["2022-07-25"],
"operação": "R"
}
]
}
Quando pretender eliminar a exclusão de todas as promoções numa determinada data , deverá indicar o seguinte formato.
- A diferença com o formato anterior é que o valor do campo promotionName é deixado como uma string vazia igual a ""
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "napse",
"promotionName": "",
"exclusionDates": [ "2022-07-25"],
"operação": "R"
}
]
}
Resposta do serviço
Se a solicitação for bem-sucedida, a seguinte resposta pode ser exibida (Interface Rest):
Solicitação bem-sucedida
{
"status": "200",
"description": "CatalogExclusionDates",
"detail": {
"result": "ok",
"detail": "Log de importação gerado com sucesso. Você pode visualizar seu status correspondente em o monitor de importação."
}
}
No caso de indicar uma empresa que não existe, será apresentada a seguinte resposta
Erro com a empresa indicada
{
"status": "400",
"description": "CatalogExclusionDates",
"detail": {
"result": "error",
"detail": "Teste de código da empresa não pertence a uma empresa existente. "
}
}
SERVIÇO DE TROCA DE PONTOS POR CATÁLOGO
(Desde 6.5.2)
Como suporte ao novo benefício de Resgate de Pontos por Catálogo (vide acima), a tabela de produtos que possuem pontos equivalentes deve ser especificada através de um catálogo definido para tal utilização.
Seguindo o formato especificado acima teremos:
| Campo | Valor |
|---|---|
| ID da empresa | O código da empresa correspondente. |
| Catálogo | "Benefício de Resgate do Catálogo." Não deve ser modificado. |
parâmetros | Uma lista vazia. Não deve ser modificado. |
| Unid | Uma lista com cada item do catálogo de Resgate de Pontos . |
Dentro dos itens, o formato é:
| Campo | Valor |
|---|---|
loja | Código da loja. Obrigatório. Alfanumérico. Caso se aplique a todas as lojas, o código da loja deve ser "-". |
código | Código do produto. Obrigatório. Alfanumérico. |
pontos | Pontos necessários. Numérico com decimais. |
valor de desconto | Valor do desconto. Numérico com decimais. |
tipo de desconto | Tipo de desconto. Aceita apenas os valores " perc" (porcentagem), "fix" (desconto fixo) ou "nprice" (novo preço) |
cirurgia | A operação a ser executada no elemento. Consulte a tabela com os valores possíveis. |
Assim teremos um exemplo de requisição para inserção de registros neste catálogo será:
{
"companyId": "napse",
"catalog": "CatalogRedeemBenefit",
"params": [],
"items": [
{
"store": "1",
"code": "10",
"points": "10.5",
"discountValue":"15" ,
"discountType": "perc",
"operation": "I"
},
{
"store": "1",
"code": "20",
"points": "20.5",
"discountValue":"20" ,
"discountType": "fix",
"operation": "I"
},
{
"store": "-",
"code": "30",
"points": "50",
"discountValue":"25" ,
"discountType": "nprice",
"operation": "I"
}
]
}
Serviço de atribuição de itens de fidelidade
Esta operação equivale à função de atribuição/actualização de elementos, acrescida da importação de novos clientes (Ver processo de atribuição de contratos em vigor). Neste caso os campos serão:.
CESSÃO A UM ELEMENTO DE UM CLIENTE, UM CONTRATO E SEU VALOR.
Esta operação realiza a atribuição de elemento, cliente, contrato e valor. O elemento deve existir previamente (ativo ou inativo), um contrato ativo, e o cliente, caso não exista, é cadastrado. Em relação ao valor pode ser atribuído um valor, inserindo o valor do valor; adicione um valor ao valor que o item possui, especificando o operador +; e no caso de subtração de saldo, deve ser especificado o operador - (veja o exemplo do campo valor abaixo).
Um esquema de exemplo é o seguinte:
{
"companyId": "napse",
"catalog": "CatalogCardAssign",
"params": [
{
"cardType": "type1"
},
{
"contract": "agreement1"
}
],
"items": [
{
" operação": "I",
"id": "1111000000030",
"cliente": "codCliente1",
"valor": "90,37",
"nome": "Juan",
"sobrenome": "Perez",
"gender": "hom",
"birthDate": "19900506",
"idType": "dni",
"identifier": "33334444",
"idDate": "21001005",
"nacionalidade": "Argentina",
"email": "[email protected]",
"customerType": "gold",
"address": "Urquiza 20",
"country": " ar",
"estado": "bsas",
"cidade": "tig",
"postalCode": "7669",
"telefone": "2222-4444"
}
,{outro item.......}
, {another item......}
,{another item......}
,{another item.......}
,{another item......}
,{another item.......}
]
}
Campos em negrito são obrigatórios.
| Campo | Descrição |
|---|---|
| parâmetros | cardType: Tipo de elemento de fidelidade a importar que será validado. contract: código do contrato a que pertencem estes elementos/clientes. |
cirurgia | I: Inserir / U: Atualizar / R: Excluir |
eu ia |
|
cliente |
|
quantia |
|
inhame | Nome do cliente. Corrente livre. |
sobrenome | Sobrenome. Corrente livre. |
gênero | Gênero. (consulte valores por catálogo). Depende dos valores carregados no catálogo para esse fim. |
data de nascimento | Data de nascimento. String no formato "aaaaMMdd". Mais informações sobre o formato |
idType | Tipo de identificação (consulte valores por catálogo). Depende dos valores carregados no catálogo para esse fim. |
identificador | Número de identificação do cliente |
idData | Data de vencimento da identificação. String no formato "aaaaMMdd". Mais informações sobre o formato |
nacionalidade | Nacionalidade. Cadeia Livre. |
Endereço de email. Corrente livre. | |
Tipo de Cliente | Tipo de Cliente (consulte valores por catálogo). Depende dos valores carregados no catálogo para esse fim. |
endereço | Endereço. corrente livre |
país | País. (consulte valores por catálogo). Depende dos valores carregados no catálogo para esse fim. |
status | Estado/Província (consulte valores por Catálogo). Depende dos valores carregados no catálogo para esse fim. |
cidade | Cidade (consulte valores por catálogo). Depende dos valores carregados no catálogo para esse fim. |
Código postal | Código postal |
Telefone | Telefone |
Atribuição de exemplo
Tendo em conta que existe um contrato ativo com o código c1, e que existe um elemento existente, com o código 1234000000000, e que pertence ao tipo de elemento código verão, o referido contrato, o valor de 100, e um novo cliente são atribuído ao elemento. Como não existe, fica registrado no banco de dados.
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCardAssign",
"params": [
{"cardType": "summer"},
{"contract": "c1"}
],
"itens" : [{
"operação": "I",
"id": "1234000000000",
"cliente": "emc",
"valor": "100",
"nome": "Eugenia",
"sobrenome": "Molina" ,
"gender": "M",
"birthDate": "19900101",
"idType": "dni",
"identifier": "77778888",
"idDate": "20500101",
"nationality": "Argentina",
"email": "[email protected]",
"customerType": "vip",
"endereço": "Urquiza 5050",
"país": "ar",
"estado": "bsas",
"cidade": " tig",
"código postal": "4433",
"telefone": "2222-9999"
}]
}
aumento de saldo
Para aumentar o saldo do elemento, um operador + é especificado com o valor a ser adicionado. Seguindo o exemplo anterior, onde o item tinha um saldo de 100, 50 é adicionado a ele neste exemplo. Após esta operação o saldo resultante será de 150.
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCardAssign",
"params": [
{"cardType": "summer"},
{"contract": "c1"}
],
"itens" : [{
"operação": "I",
"id": "1234000000000",
"cliente": "emc",
"valor": "+50",
"nome": "Eugenia",
"sobrenome": "Molina ",
"gender": "M",
"birthDate": "19900101",
"idType": "dni",
"identifier": "77778888",
"idDate": "20500101",
"nationality": "Argentina",
"email": "[email protected]",
"customerType": "vip",
"endereço": "Urquiza 5050",
"país": "ar",
"estado": "bsas",
"cidade": " tig",
"código postal": "4433",
"telefone": "2222-9999"
}]
}
diminuição do saldo
Semelhante ao incremento. Para subtrair saldo, use o operador - e depois o valor da quantia a ser subtraída. Se o item anteriormente tinha 150, subtraindo 20 deixa o valor 130.
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCardAssign",
"params": [
{"cardType": "summer"},
{"contract": "c1"}
],
"itens" : [{
"operação": "I",
"id": "1234000000000",
"cliente": "emc",
"valor": "-20",
"nome": "Eugenia",
"sobrenome": "Molina ",
"gender": "M",
"birthDate": "19900101",
"idType": "dni",
"identifier": "77778888",
"idDate": "20500101",
"nationality": "Argentina",
"email": "[email protected]",
"customerType": "vip",
"endereço": "Urquiza 5050",
"país": "ar",
"estado": "bsas",
"cidade": " tig",
"código postal": "4433",
"telefone": "2222-9999"
}]
}
Transferência de saldo.
Uma transferência de saldo pode ser total, quando todo o valor é transferido, ou parcial, se apenas parte do valor é trocado. No caso de uma transferência total, é necessário considerar a exclusão do primeiro elemento de fidelidade, do qual o valor é obtido.
Para realizar uma transferência de saldo, tanto o elemento de origem (aquele que dá saldo) quanto o elemento de destino (aquele que recebe saldo) devem ser do mesmo tipo.
No seq=1 enviado pelo PDV, será informado o elemento fonte, ou seja, de quem serão deduzidos os pontos, dinheiro, milhas, etc.
No seq=2 enviado pelo PDV, será informado o elemento destino, ou seja, aquele que receberá os pontos, dinheiro, milhas, etc.
(Veja também o Manual do Usuário, "Conceitos do Cartão Fidelidade" para mais detalhes sobre os diferentes tipos de transferências possíveis)
transferência parcial
Já tendo um elemento de código 2345000000000 com valor de 100 e 2345000000001 com valor de 25, 50 de valor é transferido para o segundo elemento. O resultado é que o elemento 2345000000000 ficará com 50 de valor, e o segundo 2345000000001 com 75. O tipo de elemento, inverno, especifica que a transferência é parcial.
Ao operar com carteiro, como a mensagem correspondente estará no formato xml, o cabeçalho do tipo de conteúdo terá o valor application/xml ao invés de application/json.
Leve em consideração que a url muda para fazer esta operação, pois ela interage com o motor. O valor que aparece à direita de avaliar, no endereço, é preenchido automaticamente pelo carteiro. O corpo da mensagem (corpo) terá que estar vazio. As mensagens serão enviadas como parâmetro no endereço. Este parâmetro é solicitado. Separe o valor com dois pontos. Para facilitar a entrada de dados, clique em edição em massa (à direita da solicitação), que muda para edição de valor-chave. O valor do parâmetro request é o xml a ser enviado ao motor, que não deve ter espaços entre as tags.
A resposta mostra como esses cartões ficariam se a operação fosse confirmada. A operação é confirmada com a mesma mensagem, mas com o atributo de status definido como "commit" em vez de "loyaltyTransfer" ou "rollback" para cancelar.
Ao confirmar a operação....
A alteração será refletida no console.
Registo do Elemento Fidelização associado ao cliente identificado na transação (no momento da aplicação do benefício de acumulação)
Para a atribuição e carregamento de um elemento de fidelização que acumule autocolantes, deve ser considerada a seguinte sequência entre o pos e o Promo:
- Pré requisitos:
Para que os clientes sejam cadastrados no momento do processamento de uma transação, o seguinte atributo deve estar habilitado no arquivo de configuração do Promo Console (“ momoplus.properties ”):
# Permite o registro do cliente em tempo real promo.allowNonExistingCustomers = verdadeiro |
Depois de atualizado, o Wildfly deve ser reiniciado para que as alterações sejam feitas corretamente.
- Cadastro de cliente
Os clientes serão criados usando o status " LealityValidation " no caso de enviar os dados mínimos e ao mesmo tempo Promo detectar que o cliente não existe. Os dados mínimos mencionados são (marcados em vermelho):
<customer-add seq="1" id="10090504" identifier="10090504" tipo ="test" de nome ="pepe" último ="rodrigues" identificador de nome ="cpf" e-mail tipo ="mimail@test.com" />
Entrada
Entrada
|
Na resposta à validação de fidelidade, nenhum cartão será informado, pois o cliente acabou de entrar no console Promo.
Saída
|
entrada de item
Entrada
|
Promoção que aplica pontos aos Stickers Um elemento Output é retornado
|
Uma vez que o cliente não tem elementos associados, deverá registar um número no Promo. elemento do mesmo tipo que recebe o benefício informado, e associá-lo ao cliente.
OBSERVAÇÃO
Os benefícios do tipo Lealdade que informam a palavra “ externo ” em seu tipo (“ tipo ”) , corresponderão a tipos de elementos não administrados por promo, que não participam de Stickers.
Atualização: O status “loyaltyActivation” será utilizado para cadastrar elementos durante a transação, enviando na tag <loyaltyCard-add/> o parâmetro status=”CREATE”, o campo Tipo da mesma tag deve corresponder ao tipo de elemento que está sendo beneficiado durante a transação, devendo ser indicado no campo id o número do elemento a ser atribuído.
Este número não tem necessariamente que corresponder ao comprimento e prefixo indicados no tipo de elemento, pode-se indicar um código livre e verificar-se-á que para o referido tipo de elemento não existem dois números iguais de elementos.
Entrada
|
|
Esta operação não requer FINISH ou COMMIT.
Para confirmar a associação correta, deve-se realizar uma LoyaltyValidation do cliente e aqui deve-se modificar o TimeStamp da transação para que os pontos atribuídos posteriormente pelo benefício sejam corretamente atribuídos ao elemento recém-criado.
Entrada
|
Saída
|
Uma vez que o cliente já tenha o elemento associado e ativo, pode entrar na transação para atribuir os pontos atribuídos ao benefício.
Entrada
|
Saída
|
Entrada
|
Saída
|
Entrada
|
Saída
|
Entrada
|
Saída
|
Para confirmar a correta imputação, pode ser efetuada uma LoyaltyValidation do cliente e/ou elemento e verificados os dados.
Entrada
|
Saída
|
Após o fechamento da transação, o novo elemento criado com o saldo atribuído pode ser visualizado no console Promo.
Serviço de Importação de Segmentos
(v 6.5) Síncrono
Serviço de rest que opera de forma síncrona para gerenciar clientes associados a segmentos.
Uma vez obtido o token de acesso, o serviço pode ser invocado usando o método POST, a partir da URL: <promo> /api/rest/segments
Serviço de administração de elementos de fidelidade
Serviço de rest que opera de forma síncrona para gerenciar elementos de fidelidade.
Uma vez obtido o token de acesso, o serviço pode ser invocado usando o método POST, a partir da URL: <promo>/api/rest/cards/admin **
O formato de resposta geral é:
{
"status": 200,
"description": "rest::cardAdmin",
"transactionId": "SVC_CRD_20230814181744",
"detail": {
"result": "ok",
"detail": "",
"updated": 0,
"ignored": 0,
"inserted": 5,
"removed": 0,
"errors": 3,
"processed": 8,
"errorDetails": [
{
"rec": 1,
"code": "9520",
"info": null
},
{
"rec": 5,
"code": "9520",
"info": null
},
{
"rec": 8,
"code": "9520",
"info": null
}
],
"successDetails": [
{
"rec": 2,
"code": "1010000000",
"amount": "150.0"
},
{
"rec": 3,
"code": "2010000001",
"amount": "50.0"
},
{
"rec": 4,
"code": "7010000000",
"amount": "1000.0"
},
{
"rec": 6,
"code": "1300000001",
"amount": "100.0"
},
{
"rec": 7,
"code": "7000000000",
"amount": "1000.0"
}
]
}
}
A resposta informa sobre o Id da transação:
E o amount do elemento de fidelidade:
2. Foi solicitado alterar o saldo do cartão 1000000010 com 1000.
{
"companyId": "2",
"params": [{"oneActiveCardByCustomer":"false", "validatedCard":"true"}],
"items": [
{ "operation": "AMOUNT_UPDATE", "code": "1000000010", "type": "1", "validFrom":"", "validTo":"", "amount":"1000.00", "customerId":"", "cvv":"", "reason":"" }
]
}
{
"status": 200,
"description": "rest::cardAdmin",
"transactionId": "SVC_CRD_20230814182939",
"detail": {
"result": "ok",
"detail": "",
"updated": 1,
"ignored": 0,
"inserted": 0,
"removed": 0,
"errors": 0,
"processed": 1,
"errorDetails": [],
"successDetails": [
{
"rec": 1,
"code": "1000000010",
"amount": "2000.0"
}
]
}
}
3. Foi solicitado consumir 30 do cartão "1010000000":
{
"companyId": "2",
"params": [{"oneActiveCardByCustomer":"false", "validatedCard":"true"}],
"items": [
{ "operation": "CONSUME", "code": "1010000000", "type": "1", "validFrom":"", "validTo":"", "amount":"30.00", "customerId":"", "cvv":"", "reason":"" }
]
}
{
"status": 200,
"description": "rest::cardAdmin",
"transactionId": "SVC_CRD_20230814183317",
"detail": {
"result": "ok",
"detail": "",
"updated": 1,
"ignored": 0,
"inserted": 0,
"removed": 0,
"errors": 0,
"processed": 1,
"errorDetails": [],
"successDetails": [
{
"rec": 1,
"code": "1010000000",
"amount": "120.0"
}
]
}
}
É possível observar que agora o cartão tem um saldo de 120, quando inicialmente tinha 150.
4. Foi solicitado recarregar 30 no cartão "4200000002"
{
"companyId": "2",
"params": [{"oneActiveCardByCustomer":"false", "validatedCard":"true"}],
"items": [
{ "operation": "RECHARGE", "code": "4200000002", "type": "6", "validFrom":"", "validTo":"", "amount":"30.00", "customerId":"", "cvv":"", "reason":"" }
]
}
{
"status": 200,
"description": "rest::cardAdmin",
"transactionId": "SVC_CRD_20230814183628",
"detail": {
"result": "ok",
"detail": "",
"updated": 1,
"ignored": 0,
"inserted": 0,
"removed": 0,
"errors": 0,
"processed": 1,
"errorDetails": [],
"successDetails": [
{
"rec": 1,
"code": "4200000002",
"amount": "1180.0"
}
]
}
}
5. Foi solicitado carregar 1000 no cartão "7000000000"
{
"companyId": "2",
"params": [{"oneActiveCardByCustomer":"false", "validatedCard":"true"}],
"items": [
{ "operation": "CHARGE", "code": "7000000000", "type": "7", "validFrom":"", "validTo":"", "amount":"1000.00", "customerId":"", "cvv":"", "reason":"" }
]
}
{
"status": 200,
"description": "rest::cardAdmin",
"transactionId": "SVC_CRD_20230814184411",
"detail": {
"result": "ok",
"detail": "",
"updated": 1,
"ignored": 0,
"inserted": 0,
"removed": 0,
"errors": 0,
"processed": 1,
"errorDetails": [],
"successDetails": [
{
"rec": 1,
"code": "7000000000",
"amount": "2000.0"
}
]
}
}
6. Foi solicitado cancelar o cartão "7000000000"
{
"companyId": "2",
"params": [{"oneActiveCardByCustomer":"false", "validatedCard":"true"}],
"items": [
{ "operation": "CHARGE", "code": "7000000000", "type": "7", "validFrom":"", "validTo":"", "amount":"1000.00", "customerId":"", "cvv":"", "reason":"" }
]
}
{
"status": 200,
"description": "rest::cardAdmin",
"transactionId": "SVC_CRD_20230814184627",
"detail": {
"result": "ok",
"detail": "",
"updated": 1,
"ignored": 0,
"inserted": 0,
"removed": 0,
"errors": 0,
"processed": 1,
"errorDetails": [],
"successDetails": [
{
"rec": 1,
"code": "7000000000",
"amount": "2000.0"
}
]
}
}
onde
Campo | Descrição | Tipo de Dados |
|---|---|---|
transactionId | Id da transação | string |
status | Código de resposta | 200 indica que foi processado com sucesso. |
| detail.updated | Quantidade de itens atualizados | inteiro |
| detail.successDetails | Detalhe de cada registro processado corretamente | rec: Numero de registro na solicitação code: código do elemento. amount: saldo do elemento de fidelidade |
| detail.result | Resultado geral do processo | ok indica processo realizado |
| detail.removed | quantidade de itens removidos | inteiro |
| detail.processed | quantidade de itens processados | inteiro |
| detail.inserted | quantidade de itens adicionados | inteiro |
| detail.ignored | quantidade de itens ignorados | inteiro |
| detail.errors | quantidade de itens com erro | inteiro |
| detail.errorDetails | Detalhe de cada registro com erro | rec: numero de registro na solicitação code: código de erro. Ver lista de erros em Manual de Integração - Motor 7.2, info: mensagem informativa do erro, pode devolver NULL. |
| detail.detail | Mensagem detalhada sobre o processo | vazio no caso de ok |
| detail | Detalhe do processo | array |
| description | Descrição geral | Fixo "rest::cardAdmin' |
Os resultados destas operações podem ser vistas no Console em: Menu/ Fidelidade/ Elementos de Fidelidade.
Serviço de Administração de Cupons
Criar, ativar e resgatar cupons
Serviço Rest que opera de forma síncrona para gerenciar Cupons.
Uma vez obtido o token de acesso, o serviço pode ser invocado usando o método POST, a partir da URL: <promo>/api/rest/coupons/admin **
Serviço de Administração de Clientes
Criar, Modificar e Eliminar Clientes e Criação automática de elementos de fidelização associados
O serviço síncrono de rest do cliente (cadastro, cancelamento e alteração) também cria e associa elementos (o número do elemento é gerado com o prefixo mais o identificador do cliente).
Até 100 clientes podem ser gerados.
Usando o método POST :
http://localhost:8072/promo/api/rest/customer
O campo "autoCard" conterá um tipo de elemento, que caso o cliente não possua será criado.
Este elemento seguirá a definição do seu tipo, mas no número atribuirá o número do documento do cliente, além do prefixo e comprimento da numeração.
Se o elemento existir, ele não será criado. Se criado, respeita o saldo inicial, vencimentos e todos os dados definidos no tipo de elemento. É associado ao cliente no mesmo acto em que é criado.
{
"companyId": "napse",
"catalog": "CatalogCustomer",
"params": [],
"itens": [
{ "code": "codigo32", "name": "Ricardo", "lastName": "Pérez", "gender": "m", "birthDate": "2012-04-23", "identificationType": " dni", "identifier": "28710943", "identificationExpiration": "2050-01-01", "nacionality": "arg", "email": "[email protected]", "customerType": "EMPLOYEE" , "address": "diagonal 12 2233", "addressCountry": "arg", "addressState": "bsas", "addressCity":"tig", "addressPostalCode": "22223", "phone": "1111111123", "isActive": "true", "operation": "U", "autoCard":"cardType1" }
,
{ "code": "codigo33", "name": "Ricardo", "lastName": "Pérez", "gender": "m", "birthDate": "2012-04-23", "identificationType": " dni", "identifier": "28710944", "identificationExpiration": "2050-01-01", "nacionality": "arg", "email": "[email protected]", "customerType": "EMPLOYEE" , "address": "diagonal 12 2233", "addressCountry": "arg", "addressState": "bsas", "addressCity":"tig", "addressPostalCode": "22223", "phone": "1111111123", "isActive": "true", "operation": "I", "autoCard":"cardType2" }
,
{ "code": "codigo34", "name": "Ricardo", "lastName": "Pérez", "gender": "m", "birthDate": "2012-04-23", "identificationType": " dni", "identifier": "28710944", "identificationExpiration": "2050-01-01", "nacionality": "arg", "email": "[email protected]", "customerType": "EMPLOYEE" , "address": "diagonal 12 2233", "addressCountry": "arg", "addressState": "bsas", "addressCity":"tig", "addressPostalCode": "22223", "phone": "1111111123", "isActive": "true", "operation": "I", "autoCard":"cardType2" }
,
{ "code": "codigo35", "name": "Ricardo", "lastName": "Pérez", "gender": "m", "birthDate": "2012-04-23", "identificationType": " dni", "identifier": "28710945", "identificationExpiration": "2050-01-01", "nacionality": "arg", "email": "[email protected]", "customerType": "EMPLOYEE" , "address": "diagonal 12 2233", "addressCountry": "arg", "addressState": "bsas", "addressCity":"tig", "addressPostalCode": "22223", "phone": "1111111123", "isActive": "true", "operation": "U", "autoCard":"cardType1" }
]
}
Serviço de Administração de Limites
Criar, Modificar e Eliminar Limites de Promoções por Lojas
Você pode registrar limites maciços via api rest. O Json neste caso será:
{
"companyId":"napse",
"limits": [
{
"operation":"I",
"promotionName":"Limites promocionais 3",
"benefitId": "62d575e6c1ac1f2fe0707033",
"limitId": "",
"limitScope ":"VAREJISTA",
"storeCode": "",
"description": "",
"limitPeriod":"DAY",
"numberDays":"2",
"limitTypeCode": "benefiedProductCount",
"value": "4 "
},
{
"operation":"I",
"promotionName":"Limites da promoção 3",
"benefitId": "62d575e6c1ac1f2fe0707033",
"limitId": "",
"limitScope":"STORE",
"storeCode": "napse",
"description": "",
"limitPeriod":"DAY",
"numberDays":"5",
"limitTypeCode": "benefiedProductCount",
"value": "2"
}
]
}
{
"companyId":"napse",
"limits": [
{
"operation":"U",
"limitId": "62d57724c1ac1f2fe0707038",
"limitScope":"RETAILER",
"storeCode": "",
"description": "",
"limitPeriod":"DAY",
"numberDays":"2",
"limitTypeCode": "benefiedProductCount",
"value": "5"
}
]
}
{
"companyId":"napse",
"limits": [
{
"operation":"R",
"limitId": "62d57724c1ac1f2fe0707038"
}
]
}
Toda vez que um Json com limites para promoções for executado, isso gerará um registro de importação, cujo status será visível no Monitor de Suporte/Importação.