Em geral, a BonifiQ gera cupons automaticamente nas plataformas em que está integrada. Quando alguma plataforma deseja se integrar com a BonifiQ, ela precisa atender a alguns protocolos e oferecer algumas APIs que possam ser consumidas no decorrer do uso do programa de pontos.

Esse documento detalha quais endpoints precisamos utilizar e os respectivos campos que devem ser disponibilizados.

Endpoints de Pedido

Busca de Pedidos por Data de Criação

A BonifiQ busca os pedidos realizados na plataforma com alguma frequência (geralmente a cada hora). Essa busca deve retornar os pedidos feitos com filtro de data, de forma paginada. 

Parâmetros de entrada

- Data de Início: Data inicial de criação do pedido a partir da qual estamos buscando

- Data de Finalização: Data final de criação do pedido a partir da qual estamos buscando

- Pagina: Página dos resultados que estamos buscando

Retorno esperado

- Id do Pedido: Esse é o ID do pedido no seu sistema. Ele é utilizado em diversos locais na BonifiQ, como envio de e-mail, relatório de pedidos, etc. Também é utilizado para atualizar este mesmo pedido, se necessário.

- Data Criação: Essa é a data que o pedido foi realizado no seu sistema. Deve ser em formato UTC ou com Timezone explícito.

- Data do últimos Status: data em que o pedido mudou de status

- Valor Pedido: Esse é o valor líquido do pedido. Deve ser desconsiderados os descontos, promoções, cupons, vales, frete, etc. Esse é o valor que será utilizado como base para conceder os pontos.

- Status: Esse é o status do pedido na sua plataforma, pode ser qualquer texto. Será utilizado posteriormente na busca de status possíveis

- Consumidor: Precisamos de nome, e-mail, telefone, data de aniversário e documento.

- Produtos Opcional. Permite criar regras de pontuação por produto. Precisamos de Id, Nome e valor pago pelo produto nesse pedido.

- Cupom: Código do cupom utilizado no resgate. É utilizado para relacionar vendas feitas com cupom BonifiQ

- Dados de paginação: Para identificarmos a página atual e quantas ainda estão disponíveis

Importante: os dados devem ser retornados em ordem crescente de data de criação (ou seja, pedidos antigos primeiro)

Busca de Pedidos por Id

Utilizamos esse endpoint para atualizar o status dos pedidos. O retorno deve ser o mesmo que a busca de pedidos por criação.

Busca de Pedidos por E-mail de Consumidor

Utilizamos esse endpoint no "Indique um Amigo" para garantir que o consumidor não tenha ainda efetivado uma compra. O endpoint recebe o e-mail do consumidor e retorna uma lista de suas compras.

Busca Status de Pedido

Lista todos os Status possíveis em que um pedido pode estar. Se necessário, pode ser uma lista paginada.

Precisamos ao menos do nome do status, que deve ser o mesmo utilizado no endpoint de pedidos.

Utilizamos esse endpoint para permitir que o lojista escolha em quais status o pedido deve ser concluído ou cancelado. 

Em uma forma alternativa, caso os status sejam estáticos, eles podem ser fixados na integração pela BonifiQ.

Endpoints de Consumidores

Busca Consumidores por Data de Criação

Esse endpoint busca os novos cadastros de clientes na plataforma com a finalidade de oferecer bonificação por cadastro.

Parâmetros de entrada

- Data de Início: Data inicial da criação da conta

- Data de Finalização: Data final da criação da conta 

- Pagina: Página dos resultados que estamos buscando

Retorno esperado

- Email: Endereço de e-mail do consumidor

- Nome: Nome completo do consumidor

- Documento: CPF ou CNPJ do consumidor

- Telefone: Número utilizado no cadastro

- Data de aniversário: Opcional, caso a plataforma solicite esse dado. Utilizado para bonificar por aniversário.

- Dados de paginação: Para identificarmos a página atual e quantas ainda estão disponíveis

Busca consumidor por e-mail

Informamos o e-mail completo e deve ser retornado os dados do consumidor, como no endpoint de busca de consumidores.

Endpoints de Produtos

Os endpoints de produto permitem que seja configurado os Pontos Extras por Produto.

Busca Produtos por Data de Criação

Esse endpoint busca os novos cadastros de produtos na plataforma

Parâmetros de entrada

- Data de Início: Data inicial da criação do produto

- Data de Finalização: Data final da criação do produto 

- Pagina: Página dos resultados que estamos buscando

Retorno esperado

- Id: Identificador do produto na plataforma

- Nome: Nome do produto na plataforma

- Url: Endereço web do produto, se existir

- Imagem: Endereço da imagem do produto, se existir

Busca Produtos por nome parcial

Esse endpoint recebe um texto (nome do produto) e deve retornar os produtos encontrados (no mesmo formato acima). Por exemplo, ao buscar por "camis", poderia retornar os produtos "camiseta branca" e "camiseta preta".

Endpoints de Cupom

Esses endpoints são utilizados para geração e verificação de cupons na plataforma parceira.

Criar cupom

Esse endpoint deve ser responsável por criar um novo cupom para um consumidor

Parâmetros de entrada

- Código do Cupom: Gerado pela BonifiQ. Pode ter até 36 caracteres, entre letras e números

- Tipo de cupom: Cupom percentual (ex: 10%) ou de valor  (ex: R$10,00)

- Valor do cupom: Valor decimal

- Data de início: data a partir da qual o cupom poderá ser utilizado

- Data de fim: data a partir da qual o cupom não poderá mais ser utilizado

- Cumulativo?: Se true, pode ser utilizado em conjunto com outras promoções;

- Valor Mínimo: Valor mínimo do carrinho para que o cupom possa ser utilizado

- Email Consumidor: Se o campo estiver preenchido então o cupom só poderá ser utilizado por este consumidor

Retorno esperado

- Id: Identificador do cupom na plataforma

- Codigo: Mesmo código enviado como parâmetro de entrada

- Sucesso: se true, o cupom foi gerado corretamente

Validar que cupom existe

Recebe o código do cupom e o endpoint retorna true caso o cupom exista e false de outra forma

Validar que cupom foi utilizado

Recebe o código do cupom e o endpoint retorna true caso o cupom tenha sido utilizado em uma compra e não pode ser utilziado novamente

Desabilitar cupom

Recebe o código do cupom e o endpoint retorna true caso o cupom tenha sido utilizado em uma compra e não pode ser utilizado novamente