<style>
.div-1 {
background-color: #EBEBEB;
}
</style>
<div class="div-1"> <h1 style="font-size:200%">[/identification/forms]</h1> </div>
|
Retorna a forma de identificação do cliente Descrição: Essa API retorna as formas de identificação do cliente para o parceiro de bônus cadastrado.
A partir desse retorno deverá ser criada uma interface para identificar o cliente no parceiro de bônus. Caso o cliente já tenha sido identificado no PDV os campos podem ser carregados automaticamente. Campos Obrigatórios - partnerCode (String):
- Parâmetro que é o Código do parceiro Bônus.
- Deve ser armazenado em memória para usar nas próximas chamadas do processo de venda com bônus.
Detalhes do Response:- nextStep (String):
- Devolve o próximo passo a ser realizado pelo PDV no processo de bônus.
Valores de retorno:"identification","authentication","bonus","campaign","finalize", ao receber um desses valores o PDV deverá chamar a próxima API correspondente no momento correto da venda.
- customerText (String):
- Texto a ser apresentado ao cliente quando o sistema utilizar layout com tela secundária. Este campo pode ou não ser retornado dependendo do parceiro de bônus utilizado.
- operatorText (String):
- Texto a ser apresentado ao operador na montagem da interface de identificação do cliente. É neste campo que o parceiro poderá customizar os textos informativos que deseja aparecer na tela dos fluxos das API’s. Como exemplo: “Solicite os dados do cliente”, “Digite e confirme os dados necessário para a identificação do cliente para o programa bônus”, etc.
- identificationForms (String):
- Retorna uma lista de campos para identificação do cliente exigida pelo parceiro de bônus.
Detalhes do IdentificationForms:- isIdentificationCode (Lógica/Booleana):
- Define se este campo é de identificação única pelo parceiro de bônus. Deve ser armazenado em memória para usar nas próximas chamadas do processo de venda com bônus.
-
type - “Phone” (String):
- Somente números, sem máscara, sem DDI, DDD com dois dígitos sem Zero. Exemplo: 11988887777
- “name” (String):
- “email” (String):
- “birth” (String):
- Formato aaaa-mm-dd Exemplo: 2000-01-25
- “cpf” (String):
- Somente números, sem máscara.
- “gender” (String):
- "operatorText" (String):
- Texto a ser apresentado ao cliente para identificação na interface. Nesta variável, é onde poderá ser customizado os textos informativos conforme a necessidade do parceiro.
- "customerText" (String):
- Texto a ser apresentado ao operador para identificação na interface.
- "required" (Lógica):
- Identifica se o campo será obrigatório ou não no fluxo. Para “False” o campo não será obrigatório e não será exibido, para “True” o campo será obrigatório e será exibido.
- "isPassword" (Lógica):
LEMBRETE: Para todos os campos que são necessários no Response, eles sempre deverão retornar um valor, independente do tipo deles, caso retornem NULL ou outro tipo que não seja o deles, poderá haver conflito no Protheus. |
Exemplo do Json: GET /identification/forms/001
Request:
{}
Response:
{
"partnerCode": "123456789",
"nextStep": "identification",
"customerText": "",
"operatorText": "Solicite e confirme os dados do cliente para o programa de bônus",
"identificationForms": [
{
"isIdentificationCode": true,
"type": "phone",
"operatorText": "Número do celular",
"customerText": "",
"required": true,
"isPassword": true
},
{
"isIdentificationCode": false,
"type": "name",
"operatorText": "Nome",
"customerText": "",
"required": false,
"isPassword": false
},
{
"isIdentificationCode": false,
"type": "email",
"operatorText": "E-mail",
"customerText": "",
"required": false,
"isPassword": false
},
{
"isIdentificationCode": false,
"type": "birth",
"operatorText": "Data de aniversário",
"customerText": "",
"required": false,
"isPassword": false
},
{
"isIdentificationCode": false,
"type": "cpf",
"operatorText": "CPF",
"customerText": "",
"required": false,
"isPassword": false
},
{
"isIdentificationCode": false,
"type": "gender",
"operatorText": "Gênero",
"customerText": "",
"required": false,
"isPassword": false
}
],
"_expandables": []
}
} |
|
<style>
.div-1 {
background-color: #EBEBEB;
}
</style>
<div class="div-1"> <h1 style="font-size:200%">[/identification]</h1> </div>
|
Envia os dados dos clientes e recupera a identificação Descrição: Essa API retorna os dados de identificação do cliente. Campos Obrigatórios - partnerCode (String):
- Parâmetro que é o Código do parceiro Bônus
- Deve ser armazenado em memória para usar nas próximas chamadas do processo de venda com bônus.
Detalhes do Response: - nextStep (String):
- Devolve o próximo passo a ser realizado pelo PDV no processo de bônus.
Valores de retorno:"identification","authentication","bonus","campaign","finalize", ao receber um desses valores o PDV deverá chamar a próxima API correspondente no momento correto da venda.
- customerText (String):
- Texto a ser apresentado ao cliente quando o sistema utilizar layout com tela secundária. Este campo pode ou não ser retornado dependendo do parceiro de bônus utilizado.
- operatorText (String):
- Texto a ser apresentado ao operador na montagem da interface de identificação do cliente. É neste campo que o parceiro poderá customizar os textos informativos que deseja aparecer na tela dos fluxos das API’s.
- identification (String):
- Objeto contendo os dados de identificação do cliente.
- “costumerId” (String):
- Código de identificação do cliente pelo parceiro. Deve ser armazenado em memória para usar nas próximas chamadas do processo de venda com bônus.
- “storeId” (String):
- Código de identificação da loja pelo parceiro. Deve ser armazenado em memória para usar nas próximas chamadas do processo de venda com bônus.
- "authentication" (String):
- Objeto contendo dos dados da autenticação do cliente
- “type” (String):
- Tipo do campo a ser apresentado na interface.
- "pin" - Código de autenticação recebido pelo cliente.
- “code” (String):
- “operatortext” (String):
- Texto a ser apresentado ao operador na montagem da interface de identificação do cliente. É neste campo que o parceiro poderá customizar os textos informativos.
- “customerText” (String):
- Texto a ser apresentado ao cliente para autenticação na interface.
- “isPassword” (Lógica):
- Identifica se o campo deverá ter seu conteúdo oculto na interface.
LEMBRETE: Para todos os campos que são necessários no Response, eles sempre deverão retornar um valor, independente do tipo deles, caso retornem NULL ou outro tipo que não seja o deles, poderá haver conflito no Protheus. |
Exemplo do Json: POST /identification
Request:
{
"externalBusinessUnitId": "001",
"partnerCode": "123456789",
"sale":
{
"netSaleValue": 110.56
},
"identification":
{
"identificationCode": "11988887777",
"document": "94837948030",
"email": "[email protected]",
"name": "Maria da Silva",
"phone": "11988887777",
"birthday": "1990-05-15"
"gender": "masculino",
"operatorCode": "2",
"operatorName": "João de Souza"
}
}
Response:
{
"nextStep": "authentication",
"partnerCode": "123456789",
"customerText": "",
"operatorText": "Solicite os dados para autenticação no programa de Bônus",
"authentication":
{
"type": "pin",
"code": "TOTVS: PIN 4375\n\n",
"operatorText": "Solicite o PIN para o Cliente.",
"customerText": "",
"isPassword": true
},
"identification":
{
"storeId": "100072",
"costumerId": "4399264"
},
"bonus": null,
"_expandables": []
} |
|
<style>
.div-1 {
background-color: #EBEBEB;
}
</style>
<div class="div-1"> <h1 style="font-size:200%">[/identification/authentication]</h1> </div>
|
Envia os dados do cliente para autenticação Descrição: Essa API retorna os dados da autenticação do cliente. Campos Obrigatórios - "partnerCode" (String)
- Parâmetro que é o Código do parceiro Bônus
- Deve ser armazenado em memória para usar nas próximas chamadas do processo de venda com bônus.
Detalhes do Response: Campos Obrigatórios - "nextStep" (String)
- Devolve o próximo passo a ser realizado pelo PDV no processo de bônus.
Valores de retorno:"identification","authentication","bonus","campaign","finalize", ao receber um desses valores o PDV deverá chamar a próxima API correspondente no momento correto da venda.
- "authentication" (String)
- Objeto contendo os dados de autenticação do cliente.
- Todos os campos são do tipo STRING
- “type” (String)
- Identifica se o cliente foi autenticado SIM/NÃO.
- Deve ser armazenado em memória para usar nas próximas chamadas do processo de venda com bônus
- “validatedByException” (String)
- Identifica se o cliente foi validado com o PIN
- Deve ser armazenado em memória para usar nas próximas chamadas do processo de venda com bônus
LEMBRETE: Para todos os campos que são necessários no Response, eles sempre deverão retornar um valor, independente do tipo deles, caso retornem NULL ou outro tipo que não seja o deles, poderá haver conflito no Protheus. |
Exemplo do Json: POST identification/authentication
Request:
{
"externalBusinessUnitId": "001",
"partnerCode": "123456789",
"sale": {
"netSaleValue": 110.56
},
"identification": {
"identificationCode": "11988887777",
"storeId": "100072",
"costumerId": "4399264"
},
"authentication": {
"code": "4375",
"type": "pin"
}
}
Response:
{
"nextStep": "bonus",
"partnerCode": "123456789",
"authentication":
{
"authenticated": true,
"validatedByException": false
}
} |
|
<style>
.div-1 {
background-color: #EBEBEB;
}
</style>
<div class="div-1"> <h1 style="font-size:200%">[/bonus]</h1> </div>
|
Envia os dados da venda e recupera bonificação do cliente. Descrição: Essa API recebe os dados da venda e verifica a bonificação do cliente no Parceiro de bônus.
Com o retorno dessa API poderá ser aplicado o desconto referente ao valor do Bônus no final da venda. Detalhes do Response: - "nextStep" (String)
- Devolve o próximo passo a ser realizado pelo PDV no processo de bônus.
Para esta etapa do fluxo das API’s, o retorno/preenchimento deste campo sempre terá que ser o “campaing” ou “ ”(em branco), caso seja colocado outra etapa do fluxo, acarretará em possíveis inconsistências no Protheus.
- "customerText" (String)
- Texto a ser apresentado ao cliente quando o sistema utilizar layout com tela secundária. Este campo pode ou não ser retornado dependendo do parceiro de bônus utilizado.
- "operatorText" (String)
- Texto a ser apresentado ao operador na montagem da interface de identificação do cliente. É neste campo que o parceiro poderá customizar os textos informativos que deseja aparecer na tela dos fluxos das API’s.
- "bonus"
- Retorna uma lista bônus para o cliente identificado.
- Essa lista que é retornada, não pode ser NULA, todos os campos deverão ao menos vir com valores em branco ou zeradas, mas nunca NULO.
- “type” (String)
- Define o tipo do bônus a ser aplicado.
- “totalDiscount" - Tipo de desconto a ser aplicado na venda
- “validatedByException” (String)
- Identifica se o cliente foi validado com o PIN
- Deve ser armazenado em memória para usar nas próximas chamadas do processo de venda com bônus.
- “bonusAmount” (Numérico)
- Valor do Bônus do cliente.
- “bonusId” (String)
- “partner” (String)
- Campo obrigatório
- Descrição do parceiro de Bônus.
- Deve ser armazenado em memória para usar nas próximas chamadas do processo de venda com bônus.
- “partnerCode” (String)
- Campo obrigatório
- Código do parceiro de Bônus.
- “mandatoryUseBonuses” (Lógico)
- Define se o PDV irá utilizar o bônus automaticamente na venda(True, .T.) ou se irá realizar a pergunta se deseja utilizar o bônus(operatorText|customerText).
- “canDiscountAfterBonus” (Lógico)
- Define se o PDV poderá aplicar outro(s) desconto(s) após ter aplicado o desconto do bônus.
- “canUsePartialBonus” (Lógico)
- Define se o PDV poderá utilizar o valor parcial de bônus.
- “operatorText” (String)
- Texto a ser apresentado ao operador referente à utilização de Bônus na venda.
- “customerText” (String)
- Texto a ser apresentado ao cliente referente à utilização de Bônus na venda.
- “bonusReferenceValue” (Numérico)
- Campo obrigatório
- Valor líquido da venda.
- “bonusMax” (Numérico)
- Valor máximo para resgate de Bônus.
- “bonusMin” (Numérico)
- Valor mínimo para resgate de Bônus.
LEMBRETE: Para todos os campos que são necessários no Response, eles sempre deverão retornar um valor, independente do tipo deles, caso retornem NULL ou outro tipo que não seja o deles, poderá haver conflito no Protheus. |
Exemplo do Json: POST /bonus/
Request:
{
"externalBusinessUnitId": "001",
"partnerCode": "123456789",
"sale": {
"netSaleValue": 99.50,
"items":
[
{
"netSaleValue": 99.50,
"itenID": 1,
"productDescription": "Produto Abc",
"productCode": "123",
"quantityItems": 1,
"grossSaleValue": 110.56
}
],
},
"identification": {
"identificationCode": "11988887777",
"storeId": "100072",
"costumerId": "4399264"
}
}
Response:
{
"nextStep": "campaign",
"customerText": "",
"operatorText": "Selecione um Bônus",
"bonus": [
{
"type": "totalDiscount",
"bonusAmount": 10.73,
"bonusId": "6919173",
"partner": "BONUSXYZ",
"partnerCode": "123456789",
"mandatoryUseBonuses": false,
"canDiscountAfterBonus": true,
"canUsePartialBonus": false,
"operatorText": "O cliente tem BONUS DE R$50,00, deseja utilizar agora?",
"customerText": "",
"bonusReferenceValue": 110.56,
"bonusMax": 30,
"bonusMin": 1
}
]
} |
|
<style>
.div-1 {
background-color: #EBEBEB;
}
</style>
<div class="div-1"> <h1 style="font-size:200%">[/campaign]</h1> </div>
|
Retorna as campanhas disponíveis para o cliente. Descrição: Essa API retorna as campanhas disponíveis para o cliente selecionado. Detalhes do Response: - "nextStep" (String)
- Devolve o próximo passo a ser realizado pelo PDV no processo de bônus. Neste ponto do fluxo, é recomendado continuar seguindo o fluxo padrão,(próxima etapa- “[/bônus/finalize]”), para que não haja conflito dentro do Protheus. Porém dependendo da regra de negócio do parceiro, há a possibilidade de ter outro fluxo.
- "customerText" (String)
- Texto a ser apresentado ao cliente quando o sistema utilizar layout com tela secundária. Este campo pode ou não ser retornado dependendo do parceiro de bônus utilizado.
- "operatorText" (String)
- Texto a ser apresentado ao operador na montagem da interface de identificação do cliente. É neste campo que o parceiro poderá customizar os textos informativos que deseja aparecer na tela dos fluxos das API’s.
- "campaigns" (String)
- Objeto com os dados das campanhas disponíveis para o cliente.
- “Id” (String)
- Código de Identificação da campanha no parceiro. Deve ser armazenado em memória para usar nas próximas chamadas do processo de venda com bônus.
- “description” (String)
- Texto a ser apresentado ao Operador na montagem da interface de identificação do cliente.
- “operatorText” (String)
- Texto a ser apresentado ao Operador na montagem da interface de identificação do cliente.
- “customerText” (String)
- Texto a ser apresentado ao cliente quando o sistema utilizar layout com tela secundária. Este campo pode ou não ser retornado dependendo do Parceiro de Bônus utilizado.
- “futureBonusValue” (Numérico)
- Valor de bônus que será gerado para o cliente após a finalização da venda.
- “startDate” (Date)
- Início da vigência da campanha
- “endDate” (Date)
- Fim da vigência da campanha
LEMBRETE: Para todos os campos que são necessários no Response, eles sempre deverão retornar um valor, independente do tipo deles, caso retornem NULL ou outro tipo que não seja o deles, poderá haver conflito no Protheus. |
Exemplo do Json: Post /campaign
Request:
{
"externalBusinessUnitId": "001",
"partnerCode": "123456789",
"sale": {
"netSaleValue": 99.50,
"items":
[
{
"netSaleValue": 99.50,
"itenID": 1,
"productDescription": "Produto Abc",
"productCode": "123",
"quantityItems": 1,
"grossSaleValue": 110.56
}
],
},
"identification": {
"identificationCode": "11988000044",
"storeId": "010203",
"costumerId": "06030204"
}
}
Response:
{
"nextStep": "finalize",
"customerText": "",
"operatorText": "Selecione uma campanha para o programa de Bônus",
"campaigns": [
{
"id": "5124",
"description": "Fidelidade",
"operatorText": "R$11.06 para a próxima compra",
"customerText": "",
"futureBonusValue": 11.06,
"startDate": "2021-04-07T17:10:40.293Z",
"endDate": "2021-05-09T17:10:40.293Z"
}
} |
|
<style>
.div-1 {
background-color: #EBEBEB;
}
</style>
<div class="div-1"> <h1 style="font-size:200%">[/bonus/finalize]</h1> </div>
|
Envia os dados da venda e finaliza a bonificação do cliente. Descrição: Essa API recebe os dados da venda e finaliza/resgata/baixa/gera a bonificação do cliente no Parceiro de bônus.
Com o retorno dessa API o processo de Consumo/Geração do Bônus é finalizado. Detalhes do Response: - "nextStep" (String)
- Devolve o próximo passo a ser realizado pelo PDV no processo de bônus. Neste ponto do fluxo, o recomendado é continuar seguindo o fluxo padrão,(próxima etapa- “[Order”]), para que não haja conflito dentro do Protheus. Porém dependendo da regra de negócio do parceiro, há a possibilidade de ter outro fluxo.
- "customerText" (String)
- Texto a ser apresentado ao cliente quando o sistema utilizar layout com tela secundária. Este campo pode ou não ser retornado dependendo do parceiro de bônus utilizado.
- "bonusId" (String)
- "partnerSaleId" (String)
- "transactionId" (String)
- Id da transação de bônus realizada.
- "message" (String)
- Mensagem que poderá ser disponibilizada com informações a critério do parceiro.
LEMBRETE: Para todos os campos que são necessários no Response, eles sempre deverão retornar um valor, independente do tipo deles, caso retornem NULL ou outro tipo que não seja o deles, poderá haver conflito no Protheus. |
Exemplo do Json: POST /bonus/finalize
Request:
{
"externalBusinessUnitId": "001",
"partnerCode": "12345678",
"identification": {
"identificationCode": "11955554444",
"storeId": "100072",
"costumerId": "4399264",
"operatorCode": "string",
"operatorName": "string",
"customerDocument": "string"
},
"bonus": {
"bonusId": "6919173",
"bonusAmountUsed": 11.06,
"bonusReferenceValue": 110.56
},
"campaigns": [
{
"id": "787877"
}
],
"authentication": {
"code": "TOTVS: PIN 4375\n\n",
"type": "pin",
"validatedByException": false
},
"sale": {
"netSaleValue": 99.50,
"posCode": "002",
"sellerName": "João",
"externalSaleId": "444555",
"fiscalId": "16270357117773000125655530000000033434367344",
"custumerName": "Maria",
"totalQuantityItems": 5,
"items":
[
{
"netSaleValue": 99.50,
"itenID": 1,
"productDescription": "Produto Abc",
"productCode": "123",
"quantityItems": 1,
"grossSaleValue": 110.56
}
],
"paymentMethods":
[
{
"netSaleValue": 99.50,
"paymentMethodId": 1,
"description": "Dinheiro"
}
]
}
}
Response:
{
"nextStep": null,
"bonusId": "6919173",
"partnerSaleId": "6923576",
"transactionId": "500877",
"message": "",
"customerText": ""
} |
|
<style>
.div-1 {
background-color: #EBEBEB;
}
</style>
<div class="div-1"> <h1 style="font-size:200%">[/order]</h1> </div>
|
Enviar as vendas realizadas no PDV. Descrição: Essa API recebe os dados da venda realizada no PDV. LEMBRETE: Todas as vendas poderão ser enviadas nesta API, mesmo aquelas que não utilizaram o bônus. |
Detalhes do Response: - "transactionId" (String)
- Devolve o Id da transação da venda. Alguns parceiros podem não devolver este número.
OBS: Para todos os campos que são necessários no Response, eles sempre deverão retornar um valor, independente do tipo deles, caso retornem NULL ou outro tipo que não seja o deles, poderá haver conflito no Protheus. |
Exemplo do Json: POST /order
Request:
{
"externalBusinessUnitId": "001",
"sale": {
"salesChannel": "fisico",
"netSaleValue": 99.5,
"posCode": "002",
"sellerName": "João",
"externalSaleId": "444555",
"items": [
{
"itenID ": 1,
"productDescription": "bolsa de couro",
"productCode": "1245",
"QuantityItems": "1",
"grossSaleValue": 55.28,
"netSaleValue": 49.75
},
{
"itenID ": 2,
"productDescription": "camiseta",
"productCode": "1245",
"QuantityItems": "1",
"grossSaleValue": 55.28,
"netSaleValue": 49.75
}
],
"fiscalId": "16270357117773000125655530000000033434367344",
"custumerName": "Maria",
"totalQuantityItems": 5,
"paymentMethods": [
{
"paymentMethodId ": "10",
"description": "Dinheiro",
"netSaleValue ": 99.5
}
]
},
"identification": {
"operatorCode": "129830",
"operatorName": "Maria Vendedora",
"customerDocument": "51399156004",
"identificationCode": "11955554444",
"storeId": "100072",
"costumerId": "4399264"
}
}
Response:
{
"transactionId": "500877"
} |
|
|
