API de Checkout e Objetivos - BonifiQ Developers

A BonifiQ já oferece uma solução nativa para integrar diretamente ao Checkout da VTEX no modelo Web. No modelo Mobile, no entanto, requer que seja realizada a integração com as APIs da BonifiQ diretamente. As integrações abrangem login seguro, consulta e aplicação de recompensa, além de gerenciamento de objetivos (missões) de fidelidade. As chamadas são projetadas para garantir uma experiência segura e eficiente para o consumidor.

Principais Etapas

Login seguro: Autenticação do usuário e obtenção de token de segurança.
Configuração do checkout: Obtenção das configurações do programa de fidelidade.
Consulta de pontos da compra: Verificação de quantos pontos o cliente ganhará na compra.
Consulta de recompensas: Verificação do saldo e regras para utilização da recompensa.
Aplicação de recompensa: Resgate de recompensa no carrinho.
Consulta de recompensa aplicada: Verificação do estado da recompensa no carrinho.
Remoção de recompensa: Remover a recompensa aplicada a um carrinho.
Objetivos: Consultar e interagir com missões de fidelidade (compra, aniversário, indicação, review, redes sociais, quiz, etc.).

Guia Visual: Como Construir as Interfaces

Cada endpoint retorna dados que precisam ser traduzidos em interfaces. Abaixo está um guia prático de como o widget BonifiQ utiliza esses dados para construir cada tela.

Tela de Recompensas

A lista de recompensas deve exibir cards com as informações retornadas pela API. Cada tipo de recompensa tem um tratamento visual diferente:

┌──────────────────────────────────────────┐
│  Saldo disponível                        │
│  💰 1.500 pontos                         │
├──────────────────────────────────────────┤
│                                          │
│  ┌────────────────────────────────────┐  │
│  │ 🏷️  R$ 10,00 de desconto          │  │
│  │    100 pontos                      │  │
│  └────────────────────────────────────┘  │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │ 🏷️  10% de desconto               │  │
│  │    200 pontos                      │  │
│  └────────────────────────────────────┘  │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │ 🚚  Frete grátis                  │  │
│  │    500 pontos  ⚠️ Pontos insuf.   │  │
│  └────────────────────────────────────┘  │
│                                          │
└──────────────────────────────────────────┘

Mapeamento de dados → interface:

Campo da API	Elemento Visual
`Title`	Título do card (ex: “R$ 10,00”)
`Points`	Subtítulo (ex: “100 pontos”)
`Description`	Descrição expandida ao clicar
`CanUse`	Card habilitado ou desabilitado
`UseReason`	Mensagem quando `CanUse = false`
`Type`	Ícone (🏷️ desconto, 🚚 frete, 💰 cashback)
`Enabled`	Visibilidade do card

Tela de Detalhe da Recompensa

Ao clicar em uma recompensa, exibir detalhes e botão de resgate:

┌──────────────────────────────────────────┐
│  ← Voltar                                │
│                                          │
│        🏷️                                │
│    R$ 10,00 de desconto                  │
│    100 pontos                            │
│                                          │
├──────────────────────────────────────────┤
│  Regras de uso                           │
│  • Válido para compras acima de R$ 50    │
│  • Não acumulável com outros cupons      │
│  • Validade: 30 dias após resgate        │
├──────────────────────────────────────────┤
│                                          │
│  ┌────────────────────────────────────┐  │
│  │         RESGATAR                   │  │
│  └────────────────────────────────────┘  │
│                                          │
└──────────────────────────────────────────┘

Lógica do botão de resgate:

Se customer == null → mostrar “Participar do Programa” (redirecionar para cadastro)
Se PointsBalance < reward.Points → desabilitar botão
Se já resgatou → desabilitar botão
Ao resgatar: chamar POST /rewards/redeem/{id} → exibir cupom gerado

Tela de Objetivos (Missões)

Cada tipo de objetivo tem um card com ícone e comportamento diferentes:

┌──────────────────────────────────────────┐
│                                          │
│  ┌────────────────────────────────────┐  │
│  │ 🎂  Cadastre seu aniversário      │  │
│  │    200 pontos              ▶      │  │
│  └────────────────────────────────────┘  │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │ 🛒  Faça uma compra               │  │
│  │    10~500 pontos           ▶      │  │
│  └────────────────────────────────────┘  │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │ 👥  Indique um amigo              │  │
│  │    500 pontos              ▶      │  │
│  └────────────────────────────────────┘  │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │ ⭐  Avalie sua compra       ✓     │  │
│  │    50 pontos   (Completado)       │  │
│  └────────────────────────────────────┘  │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │ 📝  Quiz de boas-vindas           │  │
│  │    200 pontos              ▶      │  │
│  └────────────────────────────────────┘  │
│                                          │
└──────────────────────────────────────────┘

Comportamento por tipo de objetivo ao clicar:

Tipo	Ação ao Clicar	Tela Destino
Purchase	Informativo	Exibir descrição e regras de pontuação
Birthday	Cadastrar data	Formulário de data → `POST setbirthday`
Referral	Indicar amigo	Formulário de email ou botão de compartilhar link
Review	Redirecionar	Abrir URL de avaliação em nova aba
Social	Redirecionar	Abrir rede social → `POST createpointsfollowsocialmedia`
Quiz	Responder	Tela de perguntas e respostas
Signup	Informativo	Já completado automaticamente
Custom	Redirecionar	Abrir `ActionButtonURL` em nova aba

