Web Service: ERP API

...

OBJETIVO

Integrar os sistemas Seidor e Ti9, referente aos registros de Clientes, Produtos e Pedidos de Vendas.

PRÉ-REQUISITOS

Vide Interface de Programação de Aplicativos (API) para integração ao ERP Ti9: Layout de Integração Ti9 v2.38.pdf

Vide manual da API para toda a especificação técnica: ERP-58899 - Interface de Programação de Aplicativos (API) para integração ao ERP Ti9 - V1V2.73.pdf

UTILIZAÇÃO

Através dos endpoints disponibilizados, as informações pode ser trocadas com o sistema Ti9 usando os métodos HTTP: POST e GET.

...

• Na criação de novo cliente, a resposta do servidor será: 201 - Created, seguida da mensagem que identifica, através de um número, o registro do cliente criado: "Requisição executada com sucesso. Código Pessoa: 007777", onde "007777" é o código do cliente atribuído pelo Ti9.
  
• Também sobre a inserção de um novo cliente, o valor de Código de Serviço Correios (visível através do GET Pedido Vendas) terá como valor padrão "04162".
• Caso um POST seja realizado em um registro já existente, o mesmo será atualizado com os dados do JSON (exceto o campo "codigo_servico", pois este campo nunca é atualizado e é considerado apenas na inclusão de novo cliente).
  A API reconhece o cliente através do CNPJ.
  

...

• Para inserções de pedidos via B2C o campo "ped_cliente" do layout deve ser enviado com o número do pedido Seidor. Este dado é muito importante para a identificação do pedido quando da atualização deste via B2C. Vide abaixo.
• Para atualizações de pedidos via B2B, os campos "filial" e "pedido_fil" do layout devem ser enviados com a filial e número do pedido. Tais campos podem ser encontrados ao abrir-se o pedido na tela "Vendas/Outras Saídas" no ERP-Ti9. Estes dados são muito importantes para a identificação do pedido quando da atualização deste via B2B. Vide abaixo.
• Quando da inserção do pedido de vendas, após validação, todos os dados serão salvos. A resposta do servidor será: 201 - Created, seguida da mensagem que identifica, através de um número, o pedido de vendas criado: “Pedido de vendas adicionado com sucesso! Número (Ti9): 0099999”, onde "0099999" é o número que o Ti9 atribuiu ao pedido criado.
• Os pedidos de venda serão recebidos a nível da etapa "Expedição", no Fluxo de aprovações do Ti9.
• A partir deste momento, o pedido de vendas fica aguardando a atualização por parte dos sistemas Seidor, das informações de Peso Líquido, Peso Bruto e VolumeVolume do Pedido, bem como o Lote dos itens.
  
  
•  Importante: Devido ao fato de todo o cálculo de peso bruto, líquido e volume serem feitos em outros sistemas, o Ti9 espera receber estas informações. Portanto, estas devem ser recebidas no cabeçalho do JSON como total, isto é, a soma dos pesos e volumes de todos os itens.
  
  
• O Ti9 então identifica este pedido com o status "W_UP_FROM_SEIDOR" e bloqueia qualquer tentativa de avanço no fluxo deste pedido de vendas, conforme ilustram as figuras 01 e 02:

Figura 01 - Relação dos pedidos. Aqui notamos quatro pedidos que estão com a situação de aguardo de atualizações.

Figura 02 - Pedido de vendas com fluxo bloqueado por ainda estar aguardando as atualizações de Peso Líquido, Bruto e Volume.

...

• Para contextos B2C, quando o sistema Seidor desejar enviar estas atualizações para o Ti9 ele deve realizar um novo POST, com o JSON completo do pedido de vendas. A API identificará o pedido de vendas através do campo "ped_cliente", conforme já citado.
• Para contextos B2B, para que a Seidor atualize os dados dados do pedido no Ti9 deve-se realizar um novo POST com o JSON específico para inserções de pedidos B2C. A API identificará o pedido de vendas através dos campos "filial" e "pedido_fil".
• A partir de então, serão considerados os dados de Pesos Bruto, Líquido e Líquido, Volume do Pedido e Itens (vide abaixo), o Lote dos Itens recepcionados no JSON. Os dados serão validados e estes serão atualizados no registro do pedido de vendas.
  
  
  
