Skip to main content
A autenticação na API Widget vincula o consumidor ao programa de fidelidade da BonifiQ, gerando um SecureToken necessário para acessar endpoints autenticados (saldo, resgate, cashback, afiliados, etc.).
Modelo de autenticação: você é o consumidor. 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 SecureToken representa um consumidor específico. Todas as chamadas feitas com esse token só acessam os dados dele (saldo, histórico, recompensas). O escopo é sempre limitado ao consumidor autenticado.
Existem duas formas de autenticar:
  • Token por e-mail (Challenge) — método universal, funciona em qualquer plataforma
  • Via plataforma (Wake ou VTEX) — autenticação transparente usando a sessão existente do consumidor
Endpoints marcados como Público não exigem SecureToken. Apenas o header X-BQ-Tenant é necessário.

​
Status de Autenticação dos Endpoints

EndpointStatus
POST /pub/widget/account/challengePúblico
POST /pub/widget/account/validatechallengePúblico
POST /pub/widget/account/loginPúblico
POST /pub/widget/vendors/vtex/secureloginPúblico
POST /pub/widget/vendors/fbits/secureloginPúblico

​
Autenticação via Token por E-mail (Challenge)

Método universal de autenticação em duas etapas: o consumidor informa o e-mail, recebe um código de verificação de 6 dígitos, e valida o código para obter o SecureToken. Ideal para: lojas próprias, apps mobile, plataformas sem integração nativa, ou qualquer cenário onde você quer uma autenticação independente de plataforma de e-commerce.

​
Etapa 1: Solicitar Código de Verificação

Envia um código de 6 dígitos para o e-mail do consumidor.

​
Requisição

POST /pub/widget/account/challenge Headers
​
X-Bq-Tenant
string
required
Identificador público da loja.
Body
​
email
string
required
E-mail do consumidor que receberá o código de verificação.

​
Exemplo de Request

curl -X POST "https://api.bonifiq.com.br/pub/widget/account/challenge" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "joao@email.com"
  }'

​
Resposta

​
HasError
boolean
Indica se houve erro na requisição.
​
Message
string
Mensagem de erro, se aplicável.
{
  "HasError": false,
  "Message": null,
  "Item": null
}
Uma resposta sem erro indica que o código foi enviado ao e-mail. O consumidor deve verificar a caixa de entrada (e spam).
O código de verificação expira em 10 minutos. Se expirar, solicite um novo código refazendo esta etapa.

​
Etapa 2: Validar Código e Obter SecureToken

Valida o código de 6 dígitos informado pelo consumidor e retorna o SecureToken.

​
Requisição

POST /pub/widget/account/validatechallenge Headers
​
X-Bq-Tenant
string
required
Identificador público da loja.
Body
​
email
string
required
E-mail do consumidor (o mesmo usado na etapa 1).
​
code
string
required
Código de verificação de 6 dígitos recebido pelo consumidor no e-mail.

​
Exemplo de Request

curl -X POST "https://api.bonifiq.com.br/pub/widget/account/validatechallenge" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "joao@email.com",
    "code": "482910"
  }'

​
Resposta

​
HasError
boolean
Indica se houve erro na requisição.
​
Message
string
Mensagem de erro, se aplicável.
​
Item
object
{
  "HasError": false,
  "Message": null,
  "Item": {
    "Email": "joao@email.com",
    "Name": "João Silva",
    "UserId": "joao@email.com",
    "SecureToken": "742b9b93-c1dc-4ec1-8f92-6b3a1838c613"
  }
}

​
Cenários de Erro

CenárioHasErrorMessage
Código inválidotrueCódigo de verificação inválido
Código expirado (>10 min)trueCódigo expirado. Solicite um novo código
E-mail não encontradotrueConsumidor não encontrado

​
Autenticação via Plataformas (Wake e VTEX)

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. Ideal para: lojas que rodam em VTEX ou Wake onde o consumidor já está logado na plataforma. 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, o login seguro é bem-sucedido e retorna o SecureToken.

​
Login Seguro VTEX

Autentica um consumidor que já está logado na plataforma VTEX, utilizando os tokens de sessão da VTEX.

​
Requisição

POST /pub/widget/vendors/vtex/securelogin Headers
​
X-Bq-Tenant
string
required
Identificador público da loja.
Body
​
sessionToken
string
required
Token de sessão gerado pela VTEX após o login do consumidor.
​
segmentToken
string
required
Token de segmento gerado pela VTEX.
Na VTEX, os tokens sessionToken e segmentToken são gerados automaticamente quando o consumidor faz login. Eles podem ser obtidos via Session Manager da VTEX ou através dos cookies de sessão.

