Integração WMS Operador Logístico X ERP Datasul

Contexto de Negócio (Introdução)

Muitas empresas que atuam do ramo de transportes vêm se tornando operadores logísticos, visando atender de forma mais completa as necessidades dos seus clientes.

Atualmente, há vários clientes TOTVS que se encontram nesta situação, sendo que a partir do momento em que aceitam realizar a operação logística completa dos seus clientes, necessitam ter um sistema WMS que atenda às necessidades específicas de cada um, além de contemplar também a legislação fiscal específica deste segmento.

Sistemas Envolvidos

• WMS Operador Logístico (Logix)
• ERP Datasul
  
  

Escopo

O escopo da integração de processos do WMS Operador Logístico x ERP Datasul, é:

Todas as mensagens de integração utilizadas seguem o padrão de mensagens padronizadas da TOTVS, a chamada TOTVSMessage.

No ambiente do WMS (Logix) serão utilizadas e registradas apenas informações relativas aos processos do armazém. As informações que são exclusivas de módulos como Fiscal, Contabilidade e Financeiro serão controladas apenas no ERP Datasul.

Pré-requisitos Instalação/Implantação/Utilização

No WMS, os seguintes pré-requisitos devem ser verificados:

• Versão: A partir da release 12.1.20.
• Webservice criado para permitir a comunicação com o ERP Datasul.
• Instalação do EAI Logix, que deverá estar configurado e com as mensagens de integração habilitadas no monitor (EAI10000).
• Nos casos em que o WMS já esteja em uso no cliente antes desta integração padrão, ao gerar o primeiro documento (nota fiscal de retorno simbólico, nota fiscal por conta e ordem, nota fiscal de faturamento de serviços) o sistema irá verificar se o controle de numeração de transações de documentos precisa ser ajustado. Caso seja identificada esta necessidade será apresentada a mensagem abaixo:
  
  Se a resposta for “Não” a geração do documento solicitado não será efetuada, interrompendo o processo em andamento.
  Se a resposta for “Sim” o sistema primeiro irá atualizar este controle de numeração das transações, para depois dar continuidade na geração do documento.
  Este procedimento de atualização é necessário para que não sejam duplicados os números de transações de nota fiscal gerados anteriormente, o que causaria conflitos de informações geradas antes e após a implantação da integração.

No Datasul relacionamento De/Para de códigos é visualizado através da opção disponível no TOTVS Monitor:

1. Acessar o TOTVS Monitor;

2. Clicar no Folder "EAI 2“;

3. Clicar no Folder "Aplicação Externa“;

4. Selecionar o Aplicativo Externo;

5. Clicar no botão "De-para“;

6. No combo-box "Estrutura“, selecione o De-para e faça a inclusão ou alteração conforme a necessidade.

É necessário verificar também que no registro de documentos de entrada no Datasul o número do documento irá conter zeros à esquerda, no Logix o documento (nota fiscal) é do tipo numérico.

Instalação/Configuração

Configuração do EAI Logix

Para configurar o EAI Logix devem ser executados os seguintes procedimentos:

• Informar os dados abaixo no arquivo de configuração do TOTVSTEC (TotvsAppServer.ini ou AppServer.ini):
  
  [HTTP]
  Enable=1
  Port=<escolha_uma_porta_disponivel>
  path=c:\totvs\bin\smartclient\
  
  [WEBSERVICES]
  Enable=1
  Environment=<ambiente>
  Conout=0
  Trace=0
  NameSpace=http://www.totvs.com
  URLLocation=http://<seu_ip>:<porta_escolhida_em_http>
  Logix=1
  
  [ONSTART]
  Jobs=4GLJOBEAI1
  
  [4GLJOBEAI1]
  Environment=<ambiente>
  Main=EAIStarter

• Informar os dados abaixo no arquivo de profile do TOTVSTEC (TotvsProfile.pro):
  
  eai.hostapplication=<nome para identificar o Logix na integração>
  eai.debug=<0 para inativo ou 1 para ativo>
  eai.configprovider=EAIConfigProviderLogix
  eai.userid=<usuario Logix>
  eai.companyid=<empresa Logix>

