Os endpoints de recompensas permitem listar as recompensas disponíveis para o cliente e realizar o resgate de pontos por benefícios.
Status de Autenticação dos Endpoints
| Endpoint | Status |
|---|
GET /pub/widget/rewards | Público |
POST /pub/widget/rewards/redeem/{id} | Autenticado |
GET /pub/widget/rewards/redeemed | Autenticado |
GET /pub/widget/rewards/cashback | Público |
Listar Recompensas
Retorna todas as recompensas disponíveis no programa de fidelidade.
Requisição
GET /pub/widget/rewards
Headers
Identificador público da loja.
Exemplo
curl -X GET "https://api.bonifiq.com.br/pub/widget/rewards" \
-H "X-Bq-Tenant: {tenant_key}"
Resposta
Indica se houve erro na requisição.
Lista de recompensas disponíveis.Show Propriedades de cada recompensa
Identificador único da recompensa.
Tipo da recompensa (ver tabela de tipos abaixo).
Título da recompensa (ex: “R$ 10,00”, “10%”, “Frete Grátis”).
Quantidade de pontos necessários para resgatar.
Descrição detalhada da recompensa.
Indica se a recompensa está habilitada.
Motivo pelo qual a recompensa está desabilitada (se aplicável).
Indica se o cliente pode usar esta recompensa.
Código do motivo de disponibilidade/indisponibilidade (ver tabela abaixo).
Indica se a recompensa não tem custo em pontos.
Saldo de cashback disponível (para recompensas tipo cashback).
Saldo de pontos do cliente.
Valor em reais de cada ponto para conversão em cashback.
Valor de cashback da recompensa.
Regras de utilização do cashback.
IsCashbackInformativeOnly
Indica se o cashback é apenas informativo.
Texto informativo sobre o cashback.
Valor restante para atingir o mínimo de uso.
Valor mínimo do carrinho para usar a recompensa.
Valor máximo de cashback utilizável.
Indica se há ícone customizado para o widget.
URL do ícone para exibição no widget.
Indica se há ícone customizado para a landing page.
URL do ícone para exibição na landing page.
ShouldUseCustomInstruction
Indica se deve usar instruções customizadas.
Regras de configuração da recompensa.
{
"HasError": false,
"Message": null,
"Item": [
{
"Id": 301,
"Type": 1,
"Title": "R$ 10,00",
"Points": 100,
"Description": "Cupom de desconto de R$ 10,00",
"Enabled": true,
"DisabledReason": null,
"CanUse": true,
"UseReason": 0,
"NoPointCost": false,
"CashbackBalance": null,
"PointBalance": 1500,
"MinValueToUse": 50.00,
"RemainingToUse": 0,
"WidgetIconActive": false,
"WidgetIcon": null
},
{
"Id": 302,
"Type": 0,
"Title": "10%",
"Points": 50,
"Description": "Cupom de desconto de 10%",
"Enabled": true,
"CanUse": true,
"UseReason": 0
}
]
}
Tipos de Recompensa (Type)
| Valor | Nome | Descrição |
|---|
| 0 | PercentDiscountCoupon | Cupom de desconto percentual |
| 1 | ValueDiscountCoupon | Cupom de desconto em valor fixo |
| 2 | FreightDiscountCoupon | Cupom de frete grátis |
| 3 | PointToCashback | Conversão de pontos para cashback |
| 4 | Customized | Recompensa customizada |
Motivos de Uso (UseReason)
| Valor | Nome | Descrição |
|---|
| 0 | CanUse | Recompensa disponível para uso |
| 1 | NotEnoughPoints | Pontos insuficientes |
| 2 | MinValueNotReached | Valor mínimo do carrinho não atingido |
| 3 | CashbackNotAvailable | Cashback não disponível |
| 4 | NoCustomer | Cliente não identificado |
| 5 | ValueRewardBiggerThanPurchase | Valor da recompensa maior que a compra |
| 6 | MinimumPercentPurchaseNotReached | Percentual mínimo de compra não atingido |
| 7 | CustomerNotEnrolled | Cliente não cadastrado no programa |
| 8 | CannotUseCumulativeDiscount | Não é possível acumular descontos |
Resgatar Recompensa
Realiza o resgate de uma recompensa, debitando os pontos do cliente e gerando um cupom de desconto.
Requisição
POST /pub/widget/rewards/redeem/{id}
Headers
Identificador público da loja.
Token do usuário obtido no login seguro.
ID da recompensa a ser resgatada.
Identificador do carrinho (order_form_id) para associar o resgate.
Exemplo
curl -X POST "https://api.bonifiq.com.br/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
Indica se houve erro na requisição.
Mensagem de sucesso ou erro.
Indica se o resgate foi bem-sucedido.
Mensagem de resultado para exibir ao cliente.
Código interno do resgate.
Código do cupom gerado para uso no checkout.
Indica se um código de cupom foi gerado.
Mensagem adicional após o resgate.
Detalhes da recompensa resgatada.
Pontos utilizados no resgate.
{
"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": "RDM-12345",
"CouponCode": "c806711b278a463d8e787f5f5c409f89",
"HasCouponCode": true,
"AfterMessage": null,
"Reward": {
"RedeemedId": 1416,
"Title": "R$ 10,00",
"Points": 100
}
}
}
Listar Recompensas Resgatadas
Retorna a lista de recompensas já resgatadas pelo cliente que ainda não foram utilizadas.
Requisição
GET /pub/widget/rewards/redeemed
Headers
Identificador público da loja.
Token do usuário obtido no login seguro.
Exemplo
curl -X GET "https://api.bonifiq.com.br/pub/widget/rewards/redeemed" \
-H "X-Bq-Tenant: {tenant_key}" \
-H "X-Bq-SecureToken: {secure_token}"
Resposta
{
"HasError": false,
"Message": null,
"Item": [
{
"RedeemedId": 1416,
"Id": 301,
"Type": 1,
"Title": "R$ 10,00",
"Points": 100,
"CouponCode": "c806711b278a463d8e787f5f5c409f89",
"RedeemedPoints": -100,
"RedeemedValue": 10.00
}
]
}
Retorna informações sobre o cashback disponível para o cliente.
Requisição
GET /pub/widget/rewards/cashback
Headers
Identificador público da loja.
Exemplo
curl -X GET "https://api.bonifiq.com.br/pub/widget/rewards/cashback" \
-H "X-Bq-Tenant: {tenant_key}"
Resposta
Retorna informações sobre o saldo e configurações de cashback do cliente.
{
"HasError": false,
"Message": null,
"Item": {
"CashbackBalance": 50.00,
"CashbackRules": "Pague até 50% da compra com cashback",
"MinValueToUse": 20.00
}
}
