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

# Introdução

> Documentação de referência da API Widget da BonifiQ

A **API Widget** da BonifiQ é uma API pública projetada para integração com frontends de e-commerce, aplicativos móveis e outras interfaces de usuário. Ela permite que consumidores interajam com o programa de fidelidade diretamente na experiência de compra.

## Base URL

```
https://api.bonifiq.com.br/pub/widget
```

Todos os endpoints documentados nesta referência usam o prefixo `/pub/widget/`.

## Autenticação

A API Widget utiliza dois headers principais para autenticação:

### Headers Obrigatórios

<ParamField header="X-Bq-Tenant" type="string" required>
  Identificador público da loja (tenant). Este valor é fornecido pela BonifiQ durante a configuração da conta.
</ParamField>

<ParamField header="X-Bq-SecureToken" type="string">
  Token de segurança do usuário, obtido através do endpoint de login seguro (validade de 60 minutos). Obrigatório apenas nos endpoints autenticados.
</ParamField>

## Fluxo de Autenticação

```mermaid theme={null}
sequenceDiagram
    participant App as Aplicativo
    participant VTEX as Plataforma (VTEX/Wake)
    participant BQ as BonifiQ API
    
    App->>VTEX: Login do usuário
    VTEX-->>App: sessionToken + segmentToken
    App->>BQ: POST /vendors/vtex/securelogin
    BQ-->>App: SecureToken (válido 60min)
    App->>BQ: Requisições com X-Bq-SecureToken
```

## Estrutura de Resposta Padrão

A maioria dos endpoints retorna uma estrutura padrão `BaseWidgetResponse`:

```json theme={null}
{
  "HasError": false,
  "Message": null,
  "Item": {
    // Dados específicos do endpoint
  }
}
```

| Campo      | Tipo         | Descrição                          |
| ---------- | ------------ | ---------------------------------- |
| `HasError` | boolean      | Indica se houve erro na requisição |
| `Message`  | string       | Mensagem de erro ou sucesso        |
| `Item`     | object/array | Dados retornados pelo endpoint     |

## Códigos de Resposta HTTP

| Código | Descrição                                   |
| ------ | ------------------------------------------- |
| 200    | Sucesso                                     |
| 400    | Requisição inválida (parâmetros incorretos) |
| 401    | Não autorizado (token inválido ou expirado) |
| 404    | Recurso não encontrado                      |
| 500    | Erro interno do servidor                    |

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Autenticação" icon="key" href="/api-widget/01-authentication">
    Configure o login seguro para seus usuários
  </Card>

  <Card title="Cliente" icon="user" href="/api-widget/02-customer">
    Consulte saldo de pontos e informações do cliente
  </Card>

  <Card title="Recompensas" icon="gift" href="/api-widget/03-rewards">
    Liste e resgate recompensas disponíveis
  </Card>

  <Card title="Cashback" icon="coins" href="/api-widget/05-cashback">
    Aplique cashback no checkout
  </Card>
</CardGroup>