Tela de Aniversário (Birthday)

A tela muda completamente baseado no BenefitStatus:

Se BenefitStatus = 0 (Não cadastrado):    Se BenefitStatus = 2 (Disponível):
┌───────────────────────────┐              ┌───────────────────────────┐
│  🎂 Aniversário           │              │  🎂 Aniversário           │
│                           │              │                           │
│  Cadastre sua data de     │              │  Parabéns! Seu bônus      │
│  nascimento e ganhe       │              │  está disponível!         │
│  200 pontos!              │              │                           │
│                           │              │  🎁 200 pontos            │
│  ┌─────────────────────┐  │              │                           │
│  │  DD / MM             │  │              │  ┌─────────────────────┐  │
│  └─────────────────────┘  │              │  │    RESGATAR          │  │
│                           │              │  └─────────────────────┘  │
│  ┌─────────────────────┐  │              │                           │
│  │    CADASTRAR         │  │              └───────────────────────────┘
│  └─────────────────────┘  │
│                           │              Se BenefitStatus = 1 ou 3:
└───────────────────────────┘              Não exibir (card desabilitado)

Tela de Indicação (Referral)

┌──────────────────────────────────────────┐
│  ← Voltar                                │
│                                          │
│  👥 Indique amigos                       │
│  Ganhe 500 pontos por indicação          │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │ Email do amigo                     │  │
│  │ amigo@email.com                    │  │
│  └────────────────────────────────────┘  │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │         ENVIAR CONVITE             │  │
│  └────────────────────────────────────┘  │
│                                          │
│  ─── ou compartilhe ───                  │
│                                          │
│  ┌──────┐  ┌──────┐  ┌──────┐          │
│  │  📋  │  │  📱  │  │  🔗  │          │
│  │Copiar│  │Whats │  │ Link │          │
│  └──────┘  └──────┘  └──────┘          │
│                                          │
└──────────────────────────────────────────┘

Fluxo:

Email: POST /objectives/referral/refer com email
Link/WhatsApp: POST /objectives/referral/friend → gera link para compartilhar
O campo WhatsAppShareText do objetivo contém o texto pré-formatado

Tela de Quiz

┌──────────────────────────────────────────┐
│  📝 Quiz de boas-vindas                  │
│  Responda e ganhe 200 pontos!            │
│                                          │
│  Pergunta 1 de 3                         │
│  ━━━━━━━━━━━━━░░░░░░░░░░ (33%)          │
│                                          │
│  "Qual sua cor favorita?"                │
│                                          │
│  ○ Azul                                 │
│  ● Vermelho      ← selecionado          │
│  ○ Verde                                │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │         PRÓXIMA →                  │  │
│  └────────────────────────────────────┘  │
│                                          │
└──────────────────────────────────────────┘

Renderização por tipo de questão:

Type = 0 (Multiple) → Checkboxes (múltipla seleção)
Type = 1 (Selection) → Radio buttons (seleção única)
Type = 2 (Open) → Campo de texto livre

Checkout: Cashback

┌──────────────────────────────────────────┐
│  Checkout                                │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │ 💰 Cashback disponível             │  │
│  │                                    │  │
│  │ Saldo: R$ 50,00                    │  │
│  │ Utilizável nesta compra: R$ 25,00  │  │
│  │                                    │  │
│  │ Regra: Pague até 50% com cashback  │  │
│  │                                    │  │
│  │ Valor:  ┌──────────────────┐       │  │
│  │         │ R$ 25,00         │       │  │
│  │         └──────────────────┘       │  │
│  │                                    │  │
│  │ ┌──────────────────────────────┐   │  │
│  │ │      APLICAR CASHBACK        │   │  │
│  │ └──────────────────────────────┘   │  │
│  └────────────────────────────────────┘  │
│                                          │
│  Você ganhará R$ 5,00 de cashback        │
│  nesta compra                            │
│                                          │
└──────────────────────────────────────────┘

Mapeamento de dados → interface:

Campo da API	Elemento Visual
`CashbackBalance`	”Saldo: R$ 50,00”
`UsableCashback`	”Utilizável nesta compra: R$ 25,00”
`CashbackRules`	Texto de regras
`CanUse`	Botão habilitado/desabilitado
`CashbackWillReceiveText`	Mensagem de quanto ganhará
`MinValueToUse`	Mensagem de valor mínimo
`RequiredToAddMoreText`	Mensagem de quanto falta

Estados de Interface

Toda tela deve considerar estes estados:

Estado	Quando	Como exibir
Loading	Aguardando resposta da API	Skeleton/shimmer nos cards
Sucesso	Dados carregados	Renderizar conteúdo
Lista vazia	`Item` é array vazio	”Nenhuma recompensa disponível”
Erro	`HasError = true`	Exibir `Message` + botão “Tentar novamente”
Não autenticado	Sem `SecureToken`	Exibir CTA de login
Sem pontos	`CanUse = false`	Card desabilitado + motivo (`UseReason`)

O primeiro passo é realizar o login do usuário e obter o seu token de segurança. Esse token de segurança será utilizado em todas as chamadas subsequentes. O sessionToken e o segmentToken deverão ser obtidos mediante login na VTEX.

