Contexto de negócio (Introdução)

A oferta TOTVS Colaboração, compreende toda integração entre os ERPs TOTVS com a solução NeoGrid. Este documento tem por objetivo a definição das especificações e critérios técnicos necessários para a integração da recepção de conhecimento de transporte eletrônico entre o ERP DATASUL e a Neogrid para atender a solução TOTVS Colaboração 2.0.

A integração tem o objetivo de permitir que o cliente com ERP Datasul realize o recebimento automático dos conhecimentos de transporte emitidos pela transportadora, eliminando a necessidade de digitar estes documentos manualmente.

Objetivos do projeto TOTVS Colaboração 2.0

O projeto TOTVS Colaboração 2.0 tem como objetivo a implantação de um modelo único e performático para possibilitar o relacionamento entre os clientes TOTVS que adquirem a solução TOTVS Colaboração.

O TOTVS Colaboração foi lançado em 2010 com a integração da solução ERP x TSS x Neogrid utilizando Web Services. Em julho de 2014 iniciou-se o projeto de reestruturação da arquitetura utilizada, passando a realizar a integração direta do ERP com a Neogrid através da troca de arquivos em diretório (filesystem).

Sistemas Envolvidos

• ERP Datasul – Módulo de Recebimento. Funcionalidade de recepção de notas fiscais eletrônicas.
• Client Neogrid – Responsável por entregar os arquivos no portal Neogrid.
• Neogrid.

Arquitetura de comunicação com a Neogrid

 Na versão 1.0 do TOTVS Colaboração a integração entre ERP e Neogrid era realizada via WebService com a utilização do TSS como produto fiscal único. Os XMLs eram gerados conforme padrões disponíveis no TSS.

 Na versão 2.0, a integração será realizada diretamente entre ERP e Neogrid, sem o intermédio do TSS. Essa comunicação passa a ser feita com a utilização de troca de arquivos em diretório (filesystem).

Nessa arquitetura a comunicação é feita através da utilização de um ClientEDI que deve ser instalado no cliente, o qual ficará responsável por realizar a comunicação com a Neogrid.

A integração entre a Neogrid e a TOTVS tem as seguintes premissas:

• Solução de integração simples e padronizada para todos os tipos de documentos e ERPs TOTVS, com foco na performance da solução para o cliente final e na agilidade de atendimento para as equipes de suporte;
• O padrão de comunicação entre os ERPs TOTVS e a Neogrid será realizada de forma assíncrona com troca de documentos no formato XML em diretórios;
• Existem dois tipos de integração do ponto de vista dos ERPs: envio de documentos e recebimento de documentos;
• A Neogrid deve instalar um aplicativo cliente denominado “Client Neogrid” no ambiente de cada cliente;
• Para cada tipo de documento, todos os ERPs TOTVS devem utilizar o mesmo layout de integração com a Neogrid;
• Toda e qualquer alteração futura a ser realizada na solução TOTVS Colaboração deve ser notificada para as equipes Neogrid e TOTVS, para que a integração continue funcionando corretamente.

Abaixo exemplo de comunicação na nova arquitetura:

Padrões Técnicos

1. Nomenclatura de Arquivos

A nomenclatura dos arquivos nos diretórios, tanto para envio como para retorno, deve seguir a padronização “[Tipo do Documento]_[Timestamp]_[Número sequencial].xml”, onde:

• [Tipo de Documento] é o código do tipo de documento EDI
• [Timestamp] é a data e hora no formato “yyyyMMddHHmmssSSS”
• [Número sequencial] é um número sequencial de quatro dígitos

Exemplo de nome de arquivo para um documento de recepção de CT-e: “214_20140627154700123_0001.xml”.

O envio de documentos pelo Client NeoGrid possui um controle de documentos duplicado. Arquivos enviados pelos ERPs TOTVS com o mesmo nome serão rejeitados.

A solução NeoGrid está preparada para que os ERPs enviem os arquivos de recebimento de CT-e para validação com o código EDI 165:

A solução NeoGrid está preparada para disponibilizar para os ERPs os arquivos de recebimento de CT-e com o código EDI 214:

2. Padrão de comunicação

O padrão de comunicação utilizado entre ERP e Neogrid é por troca de arquivos em diretórios (filesystem) com a utilização do Client da Neogrid. 

