Integração com App - BonifiQ Developers

Introdução

Para integrar a BonifiQ com um App é necessária a integração com diversas chamadas da nossa API. Este guia ilustra quais endpoints devem ser chamados para realizar as operações mais comuns. Em geral, o App deve replicar as funcionalidades do nosso Widget para web. Portanto, vamos utilizá-lo como referência. No projeto do App, no entanto, pode ser que algumas funcionalidades não sejam necessárias.

Base URL da API: https://api.bonifiq.com.brConsulte também a documentação interativa Swagger

Funcionalidades Principais

Saldo e Histórico

Exiba pontos/cashback e histórico de transações

Recompensas

Liste e permita o resgate de recompensas

Objetivos

Mostre formas de ganhar mais pontos

Saldo de Pontos/Cashback

Para buscar pelo saldo de pontos você pode utilizar o endpoint:

/customer/{id}/points

Retorna o saldo de pontos e cashback do cliente.

Campos de Resposta

CustomerExists

boolean

true se o consumidor existir na base da BonifiQ. Se este campo retornar false, assuma que o cliente não possui saldo de pontos/cashback.

PointsBalance

integer

O total de pontos que o consumidor possui (valor inteiro).

CashbackBalance

decimal

O total de cashback que o consumidor possui (valor decimal). Este campo somente é preenchido se a loja está com o Cashback ativo.

PointsToExpire

object

Informações sobre pontos próximos de expirar. Somente preenchido se a configuração de Expiração de Pontos está ativa na BonifiQ.

Regulamento

O regulamento se refere às regras do programa de pontos. Ele pode ser editado pelo admin da BonifiQ e normalmente é exibido no site/app ao cliente.

/terms

Retorna o regulamento do programa de fidelidade.

O regulamento retorna um HTML, que deve ser renderizado na exibição ao usuário.

Personalizações

As personalizações tratam das cores, nome do programa e logotipo.

/customization

Retorna as configurações de personalização do programa.

Campos Principais

WidgetIconUrl

URL do ícone do programa de fidelidade.

WidgetColor

Cor de fundo do ícone (no exemplo, é a cor roxa).

MainColor

Cor principal utilizada no widget, exibida nos botões, barra de título, etc.

PointsNameSingular / PointNamePlural

O lojista pode personalizar o nome “Pontos” para algo como “Moedas”. Esses campos retornam a versão alternativa para esse nome no singular e plural.

Histórico de Pontos

O histórico mostra uma lista dos pontos ganhos, perdidos e utilizados pelo cliente.

/customer/{id}/history

Retorna o histórico de pontos do cliente. Este endpoint é paginado.

Campos de Resposta

Date

datetime

Data em que o evento aconteceu.

Points

integer

Quantos pontos foram dados ou removidos.

Title

string

Descrição do evento (ex: “Realizou uma compra”).

PointType

enum

Categorização do ponto:

Valor	Descrição
0	Pontos ganhos em compras
1	Pontos ganhos ao criar conta
2	Pontos ganhos ao fazer aniversário
3	Pontos adicionados/removidos pelo admin
4	Pontos trocados por uma recompensa
5	Pontos ganhos ao fazer um review
6	Pontos reembolsados (por compras canceladas)
7	Pontos expirados
8	Pontos ganhos por indicar amigos

Listar Recompensas

As recompensas permitem que os consumidores troquem seus pontos atuais por cupons de desconto, cashback ou outras recompensas.

/RewardConfigurations

Retorna a lista de recompensas disponíveis.

Parâmetros de Requisição

IsActive

boolean

required

Filtra por recompensas ativas. Em geral, use true.

PageNumber

integer

Número da página (default: 1).

PageSize

integer

Tamanho da página (recomendado: 50).

Campos de Resposta

integer

ID da recompensa, utilizado no resgate.

RewardType

enum

Tipo da recompensa:

Valor	Descrição
0	Desconto percentual via cupom
1	Desconto de valor fixo via cupom
3	Cashback
4	Recompensa Customizada

