API para integração com o Linx emillennium
Modelo de integração, contendo os detalhes sobre nossa API no padrão ODATA que permite conversar utilizando REST, JSON, utilizado no Linx emillennium
Para permitir a chamada das funções expostas pelo servidor Linx emillennium por qualquer linguagem de programação do Windows, o Linx emillennium desenvolveu um componente ActiveX capaz de manipular e invocar as transações no servidor de aplicações por meio de TCP/IP utilizando um protocolo extremamente compacto e eficiente. A versão 2.0 do SDK possui também um gateway que permite a comunicação via OData/REST com o servidor. Este protocolo utiliza apenas padrões abertos da internet, permitindo a qualquer linguagem capaz de fazer chamadas HTTP acesso às funções do servidor. Qualquer nova integração deve utilizar a API OData/REST.
Devido ao grande volume de chamadas disponíveis na aplicação Linx emillennium, foram desenvolvidas algumas bibliotecas específicas, com chamadas mais concisas, especializadas em certas áreas. Neste documento trataremos do Linx emillennium _ECO, que foi desenvolvido para integrações onde o pedido de venda é capturado externamente ao Linx emillennium. Este cenário é típico de sites de e-commerce ou m-commerce, mas pode também ser utilizados em outros cenários como integração com coletores de dados ou qualquer outro dispositivo.
A biblioteca Millenium_Eco foi desenvolvida especialmente para facilitar o uso por integradores com a plataforma Linx | e-Millennium. Esta biblioteca expõe apenas métodos especializados em tarefas comuns de integração como:
- Leitura da árvore de classificações do produto;
- Leitura de produtos com suas características;
- Leitura de estoque;
- Leitura de preço;
- Leitura de cadastros auxiliares;
- Manutenção (inserção e alteração combinada) de clientes e consulta;
- Inserção e consulta de pedidos.
Além de limitar a lista dos registros antigos, é possível utilizar a opção $top nas chamadas para limitar o número de registros retornados. Esta forma de leitura é importante porque equilibra o processamento em lotes menores entre o servidor e sua aplicação. Os métodos que suportam controle de mudança são:
- Vitrine.Lista_Classificacoes
- Produtos.Lista ou Produtos.ListaVitrine
- Produtos.PrecoDeTabela
- Produtos.SaldoDeEstoque
- Pedido_Venda.ConsultaStatusWF
Abaixo temos um pseudo-código demonstrando este padrão para a listagem de produtos:
É importante enviar os pedidos ao Linx emillennium imediatamente após serem lançados para que o estoque seja reservado e reflita a baixa. Se isto não for feito, uma chamada que busca o estoque fará a leitura incorreta do saldo, podendo levar a vendas sem estoque disponível. Se a sua plataforma possuir o conceito de reserva, esta chance é bastante minimizada.
- SKU: Esta lista possui os dados das variações de um produto como cor e tamanho, além de suas características como dimensões e tempo de entrega. O campo “inativo” também deve ser verificado, já que o usuário pode desativar certos SKUs para que não apareçam para venda. As mudanças de preço e estoque devem ser lidas por meio dos métodos PrecoDeTabela e PRODUTOS.SaldoDeEstoque que também possuem controle de mudança.
- CLASSIFICAÇÕES: Retorna uma lista com os identificadores das classificações da vitrine associadas ao produto. Um produto pode estar associado a mais de uma classificação (isto pode ser controlado por vitrine). Se um produto é adicionado a uma classificação e depois removido, a lista ainda assim retornará tal classificação com o campo “EXCLUÍDO” marcado como true.
- ESPECIFICAÇÕES: A lista de especificações pode ser usada para adicionar classificações que variam produto a produto. Geralmente estes valores são usados para formar a área de filtro dos produtos, ou a aba de especificações técnicas. É possível identificar o uso da especificação por seu código. Cada especificação possui um tipo, um nome e uma descrição que podem ser utilizadas para compor o conteúdo dependendo da necessidade da plataforma. O uso pela plataforma (filtro, aba etc) pode ser controlado pelo tipo da especificação.
Se sua plataforma possui o conceito de reserva deve ser utilizado como saldo:
((SALDO + RESERVA_VITRINE)-(SALDO_NAOVITRINE – RESERVA_NAOVITRINE))
ESTOQUE_MIN
Se sua plataforma não possui o conceito de reserva, deve ser utilizado como saldo:
(SALDO)-(SALDO_VITRINE – RESERVA_VITRINE)-(SALDO_NAOVITRINE -RESERVA_NAOVITRINE)-ESTOQUE_MIN
Para facilitar o entendimento, vamos considerar 3 pedidos, WEB-000001 a WEB000003. O código dos pedidos deve ser enviado ao serviço da maneira que serão incluídos no Linx emillennium. É recomendado o uso de um prefixo antes do código do pedido (WEB-* no exemplo), para evitar conflito de numeração. Para cada pedido, deverá será enviado o status conforme tabela abaixo:
Status | Significado |
---|---|
0 – Aguardando Pagamento | O pedido foi inserido no site, mas o pagamento está pendente. Esta situação ocorre mais comumente em caso de pagamento por boleto, mas o Linx emillennium pode processar os cartões se assim for parametrizado. |
1 – Pagamento Confirmado | O pedido foi inserido no site e o pagamento já foi confirmado (do ponto de vista do site) |
2 – Em separação | Em outra chamada, o Linx emillennium retornou que o pedido está em separação. O site deve atualizar seu status e repassá-lo na próxima chamada. |
5 – Cancelado | O cliente cancelou o pedido no site. |
A chamada ao Linx emillennium ficará assim:
Quando o Linx emillennium retornar a ação 1, como no pedido WEB-000001 do nosso exemplo, você deve chamar a sequência de inclusão de pedidos, conforme sequencia abaixo:
Quando o Linx emillennium retorna a ação 2 (mudar status), o campo status associado à ele retornará para qual status você deve alterar seu pedido. Conforme o status, alguns campos associados ao registro também retornam conforme tabela abaixo. Note que estes status devem ser considerados sempre quando a ação é 2, em outras ações esta tabela não se aplica:
Seu Status | Status Retornado | Significado |
---|---|---|
0 – Aguardando Pagamento | 1 – Pagamento confirmado | O Linx emillennium verificou que todos os títulos financeiros associados ao pedido já foram processados. Normalmente isto ocorre em casos de boleto, já que a plataforma deve aguardar o processamento do boleto para liberar o pedido, porém existem casos onde o Linx emillennium pode processar também os cartões. |
1 – Pagamento Confirmado | 2 – Em preparação | Ao passar ao Linx emillennium a confirmação do pagamento, é executada a liberação da reserva para expedição, gerando o retorno de preparação. |
2 – Em separação | 3 – Despachado | O pedido foi faturado e a nota aprovada. Se foi implementada a integração SIGEP, o sistema irá aguardar que o numero do objeto seja informado. Os campos serão também retornados: nota, serie_nf, url_tracking_pedido, valor, data_emissao_nf |
Vale ressaltar que, enquanto o status não mudar, a ação retornada será 0 (zero), indicando que nada deve ser feito em relação ao pedido. A tabela acima aplica-se apenas quando a ação retornada é 2.
Baixe Documentação Completa
Servidor de Teste
Todos os nossos métodos para integração estão disponíveis e atualizados online em uma instância de integração que permite iniciar os testes de integração imediatamente.
Que tal uma coleção de exemplos prontos de nossa API?
Instale a extensão do Google Chrome – Postman:
Após instalar o Postman, importe a nossa Collection para ver os exemplos.
É bem simples, Copie e cole esse endereço https://www.getpostman.com/collections/48e8b7be282e4574a195 na Opção “Import a Collection” disponível no Postman, conforme figura abaixo: