> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bonifiq.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Cashback

> Endpoints para validar, aplicar e gerenciar cashback no checkout

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

<ParamField header="X-Bq-Tenant" type="string" required>
  Identificador público da loja.
</ParamField>

<ParamField header="X-Bq-SecureToken" type="string" required>
  Token do usuário obtido no login seguro.
</ParamField>

**Path Parameters (GET)**

<ParamField path="ORDER_FORM_ID" type="string" required>
  Identificador do carrinho.
</ParamField>

**Body (POST)**

<ParamField body="CheckoutId" type="string" required>
  Identificador do carrinho (order\_form\_id).
</ParamField>

<ParamField body="Total" type="number">
  Valor total do carrinho (opcional, mas recomendado para cálculos mais precisos).
</ParamField>

### Exemplo (GET)

```bash theme={null}
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)

```bash theme={null}
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

<ResponseField name="CashbackBalance" type="number">
  Saldo total de cashback do cliente.
</ResponseField>

<ResponseField name="UsableCashback" type="number">
  Valor de cashback que pode ser utilizado nesta compra (considerando regras e limites).
</ResponseField>

<ResponseField name="MaxUsableCashback" type="number">
  Valor máximo de cashback permitido para esta compra.
</ResponseField>

<ResponseField name="CashbackRules" type="string">
  Regras de utilização do cashback (texto para exibição ao cliente).
</ResponseField>

<ResponseField name="CanUse" type="boolean">
  Indica se o cliente pode usar cashback nesta compra.
</ResponseField>

<ResponseField name="CashbackWillReceiveText" type="string">
  Texto informando quanto cashback o cliente receberá nesta compra.
</ResponseField>

<ResponseField name="RequiredToAddMoreText" type="string">
  Texto informando quanto falta para usar o cashback (se aplicável).
</ResponseField>

<ResponseField name="IsCashbackAvailable" type="boolean">
  Indica se o cashback está disponível para uso.
</ResponseField>

<ResponseField name="RemainingToTotalCashback" type="number">
  Valor restante para usar todo o saldo de cashback.
</ResponseField>

<ResponseField name="RemainingToUse" type="number">
  Valor restante para atingir o mínimo necessário para usar cashback.
</ResponseField>

<ResponseField name="hasProductsIneligibleForCashback" type="boolean">
  Indica se há produtos no carrinho que não são elegíveis para cashback.
</ResponseField>

<ResponseField name="MinValueToUse" type="number">
  Valor mínimo do carrinho para usar cashback.
</ResponseField>

```json theme={null}
{
  "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**

<ParamField header="X-Bq-Tenant" type="string" required>
  Identificador público da loja.
</ParamField>

<ParamField header="X-Bq-SecureToken" type="string" required>
  Token do usuário obtido no login seguro.
</ParamField>

**Path Parameters (primeira opção)**

<ParamField path="ORDER_FORM_ID" type="string" required>
  Identificador do carrinho.
</ParamField>

**Body (primeira opção)**

<ParamField body="CashbackValue" type="number" required>
  Valor do cashback a ser resgatado.
</ParamField>

<ParamField body="Token" type="string">
  Token de validação (se aplicável).
</ParamField>

<ParamField body="RedeemOrigin" type="integer">
  Origem do resgate. Use `3` para checkout mobile.
</ParamField>

<ParamField body="Total" type="number">
  Valor do carrinho (sem descontos ou frete).
</ParamField>

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

<ParamField body="CheckoutId" type="string" required>
  Identificador do carrinho (order\_form\_id).
</ParamField>

<ParamField body="CashbackValue" type="number" required>
  Valor do cashback a ser resgatado.
</ParamField>

<ParamField body="Token" type="string">
  Token de validação (se aplicável).
</ParamField>

<ParamField body="RedeemOrigin" type="integer">
  Origem do resgate. Use `3` para checkout mobile.
</ParamField>

<ParamField body="Total" type="number">
  Valor do carrinho (sem descontos ou frete).
</ParamField>

### Exemplo (com ORDER\_FORM\_ID na rota)

```bash theme={null}
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)

```bash theme={null}
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

<ResponseField name="AppliedCashback" type="number">
  Valor de cashback efetivamente aplicado.
</ResponseField>

<ResponseField name="Success" type="boolean">
  Indica se a operação foi bem-sucedida.
</ResponseField>

<ResponseField name="CustomerMessage" type="string">
  Mensagem para exibir ao cliente.
</ResponseField>

<ResponseField name="CashbackRules" type="string">
  Regras de utilização do cashback.
</ResponseField>

<ResponseField name="InternalMessage" type="string">
  Mensagem interna (para debugging).
</ResponseField>

<ResponseField name="CouponCode" type="string">
  Código do cupom gerado (se aplicável).
</ResponseField>

<ResponseField name="Token" type="string">
  Token de validação para operações subsequentes.
</ResponseField>

```json theme={null}
{
  "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**

<ParamField header="X-Bq-Tenant" type="string" required>
  Identificador público da loja.
</ParamField>

<ParamField header="X-Bq-SecureToken" type="string" required>
  Token do usuário obtido no login seguro.
</ParamField>

**Path Parameters (GET)**

<ParamField path="ORDER_FORM_ID" type="string" required>
  Identificador do carrinho.
</ParamField>

**Body (POST)**

<ParamField body="CheckoutId" type="string" required>
  Identificador do carrinho (order\_form\_id).
</ParamField>

### Exemplo (GET)

```bash theme={null}
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

```json theme={null}
{
  "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**

<ParamField header="X-Bq-Tenant" type="string" required>
  Identificador público da loja.
</ParamField>

<ParamField header="X-Bq-SecureToken" type="string" required>
  Token do usuário obtido no login seguro.
</ParamField>

**Path Parameters (primeira opção)**

<ParamField path="ORDER_FORM_ID" type="string" required>
  Identificador do carrinho.
</ParamField>

**Body (segunda opção)**

<ParamField body="CheckoutId" type="string" required>
  Identificador do carrinho (order\_form\_id).
</ParamField>

### Exemplo

```bash theme={null}
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

<ResponseField name="CashbackRemoved" type="boolean">
  Indica se o cashback foi removido (por exemplo, se o carrinho ficou abaixo do mínimo).
</ResponseField>

<ResponseField name="CustomerMessage" type="string">
  Mensagem para exibir ao cliente.
</ResponseField>

```json theme={null}
{
  "CashbackRemoved": false,
  "CustomerMessage": "Cashback atualizado com sucesso."
}
```

<Warning>
  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.
</Warning>

***

## 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**

<ParamField header="X-Bq-Tenant" type="string" required>
  Identificador público da loja.
</ParamField>

<ParamField header="X-Bq-SecureToken" type="string" required>
  Token do usuário obtido no login seguro.
</ParamField>

**Path Parameters (DELETE)**

<ParamField path="ORDER_FORM_ID" type="string" required>
  Identificador do carrinho.
</ParamField>

**Body (POST)**

<ParamField body="CheckoutId" type="string" required>
  Identificador do carrinho (order\_form\_id).
</ParamField>

<ParamField body="Total" type="number">
  Valor do carrinho (opcional).
</ParamField>

### Exemplo (DELETE)

```bash theme={null}
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)

```bash theme={null}
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

<ResponseField name="Success" type="boolean">
  Indica se a operação foi bem-sucedida.
</ResponseField>

<ResponseField name="CustomerMessage" type="string">
  Mensagem para exibir ao cliente.
</ResponseField>

```json theme={null}
{
  "Success": true,
  "CustomerMessage": "O cashback foi removido com sucesso"
}
```

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