O SecureToken tem validade limitada e deve ser atualizado periodicamente.

Requisição

POST /pub/widget/vendors/vtex/securelogin Headers

X-Bq-Tenant

string

required

Identificador público da loja.

Body

sessionToken

string

required

Gerado pela plataforma de e-commerce após o login do consumidor.

segmentToken

string

required

Gerado pela plataforma de e-commerce.

Exemplo

curl -X POST "https://api.bonifiq.com/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.

Item

object

Show Properties

string

E-mail do usuário.

Name

string

Nome completo do usuário.

UserId

string

Identificador do usuário.

SecureToken

string

Token de segurança do usuário, com validade de 60 minutos.

{
  "HasError": false,
  "Message": null,
  "Item": {
    "Email": "usuario@dominio.com",
    "Name": "Nome Completo",
    "UserId": "usuario@dominio.com",
    "SecureToken": "742b9b93-c1dc-4ec1-8f92-6b3a1838c613"
  }
}

2. Obter Configuração do Checkout

Essa etapa é utilizada para obter as configurações do programa de fidelidade para o checkout, como cores, nome do programa e se utiliza pontos ou cashback.

Requisição

GET /pub/widget/rewards/checkout/configuration Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Exemplo

curl -X GET "https://api.bonifiq.com/pub/widget/rewards/checkout/configuration" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Resposta

Text

string

Texto customizado para exibição no checkout.

ProgramName

string

Nome do programa de fidelidade.

Color

string

Cor principal do programa (hexadecimal).

Active

boolean

Indica se o programa está ativo.

UseCashback

boolean

Indica se o programa utiliza cashback.

UsePoints

boolean

Indica se o programa utiliza pontos.

{
  "Text": "Resgate seus pontos!",
  "ProgramName": "Programa Fidelidade",
  "Color": "#FF5722",
  "Active": true,
  "UseCashback": true,
  "UsePoints": true
}

3. Consultar Pontos da Compra

Essa etapa é utilizada para exibir ao cliente quantos pontos (ou cashback) ele ganhará na compra atual. Ideal para exibir mensagens como “Você ganhará X pontos nesta compra”.

Requisição

GET /pub/widget/rewards/checkout/purchase-points Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Query Parameters

purchaseValue

number

required

Valor da compra.

checkoutCode

string

Identificador do carrinho (order_form_id). Opcional.

Exemplo

curl -X GET "https://api.bonifiq.com/pub/widget/rewards/checkout/purchase-points?purchaseValue=150.00&checkoutCode=abc123" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Resposta

MinValueToReceive

number

Valor mínimo da compra para receber pontos.

PurchasePoints

integer

Quantidade de pontos que o cliente ganhará nesta compra.

PurchaseCashback

number

Valor de cashback que o cliente ganhará nesta compra (se aplicável).

HasPurchaseObjective

boolean

Indica se existe um objetivo de compra configurado.

{
  "MinValueToReceive": 50.00,
  "PurchasePoints": 150,
  "PurchaseCashback": 7.50,
  "HasPurchaseObjective": true
}

4. Buscar Recompensas

Essa etapa será utilizada para a listagem de recompensas disponíveis para o usuário logado.

Requisição

GET /pub/widget/rewards/checkout Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Query Parameters

purchaseValue

number

required

Valor da compra. É utilizado para determinar quais recompensas (e valores) são válidos para o carrinho.

Exemplo

curl -X GET "https://api.bonifiq.com/pub/widget/rewards/checkout?purchaseValue=100.00" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Resposta

ProgramName

string

Nome do programa de fidelidade.

PointsBalance

integer

Saldo de pontos do cliente.

HasError

boolean

Indica se houve erro na requisição.

Item

array

Lista de recompensas.

Show Item Object

integer

Identificador da recompensa.

Type

integer

Tipo da recompensa (0 = Percentual, 1 = Valor fixo).

Title

string

Título da recompensa.

Points

integer

Quantidade de pontos necessários para resgatar.

Description

string

Descrição da recompensa.

Enabled

boolean

Indica se a recompensa está habilitada.

CanUse

boolean

Indica se o cliente pode usar esta recompensa.

UseReason

integer

Motivo da disponibilidade/indisponibilidade (ver tabela abaixo).

RemainingToUse

number

Valor restante para atingir o mínimo (se UseReason for 2).

MinValueToUse

number

Valor mínimo do carrinho para usar esta recompensa.

{
  "ProgramName": "VTEX IO QA",
  "PointsBalance": 10000,
  "HasError": false,
  "Message": null,
  "Item": [
    {
      "Id": 301,
      "Type": 1,
      "Title": "R$ 100,00",
      "Points": 100,
      "Description": "Descrição da recompensa...",
      "Enabled": true,
      "CanUse": true,
      "UseReason": 0,
      "RemainingToUse": 0,
      "MinValueToUse": 0
    }
  ]
}

Enumeração `UseReason`

Valor	Descrição
0	CanUse (Recompensa disponível para uso)
1	NotEnoughPoints
2	MinValueNotReached
3	CashbackNotAvailable
4	NoCustomer
5	ValueRewardBiggerThanPurchase
6	MinimumPercentPurchaseNotReached
7	CustomerNotEnrolled

4.1. Buscar Recompensas já Resgatadas

Essa etapa será utilizada para a listagem de recompensas já resgatadas e não utilizadas pelo consumidor.

