Integrar com PDV

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.

Validação (em vermelho)

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 Pedidos

Quando 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 Pedidos

Quando o pedido é cancelado a BonifiQ deve ser informado. Para realizar essa chamada pode-se utilizar o endpoint de cancelamento de pedidos:

https://api.bonifiq.com.br/apidocs/private/index.html?url=/swagger/Private%20APIs/swagger.json#/POS/POS_CancelOrder

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