Title

string

Título da recompensa (ex: “R$10,00” para desconto de valor fixo).

Description

string

Detalhes da recompensa e regras para uso.

Points

integer

Quantos pontos essa recompensa “custa”.

Value

decimal

Valor da recompensa (pode ser valor percentual ou fixo).

Tipos de Recompensa

Desconto via Cupom
Cashback
Recompensa Customizada

Desconto (Percentual ou Valor Fixo) via Cupom

Neste modelo, o campo Title é usado para exibir ao consumidor.

Ao clicar no item, exiba um popup com detalhes (campo Description da API) do resgate e as regras:

Exemplo de Resposta:

{
  "RewardType": 1,
  "Title": "R$10,00",
  "Description": "Troque 100 pontos por um cupom de desconto de R$ 10,00. Após a confirmação você receberá o cupom por e-mail.",
  "Points": 100,
  "Value": 10.00
}

Cashback

Diferente das demais recompensas, não pode existir mais de uma recompensa de cashback. É comum que a loja decida utilizar Cashback ou Desconto via cupom, mas não ambos ao mesmo tempo.O saldo de Cashback do usuário pode ser obtido no endpoint /customer/{id}/points.

Ao clicar nesse item, exiba um popup com as regras do Cashback (campo Description):

No caso do Cashback, o widget é apenas informativo. Diferente da recompensa de Desconto (que o consumidor pode resgatar direto no widget), no caso do Cashback ele faz o resgate direto no carrinho.

Recompensa Customizada

Essa é um tipo de recompensa que pode ser qualquer coisa: frete grátis, brinde, ingresso de cinema, etc. Fica a cargo do lojista fazer a configuração no admin BonifiQ.

Exemplo de Resposta:

{
  "RewardType": 4,
  "Title": "Ingresso Cinema",
  "Description": "<p>Troque 1000 pontos por um ingresso para assistir ao filme Barbie.<br>Válido para 1 ingresso por pessoa</p>"
}

Resgatar Recompensa

O resgate de recompensas ocorre quando o cliente deseja trocar seus pontos por um benefício. Na maior parte dos casos o benefício é um cupom de desconto.

/RewardConfigurations/{id}/redeem

Realiza o resgate de uma recompensa.

Parâmetros

integer

required

ID do RewardConfiguration (retornado na listagem de recompensas).

CustomerId

string

required

Identificador do consumidor na BonifiQ (geralmente o e-mail do cliente).

Resposta

No retorno, a principal informação está no item “Coupon”:

CouponCode

string

Código do cupom gerado pela BonifiQ na plataforma. Exiba ao consumidor para que possa utilizar em suas compras.

Listar Objetivos

Os Objetivos são as formas como os clientes ganham pontos. Os Objetivos podem ser informativos (ex: “ganhe 1 ponto a cada R$1,00 gasto”) ou podem requerer uma ação do cliente (ex: “Informar e-mail de um amigo para indicá-lo”).

/objectives/active

Retorna a lista de objetivos ativos.

Apesar do endpoint ser paginado, espera-se menos de 10 objetivos. Use PageNumber=1 e PageSize=50.

Campos de Resposta

Title

string

Título exibido ao cliente.

Description

string

Informações extras, geralmente regras especiais.

AmountOfPoints

integer

Quantos pontos este objetivo vale após ser completado.

Tipos de Objetivos

Criar Conta

Dá pontos para clientes que se cadastram no site. Este é um Objetivo apenas informativo. O cliente recebe pontos através da integração da BonifiQ com a plataforma.Não há interação do usuário com esse objetivo.

Fazer uma Compra

Dá pontos para compras realizadas. Novamente, é um Objetivo apenas informativo. As compras são integradas automaticamente entre a BonifiQ e a plataforma.Não há interação do usuário com esse objetivo.

Indique um Amigo

Permite dar pontos por indicações. Este objetivo requer interação do consumidor (veja seção “Indicar um Amigo” abaixo).