Requisição

GET /pub/widget/rewards/checkout/redeemed Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Query Parameters

purchaseValue

number

required

Valor da compra.

Exemplo

curl -X GET "https://api.bonifiq.com/pub/widget/rewards/checkout/redeemed?purchaseValue=100.00" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Resposta

{
  "HasError": false,
  "Message": null,
  "Item": [
    {
      "RedeemedId": 1302,
      "RedeemedPoints": -10,
      "RedeemedValue": 0,
      "Id": 302,
      "Type": 0,
      "Title": "10%",
      "Points": 10,
      "CanUse": true,
      "UseReason": 0
    }
  ]
}

5. Aplicar Recompensa

Essa etapa será utilizada para a aplicação de recompensas ainda não resgatadas.

Requisição

POST /pub/widget/rewards/redeem/{reward_id} Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters

reward_id

integer

required

ID da recompensa a ser resgatada.

Body (Opcional)

OriginalId

string

Identificador do carrinho (order_form_id).

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/redeem/301" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "OriginalId": "<order_form_id>"
  }'

Resposta

{
  "HasError": false,
  "Message": "Tudo Certo! Em breve você irá receber um e-mail com mais instruções",
  "Item": {
    "Success": true,
    "ResultMessage": "Utilize seu cupom nesta compra:",
    "CouponCode": "c806711b278a463d8e787f5f5c409f89",
    "HasCouponCode": true,
    "Reward": {
      "RedeemedId": 1416,
      "Title": "2%",
      "Points": 2
    }
  }
}

5.1. Aplicar Recompensa já Resgatada

Essa etapa será utilizada para a aplicação de recompensas já resgatadas.

Requisição

POST /pub/widget/rewardredeemed/checkout/redeem/{reward_redeemed_id}

O valor de reward_redeemed_id deverá ser o valor retornado na propriedade RedeemedId da seção “Buscar Recompensas já Resgatadas”.

Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters

reward_redeemed_id

integer

required

ID da recompensa resgatada.

Body (Opcional)

OriginalId

string

Identificador do carrinho (order_form_id).

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/rewardredeemed/checkout/redeem/1302" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "OriginalId": "<order_form_id>"
  }'

6. Validar Cashback

Essa etapa é utilizada para verificar se o cliente pode utilizar cashback e qual o valor disponível. Deve ser chamada antes de aplicar o cashback.

Requisição

GET /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID} ou POST /pub/widget/rewards/checkout/cashback Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters (GET)

ORDER_FORM_ID

string

required

Identificador do carrinho.

Body (POST)

CheckoutId

string

required

Identificador do carrinho (order_form_id).

Exemplo (GET)

curl -X GET "https://api.bonifiq.com/pub/widget/rewards/checkout/cashback/abc123" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Exemplo (POST)

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/checkout/cashback" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutId": "<order_form_id>"
  }'

Resposta

CashbackBalance

number

Saldo total de cashback do cliente.

UsableCashback

number

Valor de cashback que pode ser utilizado nesta compra.

MaxUsableCashback

number

Valor máximo de cashback permitido para esta compra.

CashbackRules

string

Regras de utilização do cashback (texto para exibição).

CanUse

boolean

Indica se o cliente pode usar cashback nesta compra.

CashbackWillReceiveText

string

Texto informando quanto cashback o cliente receberá.

RequiredToAddMoreText

string

Texto informando quanto falta para usar o cashback.

IsCashbackAvailable

boolean

Indica se o cashback está disponível.

RemainingToTotalCashback

number

Valor restante para usar todo o cashback.

RemainingToUse

number

Valor restante para atingir o mínimo necessário.

hasProductsIneligibleForCashback

boolean

Indica se há produtos no carrinho que não são elegíveis para cashback.

MinValueToUse

number

Valor mínimo do carrinho para usar cashback.

{
  "CashbackBalance": 50.00,
  "UsableCashback": 25.00,
  "MaxUsableCashback": 50.00,
  "CashbackRules": "Pague até 50% da compra com cashback.",
  "CanUse": true,
  "CashbackWillReceiveText": "Você receberá R$ 5,00 de cashback nesta compra",
  "RequiredToAddMoreText": null,
  "IsCashbackAvailable": true,
  "RemainingToTotalCashback": 0,
  "RemainingToUse": 0,
  "hasProductsIneligibleForCashback": false,
  "MinValueToUse": 20.00
}

6.1. Aplicar Cashback

Essa etapa será utilizada para a aplicação de cashback.

Requisição

POST /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeem ou POST /pub/widget/rewards/checkout/cashback/redeem Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters (primeira opção)

ORDER_FORM_ID

string

required

Identificador do carrinho.

Body

CheckoutId

string

Identificador do carrinho (order_form_id). Obrigatório na segunda opção (sem path param).

CashbackValue

number

required

Valor do cashback a ser resgatado.

RedeemOrigin

integer

required

Origem do resgate. Use 3 para checkout mobile.

Total

number

required

Valor do carrinho (sem descontos ou frete).

Exemplo (com path param)

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/checkout/cashback/abc123/redeem" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CashbackValue": 25.00,
    "RedeemOrigin": 3,
    "Total": 150.00
  }'

Exemplo (com body)

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/checkout/cashback/redeem" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutId": "<order_form_id>",
    "CashbackValue": 25.00,
    "RedeemOrigin": 3,
    "Total": 150.00
  }'