• Configurar as transações que serão enviadas e recebidas:
  
  Executar o programa EAI10000 (Monitor EAI), acesse o menu Configuração > Host Application e conferir se o nome colocado na chave eai.hostapplication do arquivo de configuração do TOTVSTEC aparece no campo Hospedeiro na interface.
  
  Se o nome do aplicativo hospedeiro estiver aparecendo corretamente, clique no botão “Modificar” e responda Sim para “Recarregar as Transações”. Neste momento o EAI irá percorrer o seu RPO para localizar os adapters existentes. Estes adapters representarão as mensagens que o EAI irá trabalhar.
  
  Ainda no programa EAI10000, acessar o menu Configuração > External Apps. O objetivo desta opção é registrar quais serão os EAIs externos que serão utilizados para se comunicar ou que serão comunicados.
  
  Clique em “Incluir” e depois no botão “Configurar”. Selecionar a “Classe canal” correspondente ao produto com o qual queira se comunicar. No quadro “Propriedades” preencher as informações solicitadas e clicar em “Confirmar”. Para configuração do webservice do Datasul é necessário informar o usuário e senha.
  
  Após isso, serão exibidas na tela principal as transações que o aplicativo externo possui e com o qual pode-se trocar informações. Clicar em “Confirmar” para finalizar a parametrização.
  
  Depois de terminar a configuração dos aplicativos externos volte para a tela Configuração > Host Application e clique novamente em “Modificar”.
  Responda Não para “Recarregar as Transações”. Em seguida dê dois cliques no campo “Rotas” de cada mensagem, para indicar para qual aplicativo externo a mesma será enviada, habilitando a rota desejada:
  

Ao executar os procedimentos acima o EAI Logix está configurado para receber e enviar mensagens.

Configuração do EAI-2 Datasul

Para configurar o EAI-2 Datasul consulte a documentação em EAI 2.

Cadastramento de Programas no Menu Logix

Parâmetros Gerais Logix

Executar o programa LOG00087 (Manutenção de Parâmetros) e acessar o seguinte caminho:

PROCESSO SAÍDAS → CADASTROS & TABELAS → CADASTROS & TABELAS

Os parâmetros abaixo fazem parte desta integração e devem ser devidamente atualizados antes da utilização:

Código Único

Em:

LOGIX WMS → LOGIX WMS → INTEGRAÇÃO COM OUTROS SISTEMAS

Entre os parâmetros apresentados, verificar e atualizar o que segue abaixo:

Em:

LOGIX WMS → OPERADOR LOGÍSTICO → EXPEDIÇÃO

Entre os parâmetros apresentados, verificar e atualizar o que segue abaixo:

(*) Estes parâmetros já existiam antes desta integração.

Engine de Regras - Datasul (aplicado no processo de Recebimento)

A Conta de aplicação e Centro de custo de aplicação são informações que o Logix não tem para enviar para o Datasul, portanto existem 2 opções:

1. Alterar o item no programa CD0138 informando a conta e centro de custo padrões do item
2. Criar engine de regras re-conta-apl-eai com a finalidade de sugerir essas informações:

• Os retornos da regra de conta aplicação podem ser a conta e o centro de custo:
• Retorno da conta: re-conta-apl-eai
• Retorno do centro de custo: re-ccusto-apl-eai
• Se a conta não utiliza centro de custo não precisa do retorno do centro de custo.

Relacionamento De/Para de Empresa/Filial no Logix

Para que uma mensagem de integração possa ser recebida, é necessário informar o código da empresa e/ou filial do sistema de origem. Quando uma mensagem é recebida pelo Logix, a partir da “Empresa Externa” e “Filial Externa” existentes na TOTVSMessage o sistema identificará qual é a “Empresa Logix” para atualização dos dados. Estas informações são registradas no EAI10000 (Controle de Mensagens EAI), dentro do cadastro de "Aplicativos Externos", na opção "De/Para Empresas".