O ClientEDI é um JOB em JAVA onde é parametrizado o tempo de monitoramento do diretório e do WebEDI. Ele acessa o WebEDI utilizando WebServices onde é utilizado um método para envio e outro para buscar as mensagens processadas. 

Dentro do diretório de instalação do Client existem duas subpastas denominadas IN e OUT, onde todos os arquivos a serem integrados devem ser depositados.

• OUT..: diretório onde os ERPs devem depositar os arquivos para envio para a Neogrid 
• IN......: diretório onde os ERPs devem ler os arquivos recebidos da Neogrid 

No ERP Datasul existe um JOB responsável por monitorar a subpasta IN e processar o retorno de todos os arquivos que forem depositados neste diretório.

Integração

A integração envolve o ERP (Datasul), a Neogrid e a SEFAZ (Secretaria da Fazenda) e prevê dois fluxos: recebimento iniciado pelo ERP e recebimento iniciado pelo Neogrid, detalhados na sequência:

Recebimento iniciado pelo ERP:

Obs.: Neste caso o cliente recebe o XML por e-mail e é necessário o envio para validação da Neogrid.

Obs. 2: Caso o cliente não utilize a emissão de NF-e/NFS-e pelo TOTVS Colaboração, a etapa “JOB Fiscal” pode ser retirada do fluxo, pois há a possibilidade de parametrizar a busca dos documentos diretamente do diretório do client Neogrid (IN).

Passos:

1. Fornecedor envia o XML do CT-e para o cliente; 
2. ERP salva o XML do CT-e no diretório “OUT” do Client Neogrid (via RE0517) - Nomenclatura arquivo: 165_*.xml; 
3. Client Neogrid envia XML do CT-e para validação na Neogrid; 
4. Neogrid valida a mensagem; 
5. Neogrid envia consulta de situação do CT-e a Secretaria da Fazenda; 
6. Secretaria da Fazenda processa consulta da situação do CT-e e retorna e resultado; 
7. 7Neogrid disponibiliza o retorno da consulta do CT-e; 
8. Client Neogrid busca XML do CT-e validado na Neogrid e salva em um diretório “IN” (Nomenclatura arquivo: 214_*.xml); 
9. ERP busca CT-e do diretório “IN” e salva em diretório para recepção (JOB Fiscal – CD0590);
10. ERP busca CT-e do diretório de recepção e efetiva no recebimento (Importação CT-e TOTVS Colaboração - RE0522).

Recebimento iniciado pelo Neogrid:

Obs.: Neste caso a recepção do XML é feita diretamente pelo Neogrid. 

Obs. 2: Caso o cliente não utilize a emissão de NF-e/NFS-e pelo TOTVS Colaboração, a etapa “JOB Fiscal” pode ser retirada do fluxo, pois há a possibilidade de parametrizar a busca dos documentos diretamente do diretório do client Neogrid (IN). 

Passos:

1. Fornecedor envia o XML do CT-e para o Neogrid;
2. Neogrid valida a mensagem;
3. Neogrid envia consulta de situação do CT-e a Secretaria da Fazenda;
4. Secretaria da Fazenda processa consulta da situação do CT-e e retorna e resultado;
5. Neogrid disponibiliza o retorno da consulta do CT-e;
6. Client Neogrid busca XML do CT-e validado na Neogrid e salva em um diretório “IN” (Nomenclatura arquivo: 214_*.xml);
7. ERP busca CT-e do diretório “IN” e salva em diretório para recepção (JOB Fiscal – CD0590);
8. ERP busca CT-e do diretório de recepção e efetiva no recebimento (Importação CT-e TOTVS Colaboração - RE0522).

Recebimento do XML de evento de cancelamento de CT-e (procEventoCTe)

O recebimento do XML de evento de cancelamento está disponível a partir do Datasul 12.1.4.

É pré-requisito para a utilização da integração que o “JOB Fiscal – CD0590” esteja em execução, seja via RPW ou via Agente. Isto se faz necessário pois o JOB irá realizar a leitura do XML de recebimento de evento de cancelamento e irá salvar os dados na tabela de integração do TC 2.0 (integr-totvs-colab).