Resposta

{
  "AppliedCashback": 25.00,
  "Success": true,
  "CustomerMessage": "Cashback resgatado com sucesso.",
  "CashbackRules": "Pague até 50% da compra com cashback.",
  "InternalMessage": null,
  "CouponCode": null
}

6.2. Consultar Cashback Aplicado

Essa etapa é utilizada para verificar se há cashback aplicado ao carrinho.

Requisição

GET /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeemed ou POST /pub/widget/rewards/checkout/cashback/redeemed Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters (GET)

ORDER_FORM_ID

string

required

Identificador do carrinho.

Body (POST)

CheckoutId

string

required

Identificador do carrinho (order_form_id).

Exemplo (GET)

curl -X GET "https://api.bonifiq.com/pub/widget/rewards/checkout/cashback/abc123/redeemed" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Resposta

{
  "AppliedCashback": 25.00,
  "Success": true,
  "CustomerMessage": "Você está utilizando R$ 25,00 de cashback.",
  "CashbackRules": "Pague até 50% da compra com cashback.",
  "InternalMessage": null,
  "CouponCode": null
}

6.3. Atualizar Cashback (Refresh)

Essa etapa é utilizada para recalcular o cashback quando o carrinho é alterado (itens adicionados/removidos).

Requisição

POST /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/refresh ou POST /pub/widget/rewards/checkout/cashback/refresh Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters (primeira opção)

ORDER_FORM_ID

string

required

Identificador do carrinho.

Body (segunda opção)

CheckoutId

string

required

Identificador do carrinho (order_form_id).

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/checkout/cashback/refresh" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutId": "<order_form_id>"
  }'

Resposta

CashbackRemoved

boolean

Indica se o cashback foi removido (por exemplo, se o carrinho ficou abaixo do mínimo).

CustomerMessage

string

Mensagem para exibir ao cliente.

{
  "CashbackRemoved": false,
  "CustomerMessage": "Cashback atualizado com sucesso."
}

7. Consultar Recompensa Aplicada

Esta etapa será utilizada para o caso do cliente sair da tela do checkout e seja necessário reaplicar o estado de recompensa resgatada a ele.

Requisição (GET)

GET /pub/widget/rewards/checkout/{checkoutCode}

Requisição (POST)

POST /pub/widget/rewards/checkout Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters (GET)

checkoutCode

string

required

Identificador do carrinho (order_form_id).

Body (POST)

CheckoutCode

string

required

Identificador do carrinho (order_form_id).

Exemplo (GET)

curl -X GET "https://api.bonifiq.com/pub/widget/rewards/checkout/abc123" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Exemplo (POST)

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/checkout" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutCode": "<order_form_id>"
  }'

Resposta

{
  "ProgramName": "VTEX IO QA",
  "HasError": false,
  "Item": {
    "Success": true,
    "CouponCode": "c806711b278a463d8e787f5f5c409f89",
    "Reward": {
      "Id": 302,
      "Title": "10%",
      "Points": 10,
      "CanUse": false
    }
  }
}

8. Remover Recompensa Aplicada

Esta etapa será utilizada para remoção de uma recompensa que foi aplicada ao carrinho.

Este método apenas remove a recompensa resgatada do carrinho. Ele não realiza o estorno dos pontos para a carteira do consumidor e nem cancela o resgate da recompensa.

Requisição

POST /pub/widget/rewards/checkout/{reward_redeemed_id}/reverse Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters

reward_redeemed_id

integer

required

ID da recompensa resgatada a ser removida do carrinho.

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/checkout/1416/reverse" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

8.1. Remover Cashback Aplicado

Esta etapa será utilizada para remoção de um cashback que foi aplicado ao carrinho.

Este método remove o cashback do carrinho e também realiza o estorno dos pontos de volta à carteira do consumidor, diferentemente da remoção de recompensa.

Requisição

DELETE /pub/widget/rewards/checkout/cashback/{ORDER_FORM_ID}/redeem ou POST /pub/widget/rewards/checkout/cashback/redeem/remove Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters (DELETE)

ORDER_FORM_ID

string

required

Identificador do carrinho.

Body (POST)

CheckoutId

string

required

Identificador do carrinho (order_form_id).

Total

number

Valor do carrinho (sem descontos ou frete). Opcional.

Exemplo (DELETE)

curl -X DELETE "https://api.bonifiq.com/pub/widget/rewards/checkout/cashback/abc123/redeem" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Exemplo (POST)

curl -X POST "https://api.bonifiq.com/pub/widget/rewards/checkout/cashback/redeem/remove" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "CheckoutId": "<order_form_id>",
    "Total": 150.00
  }'

Resposta

Success

boolean

Indica se a operação foi bem sucedida.

CustomerMessage

string

Mensagem para exibir ao cliente.

{
  "Success": true,
  "CustomerMessage": "O cashback foi removido com sucesso"
}

9. Consultar Objetivos

Essa etapa é utilizada para listar os objetivos (missões) disponíveis para o cliente no programa de fidelidade. Objetivos são formas de ganhar pontos como compras, indicações, aniversário, etc.

Requisição

GET /pub/widget/objectives Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Exemplo

curl -X GET "https://api.bonifiq.com/pub/widget/objectives" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Resposta

HasError