Relacionamento De/Para de Empresa/Estabelecimento no Datasul

Acessar o TOTVS Monitor -> Folder EAI-2 -> Folder Aplicação Externa -> Selecionar Aplicativo Externo -> Botão "De para":

No combo-box "Estrutura“, selecione o De-para e faça a inclusão ou alteração conforme a necessidade.

Empresa: CompanyInternalId - fnd_empres

Estabelecimento: BranchInternalId - estabelec
Importante: O Logix não tem a entidade estabelecimento. Para diferenciar os estabelecimentos deverá ser relacionado o código do estabelecimento Datasul x Empresa Logix.
Exemplo:
EmpresaLogix = 31
EstabelecimentoDatasul = 101

Outras Configurações no ERP Datasul

É necessário também realizar algumas configurações adicionais para Operador Logístico no ERP Datasul, para isso consultar a FAQ: DUFN0025 - Parâmetros Gerais da Integração do Operador Logístico

Configuração das Naturezas de Operação - Recebimento/Regularização Fiscal

O Datasul deve possuir no mínimo três naturezas de operação de entrada cadastradas para utilização nas mensagens InputDocument (Documento de Entrada)  e CoverageDocument (Regularização Fiscal). Cada Natureza deve ter seus campos corretamente preenchidos, conforme orientação e necessidade do usuário. É imprescindível a Natureza de operação e Engine de regras da natureza de operação estarem configurada corretamente para o correto funcionamento do processo.

1. A primeira Natureza de operação será utilizada para receber as NOTAS FISCAIS PROVISÓRIAS do WMS Logix. Os demais campos devem ser cadastrados conforme necessidade do usuário, porém os campos abaixo devem ser da seguinte maneira:

2. A segunda Natureza de operação será utilizada para receber as NOTAS FISCAIS DEFINITIVAS do WMS Logix. Os demais campos devem ser cadastrados conforme necessidade do usuário, porém os campos abaixo devem ser da seguinte maneira:

3. A terceira Natureza de Operação será utilizada para receber as NOTAS FISCAIS DEFINITIVAS do WMS Logix, resultantes do processo de Regularização Fiscal (cobertura). Os demais campos devem ser cadastrados conforme necessidade do usuário, porém os campos abaixo devem ser da seguinte maneira:

Configuração das Naturezas de Operação - Faturamento

O WMS envia na tag TypeOperation (existente na mensagem SalesOrder) o código da natureza de operação parametrizada para cada processo, conforme indicado no LOG00087 em LOGIX WMS → OPERADOR LOGÍSTICO → EXPEDIÇÃO.

A partir do conteúdo desta tag o ERP Datasul irá definir a natureza de operação a ser utilizada na nota fiscal a ser emitida, utilizando a funcionalidade de Sugestão da Natureza de Operação, conforme detalhado neste link: DPED0082 - Sugestão Automática da Natureza de Operação.

Controle de Versão

O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

Suporte

O suporte aos recursos da Integração será de responsabilidade de todas as linhas, sendo assim as equipes de suporte dos produtos WMS Operador Logístico e ERP Datasul estarão aptas a fazer a primeira análise e, quando necessário, repassar para a equipe mais adequada em cada caso.

Transações/Entidades/Mensagens únicas

Para esta integração estão previstas as mensagens abaixo:

Nota:

(*) A mensagem SalesOrder é única para todos os tipos de nota fiscal que necessitam ser gerados.

Para que cada processo indicado acima possa ocorrer, é necessário que previamente os principais cadastros também estejam integrados. São eles:

Nota:

(*) A mensagem CustomerVendor é única para fornecedores e clientes, o que diferenciará um cadastro de outro será a tag _Type, que poderá ter os valores “Customer” (Cliente), “Vendor” (Fornecedor) ou “Both” (Ambos).

Fluxo das Informações

As mensagens de integração existentes entre o WMS Operador Logístico e o ERP Datasul são:

Cadastros

1.1 Cadastro de Fornecedor / Cadastro de Cliente – CustomerVendor

