API de Checkout - BonifiQ Developers

A BonifiQ já oferece uma solução nativa para integrar diretamente ao Checkout da VTEX no modelo Web. No modelo Mobile, no entanto, requer que seja realizada a integração com as APIs da BonifiQ diretamente. 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.
Configuração do checkout: Obtenção das configurações do programa de fidelidade.
Consulta de pontos da compra: Verificação de quantos pontos o cliente ganhará na compra.
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 aplicada: Verificação do estado da recompensa no carrinho.
Remoção de recompensa: Remover a recompensa aplicada a um carrinho.

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. O sessionToken e o segmentToken deverão ser obtidos mediante login na VTEX.

O SecureToken tem validade limitada e deve ser atualizado periodicamente.

Requisição

POST /pub/widget/vendors/vtex/securelogin Headers

X-Bq-Tenant

string

required

Identificador público da loja.

Body

sessionToken

string

required

Gerado pela plataforma de e-commerce após o login do consumidor.

segmentToken

string

required

Gerado pela plataforma de e-commerce.

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/vendors/vtex/securelogin" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionToken": "<session_token>",
    "segmentToken": "<segment_token>"
  }'

Resposta

HasError

boolean

Indica se houve erro na requisição.

Item

object

Show Properties

string

E-mail do usuário.

Name

string

Nome completo do usuário.

UserId

string

Identificador do usuário.

SecureToken

string

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

{
  "HasError": false,
  "Message": null,
  "Item": {
    "Email": "[email protected]",
    "Name": "Nome Completo",
    "UserId": "[email protected]",
    "SecureToken": "742b9b93-c1dc-4ec1-8f92-6b3a1838c613"
  }
}

2. Obter Configuração do Checkout

Essa etapa é utilizada para obter as configurações do programa de fidelidade para o checkout, como cores, nome do programa e se utiliza pontos ou cashback.

Requisição

GET /pub/widget/rewards/checkout/configuration Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Exemplo

curl -X GET "https://api.bonifiq.com/pub/widget/rewards/checkout/configuration" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Resposta

Text

string

Texto customizado para exibição no checkout.

ProgramName

string

Nome do programa de fidelidade.

Color

string

Cor principal do programa (hexadecimal).

Active

boolean

Indica se o programa está ativo.

UseCashback

boolean

Indica se o programa utiliza cashback.

UsePoints

boolean

Indica se o programa utiliza pontos.

{
  "Text": "Resgate seus pontos!",
  "ProgramName": "Programa Fidelidade",
  "Color": "#FF5722",
  "Active": true,
  "UseCashback": true,
  "UsePoints": true
}

3. Consultar Pontos da Compra

Essa etapa é utilizada para exibir ao cliente quantos pontos (ou cashback) ele ganhará na compra atual. Ideal para exibir mensagens como “Você ganhará X pontos nesta compra”.

Requisição

GET /pub/widget/rewards/checkout/purchase-points Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Query Parameters

purchaseValue

number

required

Valor da compra.

checkoutCode

string

Identificador do carrinho (order_form_id). Opcional.

Exemplo

curl -X GET "https://api.bonifiq.com/pub/widget/rewards/checkout/purchase-points?purchaseValue=150.00&checkoutCode=abc123" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Resposta

MinValueToReceive

number

Valor mínimo da compra para receber pontos.

PurchasePoints

integer

Quantidade de pontos que o cliente ganhará nesta compra.

PurchaseCashback

number

Valor de cashback que o cliente ganhará nesta compra (se aplicável).

HasPurchaseObjective

boolean

Indica se existe um objetivo de compra configurado.

{
  "MinValueToReceive": 50.00,
  "PurchasePoints": 150,
  "PurchaseCashback": 7.50,
  "HasPurchaseObjective": true
}

4. 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 Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Query Parameters

purchaseValue

number

required

Valor da compra. É utilizado para determinar quais recompensas (e valores) são válidos para o carrinho.

Exemplo

curl -X GET "https://api.bonifiq.com/pub/widget/rewards/checkout?purchaseValue=100.00" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Resposta

ProgramName

string

Nome do programa de fidelidade.

PointsBalance

integer

Saldo de pontos do cliente.

HasError

boolean

Indica se houve erro na requisição.

Item

array

