> ## Documentation Index > Fetch the complete documentation index at: https://developers.bonifiq.com.br/llms.txt > Use this file to discover all available pages before exploring further. # API de Checkout e Objetivos > Integre a BonifiQ ao checkout Mobile da sua loja VTEX e gerencie objetivos de fidelidade 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 1. **Login seguro:** Autenticação do usuário e obtenção de token de segurança. 2. **Configuração do checkout:** Obtenção das configurações do programa de fidelidade. 3. **Consulta de pontos da compra:** Verificação de quantos pontos o cliente ganhará na compra. 4. **Consulta de recompensas:** Verificação do saldo e regras para utilização da recompensa. 5. **Aplicação de recompensa:** Resgate de recompensa no carrinho. 6. **Consulta de recompensa aplicada:** Verificação do estado da recompensa no carrinho. 7. **Remoção de recompensa:** Remover a recompensa aplicada a um carrinho. 8. **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:** 1. **Email**: `POST /objectives/referral/refer` com email 2. **Link/WhatsApp**: `POST /objectives/referral/friend` → gera link para compartilhar 3. 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`) | *** ## 1. Fazer Login Seguro 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** Identificador público da loja. **Body** Gerado pela plataforma de e-commerce após o login do consumidor. Gerado pela plataforma de e-commerce. ### Exemplo ```bash theme={null} 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": "", "segmentToken": "" }' ``` ### Resposta Indica se houve erro na requisição. E-mail do usuário. Nome completo do usuário. Identificador do usuário. Token de segurança do usuário, com validade de 60 minutos. ```json theme={null} { "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** Identificador da loja. Token do usuário obtido no login seguro. ### Exemplo ```bash theme={null} 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 Texto customizado para exibição no checkout. Nome do programa de fidelidade. Cor principal do programa (hexadecimal). Indica se o programa está ativo. Indica se o programa utiliza cashback. Indica se o programa utiliza pontos. ```json theme={null} { "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** Identificador da loja. Token do usuário obtido no login seguro. **Query Parameters** Valor da compra. Identificador do carrinho (order\_form\_id). Opcional. ### Exemplo ```bash theme={null} 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 Valor mínimo da compra para receber pontos. Quantidade de pontos que o cliente ganhará nesta compra. Valor de cashback que o cliente ganhará nesta compra (se aplicável). Indica se existe um objetivo de compra configurado. ```json theme={null} { "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** Identificador da loja. Token do usuário obtido no login seguro. **Query Parameters** Valor da compra. É utilizado para determinar quais recompensas (e valores) são válidos para o carrinho. ### Exemplo ```bash theme={null} 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 Nome do programa de fidelidade. Saldo de pontos do cliente. Indica se houve erro na requisição. Lista de recompensas. Identificador da recompensa. Tipo da recompensa (0 = Percentual, 1 = Valor fixo). Título da recompensa. Quantidade de pontos necessários para resgatar. Descrição da recompensa. Indica se a recompensa está habilitada. Indica se o cliente pode usar esta recompensa. Motivo da disponibilidade/indisponibilidade (ver tabela abaixo). Valor restante para atingir o mínimo (se `UseReason` for 2). Valor mínimo do carrinho para usar esta recompensa. ```json theme={null} { "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** Identificador da loja. Token do usuário obtido no login seguro. **Query Parameters** Valor da compra. ### Exemplo ```bash theme={null} 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 ```json theme={null} { "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** Identificador da loja. Token do usuário obtido no login seguro. **Path Parameters** ID da recompensa a ser resgatada. **Body (Opcional)** Identificador do carrinho (order\_form\_id). ### Exemplo ```bash theme={null} 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": "" }' ``` ### Resposta ```json theme={null} { "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** Identificador da loja. Token do usuário obtido no login seguro. **Path Parameters** ID da recompensa resgatada. **Body (Opcional)** Identificador do carrinho (order\_form\_id). ### Exemplo ```bash theme={null} 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": "" }' ``` *** ## 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** Identificador da loja. Token do usuário obtido no login seguro. **Path Parameters (GET)** Identificador do carrinho. **Body (POST)** Identificador do carrinho (order\_form\_id). ### Exemplo (GET) ```bash theme={null} 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) ```bash theme={null} 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": "" }' ``` ### Resposta Saldo total de cashback do cliente. Valor de cashback que pode ser utilizado nesta compra. Valor máximo de cashback permitido para esta compra. Regras de utilização do cashback (texto para exibição). Indica se o cliente pode usar cashback nesta compra. Texto informando quanto cashback o cliente receberá. Texto informando quanto falta para usar o cashback. Indica se o cashback está disponível. Valor restante para usar todo o cashback. Valor restante para atingir o mínimo necessário. Indica se há produtos no carrinho que não são elegíveis para cashback. Valor mínimo do carrinho para usar cashback. ```json theme={null} { "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** Identificador da loja. Token do usuário obtido no login seguro. **Path Parameters (primeira opção)** Identificador do carrinho. **Body** Identificador do carrinho (order\_form\_id). Obrigatório na segunda opção (sem path param). Valor do cashback a ser resgatado. Origem do resgate. Use `3` para checkout mobile. Valor do carrinho (sem descontos ou frete). ### Exemplo (com path param) ```bash theme={null} 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) ```bash theme={null} 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": "", "CashbackValue": 25.00, "RedeemOrigin": 3, "Total": 150.00 }' ``` ### Resposta ```json theme={null} { "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** Identificador da loja. Token do usuário obtido no login seguro. **Path Parameters (GET)** Identificador do carrinho. **Body (POST)** Identificador do carrinho (order\_form\_id). ### Exemplo (GET) ```bash theme={null} 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 ```json theme={null} { "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** Identificador da loja. Token do usuário obtido no login seguro. **Path Parameters (primeira opção)** Identificador do carrinho. **Body (segunda opção)** Identificador do carrinho (order\_form\_id). ### Exemplo ```bash theme={null} 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": "" }' ``` ### Resposta Indica se o cashback foi removido (por exemplo, se o carrinho ficou abaixo do mínimo). Mensagem para exibir ao cliente. ```json theme={null} { "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** Identificador da loja. Token do usuário obtido no login seguro. **Path Parameters (GET)** Identificador do carrinho (order\_form\_id). **Body (POST)** Identificador do carrinho (order\_form\_id). ### Exemplo (GET) ```bash theme={null} 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) ```bash theme={null} 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": "" }' ``` ### Resposta ```json theme={null} { "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** Identificador da loja. Token do usuário obtido no login seguro. **Path Parameters** ID da recompensa resgatada a ser removida do carrinho. ### Exemplo ```bash theme={null} 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** Identificador da loja. Token do usuário obtido no login seguro. **Path Parameters (DELETE)** Identificador do carrinho. **Body (POST)** Identificador do carrinho (order\_form\_id). Valor do carrinho (sem descontos ou frete). Opcional. ### Exemplo (DELETE) ```bash theme={null} 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) ```bash theme={null} 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": "", "Total": 150.00 }' ``` ### Resposta Indica se a operação foi bem sucedida. Mensagem para exibir ao cliente. ```json theme={null} { "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** Identificador da loja. Token do usuário obtido no login seguro. ### Exemplo ```bash theme={null} curl -X GET "https://api.bonifiq.com/pub/widget/objectives" \ -H "X-Bq-Tenant: {tenant_key}" \ -H "X-Bq-SecureToken: {secure_token}" ``` ### Resposta Indica se houve erro na requisição. Lista de objetivos disponíveis. Identificador do objetivo. Corresponde ao `ObjectiveType`. Tipo do objetivo (ver tabela abaixo). Título do objetivo. Descrição do objetivo. Descrição detalhada (pode conter HTML). Quantidade de pontos que o cliente ganha ao completar. Indica se o objetivo já foi completado pelo cliente. Indica se o objetivo pode ser resgatado pelo cliente. Pontos mínimos ganhos (quando há faixa variável). Pontos máximos ganhos (quando há faixa variável). Indica se o objetivo tem limite de usos. Número máximo de vezes que pode ser completado. Valor associado ao objetivo (ex: valor mínimo de compra). ```json theme={null} { "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 1. Verificar o `BenefitStatus` do objetivo 2. Se `BenefitStatus = 0`, exibir formulário para cadastrar data 3. Chamar endpoint para salvar aniversário 4. 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** Data de aniversário no formato `dd/MM` ou `yyyy-MM-dd`. ### Exemplo ```bash theme={null} 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** E-mail do amigo a ser indicado. ### Exemplo ```bash theme={null} 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** Canal de compartilhamento (ex: `whatsapp`, `copy`). ### Exemplo ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```json theme={null} { "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). #### Tipos de Rede Social | Valor | Rede Social | | ----- | ----------- | | 5 | Instagram | | 6 | Facebook | | 9 | LinkedIn | | 10 | TikTok | ### Exemplo ```bash theme={null} 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 ```json theme={null} { "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 ```bash theme={null} curl -X GET "https://api.bonifiq.com/pub/widget/quiz" \ -H "X-Bq-Tenant: {tenant_key}" \ -H "X-Bq-SecureToken: {secure_token}" ``` ### Resposta ```json theme={null} { "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** Identificador único do quiz. ### 9.6.3. Responder Quiz `POST /pub/widget/answer` **Body** Array de respostas, onde cada item contém: ID da questão sendo respondida. IDs das opções selecionadas (para questões Multiple e Selection). Resposta em texto livre (para questões Open). ### Exemplo ```bash theme={null} 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** Identificador da loja. Token do usuário obtido no login seguro. **Path Parameters** Tipo do objetivo a ser resgatado (ver tabela `ObjectiveType`). ### Exemplo ```bash theme={null} 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 ```json theme={null} { "HasError": false, "Item": { "Success": true, "ResultMessage": "Pontos creditados com sucesso!", "CouponCode": null, "HasCouponCode": false } } ```