Esta documentação fornece um guia passo a passo para integrar uma transportadora à plataforma Linx Commerce utilizando a Layer (API). O objetivo é facilitar o gerenciamento logístico e otimizar o processo de envio de pedidos.
Pré-requisitos
- Conta na Plataforma Linx Commerce: Certifique-se de que você possui uma conta ativa.
- Transportadora cadastrada na plataforma: verifique se a transportadora está cadastrada na plataforma;
- Credenciais da layer (API): Obtenha as credenciais necessárias para autenticação.
- Conhecimento Básico em Programação: Familiaridade com requisições HTTP e JSON.
1 - Configuração do envio do pedido para Consumo Integrador:
- Todo o pedido que for criado com o meio de entrega configurado para ter integração via layer (API) será necessário ser consumido pelo parceiro logístico. Para que essa integração de pedidos possa ocorrer é necessário que haja a criação de uma fila de pedido, e também, um mecanismo que envie o pedido para essa fila para consumo.
- Será criado a fila de recebimento do pedido e o workflow de envio do pedido com o meio de entrega configurado para esta mesma fila.
1.1 - Fila de integração:
- No painel, acesse o menu Integrações > Gerenciamento de filas > Adicionar Fila e clique em Adicionar Fila;
- Preencha as informações da Guia Fila e clique em salvar ou Salvar e fechar:
- Na seção Consumidores é necessário criar um usuário com permissão de administrador para receber os pedidos.
2. - Fuxo de pedido
No painel, acesse o menu Configs > Fluxos > e selecione o workflow que será desejado conter a tarefa que envia o pedido para a fila recém criada para que a transportadora possa consumir o pedido.
Ao selecionar o workflow desejado, será necessário adicionar um novo grupo e inserir a tarefa Enviar pedido para a fila de integração, e preencher conforme imagem abaixo, selecionando a fila de integração criada:
- Sendo assim, sempre que o pedido for da transportadora e entrar nesse estágio, o pedido será direcionado para a fila para ser consumido.
3. Consumo do pedido pelo Integrador:
O consumo é realizado através do pedidos contido na fila de integração criada exclusivamente para a transportadora. Sendo assim, todo o pedido que constar nessa fila será um pedido que a transportadora fará o consumo para dar as tratativas, e posteriormente, atualizar a entrega na plataforma.
3.1 - Obtendo pedidos na fila de integração
Deverá ser executado o método da API (SearchQueueItems) com o devido conteúdo no body: (o QueueAlias a ser passado é o nome da fila criado na seção 1.1)
- Método /v1/Queue/API.svc/web/SearchQueueItems.
- No retorno deve ser levado em consideração o conteúdo da propriedade EntityKeyValue, onde ele representa a identificação do pedido que deverá ser informado no método. Um ponto de observação é o conteúdo da próriedade EntityTypeName. Caso seja EZ.Store.Model.Sales.PurchaseOrder, o conteúdo da propriedade EntityKeyValue será passado no método GetOrderByNumber, mas caso seja OrderGroupNumber faremos a busca dos dados do pedido através do método GetOrderGroupByNumber.
3.2 - Busca das informações do Pedido
- Deverá ser executado o método da API GetOrderByNumber para pedidos PurchaseOrder e o método da API GetOrderGroupByNumber para o EntityTypeName OrderGroupNumber.
- Ambos os métodos o conteúdo da requisição é o número do pedido obtido na busca de pedidos na fila de integração.
3.3 - Atualização de Pedidos (UpdateOrder)
- Após consumir o pedido que consta na fila, o mesmo deverá ser removido desta fila para que tenhamos um gerência correta da integração.
Deverá ser chamado o método da API de QUEUE DequeueQueueItems com o devido conteúdo na requisição: (Notem que deve ser inserido o QUEUEITEMID do item retornado no primeiro passo de consulta a fila):
Método:/v1/Queue/API.svc/web/DequeueQueueItems
3.4 - Atualização de Pedidos (UpdateOrder)
- Após consumir o pedido que consta na fila, e dar todas as tratativas internamente na transportadora, as atualizações que ocorrerem na transportadora deverão ser enviadas para a plataforma;
- Para atualizar os pedidos, utilizamos o método v1/Sales/API.svc/web/UpdateOrder, onde através dele serão inseridas as informações de atualizações dos pedidos
WorkflowTypes permitidos:
WorkflowTypes permitidos:
- ConfirmPayment, Invoiced, Shipped, Delivered, Canceled, PickupReady, PickupFail.
4 - Coleção Postman:
Abaixo os métodos listados na seção 3 com os respectivos exemplos a serem seguidos para ter uma completa integração:
- https://api.postman.com/collections/2169989-7585118f-9eff-4ece-bf68-d845de69dfc7?access_key=PMAT-01HYDX2MMXSHXHEVVF2RZMQ1ZF
- Os métodos recebem como endpoint o nome da loja, conforme exemplo: https://nomedaloja.layer.core.dcg.com.br/v1/Sales/API.svc/web/UpdateOrder;
- A autenticação é basic auth, onde será gerada uma por ambiente visando conseguirem realizar a integração completa.
Atenção!