•  Importante:
assim como os dados Pesos Bruto e Líquido e Volume, a API também irá considerar os itens recepcionados. Isto quer dizer que, se o JSON inicial contemplava 03 itens, mas o JSON de atualização contempla 02 itens, então este pedido ficará, no final, com 02 itens. A API remove e recoloca os itens do pedido, conforme explicitado no JSON.

•  Importante: Para o funcionamento desta integração todos os pedidos devem passar pela etapa de expedição. Desta forma, caso a a necessidade da liberação de expedição do pedido for retirada o operador encontrará o seguinte erro ao tentar prosseguir com o pedido no Fluxo de Aprovações:

...

• A API também disponibiliza três GETs para que o sistema Seidor receba a situação deste pedido de vendas; isto é, em qual etapa do fluxo Ti9 ele se encontra. O primeiro destes GETs trata do contexto B2C, retornando um pedido a partir do campo "ped_cliente". O segundo e o terceiro tratam do contexto B2B, sendo que o segundo retornará um pedido a partir dos campos "filial" e "pedido_fil" e o terceiro retornará uma lista de pedidos com Status "NOVO" e "PENDENTE", ou seja, pedidos que não foram efetivadosexpedidos e estejam válidos (i.e., não encerrados nem bloqueados).
  Cada uma destas requisições GET retornará a mesma estrutura de dados, exemplificada abaixo.
  
  
•  Importante: Os status descritos abaixo seguem um padrão usado pelo cliente. Sua equivalência no fluxo de aprovação do ERP-Ti9 pode ser vista abaixo:

Image Added

Figura 05 - Relação Status Ti9 x Cliente

•  Importante: Para o GET da lista de Pedidos B2B, deve-se primeiramente parametrizar quais códigos de operação serão usados como filtro dos pedidos a serem retornados. Para tal, deve-se editar o campo "Código Operação API", encontrado no submenu "Parâmetros Gerais" da tela "Parâmetros do Faturamento".
  
  Image Added
  

  Figura 06 - Parametrização dos Códigos de Operação da API.

  
  
  
  
  
  PENDENTE: o pedido de vendas se encontra na etapa "Pedido" do fluxo do Ti9. Pode ou não já ter recebido as atualizações por parte da Seidor. O pedido pode ser atualizado por parte da Seidor quantas vezes for necessário se ainda estiver nesta etapa.
  
  

Figura 05 07 - Get do status Etapa Pendente.


Figura 06 08 - Post da atualização Etapa Pendente.


APROVADO: o pedido de vendas já foi atualizado com as informações por parte da Seidor e o usuário já o avançou no fluxo do Ti9. As atualizações neste pedido por parte da Seidor não são mais aceitas, onde qualquer tentativa retornará mensagem de crítica por parte da API.


Figura 07 09 - Get do status Aprovado.


Figura 08 10 -Post de tentativa de atualização.


FATURADO: o pedido já foi faturado no Ti9. Pode ou não já ter sua nota transmitida (NFe) para a SEFAZ. Caso já tenha sido transmitida com sucesso, o retorno também contemplará o número e série da NF, bem como o DANFE em formato Base64.


Figura 09 11 - Get do status. Pedido já faturado e NFe devidamente transmitida para a SEFAZ. Veja que o DANFE está contido no JSON, em formato Base64.

TAG de Serviço do Transportador

• Importante: Inserção de Etiquetas para parametrização de TAG de Serviço do Transportador
  Para que o código de serviço do correios seja disponibilizado no endpoint Get Pedido de Vendas, deve-se cadastrá-lo na tela "Campo do EDI e Etiquetas" de acordo com as instruções abaixo:
  
  
  1.Cadastro do Grupo “CORREIOS”
  
  2.Cadastro da variável "CÓDIGO SERVIÇO"
  
  3.Grupo "CORREIOS" inserido no cadastro do cliente 
  
  
  4.Variável do Serviço inserido no Cadastro do Cliente
  
  
  5. Sobre  Sobre a qual parte do Fluxo de Aprovações do Pedido de Vendas acionaria a disponibilização de tal campo para a OT, foi concordado que seria a etapa Expedição.
  
  
  Cabe aqui ressaltar que o Faturista poderá mudar o valor do campo "CÓDIGO SERVIÇO" na tela acima a qualquer momento antes da etapa Expedição. Caso a etapa de Expedição já tenha sido alcançada, deve-se voltar o pedido para uma etapa anterior de modo a realizar esta alteração. 
  
  

...