Cashback

Os endpoints de cashback permitem validar a disponibilidade, aplicar e remover cashback durante o processo de checkout.

Status de Autenticação dos Endpoints

Endpoint	Status
`GET /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}`	Autenticado
`POST /pub/widget/rewards/checkout/cashback`	Autenticado
`POST /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeem`	Autenticado
`POST /pub/widget/rewards/checkout/cashback/redeem`	Autenticado
`GET /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeemed`	Autenticado
`POST /pub/widget/rewards/checkout/cashback/redeemed`	Autenticado
`POST /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/refresh`	Autenticado
`POST /pub/widget/rewards/checkout/cashback/refresh`	Autenticado
`DELETE /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeem`	Autenticado
`POST /pub/widget/rewards/checkout/cashback/redeem/remove`	Autenticado

Validar Cashback

Verifica se o cliente pode utilizar cashback e qual o valor disponível para a compra atual. Deve ser chamada antes de aplicar o cashback.

Requisição (GET)

GET /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}

Requisição (POST)

POST /pub/widget/rewards/checkout/cashback 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.

Body (POST)

string

required

Identificador do carrinho (order_form_id).

number

Valor total do carrinho (opcional, mas recomendado para cálculos mais precisos).

Exemplo (GET)

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

Resposta

number

Saldo total de cashback do cliente.

number

Valor de cashback que pode ser utilizado nesta compra (considerando regras e limites).

number

Valor máximo de cashback permitido para esta compra.

string

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

boolean

Indica se o cliente pode usar cashback nesta compra.

string

Texto informando quanto cashback o cliente receberá nesta compra.

string

Texto informando quanto falta para usar o cashback (se aplicável).

boolean

Indica se o cashback está disponível para uso.

number

Valor restante para usar todo o saldo de cashback.

number

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

boolean

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

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
}

Aplicar Cashback

Aplica o cashback ao carrinho do cliente.

Requisição (com ORDER_FORM_ID na rota)

POST /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeem

Requisição (com CheckoutId no body)

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

string

required

Identificador público da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters (primeira opção)

string

required

Identificador do carrinho.

Body (primeira opção)

number

required

Valor do cashback a ser resgatado.

string

Token de validação (se aplicável).

integer

Origem do resgate. Use 3 para checkout mobile.

number

Valor do carrinho (sem descontos ou frete).

Body (segunda opção - CheckoutId no body)

string

required

Identificador do carrinho (order_form_id).

number

required

Valor do cashback a ser resgatado.

string

Token de validação (se aplicável).

integer

Origem do resgate. Use 3 para checkout mobile.

number

Valor do carrinho (sem descontos ou frete).

Exemplo (com ORDER_FORM_ID na rota)

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

Exemplo (com CheckoutId no body)

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

number

Valor de cashback efetivamente aplicado.

boolean

Indica se a operação foi bem-sucedida.

string

Mensagem para exibir ao cliente.

string

Regras de utilização do cashback.

string

Mensagem interna (para debugging).

string

Código do cupom gerado (se aplicável).

string

Token de validação para operações subsequentes.

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

Valores de `RedeemOrigin`

Valor	Descrição
0	Widget
1	Checkout Web
2	Landing Page
3	Checkout Mobile
4	API

Consultar Cashback Aplicado

Verifica se há cashback aplicado ao carrinho atual.

Requisição (GET)

GET /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeemed

Requisição (POST)

POST /pub/widget/rewards/checkout/cashback/redeemed 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.

Body (POST)

string

required

Identificador do carrinho (order_form_id).

Exemplo (GET)

curl -X GET "https://api.bonifiq.com.br/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,
  "Token": "xyz789"
}

Atualizar Cashback (Refresh)

Recalcula o cashback aplicado quando o carrinho é alterado (itens adicionados/removidos). Deve ser chamado sempre que houver mudança no carrinho.

Requisição (com ORDER_FORM_ID na rota)

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

Requisição (com CheckoutId no body)

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

string

required