Nesta mensagem serão integradas as informações principais dos cadastros de fornecedores e de clientes, que dentro do EAI é identificada pelo nome CustomerVendor.

No Logix o envio desta mensagem ocorre a partir destes programas, quando uma manutenção é realizada:

• VDP0815 - Cadastro Cliente/Fornecedor (versão 10.2/11.0)
• VDP10000 - Cadastro Cliente/Fornecedor (versão 12)

1.2 Cadastro de Transportador – Carrier

Nesta mensagem serão integradas as informações principais do cadastro de transportadoras, que dentro do EAI é identificada pelo nome Carrier.

No Logix o envio desta mensagem ocorre a partir destes programas, quando uma manutenção é realizada:

• VDP0815 - Cadastro de Cliente/Fornecedor (versão 10.2/11.0)
• VDP10000 - Cadastro de Cliente/Fornecedor (versão 12)

1.3 Cadastro de Locais de Entrega – CustomerShippingAddress

Nesta mensagem serão integradas as informações dos locais de entrega do cliente, que dentro do EAI é identificada pelo nome CustomerShippingAddress.

No Logix o envio desta mensagem ocorre a partir destes programas, quando uma manutenção é realizada:

• VDP0815 - Cadastro de Cliente/Fornecedor (versão 10.2/11.0)
• VDP10000 - Cadastro de Cliente/Fornecedor (versão 12)

1.4 Cadastro de Item – Item

Nesta mensagem serão integradas as informações principais do cadastro de item, que dentro do EAI é identificada pelo nome Item.

No Logix o envio desta mensagem ocorre a partir destes programas, quando uma manutenção é realizada:

• MAN9922 - Cadastro de Item (versão 10.2/11.0)
• MAN10021 - Cadastro de Item (versão 12)

Para os itens a serem utilizados no processo de faturamento de serviço é necessário informar o campo "Serviço prestado" na opção Comercial do MAN10021 (Cadastro de Itens). Esta informação é obrigatória para emissão da NFS-e (Nota Fiscal de Serviço Eletrônica) e corresponde ao código do SPED Fiscal, que pode ser consultado neste link: http://sped.rfb.gov.br/pagina/show/1601

No Datasul podem ser cadastrados os seguintes De-para de códigos entre o Logix→Datasul:

Processos

1.1 Nota Fiscal Recebimento WMS – InputDocument

Nesta mensagem serão integradas as informações das notas fiscais de recebimento, que dentro do EAI é identificada pelo nome InputDocument.

No Logix o envio desta mensagem ocorre a partir destes programas:

• WMS6628 – Integração Nota Fiscal Recebimento – Inclusão
  • A mensagem é enviada com o tipo de operação “upsert” (inclusão/modificação);
  •  Notas fiscais consideradas:
    • Notas fiscais Provisórias (tipo “A”).
    • Notas fiscais Definitivas (tipo “B”) marcadas para recebimento de produtos (que não são apenas para regularização fiscal).
  • Para os depositantes com contrato no regime de “Filial” não são processadas as notas fiscais.
  • Os demais tipos de nota fiscal não são tratados nesta integração.

• WMS6629 - Integração Nota Fiscal Recebimento – Exclusão
  • A mensagem é enviada com o tipo de operação “delete” (exclusão);
  •  Notas fiscais consideradas:
    • Notas fiscais Provisórias (tipo “A”).
    • Notas fiscais Definitivas (tipo “B”) marcadas para recebimento de produtos (que não são apenas para regularização fiscal).
  • Para os depositantes com contrato no regime de “Filial” não são processadas as notas fiscais.
  • Os demais tipos de nota fiscal não são tratados nesta integração.

• WMS6156 – Regularização Fiscal
  • A mensagem é enviada com o tipo de operação “upsert” (inclusão/modificação) quando a regularização fiscal é processada e como “delete” (exclusão) quando é cancelada.
  • Somente envia a mensagem para nota fiscal Definitiva – tipo “B” – que esteja regularizando outra nota fiscal Definitiva.
  • Nesta situação, a mensagem CoverageDocument (Regularização Fiscal) não é enviada.