Lista de recompensas.

Show Item Object

integer

Identificador da recompensa.

Type

integer

Tipo da recompensa (0 = Percentual, 1 = Valor fixo).

Title

string

Título da recompensa.

Points

integer

Quantidade de pontos necessários para resgatar.

Description

string

Descrição da recompensa.

Enabled

boolean

Indica se a recompensa está habilitada.

CanUse

boolean

Indica se o cliente pode usar esta recompensa.

UseReason

integer

Motivo da disponibilidade/indisponibilidade (ver tabela abaixo).

RemainingToUse

number

Valor restante para atingir o mínimo (se UseReason for 2).

MinValueToUse

number

Valor mínimo do carrinho para usar esta recompensa.

{
  "ProgramName": "VTEX IO QA",
  "PointsBalance": 10000,
  "HasError": false,
  "Message": null,
  "Item": [
    {
      "Id": 301,
      "Type": 1,
      "Title": "R$ 100,00",
      "Points": 100,
      "Description": "Descrição da recompensa...",
      "Enabled": true,
      "CanUse": true,
      "UseReason": 0,
      "RemainingToUse": 0,
      "MinValueToUse": 0
    }
  ]
}

Enumeração `UseReason`

Valor	Descrição
0	CanUse (Recompensa disponível para uso)
1	NotEnoughPoints
2	MinValueNotReached
3	CashbackNotAvailable
4	NoCustomer
5	ValueRewardBiggerThanPurchase
6	MinimumPercentPurchaseNotReached
7	CustomerNotEnrolled

4.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 Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Query Parameters

purchaseValue

number

required

Valor da compra.

Exemplo

curl -X GET "https://api.bonifiq.com/pub/widget/rewards/checkout/redeemed?purchaseValue=100.00" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Resposta

{
  "HasError": false,
  "Message": null,
  "Item": [
    {
      "RedeemedId": 1302,
      "RedeemedPoints": -10,
      "RedeemedValue": 0,
      "Id": 302,
      "Type": 0,
      "Title": "10%",
      "Points": 10,
      "CanUse": true,
      "UseReason": 0
    }
  ]
}

5. 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} Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters

reward_id

integer

required

ID da recompensa a ser resgatada.

Body (Opcional)

OriginalId

string

Identificador do carrinho (order_form_id).

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/redeem/301" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "OriginalId": "<order_form_id>"
  }'

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:",
    "CouponCode": "c806711b278a463d8e787f5f5c409f89",
    "HasCouponCode": true,
    "Reward": {
      "RedeemedId": 1416,
      "Title": "2%",
      "Points": 2
    }
  }
}

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

O valor de reward_redeemed_id deverá ser o valor retornado na propriedade RedeemedId da seção “Buscar Recompensas já Resgatadas”.

Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters

reward_redeemed_id

integer

required

ID da recompensa resgatada.

Body (Opcional)

OriginalId

string

Identificador do carrinho (order_form_id).

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/rewardredeemed/checkout/redeem/1302" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "OriginalId": "<order_form_id>"
  }'

6. Validar Cashback

Essa etapa é utilizada para verificar se o cliente pode utilizar cashback e qual o valor disponível. Deve ser chamada antes de aplicar o cashback.

Requisição

GET /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID} ou POST /pub/widget/rewards/checkout/cashback Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters (GET)

ORDER_FORM_ID

string

required

Identificador do carrinho.

Body (POST)

CheckoutId

string

required

Identificador do carrinho (order_form_id).

Exemplo (GET)

curl -X GET "https://api.bonifiq.com/pub/widget/rewards/checkout/cashback/abc123" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Exemplo (POST)

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/checkout/cashback" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutId": "<order_form_id>"
  }'

Resposta

CashbackBalance

number

Saldo total de cashback do cliente.

UsableCashback

number

Valor de cashback que pode ser utilizado nesta compra.

MaxUsableCashback

number

Valor máximo de cashback permitido para esta compra.

CashbackRules

string

Regras de utilização do cashback (texto para exibição).

CanUse

boolean

Indica se o cliente pode usar cashback nesta compra.

CashbackWillReceiveText

string

Texto informando quanto cashback o cliente receberá.

RequiredToAddMoreText

string

Texto informando quanto falta para usar o cashback.

