Construindo sua Interface de Fidelidade

Este guia ensina como construir sua própria interface de fidelidade (widget, app mobile, seção no site) consumindo a API Widget da BonifiQ. O foco aqui é entender o que cada funcionalidade resolve, quando usar, e como apresentar ao consumidor final.

O que você pode construir

Widget Customizado

Interface flutuante no seu e-commerce com sua identidade visual

Seção no App Mobile

Tela de fidelidade integrada ao seu aplicativo nativo

Página de Fidelidade

Landing page completa do programa de fidelidade

Integração no Checkout

Aplicação de recompensas e cashback durante a compra

Visão Geral das Funcionalidades

Cada funcionalidade da API Widget existe para resolver uma necessidade específica na jornada do consumidor. Antes de implementar, entenda o papel de cada uma:

Autenticação

O que é: Vincula o consumidor ao programa de fidelidade da BonifiQ, gerando um token seguro (SecureToken) que identifica o consumidor nas chamadas autenticadas. Quando usar: Sempre que o consumidor acessar endpoints autenticados (ex.: saldo, resgate, cashback no checkout, afiliados). Para endpoints públicos, a autenticação não é obrigatória.

Modelo de autenticação: você é o consumidor. A API Widget funciona no contexto do consumidor final. O SecureToken gerado representa aquele consumidor específico — e todas as chamadas feitas com esse token só acessam os dados dele (saldo, histórico, recompensas). Isso é diferente de uma API de backend tradicional, onde você autentica com credenciais da sua aplicação e pode consultar/interagir com qualquer cliente. Na API Widget, o escopo é sempre limitado ao consumidor autenticado.

Nem todos os endpoints da API Widget exigem X-BQ-SecureToken. A referência de cada endpoint informa explicitamente o status Público ou Autenticado.

O que você recebe após autenticar (em qualquer método):

SecureToken — token que identifica o consumidor (validade de 60 minutos)
Name, Email — dados para personalizar a experiência

O SecureToken expira em 60 minutos. Implemente renovação automática: se qualquer chamada retornar erro de autenticação, refaça o login silenciosamente.

Opção 1: Token por E-mail (Challenge)

O que é: Autenticação universal via código de verificação enviado por e-mail. O consumidor informa o e-mail, recebe um código de 6 dígitos e valida para obter o SecureToken. Quando usar: Ideal para qualquer plataforma — lojas próprias, apps mobile, plataformas sem integração nativa, ou quando você quer uma autenticação independente de plataforma de e-commerce. Onde exibir: Tela de login visível com dois passos:

Campo de e-mail → consumidor digita o e-mail e clica em “Enviar código”
Campo de código (estilo OTP) → consumidor digita o código de 6 dígitos recebido no e-mail

Fluxo:

Chame POST /account/challenge com o e-mail do consumidor → um código é enviado ao e-mail
Chame POST /account/validatechallenge com o e-mail + código → receba o SecureToken

APIs: POST /account/challenge + POST /account/validatechallenge

O código de verificação expira em 10 minutos. Se expirar, solicite um novo código refazendo a etapa 1.

Opção 2: Via Plataforma (Wake e VTEX)

O que é: Autenticação transparente que usa a sessão que o consumidor já tem na plataforma de e-commerce. Não exige interação do usuário — acontece em background. Quando usar: Quando sua loja roda em VTEX ou Wake e o consumidor já está logado na plataforma. A autenticação é automática e silenciosa. Onde exibir: Não é uma tela visível. A autenticação deve acontecer automaticamente em background assim que o consumidor acessar a área de fidelidade. Se falhar (consumidor não está logado na plataforma), exiba: “Faça login na loja para acessar seus pontos”.

Plataforma	API	Dados necessários
VTEX	`POST /vendors/vtex/securelogin`	`sessionToken` + `segmentToken` da sessão VTEX
Wake	`POST /vendors/fbits/securelogin`	Token de sessão do consumidor na Wake

Como funciona: A API da BonifiQ consulta a plataforma usando os tokens de sessão do consumidor para validar a identidade. Se o consumidor estiver logado na plataforma, o login seguro é bem-sucedido e retorna o SecureToken.

Informações do Cliente

Saldo de Pontos

O que é: O número de pontos (ou valor em cashback) que o consumidor tem disponível. Quando usar: Em toda tela que envolva fidelidade. O saldo é a informação mais importante — é o que motiva o consumidor a engajar. Onde exibir:

Tela inicial do widget: destaque principal
Header de navegação: sempre visível
Checkout: ao lado das opções de resgate
Push notifications: “Você tem 1.500 pontos! Resgate agora”

API: GET /customer/points (saldo rápido) ou GET /customer/info (saldo + dados completos)

Informações Completas

O que é: Dados do consumidor no programa: nome, saldo, nível/tier atual, data do último ponto. Quando usar: Na tela inicial/home do widget para dar ao cliente uma visão geral completa do status dele. Onde exibir: Tela principal de fidelidade, cabeçalho do perfil. API: GET /customer/info

Histórico de Pontos

O que é: Extrato completo de todas as movimentações de pontos — ganhos, gastos, expirados. Quando usar: Quando o consumidor quer entender de onde vieram seus pontos e como os usou. É essencial para transparência e confiança no programa. Onde exibir:

Aba “Extrato” ou “Histórico” no widget
Tela dedicada acessível a partir da home
Similar ao extrato bancário — lista paginada com data, descrição e valor

Por que é importante: Consumidores que entendem como ganham pontos tendem a engajar mais. Se ele vê “Compra #123: +150 pontos”, entende a relação entre comprar e ganhar. API: GET /customer/history?page={n}

Pontos a Expirar

O que é: Lista de lotes de pontos com data de expiração próxima. Quando usar: Para criar urgência e incentivar o resgate antes da expiração. Onde exibir:

Banner de alerta na home: “⚠️ 200 pontos expiram em 15 dias!”
Push notification / email de lembrete
Badge no ícone do widget

Por que é importante: É uma das maiores alavancas de conversão. Consumidores resgatam muito mais quando sabem que vão perder pontos. API: GET /customer/expiringpoints

Níveis / Tiers

O que é: Sistema de progressão onde o consumidor sobe de nível conforme acumula pontos ou compras, desbloqueando benefícios melhores. Quando usar: Apenas se o programa da loja tem tiers configurados. Verifique com o lojista. Onde exibir:

Home: badge com nível atual + barra de progresso até o próximo
Tela dedicada: lista de todos os níveis com benefícios de cada um
Mensagem motivacional: “Faltam 300 pontos para Ouro!”

Por que é importante: Tiers criam aspiração. O consumidor não quer apenas resgatar — ele quer subir de nível. Isso aumenta frequência de compra e ticket médio. API: GET /tiers (lista todos os níveis) + GET /customer/info (nível atual no campo CurrentTier)

Recompensas

O que é: Prêmios que o consumidor pode trocar por seus pontos — cupons de desconto, frete grátis, cashback, recompensas customizadas. Quando usar: É o coração do programa. Sem recompensas, não há motivo para acumular pontos. Onde exibir:

Aba “Recompensas” no widget — a mais acessada
Destaque na home: “3 recompensas disponíveis!”
Checkout: recompensas que se aplicam ao carrinho

Tipos de Recompensa e Quando Usar Cada Um

Tipo	O que é	Quando Exibir	Exemplo
Desconto %	Cupom de desconto percentual	Widget + Checkout	”10% de desconto por 100 pontos”
Desconto R$	Cupom de desconto em valor fixo	Widget + Checkout	”R$ 20 OFF por 200 pontos”
Frete Grátis	Cupom de frete grátis	Widget + Checkout	”Frete grátis por 150 pontos”
Cashback	Conversão de pontos em saldo monetário	Widget + Checkout	”Converter pontos em cashback”
Customizada	Qualquer prêmio definido pela loja	Widget	”Brinde exclusivo”, “Experiência VIP”

Elegibilidade

Cada recompensa retorna CanUse (boolean) e UseReason (motivo). Use isso para comunicar claramente ao consumidor:

UseReason	O que significa	Como comunicar
0	Disponível	Botão “Resgatar” habilitado
1	Pontos insuficientes	”Faltam X pontos”
2	Valor mínimo não atingido	”Válido para compras acima de R$ X”
5	Recompensa maior que a compra	”Adicione mais itens ao carrinho”
7	Cliente não cadastrado	”Cadastre-se no programa”

Regra de ouro: Nunca esconda recompensas que o cliente não pode usar. Mostre-as desabilitadas com o motivo — isso cria aspiração (“preciso de mais 50 pontos!”). APIs:

GET /rewards — listar recompensas (widget)
GET /rewards/checkout?purchaseValue={valor} — listar para o checkout (filtra por valor do carrinho)
POST /rewards/redeem/{id} — resgatar
GET /rewards/redeemed — cupons já resgatados mas não utilizados

Fluxo de Resgate

Recompensas já Resgatadas

O que é: Cupons que o consumidor já trocou por pontos mas ainda não usou em uma compra. Quando usar: Para lembrar o consumidor que ele tem cupons pendentes. É comum o consumidor resgatar e esquecer de usar. Onde exibir:

Seção “Meus Cupons” ou “Carteira” no widget
Lembrete no checkout: “Você tem um cupom de R$ 10 disponível!”
Push notification: “Seu cupom expira em 3 dias”

API: GET /rewards/redeemed

Cashback

O que é: Modelo onde o consumidor acumula saldo em reais (não em pontos) e pode usar esse saldo como desconto em compras futuras. Quando usar: Apenas se o programa usa cashback (verifique UseCashback na configuração do checkout). Onde exibir:

Home: “Saldo de cashback: R$ 25,00”
Checkout: componente de aplicação de cashback (ver guia de checkout)

Diferença entre pontos e cashback:

Pontos: consumidor troca por recompensas pré-definidas (cupom de 10%, R$ 20 OFF)
Cashback: consumidor escolhe o valor que quer usar (de R$ 1 até o máximo permitido)

Por que alguns programas preferem cashback: É mais simples para o consumidor entender (“você tem R$ 25 para usar”) e dá mais flexibilidade (ele escolhe quanto usar). APIs de cashback: Veja o guia completo de checkout e cashback.

Objetivos (Missões)

O que é: Ações que o consumidor pode realizar para ganhar pontos além de compras — indicar amigos, avaliar produtos, seguir redes sociais, responder quizzes. Quando usar: Para engajar o consumidor fora do momento de compra. Missões mantêm o consumidor ativo no programa entre compras. Por que é importante: Programas com missões têm 3x mais engajamento que programas só com compras. Cada missão cria um motivo para o consumidor voltar ao seu site/app. Onde exibir: Aba “Missões” ou “Ganhar Pontos” — geralmente a segunda aba mais importante depois de Recompensas. API: GET /objectives

Tipos de Missão e Quando Usar

🛒 Compra (Purchase)

O que resolve: Mostra ao consumidor quanto ele ganha por comprar. É informativo — os pontos são creditados automaticamente. Onde exibir: Na lista de missões + no checkout (“Você ganhará 150 pontos nesta compra”). Interação: Não tem ação do usuário. É apenas informativo.

🎂 Aniversário (Birthday)

O que resolve: Cria um vínculo emocional com o consumidor. Ele se sente valorizado ao receber um bônus no aniversário. Onde exibir: Na lista de missões. A tela muda conforme o estado:

Não cadastrado → Formulário para cadastrar data (DD/MM)
Cadastrado, fora do período → “Seu bônus estará disponível em ”
Bônus disponível → Botão de resgatar com destaque
Já resgatado → Card marcado como concluído

Cuidado: A data só pode ser cadastrada uma vez. Deixe isso claro na interface. API: POST /customer/setbirthday?birthday={data} + campo BenefitStatus do objetivo

👥 Indicação (Referral)

O que resolve: Transforma o consumidor em promotor da marca. É a forma mais barata de aquisição de novos clientes. Onde exibir: Na lista de missões. Ao clicar, abrir tela com:

Campo para digitar email do amigo
Botão de compartilhar via WhatsApp (usar WhatsAppShareText)
Botão de copiar link
Lista de indicações enviadas e status

Por que é poderoso: O consumidor indicado já chega com confiança (recomendação de amigo), e quem indicou ganha pontos. Todo mundo ganha. APIs:

POST /objectives/referral/refer — indicar por email
POST /objectives/referral/friend — gerar link
POST /objectives/referral/coupon — gerar cupom pro amigo
GET /objectives/referral/sent — ver indicações enviadas

⭐ Avaliação (Review)

O que resolve: Gera prova social para a loja (reviews) e engaja o consumidor com pontos extras. Onde exibir: Na lista de missões. Pode ter pontuação extra por comentário e foto:

Pontos base pela avaliação
+X pontos por deixar comentário (HasCommentPoint)
+X pontos por enviar foto (HasPhotoPoint)

