Recompensas

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

string

required

Identificador público da loja.

Exemplo

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

Resposta

boolean

Indica se houve erro na requisição.

array

Lista de recompensas disponíveis.

Show Propriedades de cada recompensa

integer

Identificador único da recompensa.

integer

Tipo da recompensa (ver tabela de tipos abaixo).

string

Título da recompensa (ex: “R$ 10,00”, “10%”, “Frete Grátis”).

integer

Quantidade de pontos necessários para resgatar.

string

Descrição detalhada da recompensa.

boolean

Indica se a recompensa está habilitada.

string

Motivo pelo qual a recompensa está desabilitada (se aplicável).

boolean

Indica se o cliente pode usar esta recompensa.

integer

Código do motivo de disponibilidade/indisponibilidade (ver tabela abaixo).

boolean

Indica se a recompensa não tem custo em pontos.

number

Saldo de cashback disponível (para recompensas tipo cashback).

integer

Saldo de pontos do cliente.

number

Valor em reais de cada ponto para conversão em cashback.

number

Valor de cashback da recompensa.

string

Regras de utilização do cashback.

boolean

Indica se o cashback é apenas informativo.

string

Texto informativo sobre o cashback.

number

Valor restante para atingir o mínimo de uso.

number

Valor mínimo do carrinho para usar a recompensa.

number

Valor máximo de cashback utilizável.

Indica se há ícone customizado para o widget.

URL do ícone para exibição no widget.

boolean

Indica se há ícone customizado para a landing page.

string

URL do ícone para exibição na landing page.

boolean

Indica se deve usar instruções customizadas.

object

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

string

required

Identificador público da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters

integer

required

ID da recompensa a ser resgatada.

Body (Opcional)

string

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

boolean

Indica se houve erro na requisição.

string

Mensagem de sucesso ou erro.

object

Show Propriedades

boolean

Indica se o resgate foi bem-sucedido.

string

Mensagem de resultado para exibir ao cliente.

string

Código interno do resgate.

string

Código do cupom gerado para uso no checkout.

boolean

Indica se um código de cupom foi gerado.

string

Mensagem adicional após o resgate.

object

Detalhes da recompensa resgatada.

Show Propriedades

integer

ID do resgate realizado.

string

Título da recompensa.

integer

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

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/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
    }
  ]
}

Consultar Informações de Cashback

Retorna informações sobre o cashback disponível para o cliente.

Requisição

GET /pub/widget/rewards/cashback Headers

string

required

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

Introdução

Autenticação

Cliente

Gamificação

Outros

Recompensas

Status de Autenticação dos Endpoints

Listar Recompensas

Requisição

Exemplo

Resposta

Tipos de Recompensa (`Type`)

Motivos de Uso (`UseReason`)

Resgatar Recompensa

Requisição

Exemplo

Resposta

Listar Recompensas Resgatadas

Requisição

Exemplo

Resposta

Consultar Informações de Cashback

Requisição

Exemplo

Resposta

​Status de Autenticação dos Endpoints

​Listar Recompensas

​Requisição

​Exemplo

​Resposta

​Tipos de Recompensa (Type)

​Motivos de Uso (UseReason)

​Resgatar Recompensa

​Requisição

​Exemplo

​Resposta

​Listar Recompensas Resgatadas

​Requisição

​Exemplo

​Resposta

​Consultar Informações de Cashback

​Requisição

​Exemplo

​Resposta

Status de Autenticação dos Endpoints

Listar Recompensas

Requisição

Exemplo

Resposta

Tipos de Recompensa (`Type`)

Motivos de Uso (`UseReason`)

Resgatar Recompensa

Requisição

Exemplo

Resposta

Listar Recompensas Resgatadas

Requisição

Exemplo

Resposta

Consultar Informações de Cashback

Requisição

Exemplo

Resposta