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 ┌─────────────────────────────────────────────────────────────────┐ │ Sua Aplicação │ │ │ │ Frontend (Browser/App) Backend (Servidor) │ │ ┌───────────────────┐ ┌───────────────────┐ │ │ │ │ │ │ │ │ │ API Widget │ │ API Privada │ │ │ │ (SecureToken) │ │ (API Key) │ │ │ │ │ │ │ │ │ │ API Pública │ │ │ │ │ │ (API Key pública)│ │ │ │ │ │ │ │ │ │ │ └───────┬───────────┘ └────────┬──────────┘ │ │ │ │ │ └───────────┼───────────────────────────────────┼─────────────────┘ │ │ ▼ ▼ ┌───────────────────────────────────────────────────────────────┐ │ API BonifiQ │ │ │ │ Webhooks ──────────────────► Seu Endpoint │ └───────────────────────────────────────────────────────────────┘
API Widget Para interfaces de fidelidade voltadas ao consumidor final
Quando Usar
Construir uma interface de fidelidade no seu site ou app
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
API Pública Para consultas simples a partir do frontend sem autenticação de consumidor
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)
API Privada Para integrações entre servidores com acesso completo
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
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)
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.
Webhooks
Webhooks Para reagir a eventos em tempo real
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 Preciso integrar a BonifiQ... ├─ No FRONTEND (browser/app do consumidor)? │ ├─ O consumidor está logado? │ │ ├─ SIM → API Widget (SecureToken) │ │ └─ NÃO → API Pública │ └─ É no checkout mobile? │ └─ SIM → API Widget (guia vtex-cashback-checkout) │ ├─ No BACKEND (servidor)? │ └─ SIM → API Privada (API Key) │ └─ Preciso REAGIR a eventos? └─ SIM → Webhooks
Combinando as APIs Na prática, a maioria das integrações usa mais de uma forma de integração:
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ App Mobile │────▶│ Seu Backend │────▶│ BonifiQ │ │ │ │ │ │ │ │ API Widget │ │ API Privada │ │ Webhooks │──▶ Seu Backend │ (pontos, │ │ (creditar │ │ (eventos) │ │ resgatar) │ │ pontos) │ │ │ └─────────────┘ └──────────────┘ └─────────────┘
App Mobile usa API Widget para exibir pontos e resgatar recompensasSeu Backend usa API Privada para creditar pontos de compras presenciaisWebhooks notificam seu backend quando pontos são creditados para enviar push notification
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