Interação: Ao clicar, redirecionar para a URL de avaliação (GET /objectives/review/urls). O que resolve: Aumenta seguidores da loja nas redes sociais. Onde exibir: Na lista de missões, com ícone da rede social correspondente (Instagram, Facebook, LinkedIn, TikTok). Interação: Ao clicar, abrir o perfil da loja na rede social em nova aba/app. Quando o consumidor voltar, registrar o follow via POST /objectives/createpointsfollowsocialmedia.

A plataforma confia que o consumidor realmente seguiu. Não há verificação automática.

📝 Quiz

O que resolve: Coleta dados qualitativos do consumidor (preferências, feedback) enquanto engaja com pontos. Onde exibir: Na lista de missões/objetivos, misturado com os outros tipos. Ao clicar, abrir tela de perguntas estilo wizard (uma por vez, com barra de progresso). Tipos de pergunta:

Seleção única — radio buttons
Múltipla escolha — checkboxes
Resposta aberta — campo de texto

APIs: GET /quiz (listar) → GET /quiz/{uid} (perguntas) → POST /answer (responder)

🎯 Customizado (Custom)

O que resolve: Permite que a loja crie qualquer tipo de missão personalizada. Onde exibir: Na lista de missões, com ícone customizado (CustomIcon) e botão de ação (ActionButtonText). Interação: Ao clicar, redirecionar para ActionButtonURL. Pode ser qualquer coisa: participar de evento, preencher formulário, baixar app.

Regulamento (Terms)

O que é: Texto legal do programa de fidelidade — regras, condições de uso, política de privacidade, como funciona o acúmulo e resgate. Quando usar: É obrigatório em qualquer programa de fidelidade. O regulamento protege juridicamente tanto a loja quanto o consumidor. Onde exibir:

Link no rodapé do widget: “Regulamento do Programa”
Tela dedicada com scroll, acessível a qualquer momento
Durante o cadastro: “Ao participar, você concorda com o [regulamento]”
Antes de resgatar (opcional): link discreto nas regras da recompensa

Por que é importante:

Exigência legal para programas de fidelidade
O consumidor deve ter acesso fácil às regras
Evita disputas sobre como funciona o programa

API: GET /terms O que você recebe:

Content — HTML do regulamento, pronto para renderizar

Landing Page

O que é: Dados de customização da página pública do programa de fidelidade — textos, imagens, cores que a loja configurou no painel BonifiQ. Quando usar: Se você está construindo uma página pública de apresentação do programa (acessível sem login). Onde exibir:

Página “/fidelidade” ou “/programa-de-pontos” no site
Seção informativa antes do login
Material de divulgação do programa

Por que existe: Nem todo mundo que acessa é já membro. A landing page convence o visitante a se cadastrar, explicando os benefícios do programa. API: GET /landing-page

Configuração do Checkout

O que é: Informações sobre como o programa funciona no checkout — cores, nome, se usa pontos ou cashback. Quando usar: Para configurar visualmente o componente de fidelidade no checkout da loja. Onde exibir: No checkout, para estilizar o componente de fidelidade com as cores e textos do programa. Campos importantes:

ProgramName — nome para exibir (“Programa Fidelidade”)
Color — cor principal para botões e destaques
UseCashback / UsePoints — determina qual fluxo exibir
Active — se false, não exibir nada no checkout

API: GET /rewards/checkout/configuration

Afiliados

O que é: Informações sobre o programa de afiliados — histórico de comissões e vendas geradas pelo consumidor como afiliado. Quando usar: Apenas se a loja tem programa de afiliados configurado. Não é comum em todos os programas. Onde exibir: Seção separada “Meus Ganhos como Afiliado” — disponível apenas para consumidores que são afiliados (IsAffiliate = true em /customer/info). API: GET /affiliate/infohistory

Configuração Técnica

Setup do Cliente HTTP

Nem toda requisição precisa dos dois headers:

Header	Quando	Descrição
`X-BQ-Tenant`	Sempre	Identificador público da loja
`X-BQ-SecureToken`	Somente endpoints autenticados	Token do consumidor (60min)

const bonifiqApi = axios.create({
  baseURL: 'https://api.bonifiq.com.br/pub/widget',
  headers: { 'X-BQ-Tenant': 'SUA_TENANT_KEY' }
});

// Após login seguro, adicionar o SecureToken
bonifiqApi.defaults.headers['X-BQ-SecureToken'] = customer.SecureToken;

Tratamento de Erros

