Visão Geral
A API de Extrator de Vendas do LinxERP para Envio ao Equals é uma funcionalidade que permite extrair as informações de vendas registradas no LinxERP e enviá-las para a plataforma Equals. Essa integração possibilita uma conciliação precisa e automatizada dos pagamentos realizados com cartões de crédito.
Sobre o Extrator de Vendas Linx
O extrator de vendas da Linx refere-se as vendas efetuadas dentro do ERP com suas respectivas informações que serão apresentadas abaixo, os dados desta extração.
Integração Linx Extrator de Vendas: Chamada API GraphQl
Para a utilização da API do Extrator de Vendas da Linx são utilizadas as seguintes variáveis de chamada (idEstabelecimentoERP, dataInicial, dataFinal, regerar e sistema).
Figura 1 – Exemplo do objeto Json de chamada
{ "input": { "idEstabelecimentoERP": "000010", "dataInicial": "2019-01-01", "dataFinal": "2020-03-31", "regerar": false, "sistema": 1 } }
Atenção
Abaixo são apresentados os campos, sua obrigatoriedade, os tipos do campo, tamanho máximo de cada campo, assim como uma breve descrição de cada campo.
Figura 2 – Layout das Variáveis
Campo | Obrigatório | Tipo do Campo | Tamanho Máximo | Conteúdo |
IdEstabelecimentoERP | Sim | Alfanumérico | 50 | Código que identifica a loja/filial onde a venda foi registrada a ser integrado. |
DataInicial | Sim | Data | 10 | Data Inicial para Consulta em padrão SQL Americano. |
DataFinal | Não | Data | 10 | Data Final para Consulta em padrão SQL Americano. |
Regerar | Não | Booleano | True/false | Verificar se será selecionado as vendas com problemas de processamento anteriormente, e não foram conciliadas. |
Sistema | Não | Numérico | 1 | Enumerador: LINX ERP: Valor 1 |
Atenção
Abaixo é apresentado o modelo de uma busca de variável nas ferramentas Banana Cake POP, Banana Cake Web e Postman para uma busca no Extrator de Vendas do ERP.
Figura 3 – Exemplo Banana Cake POP, Banana Cake Web e Postman
Resposta da API
- A API retornará um código de status 200 (OK) em caso de sucesso, juntamente com um objeto JSON contendo as informações das vendas extraídas do LinxERP.
- Em caso de falha, a API retornará um código de status apropriado, juntamente com uma mensagem de erro descrevendo o motivo da falha.
Integração Linx Extrator de Vendas: Retorno API GraphQl
Para a utilização da API do Extrator de Vendas da Linx são utilizadas as seguintes query de retorno (nSR, iDEstabelecimentoERP, data, numeroUnicoERP, numeroUnicoNegocioLocalizado, nomeCliente, documentoCliente, observacaoVendas, informacaoAdicional1Venda, informacaoAdicional2Venda, flagCancelamento, iDTransacao, autorizacao, nSU, tID, documento, parcelas, iAdquirente, iDBandeira, iDFormaDePagamento, iDMeiodeCaptura, observacaoTransacao, informacaoAdicional1Pagamento, informacaoAdicional2Pagamento, valor).
Figura 4 – Exemplo do objeto Json de retorno
mutation testeIntegration($input: AddExtratorVendasCommandInput){ addExtratorVendas(input: $input){ vendas{ nSR, iDEstabelecimentoERP, data, numeroUnicoERP, numeroUnicoNegocioLocalizado, nomeCliente, documentoCliente, observacaoVenda, informacaoAdicional1Venda, informacaoAdicional2Venda, flagCancelamento, iDTransacao, autorizacao, nSU, tID, documento, parcelas, iDAdquirente, iDBandeira, iDFormaDePagamento, iDMeioDeCaptura, observacaoTransacao, informacaoAdicional1Pagamento, informacaoAdicional2Pagamento, valor } } }
Atenção
Abaixo são apresentados os campos, os tipos do campo, seu conteúdo, assim como as observações de cada campo.
Figura 5 – Layout da Query
Campo | Tipo do Campo | Conteúdo | Observações |
Vendas | Array [] Vendas com os campos a seguir: | Lista de Vendas no ERP | Retorna o objeto contendo a lista de vendas do ERP a Integrar conforme a chamada |
NSR | Data | Número sequencial do registro no arquivo | Deve evoluir de 1 em 1 para cada registro (linha) dentro do arquivo |
IdEstabelecimentoERP | Alfanumérico | Código que identifica a loja/filial onde a venda foi registrada a ser integrado. | |
Data | Data | Data da Venda | |
NumeroUnicoERP | Alfanumérico | Identificador da venda no sistema interno | Deve ser único para cada venda |
NumeroUnicoNegocioLocalizado | Alfanumérico | Código utilizado para pesquisar facilmente a venda no Equals | Localizador: Pode se repetir entre vendas diferentes |
NomeCliente | Alfanumérico | Nome do cliente comprador | |
DocumentoCliente | Alfanumérico | CPF ou CNPJ do cliente comprador | Pode ser utilizado para enviar algum outro código interno que identifique o comprador, caso exista |
ObservacaoVenda | Alfanumérico | Observação sobre a venda | Tamanho máximo: 200 |
InformacaoAdicional1Venda | Alfanumérico | Informação adicional da venda | |
InformacaoAdicional2Venda | Alfanumérico | Informação adicional da venda | |
FlagCancelamento | Alfanumérico | “C” para indicar cancelamento | Se o campo estiver vazio ou com qualquer outro caractere diferente de “C”, o registro será considerado vinculado a uma transação de pagamento |
IDTransacao | Alfanumérico | Identificador da transação no sistema interno | Se enviado, deve ser único para cada transação |
Autorizacao | Alfanumérico | Código de autorização gerado pela adquirente | |
NSU | Numérico | NSU gerado pela adquirente ou Nosso Número gerado pelo banco para boletos | |
TID | Alfanumérico | TID (Transaction ID) gerado pela adquirente para transações via e-commerce | Transação |
Documento | Alfanumérico | Número do Cartão | Deve demonstrar somente os 6 primeiros e 4 últimos dígitos, mascarando o restante. Ex: 123456******7890 |
Parcelas | Numérico | Total de parcelas da transação | |
IDAdquirente | Numérico | ||
IDBandeira | Numérico | ||
IDFormaDePagamento | Alfanumérico | ||
IDMeioCaptura | Numérico | ||
ObservacaoTransacao | Alfanumérico | Observação sobre a transação | |
InformacaoAdicional1Pagamento | Alfanumérico | Informação adicional da transação de pagamento | Não preenche para cancelamentos |
InformacaoAdicional2Pagamento | Alfanumérico | Informação adicional da transação de pagamento | Não preenche para cancelamentos |
Valor | Numérico | Valor da venda, decimal de duas casas. | Números não inteiros devem ser informados com vírgula e no máximo duas casas decimais, considerando o valor bruto da transação. Ex: 10,99 |
Atenção
Abaixo é apresentado o modelo de uma busca de query nas ferramentas Banana Cake POP, Banana Cake Web e Postman para uma busca no Extrator de Vendas do ERP.
Figura 6 – Exemplo Banana Cake POP, Banana Cake Web e Postman
Integração Linx Extrator de Vendas: Comunicação com a API
Para a utilização da API do Extrator de Vendas da Linx e sua integração são liberados dois endpoints, um apontado para um ambiente de desenvolvimento e outro para um ambiente de testes.
Para os mesmos ambientes é disponibilizado o mesmo token, que seguem abaixo com os exemplos:
Ambiente DEV: https://dev-linx-erp-extrator-vendas.azurewebsites.net/graphql/
Figura 7 – Endereço da API de DEV nas ferramentas Banana Cake Pop e Postman
Ambiente QA: https://qa-linx-erp-extrator-vendas.azurewebsites.net/graphql/
Figura 8 – Endereço da API de QA nas ferramentas Banana Cake Pop e Postman
Autenticação: Para QA e DEv utilizar a autenticação do token Bearer, Chave única:
"Token": "f3413f64-3e3c-415b-a274-d417828ea2d9"
Figura 9 - Exemplo de autenticação via Banana Cake Pop, Bana Cake Web e Postman
Para o Postman você pode criar coleções para o seu teste assim como criar ambientes específicos para os testes exemplo: ambiente de desenvolvimento e ambiente de teste.
Figura 10 - Exemplo de Ambientes para testes
Resposta da API
- A API retornará um código de status 200 (OK) em caso de sucesso, juntamente com um objeto JSON contendo as informações das vendas extraídas do LinxERP.
- Em caso de falha, a API retornará um código de status apropriado, juntamente com uma mensagem de erro descrevendo o motivo da falha.
Importante
Para produção cada cliente terá seu endereço “URL” e seus respectivos tokens para acesso à produção.