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:

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:

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:

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:

Tela de Indicação (Referral)

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

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

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

string

required

Identificador público da loja.

Body

string

required

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

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

boolean

Indica se houve erro na requisição.

object

Show Properties

string

E-mail do usuário.

string

Nome completo do usuário.

string

Identificador do usuário.

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

string

required

Identificador da loja.

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

string

Texto customizado para exibição no checkout.

string

Nome do programa de fidelidade.

string

Cor principal do programa (hexadecimal).

boolean

Indica se o programa está ativo.

boolean

Indica se o programa utiliza cashback.

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

string

required

Identificador da loja.

string

required

Token do usuário obtido no login seguro.

Query Parameters

number

required

Valor da compra.

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

number

Valor mínimo da compra para receber pontos.

integer

Quantidade de pontos que o cliente ganhará nesta compra.

number

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

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

string

required

Identificador da loja.

string

required

Token do usuário obtido no login seguro.

Query Parameters

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

string

Nome do programa de fidelidade.

integer

Saldo de pontos do cliente.

boolean

Indica se houve erro na requisição.

array

Lista de recompensas.

Show Item Object

integer

Identificador da recompensa.

integer

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

string

Título da recompensa.

integer

Quantidade de pontos necessários para resgatar.

string

Descrição da recompensa.

boolean

Indica se a recompensa está habilitada.

boolean

Indica se o cliente pode usar esta recompensa.

integer

Motivo da disponibilidade/indisponibilidade (ver tabela abaixo).

number

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

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

string

required

Identificador da loja.

string

required

Token do usuário obtido no login seguro.

Query Parameters

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

string

required

Identificador da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters

integer

required

ID da recompensa a ser resgatada.

Body (Opcional)

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

string

required

Identificador da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters

integer

required

ID da recompensa resgatada.

Body (Opcional)

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

string

required

Identificador da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters (GET)

string

required

Identificador do carrinho.

Body (POST)

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

number

Saldo total de cashback do cliente.

number

Valor de cashback que pode ser utilizado nesta compra.

number

Valor máximo de cashback permitido para esta compra.

string

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

boolean

Indica se o cliente pode usar cashback nesta compra.

string

Texto informando quanto cashback o cliente receberá.

string

Texto informando quanto falta para usar o cashback.

boolean

Indica se o cashback está disponível.

number

Valor restante para usar todo o cashback.

number

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

boolean

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

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

string

required

Identificador da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters (primeira opção)

string

required

Identificador do carrinho.

Body

string

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

number

required

Valor do cashback a ser resgatado.

integer

required

Origem do resgate. Use 3 para checkout mobile.

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

string

required

Identificador da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters (GET)

string

required

Identificador do carrinho.

Body (POST)

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

string

required

Identificador da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters (primeira opção)

string

required

Identificador do carrinho.

Body (segunda opção)

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

boolean

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

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

string

required

Identificador da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters (GET)

string

required

Identificador do carrinho (order_form_id).

Body (POST)

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

string

required

Identificador da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters

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

string

required

Identificador da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters (DELETE)

string

required

Identificador do carrinho.

Body (POST)

string

required

Identificador do carrinho (order_form_id).

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

boolean

Indica se a operação foi bem sucedida.

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

string

required

Identificador da loja.

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

boolean

Indica se houve erro na requisição.

array

Lista de objetivos disponíveis.

Show Objetivo Object

integer

Identificador do objetivo. Corresponde ao ObjectiveType.

integer

Tipo do objetivo (ver tabela abaixo).

string

Título do objetivo.

string

Descrição do objetivo.

string

Descrição detalhada (pode conter HTML).

integer

Quantidade de pontos que o cliente ganha ao completar.

boolean

Indica se o objetivo já foi completado pelo cliente.

boolean

Indica se o objetivo pode ser resgatado pelo cliente.

number

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

number

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

boolean

Indica se o objetivo tem limite de usos.

integer

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

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

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

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

string

required

Identificador único do quiz.

9.6.3. Responder Quiz

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

integer

required

ID da questão sendo respondida.

array

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

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

string

required

Identificador da loja.

string

required

Token do usuário obtido no login seguro.

Path Parameters

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
  }
}

​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

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