Quando Usar Cada API

​

Visão Geral

​

API Widget (Frontend)

​

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

​

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

​

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

​

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)

​

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

​

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)

​

Webhooks

​

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

​

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

​

Comparativo Rápido

​

Árvore de Decisão

​

Combinando as APIs

​

Exemplo: App Mobile com Fidelidade

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