boolean

Indica se houve erro na requisição.

Item

array

Lista de objetivos disponíveis.

Show Objetivo Object

integer

Identificador do objetivo. Corresponde ao ObjectiveType.

Type

integer

Tipo do objetivo (ver tabela abaixo).

Title

string

Título do objetivo.

Description

string

Descrição do objetivo.

DetailedDescription

string

Descrição detalhada (pode conter HTML).

Points

integer

Quantidade de pontos que o cliente ganha ao completar.

IsCompleted

boolean

Indica se o objetivo já foi completado pelo cliente.

CanRedeem

boolean

Indica se o objetivo pode ser resgatado pelo cliente.

MinPoints

number

Pontos mínimos ganhos (quando há faixa variável).

MaxPoints

number

Pontos máximos ganhos (quando há faixa variável).

HasMaxUses

boolean

Indica se o objetivo tem limite de usos.

MaxUses

integer

Número máximo de vezes que pode ser completado.

Value

number

Valor associado ao objetivo (ex: valor mínimo de compra).

{
  "HasError": false,
  "Item": [
    {
      "Id": 0,
      "Type": 0,
      "Title": "Faça uma compra",
      "Description": "Ganhe pontos a cada compra realizada",
      "Points": 100,
      "IsCompleted": false,
      "CanRedeem": false,
      "MinPoints": 10,
      "MaxPoints": 500
    },
    {
      "Id": 2,
      "Type": 2,
      "Title": "Cadastre seu aniversário",
      "Description": "Ganhe pontos bônus no seu aniversário",
      "Points": 200,
      "IsCompleted": false,
      "CanRedeem": false,
      "BenefitStatus": 0
    },
    {
      "Id": 4,
      "Type": 4,
      "Title": "Indique um amigo",
      "Description": "Ganhe pontos por cada amigo que comprar",
      "Points": 500,
      "IsCompleted": false,
      "CanRedeem": false,
      "WhatsAppShareText": "Cadastre-se e ganhe desconto!"
    }
  ]
}

Enumeração `ObjectiveType`

Valor	Tipo	Descrição
0	Purchase	Fazer uma compra
1	Signup	Criar conta
2	Birthday	Aniversário
3	Review	Fazer avaliação
4	Referral	Indicar amigo
5	SocialMediaFollowInstagram	Seguir no Instagram
6	SocialMediaFollowFacebook	Seguir no Facebook
9	SocialMediaFollowLinkedin	Seguir no LinkedIn
10	SocialMediaFollowTikTok	Seguir no TikTok
999	Custom	Objetivo customizado

9.1. Objetivo de Compra (Purchase)

O objetivo de compra informa ao cliente quantos pontos ele ganhará ao realizar compras. Os pontos são atribuídos automaticamente quando a compra é confirmada.

Este objetivo é informativo. Os pontos são creditados automaticamente pela plataforma ao confirmar o pedido. Não é necessário chamar nenhum endpoint para “completar” este objetivo.

Campos específicos:

Campo	Tipo	Descrição
`MinPoints`	number	Pontos mínimos que o cliente pode ganhar
`MaxPoints`	number	Pontos máximos que o cliente pode ganhar
`Value`	number	Valor em reais por ponto (ex: R$ 1 = 1 ponto)
`HasMaxUses`	boolean	Se há limite de compras que geram pontos

Exemplo de exibição:

“Ganhe de 10 a 500 pontos a cada compra realizada”

9.2. Objetivo de Aniversário (Birthday)

O objetivo de aniversário permite ao cliente cadastrar sua data de nascimento e receber um bônus. O bônus pode ser em pontos ou em recompensa (cupom de desconto).

Fluxo

Verificar o BenefitStatus do objetivo
Se BenefitStatus = 0, exibir formulário para cadastrar data
Chamar endpoint para salvar aniversário
Se BenefitStatus = 2, o bônus está disponível para resgate

Enumeração `BenefitStatus`

Valor	Status	Descrição
0	BirthDayDateNotSet	Data de nascimento não cadastrada
1	BirthDayDateSetAfterAvailablePeriod	Data cadastrada, fora do período do bônus
2	BirthDayBenefitAvailable	Bônus de aniversário disponível para resgate
3	BirthDayBenefitRedeemed	Bônus já resgatado

Cadastrar Aniversário

POST /pub/widget/customer/setbirthday Query Parameters

birthday

string

required

Data de aniversário no formato dd/MM ou yyyy-MM-dd.

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/customer/setbirthday?birthday=15/03" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Campos específicos do objetivo de aniversário:

Campo	Tipo	Descrição
`BenefitStatus`	integer	Status atual do benefício (ver tabela acima)
`PointBasedBonification`	boolean	Se `true`, o bônus é em pontos. Se `false`, é uma recompensa
`RewardType`	integer	Tipo da recompensa (quando não é por pontos)
`RewardValue`	number	Valor da recompensa
`MinimalValue`	number	Valor mínimo de compra para usar a recompensa

A data de aniversário só pode ser cadastrada uma vez. Após definida, não pode ser alterada.

9.3. Objetivo de Indicação (Referral)

O objetivo de indicação permite que o cliente indique amigos e ganhe pontos quando o amigo indicado realiza uma compra.

9.3.1. Indicar Amigo por Email

POST /pub/widget/objectives/referral/refer Body

string

required

