Para integrar a BonifiQ com um App é necessária a integração com diversas chamadas da nossa API. Esse 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.
Tela inicial do App (click para ver maior).
Saldo de Pontos/Cashback
Para buscar pelo saldo de pontos você pode utilizar o endpoint
Esse endpoint retorna:
- CustomerExists: true se o consumidor existir na base da BonifiQ. Se esse campo retornar false, então você deve assumir que o cliente não possui saldo de pontos/cashback
- PointsBalance: O total de pontos que o consumidor possui (valor inteiro)
- CashbackBalance: O total de cashback que o consumidor possui (valor decimal). Esse campo somente é preenchido se a loja está com o Cashback ativo.
- PointsToExpire: Além de exibir o saldo de pontos é possível exibir quando os pontos estão próximos de expirar. Essa opção somente é preenchida se a configuração de Expiração de Pontos está ativa na BonifiQ. São retornados apenas pontos que estão próximos de expirar.
O saldo de pontos é exibido no topo do Widget
Regulamento
O regulamento se refere às regras do programa de pontos. Ele pode ser editar pelo admin da BonifiQ e normalmente é exibido no site/app ao cliente. Pode-se utilizar o endpoint:
Cabe notar que o regulamento retorna um HTML, que deve ser renderizado na exibição ao usuário.
Histórico de Pontos
O histórico mostra uma lista dos pontos ganhos, perdidos e utilizados pelo cliente.
Deve-se utilizar o endpoint:
Esse endpoint é paginado. Um cliente pode ter dezenas de registros, então é recomendável aplicar a paginação.
A resposta da chamada retorna:
- Date: Data em que o evento aconteceu
- Points: quantos pontos foram dados ou removidos
- Title: Descrição do evento (ex: Realizou uma compra)
- PontType: Categorização do pontos. Os possíveis valores são:
0 - Pontos ganho 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. Para listar as recompensas disponíveis, pode-se chamar o endpoint:
É necessário informar:
- IsActive: Uma recompensa pode estar ativa ou inativa. Em geral, você irá exibir apenas recompensas ativas. Nesse caso, portanto, o valor deve ser true
- PageNumber/PageSize: A lista de recompensas pode ser grande, o que geraria paginação. Na maioria dos casos, no entanto, a quantidade de Recompensas ativas é de no máximo 2 dezenas. É seguro assumir o valor de PageNumber=1 e PageSize=50. Assim, na grande maioria dos casos, todas as recompensas ativas serão retornadas.
O retorno a ser utilizado é:
- Id: é importante caso o cliente deseje trocar os pontos por uma recompensa. Esse ID é utilizado nesse caso (veja abaixo)
- RewardType: O tipo de recompensa. Os valores possíveis são:
0 - Desconto percentual via cupom
1 - Desconto de valor fixo via cupom
2 - (não utilizado)
3 - Cashback
4 - Recompensa Customizada
- Title: Título da recompensa recompensa, que depende do RewardType (ex: R$10,00 no caso de desconto de valor fixo)
- Description: Detalhes da recompensa. Pode conter, também, as regras para uso da recompensa (ex: valor mínimo de compra)
- Points: Quantos pontos essa recompensa "custa"
- Value: Valor da recompensa. Depende do RewardType (pode ser valor pecentual ou fixo)
Em geral, a exibição pode ser:
a) Desconto (percentual ou valor fixo) via cupom
A visualização na Lista de Recompensas do Widget fica assim:
Nesse modelo, pode-se pegar o valor de retorno do campo Title para exibir ao consumidor.
Os modelos e comportamentos de cupom percentual e valor fixo são muito parecidos.
Ao clicar no item, exibimos um popup com detalhes (campo Description da API) do resgate e as regras
Ao clicar em CONFIRMAR o cliente pode confirmar a troca de pontos pelo cupom de desconto (vide seção "Resgatar Recompensa" abaixo).
RewardType = 0 (desconto de valor fixo)
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: 1,
Value": 100
b) Cashback.
Diferente das demais recompensas, não poderá 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
RewardType = 3
Ao clicar no nesse item é exibido um popup com as regras do Cashback (campo Description do retorno da API). Ex:
Importante: No caso do Cashback, o widget é apenas informativo. Ou seja, diferente da recompensa de Desconto, que o consumidor pode resgatar direto no widget, no caso do Cashback ele faz o resgate direto no carrinho.
c) 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.
RewardType=4
Description = <p>Troque 1000 pontos por um ingresso para assistir ao filme Barbie. <br>Válido para 1 ingresso por pessoa</p>
No widget, as recompensas aparecem em uma lista, numa aba chamada "Recompensas"
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.
Para isso, basta utilizar o endpoint abaixo:
/RewardConfigurations/{id}/redeem
É necessário informar:
- id: Na URL. Esse ID é o ID do RewardConfiguration, retornado na chamada anterior.
- CustomerId: Identificador do consumidor na BonifiQ. Na maioria das plataformas é o e-mail do cliente.
No retorno existem diversas informações. A principal é a que está no item "Coupon":
O "CouponCode" é o código gerado pela BonifiQ na plataforma. Ele pode ser exibido 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).
Para listar os objetivos pode-se utilizar o endpoint:
Apesar do endpoint ser paginado, em geral, espera-se menos de 10 objetivos. Na chamada, informe PageNumber=1 e PageSize=50 e é suficiente.
O retorno do endpoint é uma Lista dos Objetivos que estão atualmente ativos. Os campos são:
- Title: Título exibido ao cliente
- Description: Informações extras que podem ser exibidas ao cliente, geralmente regras especiais
- AmountOfPoints: Quantos pontos este objetivo vale após ser completado
Atualmente os Objetivos são:
Criar Conta
Dá pontos para cliente que se cadastram no site. Em geral, esse é um Objetivo apenas informativo. O cliente recebe pontos através da integração da BonifiQ com a plataforma, não sendo necessário chamar as APIs da BonifiQ diretamente.
Não há, portanto, 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á, portanto, interação do usuário com esse objetivo.
Indique um Amigo
Permite dar pontos por indicações. Esse objetivo requer interação do consumidor, os detalhes estão abaixo.
Ganhe pontos por Reviews
Dá pontos para clientes que fazem avaliações. Esse objetivo é apenas informativo, o cliente não consegue fazer a avaliação diretamente pelo widget.
Na verdade, o site utiliza uma ferramenta parceira, como a Yourviews para coletar reviews. A BonifiQ, então, se integra ao parceira e concede os pontos, conforme configurado.
Nesse caso, o usuário pode clicar no botão "Saiba Mais" para entender melhor como irá ganhar pontos
É importante notar que esse popup exibe mais informações que o normal (como pontos extras ao deixar fotos junto do review). Esses campos extras estão mapeados na API, no campo "Details". Um exemplo de retorno abaixo:
"Title": "Ganhe 20 pontos ao fazer reviews",
"Description": "Avalie suas compras e ganhe 11 pontos. Ganhe mais 6 pontos por deixar um comentário. Ganhe mais 3 pontos por enviar uma foto. Utilize até 1 vez(es).",
"AmountOfPoints": 11,
"Active": true,
"Details": {
"HasCommentPoint": true,
"CommentPoints": 6,
"HasPhotoPoint": true,
"PhotoPoints": 3,
"HasUsageLimit": true,
"UsageLimit": 1,
"MaxGainedPoints": 20
}
Os campos desse retorno são:
- HasCommentPoint: Indica se podem ser dados pontos extras por comentários deixados junto do review
- CommentPoints: Quantos são os pontos extras por deixar comentários
- HasPhotoPoint: Indica se podem ser dados pontos extras por fotos deixados junto do review
- PhotoPoints: Quantos são os pontos extras por deixar fotos
- HasUsageLimit: Se há limitação em número de vezes a ganhar pontos por fazer reviews
- UsageLimit: Qual o limite de vezes que pode-se ganhar ponto por deixar reviews
A imagem abaixo detalha o de-para:
Aniversário
O Objetivo de Aniversário permite dar pontos na data de aniversário do cliente. Quando disponível na plataforma, a BonifiQ integra a data automaticamente e nenhuma ação é necessário.
Quando essa informação não está disponível, no entanto, o próprio cliente pode definir sua data de nascimento.
Para saber se o cliente possui data de aniversário, basta consultar o endpoint GET /customer/{id}. Pode-se verificar o campo "BirthdayDate". Se ele for null, então a data ainda não foi configurada.
No exemplo abaixo, quando o usuário não possui data de aniversário o widget exibe o texto "Não sabemos seu aniversário. Clique para nos informar". Ao clicar, o usuário informar sua data de nascimento.
Ao informar a data de nascimento, pode-se chamar o endpoint POST /customer/{id}/setbirthday
Esse endpoint recebe apenas um campo, que é a data informada pelo usuário.
Quando o usuário já possui data de aniversário, o widget se torna apenas informativo:
Importante: Apesar da BonifiQ utilizar apenas o componente de mês e dia das datas, por questão de compatibilidade, utilizamos o formato ISO 8601.
Indicar um Amigo
Uma das formas que o cliente tem para ganhar mais pontos é através da indicação de amigos. Um cliente atual, portanto, informa o e-mail do seu amigo. A BonifiQ envia um e-mail para esse amigo, convidando-o à se tornar cliente e oferecendo um cupom de desconto.
Para isso, utiliza-se o endpoint:
customers/{id}/referfriend/{email}
O "Id" normalmente é o e-mail do cliente atual, logado. O e-mail deve ser informado pelo cliente.
Dúvidas comuns
Os objetivos são fixos? Podem ser adicionados novos ou removidos?
Os objetivos não são fixos. Podemos ter novos Objetivos (por exemplo, um novo tipo de objetivo criado na BonifiQ) ou podem ser removidos (por exemplo, cliente desabilitou um Objetivo).
A ordem em que eles aparecem não é garantida.
O algoritmo recomendado, portanto, é algo como:
foreach (Objective in AllObjectives) {
if (Objective.Type == 0) {
//EXIBE CARD DE DESCONTO PERCENTUAL
}
else if (Objective.Type == 1) {
//EXIBE CARD DE DESCONTO DE VALOR FIXO
}
//...Outros else if para os demais Types...
else {
continue; //Se trata de um Objetivo ainda não tratado. Basta ignorá-lo, até que seja implementado.
}
}
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, que serão utilizados em recompensas.
Preciso chamar as APIs para gerar pontos?
Em geral, não. A BonifiQ gera pontos automaticamente quando um objetivo é concluído (como fazer compras, aniversário, cadastro, etc).
É possível, no entanto, gerar pontos via API para cenários não previstos na BonifiQ, como geração de pontos por ações do consumidor que fogem aos objetivos padrão.
Este artigo foi útil?
Que bom!
Obrigado pelo seu feedback
Desculpe! Não conseguimos ajudar você
Obrigado pelo seu feedback
Feedback enviado
Agradecemos seu esforço e tentaremos corrigir o artigo