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

> Endpoints para listar e resgatar recompensas disponíveis

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

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

### Exemplo

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

### Resposta

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

<ResponseField name="Item" type="array">
  Lista de recompensas disponíveis.

  <Expandable title="Propriedades de cada recompensa">
    <ResponseField name="Id" type="integer">
      Identificador único da recompensa.
    </ResponseField>

    <ResponseField name="Type" type="integer">
      Tipo da recompensa (ver tabela de tipos abaixo).
    </ResponseField>

    <ResponseField name="Title" type="string">
      Título da recompensa (ex: "R\$ 10,00", "10%", "Frete Grátis").
    </ResponseField>

    <ResponseField name="Points" type="integer">
      Quantidade de pontos necessários para resgatar.
    </ResponseField>

    <ResponseField name="Description" type="string">
      Descrição detalhada da recompensa.
    </ResponseField>

    <ResponseField name="Enabled" type="boolean">
      Indica se a recompensa está habilitada.
    </ResponseField>

    <ResponseField name="DisabledReason" type="string">
      Motivo pelo qual a recompensa está desabilitada (se aplicável).
    </ResponseField>

    <ResponseField name="CanUse" type="boolean">
      Indica se o cliente pode usar esta recompensa.
    </ResponseField>

    <ResponseField name="UseReason" type="integer">
      Código do motivo de disponibilidade/indisponibilidade (ver tabela abaixo).
    </ResponseField>

    <ResponseField name="NoPointCost" type="boolean">
      Indica se a recompensa não tem custo em pontos.
    </ResponseField>

    <ResponseField name="CashbackBalance" type="number">
      Saldo de cashback disponível (para recompensas tipo cashback).
    </ResponseField>

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

    <ResponseField name="CashbackPointValue" type="number">
      Valor em reais de cada ponto para conversão em cashback.
    </ResponseField>

    <ResponseField name="CashbackAmount" type="number">
      Valor de cashback da recompensa.
    </ResponseField>

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

    <ResponseField name="IsCashbackInformativeOnly" type="boolean">
      Indica se o cashback é apenas informativo.
    </ResponseField>

    <ResponseField name="CashbackInformativeText" type="string">
      Texto informativo sobre o cashback.
    </ResponseField>

    <ResponseField name="RemainingToUse" type="number">
      Valor restante para atingir o mínimo de uso.
    </ResponseField>

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

    <ResponseField name="MaxUsableCashback" type="number">
      Valor máximo de cashback utilizável.
    </ResponseField>

    <ResponseField name="WidgetIconActive" type="boolean">
      Indica se há ícone customizado para o widget.
    </ResponseField>

    <ResponseField name="WidgetIcon" type="string">
      URL do ícone para exibição no widget.
    </ResponseField>

    <ResponseField name="LandingPageIconActive" type="boolean">
      Indica se há ícone customizado para a landing page.
    </ResponseField>

    <ResponseField name="LandingPageIcon" type="string">
      URL do ícone para exibição na landing page.
    </ResponseField>

    <ResponseField name="ShouldUseCustomInstruction" type="boolean">
      Indica se deve usar instruções customizadas.
    </ResponseField>

    <ResponseField name="Rules" type="object">
      Regras de configuração da recompensa.
    </ResponseField>
  </Expandable>
</ResponseField>

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

<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 da recompensa a ser resgatada.
</ParamField>

**Body (Opcional)**

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

### Exemplo

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

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

<ResponseField name="Message" type="string">
  Mensagem de sucesso ou erro.
</ResponseField>

<ResponseField name="Item" type="object">
  <Expandable title="Propriedades">
    <ResponseField name="Success" type="boolean">
      Indica se o resgate foi bem-sucedido.
    </ResponseField>

    <ResponseField name="ResultMessage" type="string">
      Mensagem de resultado para exibir ao cliente.
    </ResponseField>

    <ResponseField name="Code" type="string">
      Código interno do resgate.
    </ResponseField>

    <ResponseField name="CouponCode" type="string">
      Código do cupom gerado para uso no checkout.
    </ResponseField>

    <ResponseField name="HasCouponCode" type="boolean">
      Indica se um código de cupom foi gerado.
    </ResponseField>

    <ResponseField name="AfterMessage" type="string">
      Mensagem adicional após o resgate.
    </ResponseField>

    <ResponseField name="Reward" type="object">
      Detalhes da recompensa resgatada.

      <Expandable title="Propriedades">
        <ResponseField name="RedeemedId" type="integer">
          ID do resgate realizado.
        </ResponseField>

        <ResponseField name="Title" type="string">
          Título da recompensa.
        </ResponseField>

        <ResponseField name="Points" type="integer">
          Pontos utilizados no resgate.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

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

<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/redeemed" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"
```

### Resposta

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

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

### Exemplo

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

```json theme={null}
{
  "HasError": false,
  "Message": null,
  "Item": {
    "CashbackBalance": 50.00,
    "CashbackRules": "Pague até 50% da compra com cashback",
    "MinValueToUse": 20.00
  }
}
```