E-mail do amigo a ser indicado.

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/objectives/referral/refer" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "amigo@email.com"
  }'

9.3.2. Gerar Link de Indicação

POST /pub/widget/objectives/referral/friend Gera um link de indicação que pode ser compartilhado via WhatsApp, redes sociais ou copiado. Body

channel

string

Canal de compartilhamento (ex: whatsapp, copy).

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/objectives/referral/friend" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp"
  }'

9.3.3. Gerar Cupom para Amigo

POST /pub/widget/objectives/referral/coupon Gera um cupom de desconto que será utilizado pelo amigo indicado na primeira compra.

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/objectives/referral/coupon" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json"

9.3.4. Consultar Indicações Enviadas

GET /pub/widget/objectives/referral/sent Retorna a lista de indicações feitas pelo cliente e o status de cada uma.

Exemplo

curl -X GET "https://api.bonifiq.com/pub/widget/objectives/referral/sent" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Campos específicos do objetivo de indicação:

Campo	Tipo	Descrição
`WhatsAppShareText`	string	Texto pré-formatado para compartilhar via WhatsApp
`ReferralUrl`	string	URL base para o link de indicação

9.4. Objetivo de Review (Review)

O objetivo de review recompensa o cliente por avaliar produtos ou a loja.

Consultar URLs de Avaliação

GET /pub/widget/objectives/review/urls Retorna as URLs de avaliação disponíveis para o cliente (ex: avaliações de pedidos recentes).

Exemplo

curl -X GET "https://api.bonifiq.com/pub/widget/objectives/review/urls" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Resposta

{
  "HasError": false,
  "Item": [
    {
      "Url": "https://loja.com/review/pedido-123",
      "OrderId": "pedido-123"
    }
  ]
}

Campos específicos do objetivo de review:

Campo	Tipo	Descrição
`IsStoreReview`	boolean	Se `true`, é avaliação da loja. Se `false`, é de produto
`HasCommentPoint`	boolean	Se comentários na avaliação dão pontos extras
`CommentPoints`	number	Pontos extras por deixar um comentário
`HasPhotoPoint`	boolean	Se enviar foto na avaliação dá pontos extras
`PhotoPoints`	number	Pontos extras por enviar foto
`ReviewAllowRedirect`	boolean	Se deve redirecionar o cliente para a URL de review

Exemplo de exibição:

“Avalie sua compra e ganhe 50 pontos + 20 pontos extras por comentário + 30 pontos extras por foto”

9.5. Objetivos de Redes Sociais

Esses objetivos recompensam o cliente por seguir a loja nas redes sociais.

Registrar Follow

POST /pub/widget/objectives/createpointsfollowsocialmedia Body

Tipo da rede social (ver tabela abaixo).

Valor	Rede Social
5	Instagram
6	Facebook
9	LinkedIn
10	TikTok

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/objectives/createpointsfollowsocialmedia" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "pointTypeSocialMedia": 5
  }'

Resposta

{
  "HasError": false,
  "Item": {
    "Points": 100,
    "Valid": true
  }
}

Os pontos de redes sociais são baseados na confiança — a plataforma registra que o cliente clicou para seguir, mas não verifica automaticamente se ele realmente seguiu.

9.6. Quiz

Quizzes são enquetes interativas que recompensam o cliente por responder perguntas.

9.6.1. Listar Quizzes

GET /pub/widget/quiz

Exemplo

curl -X GET "https://api.bonifiq.com/pub/widget/quiz" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Resposta

{
  "HasError": false,
  "Item": [
    {
      "Id": 1,
      "Name": "Quiz de boas-vindas",
      "AmountOfPoints": 200,
      "AttemptsLeft": 1,
      "IsCompleted": false,
      "Questions": [
        {
          "Id": 10,
          "Question": "Qual sua cor favorita?",
          "Order": 1,
          "Type": 1,
          "Options": [
            { "Id": 100, "Text": "Azul", "Order": 1 },
            { "Id": 101, "Text": "Vermelho", "Order": 2 },
            { "Id": 102, "Text": "Verde", "Order": 3 }
          ]
        }
      ]
    }
  ]
}

Tipos de Questão

Valor	Tipo	Descrição
0	Multiple	Múltipla escolha (várias opções podem ser selecionadas)
1	Selection	Seleção única (apenas uma opção)
2	Open	Resposta aberta (texto livre)

9.6.2. Obter Quiz Específico

GET /pub/widget/quiz/{uid} Path Parameters

uid

string

required

Identificador único do quiz.

9.6.3. Responder Quiz

POST /pub/widget/answer Body Array de respostas, onde cada item contém:

QuizQuestionId

integer

required

ID da questão sendo respondida.

OptionIds

array

IDs das opções selecionadas (para questões Multiple e Selection).

OpenAnswer

string

Resposta em texto livre (para questões Open).

Exemplo

curl -X POST "https://api.bonifiq.com/pub/widget/answer" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "QuizQuestionId": 10,
      "OptionIds": [100]
    },
    {
      "QuizQuestionId": 11,
      "OpenAnswer": "Minha resposta em texto"
    }
  ]'

9.7. Objetivo Customizado (Custom)

Objetivos customizados são configurados pela loja e podem representar qualquer ação personalizada. Eles possuem um botão de ação que redireciona o cliente para uma URL externa. Campos específicos:

Campo	Tipo	Descrição
`ActionButtonText`	string	Texto do botão de ação (ex: “Participar”)
`ActionButtonURL`	string	URL para onde o cliente será redirecionado
`CustomIcon`	string	URL do ícone customizado do objetivo

Exemplo de exibição:

“Participe do evento exclusivo e ganhe 300 pontos” [Botão: “Participar” → redireciona para URL]

9.8. Resgatar Objetivo

Para objetivos que permitem resgate manual (como aniversário ou signup), utilize este endpoint.

Requisição

GET /pub/widget/objectives/{objectiveType}/redeem Headers

X-Bq-Tenant

string

required

Identificador da loja.

X-Bq-SecureToken

string

required

Token do usuário obtido no login seguro.

Path Parameters

objectiveType

integer

required

Tipo do objetivo a ser resgatado (ver tabela ObjectiveType).

Exemplo

curl -X GET "https://api.bonifiq.com/pub/widget/objectives/2/redeem" \
  -H "X-Bq-Tenant: {tenant_key}" \
  -H "X-Bq-SecureToken: {secure_token}"

Resposta

{
  "HasError": false,
  "Item": {
    "Success": true,
    "ResultMessage": "Pontos creditados com sucesso!",
    "CouponCode": null,
    "HasCouponCode": false
  }
}

Primeiros Passos

​Principais Etapas

​Guia Visual: Como Construir as Interfaces

​Tela de Recompensas

​Tela de Detalhe da Recompensa

​Tela de Objetivos (Missões)

​Tela de Aniversário (Birthday)

​Tela de Indicação (Referral)

​Tela de Quiz

​Checkout: Cashback

​Estados de Interface

​1. Fazer Login Seguro

​Requisição

​Exemplo

​Resposta

​2. Obter Configuração do Checkout

​Requisição

​Exemplo

​Resposta

​3. Consultar Pontos da Compra

​Requisição

​Exemplo

​Resposta

​4. Buscar Recompensas

​Requisição

​Exemplo

​Resposta

​Enumeração UseReason

​4.1. Buscar Recompensas já Resgatadas

​Requisição

​Exemplo

​Resposta

​5. Aplicar Recompensa

​Requisição

​Exemplo

​Resposta

​5.1. Aplicar Recompensa já Resgatada

​Requisição

​Exemplo

​6. Validar Cashback

​Requisição

​Exemplo (GET)

​Exemplo (POST)

​Resposta

​6.1. Aplicar Cashback

​Requisição

​Exemplo (com path param)

​Exemplo (com body)

​Resposta

​6.2. Consultar Cashback Aplicado

​Requisição

​Exemplo (GET)

​Resposta

​6.3. Atualizar Cashback (Refresh)

​Requisição

​Exemplo

​Resposta

​7. Consultar Recompensa Aplicada

​Requisição (GET)

​Requisição (POST)

​Exemplo (GET)

​Exemplo (POST)

​Resposta

​8. Remover Recompensa Aplicada

​Requisição

​Exemplo

​8.1. Remover Cashback Aplicado

​Requisição

​Exemplo (DELETE)

​Exemplo (POST)

​Resposta

​9. Consultar Objetivos

​Requisição

​Exemplo

​Resposta

​Enumeração ObjectiveType

​9.1. Objetivo de Compra (Purchase)

​9.2. Objetivo de Aniversário (Birthday)

​Fluxo

​Enumeração BenefitStatus

Principais Etapas

Guia Visual: Como Construir as Interfaces

Tela de Recompensas

Tela de Detalhe da Recompensa

Tela de Objetivos (Missões)

Tela de Aniversário (Birthday)

Tela de Indicação (Referral)

Tela de Quiz

Checkout: Cashback

Estados de Interface

1. Fazer Login Seguro

Requisição

Exemplo

Resposta

2. Obter Configuração do Checkout

Requisição

Exemplo

Resposta

3. Consultar Pontos da Compra

Requisição

Exemplo

Resposta

4. Buscar Recompensas

Requisição

Exemplo

Resposta

Enumeração `UseReason`

4.1. Buscar Recompensas já Resgatadas

Requisição

Exemplo

Resposta

5. Aplicar Recompensa

Requisição

Exemplo

Resposta

5.1. Aplicar Recompensa já Resgatada

Requisição

Exemplo

6. Validar Cashback

Requisição

Exemplo (GET)

Exemplo (POST)

Resposta

6.1. Aplicar Cashback

Requisição

Exemplo (com path param)

Exemplo (com body)

Resposta

6.2. Consultar Cashback Aplicado

Requisição

Exemplo (GET)

Resposta

6.3. Atualizar Cashback (Refresh)

Requisição

Exemplo

Resposta

7. Consultar Recompensa Aplicada

Requisição (GET)

Requisição (POST)

Exemplo (GET)

Exemplo (POST)

Resposta

8. Remover Recompensa Aplicada

Requisição

Exemplo

8.1. Remover Cashback Aplicado

Requisição

Exemplo (DELETE)

Exemplo (POST)

Resposta

9. Consultar Objetivos

Requisição

Exemplo

Resposta

Enumeração `ObjectiveType`

9.1. Objetivo de Compra (Purchase)

9.2. Objetivo de Aniversário (Birthday)

Fluxo

Enumeração `BenefitStatus`

Cadastrar Aniversário