IsCashbackAvailable

boolean

Indica se o cashback está disponível.

RemainingToTotalCashback

number

Valor restante para usar todo o cashback.

RemainingToUse

number

Valor restante para atingir o mínimo necessário.

hasProductsIneligibleForCashback

boolean

Indica se há produtos no carrinho que não são elegíveis para cashback.

MinValueToUse

number

Valor mínimo do carrinho para usar cashback.

{
  "CashbackBalance": 50.00,
  "UsableCashback": 25.00,
  "MaxUsableCashback": 50.00,
  "CashbackRules": "Pague até 50% da compra com cashback.",
  "CanUse": true,
  "CashbackWillReceiveText": "Você receberá R$ 5,00 de cashback nesta compra",
  "RequiredToAddMoreText": null,
  "IsCashbackAvailable": true,
  "RemainingToTotalCashback": 0,
  "RemainingToUse": 0,
  "hasProductsIneligibleForCashback": false,
  "MinValueToUse": 20.00
}

6.1. Aplicar Cashback

Essa etapa será utilizada para a aplicação de cashback.

Requisição

POST /pub/widget/rewards/checkout/cashback/redeem Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Body

CheckoutId

string

required

Identificador do carrinho (order_form_id).

CashbackValue

number

required

Valor do cashback a ser resgatado.

RedeemOrigin

integer

required

Origem do resgate. Use 3 para checkout mobile.

Total

number

required

Valor do carrinho (sem descontos ou frete).

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/checkout/cashback/redeem" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutId": "<order_form_id>",
    "CashbackValue": 25.00,
    "RedeemOrigin": 3,
    "Total": 150.00
  }'

Resposta

{
  "AppliedCashback": 25.00,
  "Success": true,
  "CustomerMessage": "Cashback resgatado com sucesso.",
  "CashbackRules": "Pague até 50% da compra com cashback.",
  "InternalMessage": null,
  "CouponCode": null
}

6.2. Consultar Cashback Aplicado

Essa etapa é utilizada para verificar se há cashback aplicado ao carrinho.

Requisição

GET /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeemed ou POST /pub/widget/rewards/checkout/cashback/redeemed Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters (GET)

ORDER_FORM_ID

string

required

Identificador do carrinho.

Body (POST)

CheckoutId

string

required

Identificador do carrinho (order_form_id).

Exemplo (GET)

curl -X GET "https://api.bonifiq.com/pub/widget/rewards/checkout/cashback/abc123/redeemed" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Resposta

{
  "AppliedCashback": 25.00,
  "Success": true,
  "CustomerMessage": "Você está utilizando R$ 25,00 de cashback.",
  "CashbackRules": "Pague até 50% da compra com cashback.",
  "InternalMessage": null,
  "CouponCode": null
}

6.3. Atualizar Cashback (Refresh)

Essa etapa é utilizada para recalcular o cashback quando o carrinho é alterado (itens adicionados/removidos).

Requisição

POST /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/refresh ou POST /pub/widget/rewards/checkout/cashback/refresh Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters (primeira opção)

ORDER_FORM_ID

string

required

Identificador do carrinho.

Body (segunda opção)

CheckoutId

string

required

Identificador do carrinho (order_form_id).

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/checkout/cashback/refresh" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutId": "<order_form_id>"
  }'

Resposta

CashbackRemoved

boolean

Indica se o cashback foi removido (por exemplo, se o carrinho ficou abaixo do mínimo).

CustomerMessage

string

Mensagem para exibir ao cliente.

{
  "CashbackRemoved": false,
  "CustomerMessage": "Cashback atualizado com sucesso."
}

7. Consultar Recompensa Aplicada

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

Requisição (GET)

GET /pub/widget/rewards/checkout/{checkoutCode}

Requisição (POST)

POST /pub/widget/rewards/checkout Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters (GET)

checkoutCode

string

required

Identificador do carrinho (order_form_id).

Body (POST)

CheckoutCode

string

required

Identificador do carrinho (order_form_id).

Exemplo (GET)

curl -X GET "https://api.bonifiq.com/pub/widget/rewards/checkout/abc123" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Exemplo (POST)

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/checkout" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutCode": "<order_form_id>"
  }'

Resposta

