Integrar App com Cashback na VTEX

Criada por Alex Camargo, Modificado em Ter, 25 Mar na (o) 5:20 PM por Alex Camargo

Resumo

Este documento descreve as APIs necessárias para integrar o sistema de checkout BonifiQ ao aplicativo do cliente. As integrações abrangem login seguro, consulta e aplicação de recompensa. As chamadas são projetadas para garantir uma experiência segura e eficiente para o consumidor.

Principais Etapas

Login seguro: Autenticação do usuário e obtenção de token de segurança.
Consulta de recompensas: Verificação do saldo e regras para utilização da recompensa.
Aplicação de recompensa: Resgate de recompensa no carrinho.
Consulta de recompensa aplicado: Verificação do estado da recompensa no carrinho.
Remoção de recompensa: Remover a recompensa aplicada a um carrinho.

1. Fazer Login Seguro

O primeiro passo é realizar o login do usuário e obter o seu token de segurança. Esse token de segurança será utilizado em todas as chamadas subsequentes.

Requisição

POST /pub/widget/vendors/{platform}/securelogin
 X-Bq-Tenant: {tenant_key}

Corpo da Requisição

{
  "sessionToken": "<session_token>",
  "segmentToken": "<segment_token>"
 }

Parâmetros

X-Bq-Tenant: Identificador público da loja.
sessionToken: Gerado pela plataforma de e-commerce após o login do consumidor.
segmentToken: Gerado pela plataforma de e-commerce.

Exemplo de Resposta

{
  "HasError": false,
  "Message": null,
  "Item": {
    "Email": "usuario@dominio.com",
    "Name": "Nome Completo",
    "UserId": "usuario@dominio.com",
    "SecureToken": "742b9b93-c1dc-4ec1-8f92-6b3a1838c613"
  }
 }

Descrição dos Campos

SecureToken: Token de segurança do usuário, com validade de 60 minutos.

2. Buscar Recompensas

Essa etapa será utilizada para a listagem de recompensas disponíveis para o usuário logado:

Requisição

GET /pub/widget/rewards/checkout?purchaseValue=XXX
 X-Bq-Tenant: {tenant_key}
 X-Bq-SecureToken: {secure_token}

Parâmetros

purchaseValue: Valor da compra
X-Bq-Tenant: Identificador da loja.
X-Bq-SecureToken: Token do usuário obtido no login seguro.
order_form_id: Identificador do carrinho.

Exemplo de Resposta

{
  "ProgramName": "VTEX IO QA",
  "PointsBalance": 10000,
  "HasError": false,
  "Message": null,
  "Item": [
    {
      "Id": 301,
      "Type": 1,
      "Title": "R$ 100,00",
      "Points": 100,
      "Description": "Troque 100 Moedas por um cupom de desconto de R$ 100,00. Após a confirmação você receberá o cupom por e-mail. Válido para compras acima de R$ 100,00 (sem considerar frete e outras promoções). Cupom válido por 365 dias após resgate. Não acumulativo com outras promoções.",
      "Enabled": true,
      "DisabledReason": null,
      "PointBalance": null,
      "NoPointCost": false,
      "CanUse": true,
      "UseReason": 0,
      "RemainingToUse": 445,
           "MinValueToUse": 0
    }
  ]
 }

O campo UseReason se refere ao uso da recompensa, podendo possuir os valores abaixo:

enum RewardCheckoutUseReason {
  CanUse = 0, // Recompensa disponível para uso
  NotEnoughPoints = 1, // Cashback não disponível
  MinValueNotReached = 2, // Cliente não cadastrado
  CashbackNotAvailable = 3, // Valor mínimo não atingido
  NoCustomer = 4, // Porcentagem mínima de compra não atingida
  ValueRewardBiggerThanPurchase = 5, // Nenhum cliente
  MinimumPercentPurchaseNotReached = 6, // Não há pontos suficientes
  CustomerNotEnrolled = 7, // Recompensa de valor maior que a compra
 }

O campo RemainingToUse virá com um valor numérico caso o campo UseReason possua o valor 2 (MinValueNotReached)

2.1. Buscar Recompensas já Resgatadas

Essa etapa será utilizada para a listagem de recompensas já resgatadas e não utilizadas pelo consumidor:

Requisição

GET /pub/widget/rewards/checkout/redeemed?purchaseValue=XXX
 X-Bq-Tenant: {tenant_key}
 X-Bq-SecureToken: {secure_token}

Parâmetros

purchaseValue: Valor da compra
X-Bq-Tenant: Identificador da loja.
X-Bq-SecureToken: Token do usuário obtido no login seguro.
order_form_id: Identificador do carrinho.

Exemplo de Resposta

{
  "HasError": false,
  "Message": null,
  "Item": [
    {
      "RedeemedId": 1302,
      "RedeemedPoints": -10,
      "RedeemedValue": 0,
      "Id": 302,
      "Type": 0,
      "Title": "10%",
      "Points": 10,
      "Description": "Troque 100 Moedas por um cupom de desconto de R$ 100,00. Após a confirmação você receberá o cupom por e-mail. Válido para compras acima de R$ 100,00 (sem considerar frete e outras promoções). Cupom válido por 365 dias após resgate. Não acumulativo com outras promoções.",
      "Enabled": true,
      "DisabledReason": null,
      "CanUse": true,
      "UseReason": 0,
      "RemainingToUse": null,
      "MinValueToUse": 100
    }
  ]
 }