Ao rodar o programa RE0522 que busca os documentos XML do diretório haverá também a leitura dos registros código  EDI 383 da tabela de integração. Nomenclatura arquivo: 383_*.xml. 

Fluxo de integração:

Passos do processo:

Escopo

O escopo desta integração é o recebimento do Conhecimento de Transporte que foi enviado pelo Transportador, pelo contratante do serviço de frete. O frete pode ter sido contratado para buscar mercadorias adquiridas pela empresa, gerando nesse caso uma nota de rateio no Recebimento, ou frete contratado para levar as mercadorias até o cliente, gerando nesse caso uma nota de compra de serviço de frete.

Esta integração contempla a recepção do layout 1.04 e 2.00 do CT-e.

Não está compreendida a geração do conhecimento no módulo TMS.

Não está compreendido no escopo o recebimento de Notas de Serviço de Frete prestado dentro do município.

Pré-requisitos instalação/implantação/utilização

Pré-requisitos (técnicos ou de negócio) para o funcionamento da integração: 

• Versões mínimas de produto:
  • Datasul 12.1.2 em diante;
  • Recepção do evento de cancelamento somente a partir do Datasul 12.1.4;
  • Client Neogrid na versão disponibilizada e instalada pela Neogrid;
• Pré-requisitos de negócio:
  • Contratação da oferta do TOTVS Colaboração (TOTVS e Neogrid);
  • Demais parametrizações no ERP, conforme detalhado na sequência. 
• Pré-requisitos para utilização no ERP:
  • Ativar a função "TOTVS-COLABORACAO" (via programa CD7070);
  • Acessar os parâmetros globais (CD0101), pasta “Integr. II” e habilitar o TOTVS Colaboração e a versão 2.0;
  • Acessar o programa de configuração de diretórios do Colaboração 2.0 (CD0360A) e configurar os diretórios do Client Neogrid, conforme figura que segue.
    
    No campo “Diretório Recepção Documentos” deve ser informado o diretório onde o ERP irá buscar os documentos.
    
    
  • Configurar a execução do JOB Fiscal que realiza a leitura dos documentos da pasta “IN”.

    Este JOB pode ser executado de 2 formas:

    • Programa CD0590 rodando em RPW;
    • Programa Agente;

  • OBS: Para mais detalhes sobre o JOB Fiscal devem ser acessados os manuais de emissão de NF-e no TOTVS Colaboração 2.0.

• 
  
  • Configurar os parâmetros do conversor de documentos de entrada (RE0119);
  • Habilitar a funcionalidade para receber Conhecimento de Transporte, parâmetro “Habilita CT-e”, nos parâmetros do Conversor (RE0119);
  • Parametrizar o Fornecedor informando que ele emite NF-e/CT-e (CD0401);

  • Configurar o engine de regras: O Engine de Regras possibilita configurar as condições externalizando a regra de negócio. Utilizar os programas CD0024 para cadastro das regras, CD0025 para cadastros de tipos de operação e CD0026 para testes.
    As operações que podem ser cadastradas no Engine para conversão/sugestão de valores para entrada da nota no recebimento são apresentadas na sequência:

    Tipo de Operação	Descrição
    serie-docto	Serie Documento
    cod-observa	Código Observação
    it-codigo	Código Item
    nat-operacao	Natureza Operação
    cod-emitente	Código do Emitente
    cod-gr-forn	Grupo do Fornecedor

    As variáveis que podem ser cadastradas no Engine de Regras para utilização nas regras são estas:
    

    Variável	Descrição
    serie-docto	Serie Documento
    cod-observa	Código Observação
    it-codigo	Código Item
    nat-operacao	Código do CFOP do XML
    cod-emitente	Código do Emitente
    cod-gr-forn	Grupo do Fornecedor
    UF-dest	Unidade Federação Destinatário
    UF-ent	Unidade Federação Local Entrega

    Observações sobre as variáveis de Unidade de federação:

    UF-ent: Será lida a TAG “UF” que está abaixo da TAG pai “locEnt”. Como a TAG “locEnt” não é obrigatória, quando ela não for encontrada será atribuído a UF-ent o mesmo valor da variável UF-dest. 

    UF-dest: Será lida a TAG “UF” que está abaixo da TAG pai “EnderDest”. Esta TAG é obrigatória.

