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

# Recompensas no Checkout

> Endpoints para gerenciar recompensas durante o processo de 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**

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

### Exemplo

```bash theme={null}
curl -X GET "https://api.bonifiq.com.br/pub/widget/rewards/checkout/configuration" \
  -H "X-Bq-Tenant: {tenant_key}"
```

### Resposta

<ResponseField name="Text" type="string">
  Texto customizado para exibição no checkout.
</ResponseField>

<ResponseField name="ProgramName" type="string">
  Nome do programa de fidelidade.
</ResponseField>

<ResponseField name="Color" type="string">
  Cor principal do programa (formato hexadecimal).
</ResponseField>

<ResponseField name="Active" type="boolean">
  Indica se o programa está ativo.
</ResponseField>

<ResponseField name="UseCashback" type="boolean">
  Indica se o programa utiliza cashback.
</ResponseField>

<ResponseField name="UsePoints" type="boolean">
  Indica se o programa utiliza pontos.
</ResponseField>

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

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

**Query Parameters**

<ParamField query="purchaseValue" type="number" required>
  Valor total da compra.
</ParamField>

<ParamField query="checkoutCode" type="string">
  Identificador do carrinho (order\_form\_id). Opcional, mas recomendado para cálculos mais precisos.
</ParamField>

### Exemplo

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

<ResponseField name="MinValueToReceive" type="number">
  Valor mínimo da compra para receber pontos.
</ResponseField>

<ResponseField name="PurchasePoints" type="integer">
  Quantidade de pontos que o cliente ganhará nesta compra.
</ResponseField>

<ResponseField name="PurchaseCashback" type="number">
  Valor de cashback que o cliente ganhará nesta compra (se aplicável).
</ResponseField>

<ResponseField name="HasPurchaseObjective" type="boolean">
  Indica se existe um objetivo de compra configurado.
</ResponseField>

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

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

**Query Parameters**

<ParamField query="purchaseValue" type="number" required>
  Valor da compra. Usado para determinar quais recompensas são válidas para o carrinho.
</ParamField>

### Exemplo

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

<ResponseField name="ProgramName" type="string">
  Nome do programa de fidelidade.
</ResponseField>

<ResponseField name="PointsBalance" type="integer">
  Saldo de pontos do cliente.
</ResponseField>

<ResponseField name="HasError" type="boolean">
  Indica se houve erro na requisição.
</ResponseField>

<ResponseField name="Item" type="array">
  Lista de recompensas disponíveis para o valor do carrinho.
</ResponseField>

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

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

**Query Parameters**

<ParamField query="purchaseValue" type="number" required>
  Valor da compra.
</ParamField>

### Exemplo

```bash theme={null}
curl -X GET "https://api.bonifiq.com.br/pub/widget/rewards/checkout/redeemed?purchaseValue=100.00" \
  -H "X-Bq-Tenant: {tenant_key}"
```

### Resposta

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

<Warning>
  O parâmetro `id` deve ser o valor do campo `RedeemedId` retornado na consulta de recompensas resgatadas, não o ID da recompensa original.
</Warning>

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

<ParamField path="id" type="integer" required>
  ID do resgate (RedeemedId).
</ParamField>

**Body (Opcional)**

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

### Exemplo

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

<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="checkoutCode" type="string" required>
  Identificador do carrinho (order\_form\_id).
</ParamField>

**Body (POST)**

<ParamField body="CheckoutCode" 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/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" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutCode": "<order_form_id>"
  }'
```

### Resposta

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

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

### Requisição

`POST /pub/widget/rewards/checkout/{id}/reverse`

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

<ParamField path="id" type="integer" required>
  ID do resgate (RedeemedId) a ser removido do carrinho.
</ParamField>

### Exemplo

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

```json theme={null}
{
  "ProgramName": "Programa Fidelidade",
  "HasError": false,
  "Item": {
    "Success": true,
    "CouponCode": null,
    "Reward": null
  }
}
```