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

string

required

Identificador público da loja.

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

string

Texto customizado para exibição no checkout.

string

Nome do programa de fidelidade.

string

Cor principal do programa (formato hexadecimal).

boolean

Indica se o programa está ativo.

boolean

Indica se o programa utiliza cashback.

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

string

required

Identificador público da loja.

Query Parameters

number

required

Valor total da compra.

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

number

Valor mínimo da compra para receber pontos.

integer

Quantidade de pontos que o cliente ganhará nesta compra.

number

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

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

string

required

Identificador público da loja.

Query Parameters

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

string

Nome do programa de fidelidade.

integer

Saldo de pontos do cliente.

boolean

Indica se houve erro na requisição.

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

string

required

Identificador público da loja.

Query Parameters

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

string

required

Identificador público da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters

integer

required

ID do resgate (RedeemedId).

Body (Opcional)

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

string

required

Identificador público da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters (GET)

string

required

Identificador do carrinho (order_form_id).

Body (POST)

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

string

required

Identificador público da loja.

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

​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