Integração TOTVS Colaboração 2.0 Recepção NF-e - Datasul

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 nota fiscal eletrônica entre o ERP DATASUL e a Neogrid para atender a solução TOTVS Colaboração 2.0.

A integração referente à recepção de Notas fiscais eletrônicas (NF-e) de fornecedores abrange a utilização dos dados do XML da NF-e recebido dos fornecedores para geração de informações para automatização do recebimento (digitação de notas fiscais dentro do ERP).

Entre as vantagens que esta integração proporciona, estão:

• Segurança: A nota poderá ser importada no recebimento logo após ser validada na SEFAZ o que garante a consistência e autenticidade das informações;
• Redução de Custos: Redução do volume de digitação de notas fiscais no Recebimento. Isso pode representar redução de custos de mão-de-obra para efetuar a digitação, bem como a redução de possíveis erros de digitação de informações;
• Previsibilidade: Planejamento de logística de recepção de mercadorias pelo conhecimento antecipado da informação da NF-e, pois a previsibilidade das mercadorias a caminho permitirá prévia conferência da Nota Fiscal com o pedido, quantidade e preço, permitindo, além de outros benefícios, o melhor uso de docas e áreas de estacionamento para caminhões;
• Redução de Erros: Redução de erros de escrituração devido à eliminação de erros de digitação de notas fiscais;
• Redução de Lead Time: Incentivo a B2B.

A recepção de NF-e de fornecedores, contempla a recepção, validação e tradução das informações inerentes ao negócio do fornecedor para informações de negócio do cliente.