Todas as respostas seguem o mesmo formato. Use HasError para determinar sucesso/falha:

{
  "HasError": false,    // true = erro
  "Message": null,      // mensagem de erro quando HasError = true
  "Item": { ... }       // dados da resposta
}

Cenários de erro comuns:

Cenário	Como detectar	O que fazer
Token expirado	Status 401 ou `HasError: true`	Refazer login silenciosamente
Pontos insuficientes	`UseReason = 1`	Mostrar “Faltam X pontos”
Programa inativo	`Active = false`	Não exibir componente de fidelidade
Erro de rede	Timeout / erro HTTP	Exibir “Tente novamente” + botão retry

Estados de Interface

Toda tela deve considerar estes estados:

Estado	Quando	O que exibir
Loading	Aguardando API	Skeleton/shimmer nos cards
Sucesso	Dados carregados	Conteúdo normal
Lista vazia	`Item` é array vazio	”Nenhuma recompensa disponível” (com ilustração)
Erro	`HasError = true`	Mensagem de erro + botão “Tentar novamente”
Não autenticado	Sem SecureToken	”Faça login para ver seus pontos”

Estrutura de Navegação Recomendada

Seção	O que mostra	APIs
Home	Saldo + alertas + atalhos	`GET /customer/info`, `GET /customer/expiringpoints`
Missões	Formas de ganhar pontos	`GET /objectives`, `GET /quiz`
Recompensas	Formas de gastar pontos	`GET /rewards`
Carteira	Cupons resgatados não usados	`GET /rewards/redeemed`
Extrato	Histórico de movimentações	`GET /customer/history`
Níveis	Progressão do consumidor	`GET /tiers`
Regulamento	Regras do programa	`GET /terms`

Próximos Passos

Checkout e Cashback

Integre recompensas e cashback no checkout

Quando Usar Cada API

Entenda a diferença entre API Widget, Pública, Privada e Webhooks

Referência da API Widget

Documentação completa de todos os endpoints

Webhooks

Receba notificações em tempo real

Guias de Integração

​O que você pode construir

Widget Customizado

Seção no App Mobile

Página de Fidelidade

Integração no Checkout

​Visão Geral das Funcionalidades

​Autenticação

​Opção 1: Token por E-mail (Challenge)

​Opção 2: Via Plataforma (Wake e VTEX)

​Informações do Cliente

​Saldo de Pontos

​Informações Completas

​Histórico de Pontos

​Pontos a Expirar

​Níveis / Tiers

​Recompensas

​Tipos de Recompensa e Quando Usar Cada Um

​Elegibilidade

​Fluxo de Resgate

​Recompensas já Resgatadas

​Cashback

​Objetivos (Missões)

​Tipos de Missão e Quando Usar

​🛒 Compra (Purchase)

​🎂 Aniversário (Birthday)

​👥 Indicação (Referral)

​⭐ Avaliação (Review)

​📱 Redes Sociais (Social)

​📝 Quiz

​🎯 Customizado (Custom)

​Regulamento (Terms)

​Landing Page

​Configuração do Checkout

​Afiliados

​Configuração Técnica

​Setup do Cliente HTTP

​Tratamento de Erros

​Estados de Interface

​Estrutura de Navegação Recomendada

​Próximos Passos

Checkout e Cashback

Quando Usar Cada API

Referência da API Widget

Webhooks

O que você pode construir

Visão Geral das Funcionalidades

Autenticação

Opção 1: Token por E-mail (Challenge)

Opção 2: Via Plataforma (Wake e VTEX)

Informações do Cliente

Saldo de Pontos

Informações Completas

Histórico de Pontos

Pontos a Expirar

Níveis / Tiers

Recompensas

Tipos de Recompensa e Quando Usar Cada Um

Elegibilidade

Fluxo de Resgate

Recompensas já Resgatadas

Cashback

Objetivos (Missões)

Tipos de Missão e Quando Usar

🛒 Compra (Purchase)

🎂 Aniversário (Birthday)

👥 Indicação (Referral)

⭐ Avaliação (Review)

📱 Redes Sociais (Social)

📝 Quiz

🎯 Customizado (Custom)

Regulamento (Terms)

Landing Page

Configuração do Checkout

Afiliados

Configuração Técnica

Setup do Cliente HTTP

Tratamento de Erros

Estados de Interface

Estrutura de Navegação Recomendada

Próximos Passos