A integração com PDV permite que sistemas de ponto de venda utilizem os recursos de fidelidade da BonifiQ diretamente no fluxo de compra do consumidor utilizando nossas APIs. Esta documentação cobre todos os endpoints e fluxos necessários para uma integração completa.
Na BonifiQ é possível que sejam configuradas uma ou mais recompensas.
As recompensas podem ser aplicadas aos pedidos, oferecendo um desconto na compra do cliente.
Alguns exemplos: “desconto de 10% por 1000 pontos”, “desconto de R$ 10 por 100 pontos”, “cashback de R$ 10,00”, etcPara realizar essa consulta, pode-se chamar o endpoint POS/rewards/available. No corpo da chamada, deve-se informar o identificador do usuário (geralmente o CPF ou CNPJ). Esse endpoint retorna uma lista de Recompensas disponíveis para este consumidor.As recompensas podem ser de 2 tipos:
Desconto fixo (ex: R$ 10,00) ou Desconto percentual (ex: 10%)
Cashback (que também pode ser um desconto)
No caso em que exista mais de uma recompensa possível o PDV deverá exibir uma lista de recompensas ao vendedor, que escolhe apenas uma delas: somente uma recompensa é permitida por compra.Caso a recompensa escolhida seja Cashback deverá ser possível ao vendedor informar o valor que deseja ser aplicado. Por ex: o cliente possui R$ 20,00 de Cashback, mas deseja utilizar apenas R$10,00 nesta compra.Outro campo importante a se notar é o “Requirements”, ele elenca as regras que serão aplicadas para que seja possível utilizar a recompensa. Por exemplo: A recompensa é R$ 20,00 de Cashback, mas somente poderá ser utiliza em compras acima de R$ 100,00.
Nesse caso, ao tentar utilizar uma recompensa que não atende às regras, a BonifiQ retorna um erro.
Os mockups abaixo ilustram um fluxo comum de consulta de recompensas:
O primeiro passo é a consulta das recompensas. É feita chamada para o endpoint, informando o documento do consumidor (apenas números) e o valor atual do pedido.
A primeira possibilidade de retorno é uma lista de recompensas disponíveis de Desconto. A imagem detalha quais campos do retorno são utilizados na exibição de cada elemento. Esse cenário não contempla uso de Cashback.
É importante notar que a última recompensa está inativa (CanUse=false) pois o consumidor não possui pontos suficientes.
Ao clicar em Escolher o fluxo pode continuar.
A segunda possibilidade de retorno é o Cashback. É importante notar que é possível que sejam retornados Cashback e Descontos ao mesmo tempo.
Ao clicar em Escolher, deve-se exibir o seletor de valor (vide abaixo).
Quando se deseja utilizar Cashback é possível que seja utilizado apenas parte do mesmo. No exemplo acima podemos observar:
a) O valor total de cashback que o cliente tem é R$100,00
b) O máximo de cashback que ele pode utilizar na compra atual é R$10,00 (devido à regra descrita em Requirements)
c) O cliente pode escolher qualquer valor entre R$1,00 e R$10,00
Ao clicar em Confirmar o fluxo pode continuar normalmente.
Por fim, a terceira possibilidade desse fluxo é de que não há recompensas disponíveis para utilização.
Retorna a lista de recompensas disponíveis para um cliente específico.
Este endpoint retorna todas as recompensas configuradas, mesmo aquelas que o cliente não pode usar no momento (por falta de pontos, por exemplo). Isso permite exibir ao cliente quais recompensas ele poderá obter no futuro.
Valor de desconto já aplicado no pedido (que não seja da BonifiQ). A BonifiQ usa esta informação para retornar apenas recompensas que podem ser acumuladas com outros descontos. Se não houver desconto, envie null ou 0.
Essa é uma etapa de segurança, que visa reduzir chances de mal-uso dos benefícios. Sua aplicação, no entanto, é opcional.Após a escolha da recompensa, o PDV deverá chamar o endpoint POS/customers//challenge. O nesse caso é o CPF ou CNPJ do consumidor. O endpoint também pode receber um número de telefone, para o caso de ainda não existir um número cadastrado.A BonifiQ, então, irá enviar um código por SMS e/ou e-mail ao consumidor. Ele deverá informar esse código ao vendedor, que por fim, informa ao PDV. O PDV, então, informa esse código ao endpoint POS/customers//challengevalidate. Se houver uma resposta positiva, o PDV libera para que a compra seja concluída.
1
Enviar Challenge
Chame o endpoint de challenge para enviar o código PIN ao cliente.
2
Cliente Recebe o Código
O cliente recebe o código por SMS ou e-mail.
3
Validar Código
O cliente informa o código ao vendedor, que valida através da API.
Agora, ao finalizar a compra, o PDV chama o endpoint de resgate de recompensa confirmando o resgate. Deve-se utilizar o endpoint POS/rewards//redeem.Com a resposta positiva da API, o PDV deve então aplicar o respectivo desconto no pedido.
Realiza o resgate de uma recompensa para o cliente.
Importante: Diferente de outros endpoints da BonifiQ, este endpoint NÃO gera um cupom automaticamente. O PDV é responsável por aplicar o desconto diretamente no pedido.
Chave única para garantir idempotência. Mesmo que a requisição seja feita mais de uma vez, o resgate acontecerá apenas uma vez.Sugestão de formato: {rewardId}-{customerId}-{orderId}-{value}Exemplo: 3-12345678900-PDV001-15.00
Quantidade de pontos utilizados (valor negativo indica débito).
Após receber a resposta de sucesso, aplique o desconto correspondente no pedido do PDV. O tipo e valor do desconto foram informados no endpoint /rewards/available.
Cadastra um pedido na BonifiQ para que o cliente receba os pontos correspondentes.
Deve-se notar que o campo OrderTotal deve conter o valor pago pelo consumidor, portanto não deve conter valores de descontos, cupons, cashback, promoções, etc.
IMPORTANTE: Se o pedido utilizou uma recompensa da BonifiQ, informe aqui o ExternalCode retornado no resgate. Se não utilizou recompensa BonifiQ mas usou outro cupom, informe o código do cupom.
O cancelamento parcial estorna pontos/cashback proporcionalmente ao valor devolvido. Por exemplo, se o pedido original era de R$200,00 e rendeu 200 pontos, um estorno de R$50,00 removerá aproximadamente 50 pontos do cliente.
Quando um resgate é realizado, os pontos correspondentes são debitados do cliente.
Se a venda ainda não foi concluída, é possível cancelar o resgate - devolvendo os pontos (ou cashback) de volta ao cliente.Existem duas formas de cancelar uma recompensa resgatada:
Em sistemas distribuídos, falhas de rede podem causar requisições duplicadas. Use sempre a OriginalKey com um valor único e consistente para evitar resgates ou cancelamentos duplicados.
Vincule o resgate ao pedido
Sempre envie o ExternalCode retornado no resgate como valor do campo Coupon ao cadastrar o pedido. Isso permite rastreamento completo.
Não inclua descontos no OrderTotal
O OrderTotal deve refletir apenas o valor efetivamente pago pelo cliente, sem frete, descontos, cupons ou promoções. Isso garante o cálculo correto de pontos.
Trate a validação como opcional
Verifique o campo shouldValidateCustomer antes de iniciar o fluxo de challenge. Se false, pule direto para o resgate.
Exiba recompensas indisponíveis como desabilitadas
Mesmo que canUse=false, exiba a recompensa ao cliente (em estado desabilitado). Isso o motiva a acumular mais pontos para futuras compras.
Disponibilizamos um repositório público no GitHub com um PDV mockado que demonstra a integração completa com a BonifiQ. Este projeto pode ser usado como referência para auxiliar no desenvolvimento da sua integração.
Para garantir a estabilidade do serviço, a API possui limites de requisições:
Tipo de Limite
Valor
Período
Requisições por segundo
10
Por segundo
Requisições por minuto
300
Por minuto
Requisições por hora
10.000
Por hora
Se você atingir o limite, receberá uma resposta HTTP 429 Too Many Requests. Implemente um mecanismo de retry com backoff exponencial para lidar com esses casos.
Benefício que o cliente pode resgatar usando seus pontos acumulados. Pode ser um desconto fixo (ex: R$10,00), desconto percentual (ex: 15% off), ou cashback.
Pontos
Unidade de crédito acumulada pelo cliente a cada compra. A quantidade de pontos é calculada com base no valor do pedido e nas regras configuradas pelo lojista.
Cashback
Pontos e Cashback são intercambiáveis - cada ponto possui um valor em reais definido pelo lojista. Ao resgatar uma recompensa de cashback, o cliente utiliza seus pontos para obter um saldo em reais.
Ela é um tipo especial de recompensa: diferente dos pontos, o cliente pode escolher quanto do cashback deseja utilizar.
Challenge
Processo de validação de identidade onde um código PIN é enviado ao cliente por SMS ou e-mail. O cliente deve informar este código ao vendedor para confirmar que é o titular da conta.
OriginalKey
Chave única usada para garantir idempotência nas operações. Se a mesma OriginalKey for enviada mais de uma vez, a API garante que a operação será executada apenas uma vez, evitando duplicações.
ExternalCode
Código informado no momento do resgate de uma recompensa. Este código deve ser enviado no campo Coupon ao cadastrar o pedido, permitindo vincular o resgate ao pedido final.
PDV (Point of Sale)
Sistema de Ponto de Venda utilizado em lojas físicas para processar vendas. A integração com a BonifiQ permite que o PDV consulte e resgate recompensas durante o processo de venda.
OrderTotal
Valor efetivamente pago pelo cliente, excluindo frete, descontos, cupons e promoções. Este valor é usado para calcular os pontos que o cliente receberá pela compra.
O que acontece se eu enviar o mesmo pedido duas vezes?
Se você enviar um pedido com o mesmo OriginalId, a BonifiQ atualizará o pedido já existente na base.
Posso usar mais de uma recompensa por compra?
Não. O sistema permite apenas uma recompensa por compra. Se houver múltiplas recompensas disponíveis, o vendedor deve apresentar as opções ao cliente para que ele escolha qual deseja utilizar.
Quanto tempo o código PIN do challenge é válido?
O código PIN é válido por 60 minutos após o envio. Se expirar, o vendedor deve solicitar um novo código através do endpoint de challenge.
O cliente precisa estar cadastrado previamente na BonifiQ?
Não necessariamente. Se o cliente não existir, ele será criado automaticamente quando o primeiro pedido for cadastrado. Porém, para consultar recompensas e resgatar benefícios, o cliente precisa ter um histórico de compras que tenha gerado pontos.
Como sei se devo pedir validação por challenge?
Verifique o campo ShouldValidateCustomer na resposta do endpoint /rewards/available. Se for true, você deve executar o fluxo de challenge antes do resgate. Se for false, pode pular direto para o resgate.
Posso cancelar uma recompensa já resgatada?
Sim, desde que o pedido ainda não tenha sido finalizado. Use o endpoint de cancelamento de recompensa (DELETE /rewards/{id}) ou envie a OriginalKey para cancelar. Os pontos/cashback serão devolvidos ao cliente.
O que é a OriginalKey e como devo gerá-la?
A OriginalKey é uma chave única que identifica uma operação específica. Recomendamos o formato: {rewardId}-{customerId}-{orderId}-{timestamp}. Ela garante que mesmo se houver falha de rede e você reenviar a requisição, a operação será executada apenas uma vez.
Por que meu OrderTotal deve excluir descontos?
O OrderTotal representa o valor real da compra para cálculo de pontos. Se incluir descontos, o cliente receberia menos pontos do que deveria. Envie sempre o valor dos produtos antes de qualquer desconto, cupom ou promoção.
Preciso enviar pedidos que não usaram benefícios da BonifiQ?
Sim! Todos os pedidos devem ser enviados à BonifiQ, independentemente de terem utilizado recompensas ou não. Isso é essencial para que os clientes acumulem pontos em todas as compras.
Como funciona o cancelamento parcial de pedido?
O cancelamento parcial permite estornar apenas parte do valor do pedido (ex: devolução de um item). A BonifiQ calcula proporcionalmente os pontos a serem removidos. Por exemplo, se um pedido de R200gerou200pontosevoce^estornaR50, aproximadamente 50 pontos serão removidos do cliente.