{
  "ProgramName": "VTEX IO QA",
  "HasError": false,
  "Item": {
    "Success": true,
    "CouponCode": "c806711b278a463d8e787f5f5c409f89",
    "Reward": {
      "Id": 302,
      "Title": "10%",
      "Points": 10,
      "CanUse": false
    }
  }
}

8. Remover Recompensa Aplicada

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

Este método apenas remove a recompensa resgatada do carrinho. Ele não realiza o estorno dos pontos para a carteira do consumidor e nem cancela o resgate da recompensa.

Requisição

POST /pub/widget/rewards/checkout/{reward_redeemed_id}/reverse Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters

reward_redeemed_id

integer

required

ID da recompensa resgatada a ser removida do carrinho.

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/checkout/1416/reverse" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

8.1. Remover Cashback Aplicado

Esta etapa será utilizada para remoção de um cashback que foi aplicado ao carrinho.

Este método remove o cashback do carrinho e também realiza o estorno dos pontos de volta à carteira do consumidor, diferentemente da remoção de recompensa.

Requisição

POST /pub/widget/rewards/checkout/cashback/redeem/remove Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Body

CheckoutId

string

required

Identificador do carrinho (order_form_id).

Total

number

required

Valor do carrinho (sem descontos ou frete).

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/checkout/cashback/redeem/remove" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutId": "<order_form_id>",
    "Total": 150.00
  }'

Resposta

Success

boolean

Indica se a operação foi bem sucedida.

CustomerMessage

string

Mensagem para exibir ao cliente.

{
  "Success": true,
  "CustomerMessage": "O cashback foi removido com sucesso"
}

Guias de Integração

​Principais Etapas

​1. Fazer Login Seguro

​Requisição

​Exemplo

​Resposta

​2. Obter Configuração do Checkout

​Requisição

​Exemplo

​Resposta

​3. Consultar Pontos da Compra

​Requisição

​Exemplo

​Resposta

​4. Buscar Recompensas

​Requisição

​Exemplo

​Resposta

​Enumeração UseReason

​4.1. Buscar Recompensas já Resgatadas

​Requisição

​Exemplo

​Resposta

​5. Aplicar Recompensa

​Requisição

​Exemplo

​Resposta

​5.1. Aplicar Recompensa já Resgatada

​Requisição

​Exemplo

​6. Validar Cashback

​Requisição

​Exemplo (GET)

​Exemplo (POST)

​Resposta

​6.1. Aplicar Cashback

​Requisição

​Exemplo

​Resposta

​6.2. Consultar Cashback Aplicado

​Requisição

​Exemplo (GET)

​Resposta

​6.3. Atualizar Cashback (Refresh)

​Requisição

​Exemplo

​Resposta

​7. Consultar Recompensa Aplicada

​Requisição (GET)

​Requisição (POST)

​Exemplo (GET)

​Exemplo (POST)

​Resposta

​8. Remover Recompensa Aplicada

​Requisição

​Exemplo

​8.1. Remover Cashback Aplicado

​Requisição

​Exemplo

​Resposta

Principais Etapas

1. Fazer Login Seguro

Requisição

Exemplo

Resposta

2. Obter Configuração do Checkout

Requisição

Exemplo

Resposta

3. Consultar Pontos da Compra

Requisição

Exemplo

Resposta

4. Buscar Recompensas

Requisição

Exemplo

Resposta

Enumeração `UseReason`

4.1. Buscar Recompensas já Resgatadas

Requisição

Exemplo

Resposta

5. Aplicar Recompensa

Requisição

Exemplo

Resposta

5.1. Aplicar Recompensa já Resgatada

Requisição

Exemplo

6. Validar Cashback

Requisição

Exemplo (GET)

Exemplo (POST)

Resposta

6.1. Aplicar Cashback

Requisição

Exemplo

Resposta

6.2. Consultar Cashback Aplicado

Requisição

Exemplo (GET)

Resposta

6.3. Atualizar Cashback (Refresh)

Requisição

Exemplo

Resposta

7. Consultar Recompensa Aplicada

Requisição (GET)

Requisição (POST)

Exemplo (GET)

Exemplo (POST)

Resposta

8. Remover Recompensa Aplicada

Requisição

Exemplo

8.1. Remover Cashback Aplicado

Requisição

Exemplo

Resposta