Ganhe Pontos por Reviews

Dá pontos para clientes que fazem avaliações. Este objetivo é apenas informativo - o cliente não faz a avaliação diretamente pelo widget.O site utiliza uma ferramenta parceira (como Yourviews) para coletar reviews. A BonifiQ se integra ao parceiro e concede os pontos.

Ao clicar em “Saiba Mais”:

O campo Details na API contém informações extras:

{
  "Title": "Ganhe 20 pontos ao fazer reviews",
  "Description": "Avalie suas compras e ganhe 11 pontos...",
  "AmountOfPoints": 11,
  "Active": true,
  "Details": {
    "HasCommentPoint": true,
    "CommentPoints": 6,
    "HasPhotoPoint": true,
    "PhotoPoints": 3,
    "HasUsageLimit": true,
    "UsageLimit": 1,
    "MaxGainedPoints": 20
  }
}

Aniversário

Permite dar pontos na data de aniversário do cliente. Quando a data não está disponível na plataforma, o próprio cliente pode defini-la.Para verificar se o cliente possui data de aniversário, consulte GET /customer/{id} e verifique o campo BirthdayDate. Se for null, a data ainda não foi configurada.

Para definir a data de nascimento, use:

/customer/{id}/setbirthday

Define a data de aniversário do cliente.

Quando o usuário já possui data de aniversário, o widget é apenas informativo:

Apesar da BonifiQ utilizar apenas mês e dia, use o formato ISO 8601 para compatibilidade.

Objetivo Customizado

Permite ao lojista conceder pontos para cenários diferentes dos programados nativamente na BonifiQ (ex: pontos por cadastrar em mailing list).No App, é meramente informativo e pode incluir um botão de ação:

{
  "Title": "Assine BonifiQ News",
  "Description": "Assine o BonifiQ News e ganhe estalecas!",
  "AmountOfPoints": 100,
  "Active": true,
  "Details": {
    "ActionButtonText": "Assinar",
    "CustomIcon": null,
    "IsCompleted": false,
    "ActionButtonURL": "https://www.bonifiq.com.br/blog/"
  }
}

Ao clicar no botão “Assinar”, o usuário é direcionado para a URL em ActionButtonURL. Se Details for null, o botão não é exibido.

Indicar um Amigo

Uma das formas de ganhar mais pontos é através da indicação de amigos. O cliente informa o e-mail do amigo, e a BonifiQ envia um convite com cupom de desconto.

/customer/{id}/referfriend/{email}

Envia convite de indicação para um amigo.

Parâmetros

string

required

E-mail do cliente atual (logado).

string

required

E-mail do amigo a ser indicado.

Níveis (Tiers)

Os níveis são uma categorização dos consumidores: quanto mais alto o nível, mais benefícios o consumidor possui.

Nível Atual do Consumidor

/tiers/available

Retorna informações sobre os níveis disponíveis. Envie o CustomerId no body da requisição.

Campos de Resposta

CurrentTier

object

Dados do Tier em que o consumidor se encontra (se informado o ID do consumidor).

NextTier

object

Qual o nível seguinte que o consumidor poderá subir.

AllTiers

array

Todos os níveis disponíveis.

Próximos Níveis

Exiba a lista de benefícios do Tier atual (CurrentTier.Benefits) e os benefícios dos próximos níveis (NextTiers):

Quiz

O Quiz é um Objetivo especial que permite aos lojistas criarem questionários para os consumidores responderem.

Listagem de Quiz

/quiz/list

Retorna a lista de Quiz disponíveis para resposta. Opcionalmente, envie o customerId como query parameter.

Campos de Resposta

Name

string

Nome do quiz.

AmountOfPoints

integer

Quantidade de pontos recebidos ao responder o questionário.

QuestionList

array

Lista de perguntas do questionário.

QuestionList[].Id

integer

ID da pergunta (usado nas respostas).

QuestionList[].Question

string

Título da pergunta.

QuestionList[].Type

enum

Tipo da pergunta:

Valor	Descrição
0	Escolha única
1	Escolha múltipla
2	Texto livre

QuestionList[].Options

array

Opções de resposta (para Type 0 ou 1).

Envio das Respostas

/quiz/answer

Envia as respostas do quiz. Envie o customerId como query parameter.

O envio deve ser feito de uma vez só, quando o usuário respondeu todas as perguntas:

[
  {
    "QuizQuestionId": 0,
    "OpenAnswer": "string",
    "OptionIds": [0]
  }
]

QuizQuestionId

integer

required

ID recebido no campo QuestionList[].Id.

OpenAnswer

string

Resposta de texto livre. Use null se a pergunta não for texto livre.

OptionIds

array

IDs das opções escolhidas (de QuestionList[].Options[].Id). Use null para texto livre.

Dúvidas Comuns

Os objetivos são fixos? Podem ser adicionados novos ou removidos?

Não são fixos. Podem haver novos Objetivos (criados na BonifiQ) ou podem ser removidos (cliente desabilitou). A ordem não é garantida.Algoritmo recomendado:

objectives.forEach(objective => {
  switch(objective.Type) {
    case 0:
      // EXIBE CARD DE DESCONTO PERCENTUAL
      break;
    case 1:
      // EXIBE CARD DE DESCONTO DE VALOR FIXO
      break;
    // ... outros tipos
    default:
      // Ignorar tipos não tratados
      break;
  }
});

Preciso gerar cupons na API da BonifiQ?

Em geral, não. Quando é feita a chamada para fazer o resgate de uma recompensa, a BonifiQ gera o cupom automaticamente na plataforma.O caso mais raro de gerar cupom na BonifiQ é quando você deseja criar um pool de cupons pré-gerados para recompensas.

Preciso chamar as APIs para gerar pontos?

Em geral, não. A BonifiQ gera pontos automaticamente quando um objetivo é concluído (compras, aniversário, cadastro, etc).É possível gerar pontos via API para cenários não previstos, como ações do consumidor que fogem aos objetivos padrão.

Suporte

Em caso de dúvidas ou problemas na integração:

Documentação Swagger: API Docs
Central de Ajuda: suporte.bonifiq.com.br
E-mail: [email protected]

Guias de Integração

​Introdução

​Funcionalidades Principais

Saldo e Histórico

Recompensas

Objetivos

​Saldo de Pontos/Cashback

​Campos de Resposta

​Regulamento

​Personalizações

​Campos Principais

​Histórico de Pontos

​Campos de Resposta

​Listar Recompensas

​Parâmetros de Requisição

​Campos de Resposta

​Tipos de Recompensa

​Desconto (Percentual ou Valor Fixo) via Cupom

​Cashback

​Recompensa Customizada

​Resgatar Recompensa

​Parâmetros

​Resposta

​Listar Objetivos

​Campos de Resposta

​Tipos de Objetivos

​Indicar um Amigo

​Parâmetros

​Níveis (Tiers)

​Nível Atual do Consumidor

​Campos de Resposta

​Próximos Níveis

​Quiz

​Listagem de Quiz

​Campos de Resposta

​Envio das Respostas

​Dúvidas Comuns

​Suporte

Introdução

Funcionalidades Principais

Saldo de Pontos/Cashback

Campos de Resposta

Regulamento

Personalizações

Campos Principais

Histórico de Pontos

Campos de Resposta

Listar Recompensas

Parâmetros de Requisição

Campos de Resposta

Tipos de Recompensa

Desconto (Percentual ou Valor Fixo) via Cupom

Cashback

Recompensa Customizada

Resgatar Recompensa

Parâmetros

Resposta

Listar Objetivos

Campos de Resposta

Tipos de Objetivos

Indicar um Amigo

Parâmetros

Níveis (Tiers)

Nível Atual do Consumidor

Campos de Resposta

Próximos Níveis

Quiz

Listagem de Quiz

Campos de Resposta

Envio das Respostas

Dúvidas Comuns

Suporte