Instalação/Atualização

Para esta integração é necessária a instalação do Client Neogrid no servidor do cliente. Esta instalação não será detalhada neste documento pois é de responsabilidade da equipe Neogrid.

Como fazer

Na sequência segue o detalhamento de como será feita a leitura do XML de CT-e recebido, quais TAGs são obrigatórias e quais serão levadas em consideração para determinar se o sistema interpretará o XML como uma nota de compra de frete ou uma nota de entrada de rateio.

1. Tomador do Serviço de Frete

O tomador do serviço é utilizado para localizar o estabelecimento que contratou o frete, e que consequentemente será o responsável pelo pagamento dele.

Por exemplo, quando o valor da TAG <toma> for igual 3, significa que foi o DESTINATÁRIO do CT-e quem contratou o frete. Nesse caso é necessário que tenha um estabelecimento cadastrado com o CNPJ que consta na TAG <dest> O contratante pode ser: 0-Remetente, 1-Expedidor, 2-Recebedor ou 3-Destinatário.

2. NF Compra de Fornecedor

Receber o XML de um conhecimento de transporte, na situação onde a empresa contratou para buscar mercadorias que comprou de um ou mais fornecedores. Nesse caso, ao receber o XML, o sistema vai gerar uma Nota de Rateio - Entrada.

Para que o sistema identifique esse tipo de nota, o XML deverá estar montado da seguinte forma:

a. O CNPJ do emitente pode ser o CNPJ de uma transportadora válida no sistema (cd0401 e cd0402);

b. O CNPJ do remetente deve ser de um fornecedor cadastrado (cd0401);

c. O CNPJ do destinatário deve ser de um estabelecimento cadastrado (cd0602);

d. As notas informadas na TAG “infNFe” devem ser notas de compra, recebidas e atualizadas no recebimento do estabelecimento da minha empresa.

3. NF Devolução de cliente

Receber o XML de um conhecimento de transporte, na situação onde a empresa contratou a transportadora para buscar mercadoria de devolução de cliente. Nesse caso, ao receber o XML, o sistema vai gerar uma Nota de Compra de Serviço de Frete.

Para que o sistema identifique esse tipo de nota, o XML deverá estar montado da seguinte forma:

a. O CNPJ do emitente pode ser o CNPJ de uma transportadora válida no sistema (cd0401 e cd0402);

b. O CNPJ do remetente deve ser o CNPJ de um cliente cadastrado (cd0704);

c. O CNPJ do destinatário deve ser de um estabelecimento cadastrado (cd0602);

d. As notas informadas na TAG “infNFe” devem ser notas de devolução de cliente, recebidas e atualizadas no recebimento do estabelecimento da minha empresa.

 

4. NF de Transferência

Receber o XML de um conhecimento de transporte, na situação onde a empresa contratou para buscar mercadorias de uma ou mais filiais. Nesse caso, ao receber o XML, o sistema vai gerar uma Nota de Rateio - Entrada.

Para que o sistema identifique esse tipo de nota, o XML deverá estar montado da seguinte forma:

a. O CNPJ do emitente pode ser o CNPJ de uma transportadora válida no sistema (cd0401 e cd0402);

b. O CNPJ do remetente deve ser de um fornecedor cadastrado (cd0401);

c. O CNPJ do destinatário deve ser de um estabelecimento cadastrado (cd0602);

d. As notas informadas na TAG “infNFe” devem ser notas de compra, recebidas e atualizadas no recebimento do estabelecimento da minha empresa;

Mensagens comuns da Integração

Nota:

- Podem ocorrer outros erros de negócio, no momento da efetivação do CT-e no recebimento fiscal, porém a solução a ser adotada é a mesma utilizada para o recebimento no produto.

Checklist de suporte da aplicação

Pontos importantes para o funcionamento e atendimento da integração.

Verificações:

• Client Neogrid deverá estar em execução (lembrando que a parametrização deste é de responsabilidade da equipe Neogrid);
• JOB Fiscal (CD0590) deverá estar rodando em RPW ou via agente;
• Importador de notas (RE0522) do módulo de recebimento deve estar rodando em RPW;
• Demais Parametrizações do tópico 8 devem ser verificadas.