Integração de Transportadora via Layer (API Linx Commerce)

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.

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.
  Exemplo de requisição: Expandir origem

  {
     "QueueID":null,
     "QueueAlias":"Transportadora",
     "LockItems":0,
     "LockSpan":null,
     "Attempts":10,
     "Page":{
        "PageIndex":0,
        "PageSize":200
     },
     "Where":"",
     "WhereMetadata":"",
     "OrderBy":""
  }
  

• 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

  
  

  Exemplo: Expandir origem

  { "QueueItems": [ "d0a81f13-6072-4c02-a960-fec808983658" ] }

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

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.