Recompensas no Checkout

Os endpoints de recompensas no checkout permitem consultar e aplicar recompensas durante o processo de compra, incluindo listagem de recompensas válidas para o carrinho atual e verificação de pontos a receber.

Status de Autenticação dos Endpoints

Endpoint	Status
`GET /pub/widget/rewards/checkout/configuration`	Público
`GET /pub/widget/rewards/checkout/purchase-points`	Público
`GET /pub/widget/rewards/checkout`	Autenticado
`GET /pub/widget/rewards/checkout/redeemed`	Público
`POST /pub/widget/rewardredeemed/checkout/redeem/{id}`	Autenticado
`GET /pub/widget/rewards/checkout/{checkoutCode}`	Autenticado
`POST /pub/widget/rewards/checkout`	Autenticado
`POST /pub/widget/rewards/checkout/{id}/reverse`	Autenticado

Obter Configuração do Checkout

Retorna as configurações do programa de fidelidade para exibição no checkout.

Requisição

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

X-Bq-Tenant

string

required

Identificador público da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Exemplo

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

Resposta

Text

string

Texto customizado para exibição no checkout.

ProgramName

string

Nome do programa de fidelidade.

Color

string

Cor principal do programa (formato 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
}

Consultar Pontos da Compra

Retorna quantos pontos (ou cashback) o cliente 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 público da loja.

Query Parameters

purchaseValue

number

required

Valor total da compra.

checkoutCode

string

Identificador do carrinho (order_form_id). Opcional, mas recomendado para cálculos mais precisos.

Exemplo

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

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
}

Listar Recompensas para o Checkout

Retorna as recompensas disponíveis considerando o valor do carrinho atual.

Requisição

GET /pub/widget/rewards/checkout Headers

X-Bq-Tenant

string

required

Identificador público da loja.

Query Parameters

purchaseValue

number

required

Valor da compra. Usado para determinar quais recompensas são válidas para o carrinho.

Exemplo

curl -X GET "https://api.bonifiq.com.br/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 disponíveis para o valor do carrinho.

{
  "ProgramName": "Programa Fidelidade",
  "PointsBalance": 10000,
  "HasError": false,
  "Message": null,
  "Item": [
    {
      "Id": 301,
      "Type": 1,
      "Title": "R$ 10,00",
      "Points": 100,
      "Description": "Cupom de R$ 10,00 de desconto",
      "Enabled": true,
      "CanUse": true,
      "UseReason": 0,
      "RemainingToUse": 0,
      "MinValueToUse": 50.00
    },
    {
      "Id": 302,
      "Type": 0,
      "Title": "10%",
      "Points": 50,
      "Description": "Cupom de 10% de desconto",
      "Enabled": true,
      "CanUse": true,
      "UseReason": 0,
      "RemainingToUse": 0,
      "MinValueToUse": 0
    }
  ]
}

Listar Recompensas já Resgatadas (Checkout)

Retorna as recompensas já resgatadas pelo cliente que podem ser aplicadas no checkout atual.

Requisição

GET /pub/widget/rewards/checkout/redeemed Headers

X-Bq-Tenant

string

required

Identificador público da loja.

Query Parameters

purchaseValue

number

required

Valor da compra.

Exemplo

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

Resposta

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

Aplicar Recompensa já Resgatada

Aplica uma recompensa que já foi resgatada anteriormente ao carrinho atual.

Requisição

POST /pub/widget/rewardredeemed/checkout/redeem/{id}

O parâmetro id deve ser o valor do campo RedeemedId retornado na consulta de recompensas resgatadas, não o ID da recompensa original.

Headers

X-Bq-Tenant

string

required

Identificador público da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters

integer

required

ID do resgate (RedeemedId).

Body (Opcional)

OriginalId

string

Identificador do carrinho (order_form_id).

Exemplo

curl -X POST "https://api.bonifiq.com.br/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>"
  }'

Resposta

Retorna a mesma estrutura do endpoint de resgate de recompensa.

Consultar Recompensa Aplicada ao Carrinho

Verifica se há uma recompensa aplicada ao carrinho atual. Útil para restaurar o estado quando o cliente retorna ao checkout.

Requisição (GET)

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

Requisição (POST)

POST /pub/widget/rewards/checkout Headers

X-Bq-Tenant

string

required

Identificador público 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.br/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.br/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": "Programa Fidelidade",
  "HasError": false,
  "Item": {
    "Success": true,
    "CouponCode": "c806711b278a463d8e787f5f5c409f89",
    "Reward": {
      "Id": 302,
      "Title": "10%",
      "Points": 10,
      "CanUse": false
    }
  }
}

Remover Recompensa do Carrinho

Remove uma recompensa que foi aplicada ao carrinho.

Este método apenas remove a recompensa 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/{id}/reverse Headers

X-Bq-Tenant

string

required

Identificador público da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters

integer

required

ID do resgate (RedeemedId) a ser removido do carrinho.

Exemplo

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

Resposta

{
  "ProgramName": "Programa Fidelidade",
  "HasError": false,
  "Item": {
    "Success": true,
    "CouponCode": null,
    "Reward": null
  }
}

Introdução

Autenticação

Cliente

Recompensas

Gamificação

Outros

Status de Autenticação dos Endpoints

Obter Configuração do Checkout

Requisição

Exemplo

Resposta

Consultar Pontos da Compra

Requisição

Exemplo

Resposta

Listar Recompensas para o Checkout

Requisição

Exemplo

Resposta

Listar Recompensas já Resgatadas (Checkout)

Requisição

Exemplo

Resposta

Aplicar Recompensa já Resgatada

Requisição

Exemplo

Resposta

Consultar Recompensa Aplicada ao Carrinho

Requisição (GET)

Requisição (POST)

Exemplo (GET)

Exemplo (POST)

Resposta

Remover Recompensa do Carrinho

Requisição

Exemplo

Resposta

Introdução

Autenticação

Cliente

Recompensas

Gamificação

Outros

​Status de Autenticação dos Endpoints

​Obter Configuração do Checkout

​Requisição

​Exemplo

​Resposta

​Consultar Pontos da Compra

​Requisição

​Exemplo

​Resposta

​Listar Recompensas para o Checkout

​Requisição

​Exemplo

​Resposta

​Listar Recompensas já Resgatadas (Checkout)

​Requisição

​Exemplo

​Resposta

​Aplicar Recompensa já Resgatada

​Requisição

​Exemplo

​Resposta

​Consultar Recompensa Aplicada ao Carrinho

​Requisição (GET)

​Requisição (POST)

​Exemplo (GET)

​Exemplo (POST)

​Resposta

​Remover Recompensa do Carrinho

​Requisição

​Exemplo

​Resposta

Status de Autenticação dos Endpoints

Obter Configuração do Checkout

Requisição

Exemplo

Resposta

Consultar Pontos da Compra

Requisição

Exemplo

Resposta

Listar Recompensas para o Checkout

Requisição

Exemplo

Resposta

Listar Recompensas já Resgatadas (Checkout)

Requisição

Exemplo

Resposta

Aplicar Recompensa já Resgatada

Requisição

Exemplo

Resposta

Consultar Recompensa Aplicada ao Carrinho

Requisição (GET)

Requisição (POST)

Exemplo (GET)

Exemplo (POST)

Resposta

Remover Recompensa do Carrinho

Requisição

Exemplo

Resposta