3. Aplicar Recompensa

Essa etapa será utilizada para a aplicação de recompensas ainda não resgatadas.

Requisição

POST /pub/widget/rewards/redeem/{reward_id}
 X-Bq-Tenant: {tenant_key}
 X-Bq-SecureToken: {secure_token}

Corpo da Requisição (Opcional)

{
  "OriginalId": "<order_form_id>"
 }

Exemplo de Resposta

{
  "HasError": false,
  "Message": "Tudo Certo! Em breve você irá receber um e-mail com mais instruções",
  "Item": {
    "Success": true,
    "ResultMessage": "Utilize seu cupom nesta compra:",
    "Code": null,
    "CouponCode": "c806711b278a463d8e787f5f5c409f89",
    "HasCouponCode": true,
    "AfterMessage": "Você também receberá esse cupom por e-mail",
    "Reward": {
      "RedeemedId": 1416,
      "RedeemedPoints": -2,
      "RedeemedValue": 0,
      "Id": 302,
      "Type": 0,
      "Title": "2%",
      "Points": 2,
      "Description": "Cupom válido por 365 dias após resgate. Não acumulativo com outras promoções.",
      "Enabled": true,
      "DisabledReason": null,
      "RemainingToUse": null,
      "MinValueToUse": null
    }
  }
 }

3.1. Aplicar Recompensa já Resgatada

Essa etapa será utilizada para a aplicação de recompensas já resgatadas.

Requisição

POST /pub/widget/rewardredeemed/checkout/redeem/{reward_redeemed_id}
 X-Bq-Tenant: {tenant_key}
 X-Bq-SecureToken: {secure_token}

<aside> ⚠️

Atenção!! O valor de reward_redeemed_id deverá ser o valor retornado na propriedade RedeemedId de acordo seção 2.1

</aside>

Corpo da Requisição (Opcional)

{
  "OriginalId": "<order_form_id>"
 }

Exemplo de Resposta

{
  "HasError": false,
  "Message": "Tudo Certo! Em breve você irá receber um e-mail com mais instruções",
  "Item": {
    "Success": true,
    "ResultMessage": "Utilize seu cupom nesta compra:",
    "Code": null,
    "CouponCode": "c806711b278a463d8e787f5f5c409f89",
    "HasCouponCode": true,
    "AfterMessage": "Você também receberá esse cupom por e-mail",
    "Reward": {
      "RedeemedId": 1416,
      "RedeemedPoints": -2,
      "RedeemedValue": 0,
      "Id": 302,
      "Type": 0,
      "Title": "2%",
      "Points": 2,
      "Description": "Cupom válido por 365 dias após resgate. Não acumulativo com outras promoções.",
      "Enabled": true,
      "DisabledReason": null,
      "RemainingToUse": null,
      "MinValueToUse": null
    }
  }
 }

4. Consultar Recompensa Aplicada

Esta etapa será utilizada para o caso do cliente saia da tela do checkout e seja necessário reaplicar o estado de recompensa resgatada a ele.

Requisição

POST /pub/widget/rewards/checkout
 X-Bq-Tenant: {tenant_key}
 X-Bq-SecureToken: {secure_token}

Corpo da Requisição (Opcional)

{
  "CheckoutCode": "<order_form_id>"
 }

Exemplo de Resposta

{
  "ProgramName": "VTEX IO QA",
  "PointsBalance": null,
  "HasError": false,
  "Message": null,
  "Item": {
    "Success": true,
    "CouponCode": "c806711b278a463d8e787f5f5c409f89",
    "Reward": {
      "Id": 302,
      "Type": 0,
      "Title": "10%",
      "Points": 10,
      "Description": "teste",
      "Enabled": true,
      "DisabledReason": null,
      "PointBalance": null,
      "NoPointCost": false,
      "CanUse": false,
      "UseReason": 0
    }
  }
 }

5. Remover Recompensa Aplicada

Esta etapa será utilizada para remoção de uma recompensa que foi aplicada ao carrinho.

Requisição

POST /pub/widget/rewards/checkout/{reward_redeemed_id}/reverse
 X-Bq-Tenant: {tenant_key}
 X-Bq-SecureToken: {secure_token}

Exemplo de Resposta

{
  "ProgramName": "VTEX IO QA",
  "PointsBalance": null,
  "HasError": false,
  "Message": null,
  "Item": {
    "Success": true,
    "CouponCode": "c806711b278a463d8e787f5f5c409f89",
    "Reward": {
      "Id": 302,
      "Type": 0,
      "Title": "10%",
      "Points": 10,
      "Description": "teste",
      "Enabled": true,
      "DisabledReason": null,
      "PointBalance": null,
      "NoPointCost": false,
      "CanUse": false,
      "UseReason": 0
    }
  }
 }

Observações Importantes

As recompensas disponíveis podem variar conforme o valor do carrinho e itens adicionados. Sempre verifique novamente após atualizações no carrinho.
Certifique-se de tratar as mensagens amigáveis retornadas pela API para melhorar a experiência do usuário.
O SecureToken tem validade limitada e deve ser atualizado periodicamente.