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):
    • Nome do cliente.
  • “email” (String):
    • E-mail do cliente.
  • “birth” (String):
    • Formato aaaa-mm-dd Exemplo: 2000-01-25
  • “cpf” (String):
    • Somente números, sem máscara.
  • “gender” (String):
    • Gênero do cliente
  • "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):
    

    • Identifica se o campo deverá ter seu conteúdo oculto na interface.

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": []
       }
    }

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):
  • Código de autenticação
• “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.

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": []
    }

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

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

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)
  
  • Id do Bônus no Parceiro
• “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.

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

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

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

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)
  
  • Id do bônus
• "partnerSaleId" (String)
  
  • Id do parceiro de bônus
• "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.

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

Enviar as vendas realizadas no PDV.

Descrição:      

Essa API recebe os dados da venda realizada no PDV.

Detalhes do Response:

• "transactionId" (String)
  
  • Devolve o Id da transação da venda. Alguns parceiros podem não devolver este número.

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