-1.png?width=398&height=150&name=Logo%20Horizontal@1x%20(1)-1.png)
Através da APIs da BonifiQ é possível a integração com sistemas de PDV. Essa integração deve ser realizada pelo próprio PDV, seguindo os fluxos descritos abaixo.
Os endpoint necessários estão na aba "PoS" da nossa documentação:
https://api.bonifiq.com.br/apidocs/private/index.html?url=/swagger/Private%20APIs/swagger.json#/POS
Fluxo de Resgate de Recompensas
O fluxo acima descreve como funciona o resgate de uma recompensa, que permite oferecer descontos ou cashback na compra do cliente.
Na figura acima, podemos dividir esse fluxo em 3 partes
Consulta e Escolha da Recompensa (em azul)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, etc
Para 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.
A documentação do Endpoint possui mais detalhes sobre sua utilização.
Os mockups abaixo servem como apoio ao uso das APIs:
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:
- O valor total de cashback que o cliente tem é R$100,00
- O máximo de cashback que ele pode utilizar na compra atual é R$10,00 (devido à regra descrita em Requirements)
- 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.
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/{id}/challenge. O {id} 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 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/{id}/challengevalidate. Se houver uma resposta positiva, o PDV libera para que a compra seja concluída.
Conclusão da Compra (em verde)Agora, ao finalizar a compra, o PDV chama o endpoint de resgate de recompensa. Deve-se utilizar o endpoint POS/rewards/{id}/redeem.
Ele pode ser utilizado tanto para resgate de recompensas de tipo Desconto como Cashback
Com a resposta positiva da API, o PDV deve então aplicar o respectivo desconto no pedido.
Cancelamento da Recompensa
Caso a compra seja cancelada e exista a necessidade de estorno da recompensa e dos pontos utilizados, pode-se utilizar o endpoint DELETE rewards/{id}.
Nesse contexto, o ID representa o campo RewardId, retornando quando foi feita a chamada para o resgate da recompensa (/rewards/{id}/redeem)
Uma recompensa estornada retorna os pontos ao consumidor, que pode utilizar novamente em uma compra futura.
Essa operação não pode ser desfeita.
Envio de PedidosQuando um pedido é concluído, é necessário chamar o endpoint POST /orders da BonifiQ.
Dessa forma, a BonifiQ pode conceder os pontos ao consumidor, conforme configurado.
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.
Cancelamento de PedidosQuando o pedido é cancelado a BonifiQ deve ser informado. Para realizar essa chamada pode-se utilizar o endpoint de cancelamento de pedidos:
Quando o pedido é cancelado a BonifiQ realiza as etapas:
- Marca o pedido como Cancelado na BonifiQ. Isso irá refletir nos relatórios.
- Estorna os pontos que foram dados, caso tenha ocorrido
- Estorna as recompensas utilizadas, caso tenham sido utilizados