É importante destacar que após a nota fiscal ter sido integrada ao Datasul não será mais possível a sua manutenção ou exclusão no Logix. Para que isso ocorra será necessário executar a exclusão da integração da nota fiscal (WMS6629).

1.2 Regularização Fiscal – CoverageDocument

Nesta mensagem serão integradas as informações da regularização fiscal, que dentro do EAI é identificada pelo nome CoverageDocument.

No Logix o envio desta mensagem ocorre a partir do programa WMS6156 (Regularização Fiscal):

• A mensagem é enviada com o tipo de operação “upsert” (inclusão/modificação) quando a regularização fiscal é processada e como “delete” (exclusão) quando é cancelada.
• Somente envia a mensagem para nota fiscal Definitiva – tipo “B” – que esteja regularizando apenas notas fiscais Provisórias.
• Se a nota fiscal for Definitiva e estiver regularizando outra nota fiscal Definitiva será enviada apenas a mensagem InputDocument.

1.3 NF Retorno Simbólico – SalesOrder

Nesta mensagem serão integradas as informações para que o ERP Datasul emita a nota fiscal de retorno simbólico para o depositante. No EAI esta mensagem é identificada pelo nome SalesOrder.

No Logix o envio desta mensagem ocorre a partir destes programas:

• WMS9745 – Emissão de Documentos
• WMS6496 – Liberação Veículo para Portaria (quando está parametrizado para gerar NF de retorno simbólico automático em caso de falta)
• SUP50001 – Conta-Corrente Inventário
• WMS7013 – Montagem/Desmontagem de Kit
• WMS6429 – Integração de Pedidos de Venda – Exclusão

1.4 NF Conta e Ordem – SalesOrder

Nesta mensagem serão integradas as informações para que o ERP Datasul emita a nota fiscal por conta e ordem. A nota fiscal por conta e ordem somente deve ser gerada nos casos em que a unidade de federação do depositante for diferente da unidade de federação da empresa (operador logístico). No EAI esta mensagem é identificada pelo nome SalesOrder.

No Logix o envio desta mensagem ocorre a partir destes programas:

• WMS9745 – Emissão de Documentos
• WMS6429 – Integração de Pedidos de Venda – Exclusão

1.5 NF Faturamento Serviço – SalesOrder

Nesta mensagem serão integradas as informações para que o ERP Datasul emita a nota fiscal de faturamento de serviço. No EAI esta mensagem é identificada pelo nome SalesOrder.

As informações tratadas atualmente nesta mensagem são:

No Logix o envio desta mensagem ocorre a partir destes programas:

• WMS6412 – Preparação e Geração Faturamento Serviço
• WMS6429 – Integração de Pedidos de Venda – Exclusão
  
  

Limitações / Restrições Gerais

• No cadastro de Cidades (VDP3080) é obrigatório o preenchimento do campo “Munícipio IBGE”, pois esta informação será a chave de comunicação para identificação dos municípios entre os dois sistemas.
• No cadastro de Países do Logix (VDP3180) é obrigatório o preenchimento do campo "Siscomex" ou "País BACEN", pois estas informações serão utilizadas para identificação do país entre os dois sistemas. No Datasul é necessário informar o código Siscomex no cadastro CD0181 (EMS2) e também o código país DIRF no cadastro bas_pais (EMS5).
• As unidades de medida e condições de pagamento deverão estar cadastradas nos dois sistemas com os mesmos códigos, pois não há de/para para estas informações.
• Para os depositantes identificados sob o regime de “Filial” não serão integradas as informações dos documentos (nota fiscal recebimento, regularização fiscal, NF de retorno simbólico, NF de conta/ordem).
• Quando o depositante não for emitente de nota fiscal (parâmetro “É emitente de NF rem.armazenagem (integração)?” na rotina WMS60013 (Contrato), opção “Expedição-Embarque/Fiscal”) não será permitido realizar a regularização fiscal (WMS6156) utilizando uma NF/Sequência definitiva para duas ou mais NF/Sequência provisórias. Nesta situação, a nota fiscal de entrada a ser emitida no ERP Datasul já deverá ter sido gerada com várias sequências de maneira que seja possível efetuar o relacionamento 1 para 1.

