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

# Quando Usar Cada API

> Entenda qual API da BonifiQ usar em cada cenário de integração

A BonifiQ oferece quatro formas de integração, cada uma projetada para um cenário específico. Escolher a forma correta é essencial para segurança, performance e manutenibilidade da sua integração.

## Visão Geral

<img src="https://mintcdn.com/bonifiq/GKwMiRtr4XYxzOf1/images/quando-usar/visao-geral.svg?fit=max&auto=format&n=GKwMiRtr4XYxzOf1&q=85&s=c84c9abae44f3ea583e051b2f242f28a" alt="" width="1400" height="760" data-path="images/quando-usar/visao-geral.svg" />

***

## API Widget (Frontend)

<Card title="API Widget" icon="window" href="/api-widget/00-introduction">
  Para interfaces de fidelidade voltadas ao consumidor final
</Card>

### Quando Usar

* Construir uma **interface de fidelidade** no seu site ou app (landing page/widget)
* Exibir saldo de pontos, recompensas, objetivos no **frontend**
* Permitir que o consumidor **resgate recompensas** ou **aplique cashback**
* Integrar fidelidade no **checkout mobile**

### Características

| Aspecto          | Detalhe                                                                  |
| ---------------- | ------------------------------------------------------------------------ |
| **Autenticação** | `X-BQ-Tenant` + `X-BQ-SecureToken` (token do consumidor, validade 60min) |
| **Chamada de**   | Frontend (browser, app mobile, webview)                                  |
| **Escopo**       | Dados do consumidor logado                                               |
| **Segurança**    | Token vinculado ao consumidor, não expõe dados de outros clientes        |

### Cenários Típicos

* Widget de fidelidade customizado no e-commerce
* Tela de "Meus Pontos" no app mobile
* Checkout com cashback no app
* Quiz e missões para o consumidor

### Exemplo de Fluxo

```
1. Consumidor faz login no seu site/app
2. Seu backend obtém sessionToken/segmentToken da VTEX
3. Chama POST /vendors/vtex/securelogin → recebe SecureToken
4. Frontend usa SecureToken para chamar APIs do widget
5. Exibe pontos, recompensas, objetivos
```

***

## API Pública

<Card title="API Pública" icon="lock-open" href="/api-public/introduction">
  Para consultas simples a partir do frontend sem autenticação de consumidor
</Card>

### Quando Usar

* Exibir informações **públicas** do programa de fidelidade
* Consultas que **não dependem** de um consumidor logado
* Operações de **leitura** genéricas

### Características

| Aspecto          | Detalhe                                  |
| ---------------- | ---------------------------------------- |
| **Autenticação** | Chave pública da loja                    |
| **Chamada de**   | Frontend (browser)                       |
| **Escopo**       | Dados públicos do programa               |
| **Segurança**    | Não expõe dados pessoais de consumidores |

### Cenários Típicos

* Exibir o nome e regras do programa de fidelidade na landing page
* Mostrar informações genéricas antes do login

***

## API Privada (Backend)

<Card title="API Privada" icon="camera-security" href="/api-private/introduction">
  Para integrações entre servidores com acesso completo
</Card>

### Quando Usar

* Integrar a BonifiQ com **ERPs, CRMs, PDVs** ou outros sistemas backend
* Realizar operações **administrativas** (creditar/debitar pontos, gerenciar clientes)
* Processar **pedidos** e sincronizar dados entre sistemas
* Qualquer operação que exija **acesso privilegiado**

### Características

| Aspecto          | Detalhe                                                    |
| ---------------- | ---------------------------------------------------------- |
| **Autenticação** | API Key privada (nunca expor no frontend!)                 |
| **Chamada de**   | Servidor/Backend apenas                                    |
| **Escopo**       | Acesso completo: clientes, pontos, pedidos, recompensas    |
| **Segurança**    | Chave secreta, deve ser armazenada em variável de ambiente |

### Cenários Típicos

* PDV/PoS creditando pontos após venda presencial
* ERP sincronizando pedidos com a BonifiQ
* Sistema administrativo consultando histórico de clientes
* Automações de marketing (creditar bônus, campanhas)
* Migração de dados de outro programa de fidelidade
* Integração com Data Lakes ou relatórios