Identificador público da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters (primeira opção)

string

required

Identificador do carrinho.

Body (segunda opção)

string

required

Identificador do carrinho (order_form_id).

Exemplo

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

boolean

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

string

Mensagem para exibir ao cliente.

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

Se CashbackRemoved for true, significa que o cashback aplicado anteriormente foi removido automaticamente porque o carrinho não atende mais aos requisitos mínimos. Neste caso, exiba a mensagem ao cliente.

Remover Cashback

Remove o cashback aplicado ao carrinho e estorna o valor de volta à carteira do cliente.

Requisição (DELETE)

DELETE /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeem

Requisição (POST)

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

string

required

Identificador público da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters (DELETE)

string

required

Identificador do carrinho.

Body (POST)

string

required

Identificador do carrinho (order_form_id).

number

Valor do carrinho (opcional).

Exemplo (DELETE)

curl -X DELETE "https://api.bonifiq.com.br/pub/widget/rewards/checkout/cashback/abc123/redeem" \
  -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/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

boolean

Indica se a operação foi bem-sucedida.

string

Mensagem para exibir ao cliente.

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

Diferentemente da remoção de recompensas, a remoção de cashback estorna automaticamente o valor de volta para a carteira do cliente.

Introdução

Autenticação

Cliente

Recompensas

Gamificação

Outros

Status de Autenticação dos Endpoints

Validar Cashback

Requisição (GET)

Requisição (POST)

Exemplo (GET)

Exemplo (POST)

Resposta

Aplicar Cashback

Requisição (com ORDER_FORM_ID na rota)

Requisição (com CheckoutId no body)

Exemplo (com ORDER_FORM_ID na rota)

Exemplo (com CheckoutId no body)

Resposta

Valores de `RedeemOrigin`

Consultar Cashback Aplicado

Requisição (GET)

Requisição (POST)

Exemplo (GET)

Resposta

Atualizar Cashback (Refresh)

Requisição (com ORDER_FORM_ID na rota)

Requisição (com CheckoutId no body)

Exemplo

Resposta

Remover Cashback

Requisição (DELETE)

Requisição (POST)

Exemplo (DELETE)

Exemplo (POST)

Resposta

​Status de Autenticação dos Endpoints

​Validar Cashback

​Requisição (GET)

​Requisição (POST)

​Exemplo (GET)

​Exemplo (POST)

​Resposta

​Aplicar Cashback

​Requisição (com ORDER_FORM_ID na rota)

​Requisição (com CheckoutId no body)

​Exemplo (com ORDER_FORM_ID na rota)

​Exemplo (com CheckoutId no body)

​Resposta

​Valores de RedeemOrigin

​Consultar Cashback Aplicado

​Requisição (GET)

​Requisição (POST)

​Exemplo (GET)

​Resposta

​Atualizar Cashback (Refresh)

​Requisição (com ORDER_FORM_ID na rota)

​Requisição (com CheckoutId no body)

​Exemplo

​Resposta

​Remover Cashback

​Requisição (DELETE)

​Requisição (POST)

​Exemplo (DELETE)

​Exemplo (POST)

​Resposta

Status de Autenticação dos Endpoints

Validar Cashback

Requisição (GET)

Requisição (POST)

Exemplo (GET)

Exemplo (POST)

Resposta

Aplicar Cashback

Requisição (com ORDER_FORM_ID na rota)

Requisição (com CheckoutId no body)

Exemplo (com ORDER_FORM_ID na rota)

Exemplo (com CheckoutId no body)

Resposta

Valores de `RedeemOrigin`

Consultar Cashback Aplicado

Requisição (GET)

Requisição (POST)

Exemplo (GET)

Resposta

Atualizar Cashback (Refresh)

Requisição (com ORDER_FORM_ID na rota)

Requisição (com CheckoutId no body)

Exemplo

Resposta

Remover Cashback

Requisição (DELETE)

Requisição (POST)

Exemplo (DELETE)

Exemplo (POST)

Resposta