Sistemas Envolvidos

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 (Portal NF-e e Web EDI).

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 NF-e: “109_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 NF-e para validação com o código EDI 143:

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

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 da NF-e para o cliente; 
2. ERP salva o XML da NF-e no diretório “OUT” do Client Neogrid (via RE0517) - Nomenclatura arquivo: 143_*.xml; 
3. Client Neogrid envia XML da NF-e para validação na Neogrid; 
4. Neogrid valida a mensagem; 
5. Neogrid envia consulta de situação da NF-e a Secretaria da Fazenda; 
6. Secretaria da Fazenda processa consulta da situação da NF-e e retorna e resultado; 
7. Neogrid disponibiliza o retorno da consulta da NF-e; 
8. Client Neogrid busca XML da NF-e validado na Neogrid e salva em um diretório “IN” (Nomenclatura arquivo: 109_*.xml); 
9. ERP busca NF-e do diretório “IN” e salva em diretório para recepção (JOB Fiscal – CD0590);
10. ERP busca NF-e do diretório de recepção e efetiva no recebimento (Importação NF-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 da NF-e para o Neogrid;
2. Neogrid valida a mensagem;
3. Neogrid envia consulta de situação da NF-e a Secretaria da Fazenda;
4. Secretaria da Fazenda processa consulta da situação da NF-e e retorna e resultado;
5. Neogrid disponibiliza o retorno da consulta da NF-e;
6. Client Neogrid busca XML da NF-e validado na Neogrid e salva em um diretório “IN” (Nomenclatura arquivo: 109_*.xml);
7. ERP busca NF-e do diretório “IN” e salva em diretório para recepção (JOB Fiscal – CD0590);
8. ERP busca NF-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 NF-e (procEventoNFe)

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 367 da tabela de integração. Nomenclatura arquivo: 367_*.xml.

Passos do processo:

1. ERP realiza o monitoramento dos documentos XML depositados pelo Client Neogrid no diretório “IN”;
2. Durante este monitoramento serão recebidos também XML’s de cancelamento por evento, criando registros na nova tabela de eventos dos documentos (NF-e/CT-e).
3. Na tela do monitor de NF-e/CT-e (RE0708) está disponível o folder “Cancelados” onde são listados os registros de cancelamento.
4. Durante a importação, havendo registro da chave de acesso nas tabelas do conversor é verificada a situação atual da NF-e.
5. Para as situações abaixo será alterada automaticamente a situação para: 5 - Cancelada:

• 2 - Nota com Erro Negócio - quando a nota apresentar erros ao processar e efetivar no recebimento (físico ou fiscal).
• 9 - Em validação - nota foi importada de um diretório e enviada para a Neogrid validar.
• 4 - Eliminada recebimento - nota foi atualizada e depois eliminada do recebimento físico/fiscal.

6. Para as situações abaixo o usuário deverá realizar as desatualizações manualmente:

• 1 - Digitada Receb. Fiscal - quando a nota estiver digitada no recebimento fiscal.
• 3 - Atualizada Receb. Fiscal - quando a nota estiver atualizada no recebimento fiscal.
• 6 - Digitada Receb. Físico - quando a nota estiver digitada no recebimento físico.
• 7 - Atualizada Receb. Físico - quando a nota estiver atualizada no recebimento físico.

Na tabela a seguir estão relacionadas as situações do documento no monitor de NF-e/CT-e e qual a ação que será tomada pelo sistema no momento da importação do XML de evento de cancelamento:

Escopo

Esta integração contempla a recepção do layout 2.00 e 3.10 da NF-e.

Não está contemplada a entrada/recepção de NFC-e (Nota Fiscal Eletrônica de Venda ao Consumidor Final), modelo 65.

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 NF-e entrada (RE0119);

  • Configurar o fornecedor: Se deve ou não atualizar a NF-e automaticamente no recebimento (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	Série do Documento
    cod-observa	Código Observação
    it-codigo	Código Item
    nat-operacao	Natureza Operação
    numero-ordem	Ordem Compra
    num-pedido	Pedido Compra
    parcela	Parcela Ordem
    nr-ord-produ	Ordem Produção
    cod-refer	Referência
    cod-depos	Depósito
    cod-localiz	Localização
    lote	Lote
    dt-vali-lote	Data Validade Lote
    un-xml	Unidade de medida do Item
    cod-emitente	Código do Emitente

    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	Série Documento
    cod-emitente	Código Emitente
    cod-observa	Código Observação
    cod-estabel	Código Estabelecimento
    it-codigo	Código Item
    nat-operacao	Código do CFOP do XML
    numero-ordem	Ordem Compra
    num-pedido	Pedido Compra
    parcela	Parcela Ordem
    nr-ord-produ	Ordem Produção
    cod-refer	Referência
    cod-depos	Depósito
    cod-localiz	Localização
    lote	Lote
    dt-vali-lote	Data Validade Lote
    cod-gr-forn	Grupo de Fornecedor
    ge-codigo	Grupo de Item / Grupo de estoque
    fm-cod-com	Família Comercial
    icms-cst	CST de ICMS dos Itens
    cod-sit-trib-ipi	CST de IPI dos Itens
    aliq-cofins-cst	CST de Cofins dos Itens
    cnpj-destino	CNPJ de Destino
    cnpj-saida	CNPJ de Saída
    cod-estabel-ori	Código Estabelecimento de Origem
    desc-item	Descrição do Item
    dt-emissao	Data de Emissão
    icms-aliq	ICMS Alíquota
    mod-frete	Modalidade do Frete
    nro-docto	Número do Documento
    reduc-bc	ICMS tag <pRedBC>":
    uf-end	Unidade de Federação do Emitente
    un-xml	Unidade de Medida do Item
    icms-csosn	Código da Situação de Operação no Simples Nacional de ICMS dos Itens

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 

Recebimento iniciado pelo ERP

O processo se inicia quando o fornecedor envia o XML da NF-e para o seu cliente, que por sua vez, para utilização da recepção de NF-e deve salvar esse XML em um diretório qualquer para posteriormente ser enviado para validação. Quando o XML é enviado diretamente do fornecedor para o cliente é necessário que este seja validado (para garantir a integridade do arquivo e também sua situação na SEFAZ), a Neogrid é quem faz essa validação.

Para o envio de XMLs de NF-e para que sejam validadas, o programa a ser utilizado é o “RE0517 – Importação de NF-e por diretório”, onde é informado o diretório da onde devem ser lidos os XMLs a serem enviados para validação. Caso necessário o programa pode ser configurado para execução em RPW. Neste processo os XMLs são copiados para a pasta “OUT” do Client Neogrid, que por sua vez envia para o WEB EDI Neogrid. Os XMLs importados por meio do RE0517 aparecem no Monitor do Conversor de NF-e (RE0708) com a situação “Em validação” e não poderão ser atualizados para o recebimento enquanto estiverem nesta situação. Caso alguma nota que está sendo importada possua CNPJ destino inválido (inexistente no ERP), não serão importadas para o conversor, ou seja, não aparecerão no conversor como “Em validação” e nem serão enviadas à Neogrid. Para este caso é apresentada uma mensagem no log indicando que o CNPJ destino é inexistente e o XML é movido para um subdiretório chamado “destino_inexistente”. Os demais XMLs que foram enviados para validação são movidos para um subdiretório chamado “lidos”.

Após os XMLs terem sido enviados pelo Client a Neogrid realiza a validação de integridade do arquivo, ela envia uma solicitação de consulta para a SEFAZ, que realiza a consulta e disponibiliza o resultado para a Neogrid. A Neogrid por sua vez, disponibiliza o XML validado para que o Client possa buscá-lo e salvar no diretório “IN”, possibilitando a leitura por parte do ERP.

É necessário que o ERP fique frequentemente verificando se existem notas a serem buscadas do diretório de recepção de documentos. Para este processo, existe o programa “RE0522 – Importação NF-e/CT-e/NFS-e TOTVS Colaboração” que pode ser programado para executar em RPW, para que de tempos em tempos verifique se há NF-es para serem efetivadas no ERP.

Quando um documento é disponibilizado no diretório de recepção e é executado o RE0522, será seguido o seguinte fluxo:

• Caso a nota exista no Conversor com o status “Em validação”, ou seja, foi enviada a partir do ERP (RE0517), então é executado o processo para enviar o documento “automaticamente” para o recebimento (se estiver parametrizado para isso). É atualizada a situação do documento para “Erro de negócio”, se não foi processada com sucesso e “Digitada Recebimento” caso tenha sido processado com sucesso.
• Caso a nota não exista no conversor, ou seja, veio diretamente pela Neogrid, então é executado o processo para criar o documento no conversor e processar “automaticamente” para o recebimento (se estiver parametrizado para isso). É atualizada a situação do documento para “Erro de negócio”, se não foi processada com sucesso e “Digitada Recebimento” caso tenha sido processado com sucesso.

Quando o documento que está sendo recebido da Neogrid possui informações de rejeição (Documento rejeitado) então é criado um erro no log “52119 – Documento <chave do documento> rejeitado pela Neogrid”, e eliminado do monitor para que não fique “poluindo” a visualização, e se preciso pode ser enviado novamente para validação.

Os documentos com erro ou processados com sucesso no recebimento, podem ser consultados através do “RE0708 – Monitor do Conversor de NF-e”, neste monitor é possível consultar a situação notas, corrigir possíveis erros e reprocessar as notas caso necessário.

Recebimento iniciado pelo Neogrid

O fluxo onde o recebimento da NF-e é iniciado pelo Neogrid é praticamente igual ao anterior, exceto pelo fato de que a NF-e é enviada diretamente para a Neogrid ao invés de para o cliente, suprimindo o processo de importação por diretório (RE0517).

Mensagens comuns de Integração

Nota:
- Podem ocorrer outros erros de negócio, no momento da efetivação da NF-e no recebimento físico ou fiscal, porém a solução a ser adotada é a mesma utilizada para o recebimento no produto (sem que seja o conversor).

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.