Como fazer

Os passos para viabilizar a integração são:

• No Logix ou no ERP Datasul efetue o cadastro das seguintes informações: Clientes, fornecedores e transportadoras.

• No Logix cadastrar um novo depositante e efetuar toda a parametrização necessária para a operação de WMS.

• No Logix cadastrar um novo produto que seja controlado pelo WMS, para o depositante cadastrado anteriormente.

• No Logix efetuar um processo de recebimento para o produto cadastrado anteriormente, utilizando uma nota fiscal provisória (tipo “A”).

• No Datasul consultar a nota fiscal de recebimento que foi registrada no Logix, validando as informações recebidas.

• No Logix efetuar um processamento de regularização fiscal, efetuando a cobertura dos produtos recebidos anteriormente.

• No Datasul verificar se foi efetuado corretamente o relacionamento entre os dois documentos. Acessar o documento fiscal referenciado:
  

• No Logix efetuar um processo de expedição para o novo produto cadastrado, até o momento do envio da mensagem de integração de nota fiscal.

• No Logix é possível consultar o número e série da nota fiscal gerada para os retornos simbólicos e conta/ordem no programa WMS6333 (Consulta de Documentos). Para os processos de faturamento de serviço o número da nota fiscal está disponível no programa WMS6411 (Movimentos a Faturar).

• As informações das integrações de Documentos de Entrada (WMS6628 e WMS6629), Regularização Fiscal (WMS6156) e Documentos de Saída (WMS9745 e WMS6429) poderão ser consultadas pelo Monitor de Integração, rotina WMS80000. Nesta rotina também é possível reprocessar documentos que ficaram pendentes.
  
  

• Para realizar o monitoramento das transações no Datasul acesse o TOTVS Monitor:

  -Acessar o Monitor do EAI-2 no Datasul: Exemplo: Se a URL do Datasul é http://cordas:8480/menu-html/ para acessar o monitor basta substituir o contexto “menu-html” por “totvs-monitor”.
  -Acessar o folder “EAI-2”, depois clicar no folder “Monitor".
  -Mensagens com Situação: DELIVERED foram integradas com sucesso;
  -Mensagens com Situação: BUSINESSERROR não foram integradas pois ocorreu erro de negócio;
  -Para que sejam listadas as situações BUSINESSERROR clicar em Filtro e marcar “Considerar mensagens arquivadas?”;
  -Para consultar o erro clicar na mensagem e no subnível haverá o conteúdo de retorno para o aplicativo externo.

  
  
  
  

Situações comuns (opcional)

Quando uma mensagem é enviada do Logix para o Datasul podem ocorrer situações em que o WebService não estará totalmente funcional. Nestes casos uma mensagem de erro genérica irá aparecer na tela:

Exemplo:

Se o arquivo de log for analisado, poderemos ver a falha na comunicação com o sistema destino:

-------------------------------------------------------------------------------

WSCERR044 / Não foi possível POST : URL http://172.16.31.57:8011/ws/FWWSEAI.apw

ADVPL WSDL Client 1.080707 / tst on 20120315 08:49:51

-------------------------------------------------------------------------------

Para resolver este problema verifique as configurações do sistema de destino, analisando o funcionamento do servidor utilizado para esta comunicação e a habilitação do endereço do WebService.

Abaixo seguem algumas consistências e mensagens que podem ocorrer durante os processos, indicando a possível solução para o problema:

Checklist de suporte da aplicação

• Verifique se os WebServices criados estão devidamente configurados. Para isso tente abrir no seu navegador internet o endereço dos WebServices. No WebService do Datasul e do Logix você deve conseguir visualizar na lista de serviços o “EAISERVICE”. 
• Faça o teste de comunicação entre os sistemas utilizando uma mensagem simples de cadastro (sugestão: Fornecedor). Faça o envio de um cadastro do Logix para o Datasul e do Datasul para o Logix.