Schema de Integração PDV por API

Introdução

A integração entre a AlterVision e o sistema de PDV das lojas tem como objetivo importar os resumos diários de vendas de cada vendedor para a plataforma. A AlterVision deve exibir as mesmas informações que os usuários visualizam nos relatórios de seus sistemas de vendas, ou seja, o usuário precisa confirmar que os números na AlterVision correspondem exatamente aos do PDV.

Nosso modelo de integração busca manter o histórico de dados das lojas sempre atualizado. Para evitar discrepâncias decorrentes de ajustes realizados após a leitura na API (como, por exemplo, o cancelamento ou consolidação de uma transação ocorrida um ou dois dias antes), são feitas requisições diárias, que consultam os dados dos últimos 5 dias e os enviam para a plataforma.

A atualização diária tem o objetivo de alimentar a AlterVision com as informações de vendas à medida que as transações ocorrem. As requisições são realizadas a cada 20 minutos. Cada loja é atualizada individualmente, ou seja, uma requisição será feita por CNPJ (ou código de filial) registrado na AlterVision a cada consulta.

Atenção

Vale ressaltar que o fluxo de informações sempre será iniciado por uma requisição feita pela AlterVision, e o retorno dessa requisição será responsável por alimentar a plataforma.

Parâmetros

Em cada uma das requisições passaremos os seguintes parâmetros:

• CNPJ (ou código da loja)
• Data início
• Data fim

Esses parâmetros são exigidos na especificação padrão da AlterVision e serão passados em todas as requisições. O autor da API deve indicar se os parâmetros devem ser passados por headers, body ou pela URL, respeitando o verbo HTTP utilizado na requisição.

Por exemplo: utilizando o verbo GET para o endpoint genérico:

https://example.com/api/Exemplo/

enviaríamos os parâmetros:

• Cnpj: 12345678000100
• Data_inicio: 2019-06-01
• Data_fim: 2019-06-30

E com isso a URL de consulta seria:

https://example.com/api/Exemplo?Data_inicio=01/06/2019&Data_fim=
30/06/2019&Cnpj=12345678000100

Os nomes dos parâmetros não precisam ser necessariamente Cnpj, Data_inicio e Data_fim. Porém é necessário que a API aceite na URL de consulta parâmetros que filtrem a busca por cnpj, data início e data fim ou, no mínimo, data início e data fim, quando cada cnpj tiver seu próprio login/token.

Retorno dos dados

Ao enviar uma requisição de consulta na API, o retorno que será esperado pelo nosso ambiente de integração deverá conter a seguinte informação:

• Data da venda (tipo string (YYYY-MM-DD))
• Hora da venda (tipo string (HH))
• Nome do vendedor (tipo string)
• Código único ou CPF do vendedor (tipo string)
• Quantidade de vendas (líquido) (tipo integer ou float)
• Quantidade de peças (líquido) (tipo integer ou float)
• Valor total vendido (líquido) (tipo integer ou float)

Ou seja, a API de consulta deve retornar, para o CNPJ ou código informado, o resumo das vendas efetuadas entre as datas selecionadas em que a requisição foi disparada. Para a representação dos dados a empresa poderá escolher a melhor forma de representação/tecnologia que já utilize para integrações, tais como JSON ou XML, por exemplo. Se nos for oferecida a opção de escolha, sempre preferimos pelo formato .json, devido à facilidade de manuseio da informação.

Exemplo em .json

[
  {
    "data": "2025-01-01",
    "hora": "09",
    "nome": "Teste",
    "cpf": "1234567890",
    "numVendas": 30,
    "numItens": 60,
    "valor": 4000.00
  },
  {
    "data": "2025-01-01",
    "hora": "10",
    "nome": "Teste2",
    "cpf": "0987654321",
    "numVendas": 40,
    "numItens": 70,
    "valor": 4500.00
  }
]

Período de consulta das informações de vendas

Conforme descrito na seção 2, as requisições sempre serão filtradas por um período de data início e data fim. Isso significa que as informações de vendas da loja, tanto antigas quanto atuais, precisam estar disponíveis para serem consultadas a qualquer momento.

Sendo assim, caso a API tenha um limite de informações, para a integração com a AlterVision é necessário que os dados de venda da loja estejam disponíveis para consulta em uma faixa de, no mínimo, 60 dias atrás, em relação ao dia atual.

Considerações em relação a trocas/devoluções

Para que os dados na AlterVision reflitam exatamente o que é visto no relatório do PDV pelos usuários é importante que os valores para quantidade de vendas, de peças e de valores totais de vendas de cada vendedor já sejam os totais líquidos do dia.

Normalmente as trocas/devoluções são abatidas dos totais contabilizados; mas como cada PDV pode considerar essas movimentações de formas diferentes, precisamos receber essa informação já consolidada.

Verbos HTTP

Apesar dos princípios de boas práticas indicarem a obtenção de dados de um recurso através do verbo GET, a requisição de consulta na API pode ser através dos verbos HTTP GET ou POST.

É necessário que o gestor do ambiente nos sinalize qual verbo foi adotado para o retorno das requisições.

Métodos de autenticação (login)

Caso haja algum método específico de autenticação na API, é necessário descrever como invocá-lo e quais são os parâmetros envolvidos (username e password, na maioria dos casos). Nosso backend está preparado para autenticar-se em API’s via header, body ou access token.

A autenticação Basic Authorization é sempre uma opção muito conveniente para nós.

Exemplos dos métodos da API

Nos processos de integração com API’s já prontas, muitas vezes nos deparamos com documentações que não são suficientemente inteligíveis, não apresentam descrições detalhadas do conteúdo do ambiente ou não são claras o bastante sobre autenticação e/ou uso dos métodos.

Diante disso, para otimizar o processo, exemplos de uso dos métodos, descrições sucintas sobre o que o método retorna ou sinalização de em quais métodos estão as informações anteriormente solicitadas tornarão o processo mais rápido.