Baixa apresentação em PDF
Sobre a plataforma
A Cresce Vendas é uma empresa de Tecnologia que disponibiliza uma plataforma de descontos de varejistas para seus usuários.
Os descontos são cadastrados na nossa base através do nosso painel, de acordo com os interesses do varejista. Eles são específicos para cada usuário e possuem uma limitação de uso, bem como um prazo de validade.
O usuário ativa os descontos através de um aplicativo desenvolvido pela Cresce Vendas para o varejista. Uma vez ativado, ele deve pegar o produto na gôndola e levar até o caixa, onde receberá o desconto ativado, mediante informação do seu CPF ou CNPJ.
Integração com a plataforma
É imprescindível que todos os fluxos sejam mapeados e integrados, possibilitando assim que o varejista consiga não só utilizar todo o potencial da ferramenta, como resolver possíveis problemas pontuais da operação. Para tal é obrigatório que os fluxos, básico e alternativos, abaixo sejam integrados.
Fluxo básico
Uma vez recebido o CPF ou CNPJ do usuário, o fluxo de compras deve seguir normalmente até o final, antes do pagamento.
Nesse momento deve ser feita uma requisição inicial para a API da Cresce Vendas enviando a lista de compras do usuário, obtendo no retorno da mesma, informações do usuário e todos os itens nos quais o usuário possui desconto. Os descontos devem ser aplicados à compra do mesmo e o pagamento deve ser realizado.
Após o pagamento ser realizado uma nova lista deve ser enviada, desta vez não só com os itens comprados, mas com informações do pagamento e dos itens que tiveram descontos aplicados advindos da plataforma Cresce Vendas.
Esta última requisição informa o nome do usuário, a quantidade de pontos que ele ganhou com a compra e o total de pontos acumulados.
SEMPRE QUE O USUÁRIO INFORMAR O CPF OU CNPJ DEVE SER ENVIADA A LISTA DE COMPRAS. OS ENVIOS DEVEM SEMPRE CONTER TODOS OS PRODUTOS COMPRADOS, INDEPENDENTE DE DESCONTOS.
Fluxos alternativos
- Usuário não possui descontos
Neste caso, o envio inicial da lista de compras retornará um array de descontos vazio. No envio final, após o pagamento, o array com os descontos utilizados deve estar vazio;
- Usuário não possui cadastro
Neste caso, o envio inicial da lista de compras retornará um array de descontos vazio e não trará as informações do usuário. No envio final, após o pagamento, o array com os descontos utilizados deve estar vazio;
- Após o envio inicial, o usuário alterou sua compra
Sempre que o usuário alterar sua compra deve ser feito um novo envio para receber os descontos que o mesmo tem direito. Somente após aplicar todos os descontos e não haver mais alterações deve ser feito o envio final;
- Uma mensagem de erro foi exibida
Caso seja um erro de conexão ou rede, deve ser feita uma nova tentativa até que se consiga uma resposta de sucesso ou, caso persista, deve-se entrar em contato com nosso suporte imediatamente.
Caso seja um erro de inconsistência nos dados, não deve ser feita uma nova tentativa de reenvio. O erro deve ser analisado pela empresa responsável e ser corrigido o mais rápido possível;
Cancelamento de compra
Caso uma compra seja cancelada antes do pagamento, basta que não seja feito o envio final.
Caso uma compra precise ser cancelada após o pagamento, deve ser enviada uma requisição para o endpoint de cancelamento de compra, informando o número do cupom da compra.
Uma compra só pode ser cancelada a partir do mesmo acesso com a qual foi criada.
Consulta de usuário
Caso seja necessário fazer uma consulta para receber os dados do usuário, deve ser feita uma consulta para o endpoint de consulta de usuário, informando o CPF/CNPJ do mesmo.
Essa requisição também pode ser feita via GET.
A consulta retornará nome, número total de pontos e saldo total do usuário.
Caso o retorno seja nulo, o usuário não possui cadastro. Porém o fluxo deve seguir normalmente, com envio da lista inicial e final.
Envio diário do total de compras
Diariamente deve ser enviada a quantidade de compras realizadas no dia anterior, bem como o valor total das mesmas. Esses valores se referem a todas as compras da loja, incluindo as quais não foi informado CPF ou CNPJ. É possível também enviar ao final do dia, com os valores referentes ao fechamento do dia.
É possível povoar dias anteriores não enviados, bem como sobrescrever valores já enviados, basta que seja enviado com a data do dia em questão.
Cada loja (identificada através do acesso email/token) deve enviar individualmente seus totais diários.
Envio de descontos loja
Uma funcionalidade opcional, mas que traz grande agilidade, é o cadastro automático de descontos loja. São aqueles descontos cadastrados no retaguarda para preço 2. Através desse endpoint é possível enviar esses mesmos descontos para serem cadastrados diretamente na plataforma Cresce Vendas.
Os atributos básicos de cada desconto a serem cadastrado são: código, preço inicial, preço final e limite por usuário. Caso não tenha limite basta informar a quantidade 1000. Além dos atributos do desconto, deve ser informado o email e token do administrador responsável por esse cadastro, o email e token das lojas que terão esses descontos vinculados e a data de entrada e de saída dos descontos.
Uso de vale compras como pagamento
Uma funcionalidade opcional, mas que permite outra utilização do programa de vale compras no cupom fiscal, é o uso de vale compras como pagamento. Quando forma de desconto, e não pagamento, esse valor é normalmente retornado no “subtotal” do array de descontos da resposta da requisição inicial. Após o pagamento, a requisição final informa no array de descontos utilizados “code”: 0, “quantity”: 1. Entretanto, para utilizar vale compras como pagamento, e não como desconto no cupom, deve ser pedido à Cresce Vendas que altere o funcionamento para as lojas do grupo em questão.
Também não é possível alterar entre as formas de uso de vale compras – desconto no cupom, subtotal, ou pagamento.
Neste caso, a requisição inicial deixa de obter o valor de subtotal e passa a receber sempre 0 (a não ser que haja “cupom”, funcionalidade separada). Deve, então, ser feita uma requisição intermediária, em outro end-point, informando o CPF ou CNPJ do usuário e o valor que ele deseja utilizar como pagamento. O mesmo deve ser perguntado no PDV antes do pagamento e da requisição final. Caso o mesmo possua o saldo desejado em vale compras disponível para a mesma compra, o corpo de resposta terá “has_balance”: true. Caso seja insuficiente, false. Este valor é definido de acordo com os itens informados na requisição inicial e permanece fixo até a requisição inicial seguinte. O usuário deve poder informar outros valores até ter saldo suficiente ou até desistir deste pagamento com vale compras.
Por fim, a requisição final, para todas as lojas deste grupo, deve sempre informar o valor aplicado como pagamento no “quantity” do corpo da requisição, no array de descontos, referente ao “code”: “p”. Caso o “quantity” prossiga sendo informado como 1 (comportamento padrão da baixa de vale compras) isso será tratado como 1 (um) Real.
Obs.: Se o cliente integrado possuir a funcionalidade “Cupom”, além de “Vale compras”, o mesmo nunca será usado como pagamento, e retornará no “subtotal” da resposta da inicial normalmente, e deverá ser informado “code”: 0, quantity: 1 como normalmente é feito em vale compras como desconto.
Caso a requisição final informe um valor superior ao saldo disponível aprovado na requisição intermediária, a API tentará utilizar o que ainda houver de vale compras disponível para o usuário nas condições da compra e, ainda havendo resto, aplicará isso como saldo negativo na carteira do usuário (tornando negativo ou não o saldo do usuário). Este caso não deve ocorrer.
Conferir itens 17, 18 e 19.
Comunicação com a plataforma
O ambiente de produção responde nos domínios http://www.apicrescevendas.com ou https://www.apicrescevendas.com.
O ambiente de sandbox responde nos domínios http://demo.apicrescevendas.com ou https://demo.apicrescevendas.com.
O endpoint de envio de compras é /admin/api/v2/shops, seja para o envio inicial ou final.
O endpoint para cancelamento de compras é /admin/api/v2/shops/cancel.
As requisições devem ser enviadas via POST e o corpo deve estar no formato JSON, assim como as respostas das mesmas.
Para se comunicar com cada ambiente é necessário um email e token. Estes devem ser gerados por nossa equipe no início do processo de integração. Os acessos de produção serão individuais por loja e serão repassados após a homologação.
A autenticação funciona através dos cabeçalhos HTTP X-AdminUser-Email e X-AdminUser-Token. Ambos devem ser preenchidos respectivamente com o e-mail e token fornecidos. É importante que este token seja mantido de forma segura a fim de evitar possíveis fraudes.
É aconselhado utilizar o Postman (https://www.getpostman.com/) para proceder com os testes. Todos os exemplos dessa documentação foram feitos nessa ferramenta.
Ao receber um erro 4xx (401, 422, entre outros), a requisição não deve ser reenviada! Somente quando houver um problema de comunicação ou um erro interno do servidor (5xx), a requisição deve ser reenviada.