### Exemplo de Fluxo

```
1. Pedido é confirmado no seu ERP
2. Backend chama API Privada da BonifiQ
3. Credita pontos na conta do cliente
4. BonifiQ dispara webhook de pontos creditados (opcional)
```

<Warning>
  **Nunca** exponha a API Key privada no frontend, código JavaScript do browser, ou repositórios públicos. Use variáveis de ambiente no servidor.
</Warning>

***

## Webhooks

<Card title="Webhooks" icon="link-horizontal" href="/webhooks/01-introducao">
  Para reagir a eventos em tempo real
</Card>

### Quando Usar

* Receber **notificações em tempo real** quando algo acontece na BonifiQ
* Sincronizar dados **automaticamente** sem precisar fazer polling
* Disparar ações no seu sistema em resposta a eventos de fidelidade

### Características

| Aspecto       | Detalhe                                                    |
| ------------- | ---------------------------------------------------------- |
| **Direção**   | BonifiQ → Seu endpoint (push)                              |
| **Formato**   | HTTP POST com payload JSON                                 |
| **Escopo**    | Eventos configurados (pontos, pedidos, comunicações, etc.) |
| **Segurança** | Assinatura de validação no header                          |

### Cenários Típicos

* Atualizar sistema interno quando **pontos são creditados**
* Enviar notificação push quando **recompensa é resgatada**
* Sincronizar **status de pedidos** entre sistemas
* Disparar email customizado quando **cliente sobe de nível**
* Atualizar CRM quando **novo cliente** entra no programa
* Registrar quando **afiliado** gera venda

### Eventos Disponíveis

| Tópico           | Eventos                                 |
| ---------------- | --------------------------------------- |
| **Pontos**       | Pontos creditados, debitados, expirados |
| **Pedidos**      | Pedido criado, atualizado, cancelado    |
| **Comunicações** | Email enviado, notificação disparada    |
| **Afiliados**    | Venda por afiliado registrada           |
| **Clientes**     | Cliente criado, atualizado              |

***

## Comparativo Rápido

|                | API Widget        | API Pública   | API Privada     | Webhooks        |
| -------------- | ----------------- | ------------- | --------------- | --------------- |
| **Chamada de** | Frontend          | Frontend      | Backend         | BonifiQ → Você  |
| **Auth**       | SecureToken       | Chave pública | API Key privada | Assinatura      |
| **Escopo**     | Consumidor logado | Público       | Completo        | Eventos         |
| **Operações**  | Leitura + resgate | Leitura       | CRUD completo   | Receber eventos |
| **Segurança**  | Média             | Baixa         | Alta            | Média           |

### Árvore de Decisão

<img src="https://mintcdn.com/bonifiq/GKwMiRtr4XYxzOf1/images/quando-usar/arvore-decisao.svg?fit=max&auto=format&n=GKwMiRtr4XYxzOf1&q=85&s=366a5d836277e3d8e0cc453bda2d2aa5" alt="" width="1400" height="920" data-path="images/quando-usar/arvore-decisao.svg" />

***

## Combinando as APIs

Na prática, a maioria das integrações usa **mais de uma** forma de integração:

### Exemplo: App Mobile com Fidelidade

<img src="https://mintcdn.com/bonifiq/GKwMiRtr4XYxzOf1/images/quando-usar/app-mobile-fidelidade.svg?fit=max&auto=format&n=GKwMiRtr4XYxzOf1&q=85&s=0b37518cd0f7d271c01f9ac589b1dc15" alt="" width="1400" height="520" data-path="images/quando-usar/app-mobile-fidelidade.svg" />

1. **App Mobile** usa **API Widget** para exibir pontos e resgatar recompensas
2. **Seu Backend** usa **API Privada** para creditar pontos de compras presenciais
3. **Webhooks** notificam seu backend quando pontos são creditados para enviar push notification

### Exemplo: E-commerce com PDV

```
1. Site usa API Widget → consumidor vê pontos e resgata cupons
2. PDV usa API Privada → credita pontos de vendas presenciais  
3. Webhook de pontos → atualiza dashboard do gerente em tempo real
```