​
Exemplo de Request

curl -X POST "https://api.bonifiq.com.br/pub/widget/vendors/vtex/securelogin" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionToken": "<session_token>",
    "segmentToken": "<segment_token>"
  }'

​
Resposta

​
HasError
boolean
Indica se houve erro na requisição.
​
Message
string
Mensagem de erro, se aplicável.
​
Item
object
{
  "HasError": false,
  "Message": null,
  "Item": {
    "Email": "joao@email.com",
    "Name": "João Silva",
    "UserId": "joao@email.com",
    "SecureToken": "742b9b93-c1dc-4ec1-8f92-6b3a1838c613"
  }
}

​
Cenários de Erro

CenárioHasErrorMessage
Consumidor não logado na VTEXtrueSessão inválida ou expirada
Tokens de sessão inválidostrueNão foi possível validar a sessão VTEX

​
Login Seguro Wake

Autentica um consumidor que já está logado na plataforma Wake.

​
Requisição

POST /pub/widget/vendors/fbits/securelogin Headers
​
X-Bq-Tenant
string
required
Identificador público da loja.
Body
​
CustomerToken
string
required
Token de sessão do consumidor na plataforma Wake.
Na Wake, o CustomerToken é gerado automaticamente quando o consumidor faz login na loja. Ele pode ser obtido através da API de sessão da Wake ou dos cookies de autenticação.

​
Exemplo de Request

curl -X POST "https://api.bonifiq.com.br/pub/widget/vendors/fbits/securelogin" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "CustomerToken": "token-de-sessao-wake..."
  }'

​
Resposta

​
HasError
boolean
Indica se houve erro na requisição.
​
Message
string
Mensagem de erro, se aplicável.
​
Item
object
{
  "HasError": false,
  "Message": null,
  "Item": {
    "Email": "maria@email.com",
    "Name": "Maria Souza",
    "UserId": "maria@email.com",
    "SecureToken": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

​
Cenários de Erro

CenárioHasErrorMessage
Consumidor não logado na WaketrueSessão inválida ou expirada
Token de sessão inválidotrueNão foi possível validar a sessão Wake

​
Login com E-mail e Senha

Autentica um consumidor diretamente com credenciais da BonifiQ. Método alternativo para integrações que utilizam cadastro próprio no programa de fidelidade.

​
Requisição

POST /pub/widget/account/login Headers
​
X-Bq-Tenant
string
required
Identificador público da loja.
Body
​
email
string
required
E-mail do consumidor.
​
password
string
required
Senha do consumidor.

​
Exemplo de Request

curl -X POST "https://api.bonifiq.com.br/pub/widget/account/login" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "joao@email.com",
    "password": "senha123"
  }'

​
Resposta

​
HasError
boolean
Indica se houve erro na requisição.
​
Message
string
Mensagem de erro, se aplicável.
​
Item
object
{
  "HasError": false,
  "Message": null,
  "Item": {
    "Email": "joao@email.com",
    "Name": "João Silva",
    "UserId": "joao@email.com",
    "SecureToken": "742b9b93-c1dc-4ec1-8f92-6b3a1838c613"
  }
}

​
Cenários de Erro

CenárioHasErrorMessage
Credenciais inválidastrueE-mail ou senha incorretos
Consumidor não encontradotrueConsumidor não encontrado

​
Renovação do Token

O SecureToken tem validade de 60 minutos. Após a expiração, é necessário realizar um novo login para obter um novo token.
Recomendação de implementação:
  1. Intercepte erros de autenticação — se qualquer chamada autenticada retornar status 401 ou HasError: true com mensagem de token expirado, refaça o login automaticamente
  2. Renovação proativa — armazene o timestamp de quando o token foi gerado e renove antes dos 60 minutos (ex: aos 55 minutos)
  3. Transparência para o usuário — a renovação deve ser silenciosa, sem exigir interação do consumidor
// Exemplo de interceptor para renovação automática (Axios)
bonifiqApi.interceptors.response.use(
  response => response,
  async error => {
    if (error.response?.status === 401) {
      // Refazer login silenciosamente
      const newToken = await refreshSecureLogin();
      bonifiqApi.defaults.headers['X-BQ-SecureToken'] = newToken;
      // Repetir a requisição original
      error.config.headers['X-BQ-SecureToken'] = newToken;
      return bonifiqApi.request(error.config);
    }
    return Promise.reject(error);
  }
);