Integração TOTVS Colaboração 2.0 – Logix/ Obrigações Fiscais

Contexto de negócio (Introdução)

Este documento tem por objetivo a definição das especificações e critérios técnicos necessários para a integração entre o ERP LOGIX e a NeoGrid para atender a solução TOTVS Colaboração 2.0.

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 por intermédio da troca de arquivos em diretório filesystem.

Integração

O projeto TOTVS Colaboração compreende a integração dos documentos de Emissão de NF-e, Recebimento de NF-e, Emissão de NFS-e, Recebimento de NFS-e, Emissão de CT-e, Recebimento de CT-e, Emissão de MDF-e, Envio de Pedido de Compra, Emissão de Alteração de Pedido de Compra, Recepção de Pedido de Venda, Recepção de Alteração de Pedido de Venda, Envio do Espelho de NF/ASN, Recepção do Espelho de NF/ASN, Envio da Programação de Entrega e Recepção da Programação de Entrega.

Para todos os documentos a serem trafegados na solução TOTVS Colaboração, a mesma solução de integração TOTVS e NeoGrid será utilizada.

Arquitetura de Comunicação com 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 realizada com a utilização de troca de arquivos em diretório filesystem.

Nessa arquitetura a comunicação é realizada por meio 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:

Escopo

1. Nomenclatura

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

• [Tipo de Documento] é o código do tipo de documento
• [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 emissão de NF-e: “170_20140627154700123_0001.xml” .

Uma exceção à regra anterior é para os retornos de arquivos de Emissão (NF-e, CT-e, NFS-e, MDF-e e MD-e) que possam ter mais de um retorno. Estes arquivos devem seguir a padronização abaixo:

•  [Nome do arquivo original] é o nome do arquivo que o ERP gerou no envio;
•  [Número sequencial] é um número sequencial de quatro dígitos, cujo objetivo é garantir a entrega de todos os arquivos com mais de um retorno.

Exemplo de nome de arquivo para um documento de emissão de NF-e:

• Arquivo enviado pelo ERP: “170_20140627154700123_0001.xml”;
• Primeiro retorno enviado pela NeoGrid:  “170_20140627154700123_0001_0001.xml”;
• Segundo retorno enviado pela NeoGrid: “170_20140627154700123_0001_0002.xml”.

Nos processos de emissão, todos os arquivos retornados para o ERP, inclusive o primeiro retorno, sempre devem ter o código sequencial criado pela NeoGrid e o ERP sempre deve considerar a informação antes do código sequencial como sendo o nome do arquivo original. 

Os retornos de arquivos enviados pela TOTVS nos processos de Emissão (NF-e, CT-e, NFS-e, MDF-e e MD-e), terão o mesmo nome, com o acréscimo do sequencial mencionado anteriormente. Ou seja, o arquivo enviado pela TOTVS e o retorno disponibilizado pela NeoGrid terão a mesma nomenclatura para facilitar o processo de atualização no ERP.

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 os ERPs enviarem os arquivos abaixo. Todos os arquivos de emissão devem ser gerados pelo ERP sem a assinatura digital.

2. Padrão do documento XML

Todos os arquivos de emissão, com exceção da NFS-e, devem seguir o leiaute padrão definido pela Sefaz, sem a assinatura digital. Por não possuir um leiaute único para todos os municípios e para que seja possível emitir a NFS-e tanto pelo TSS quanto pelo TOTVS Colaboração, foi definido em conjunto um leiaute único a ser adotado por todos os ERPs.

3. Validação de Schema

Por ser uma ferramenta utilizada apenas para a transmissão dos documentos, a validação de schema dos documentos fiscais serão realizados no ambiente da NeoGrid. Caso o arquivo não seja validado pelo schema a NeoGrid irá retornar a rejeição.

Importante: A validação realizada pela NeoGrid não contempla estrutura do arquivo XML, ou seja, caso o XML possua, por exemplo, uma literal que deveria estar entre aspas sem esse caracter o XML não será processado pela NeoGrid e o documento não irá retornar. Nestes casos é necessário entrar em contato com a NeoGrid para verificar o motivo do não processamento do documento.

Exemplo de XML correto:

Exemplo de XML errado:

4. Padrão de Comunicação e Assinatura Digital

O padrão de comunicação utilizado entre ERP e NeoGrid será 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 LOGIX existirá um JOB responsável por monitorar a subpasta IN e processar o retorno de todos os arquivos que forem depositados neste diretório.

O certificado digital do cliente deve ser enviado para a NeoGrid para que seja realizada a assinatura digital dos documentos e efetuado a transmissão para a Sefaz. A exceção para este processo é a solução IN House do TOTVS Colaboração.

Para clientes que utilizam tanto TSS quanto TOTVS Colaboração 2.0 (ambiente misto), nos processos realizados exclusivamente pelo TSS a assinatura digital continua sendo realizada pelo TSS.

Instalação/Atualização

Logix

LOG00086 (Manutenção de Parâmetros)

No LOG00086 em Gestão Fiscal  > TOTVS Colaboração > Versão 2.00 (Nova rotina)  deverá ser configurado o parâmetro:

• Tipo de Ambiente TOTVS Colaboração (tipo_ambiente_tc_2)

Este parâmetro irá indicar o tipo de ambiente que será utilizado no TOTVS Colaboração versão 2.00. Esta parametrização foi desenvolvida para evitar o envio de documentos do ambiente de testes na Sefaz de produção.

Para a criação desse parâmetro é necessário a execução do conversor OBF00372.cnv.

1 – Homologação;

2 – Produção.

JOB de Integração Totvs Colaboração

Foi desenvolvido um JOB de integração no LOGIX, o qual será responsável por processar todos os documentos gravados na subpasta IN do Client NeoGrid.

Exemplo do diretório do Client NeoGrid: “C:\WebEDIMercadorClient_V4.1_WinService\bin\IN\”.

O JOB não foi desenvolvido utilizando o JOB0003, pois este não pode ser configurado com um tempo de execução menor do que 1 minuto. Dessa forma, foi desenvolvido um JOB exclusivo e paliativo para o TOTVS Colaboração. O Framework irá desenvolver uma solução padrão no chamado TPYO51.

Para melhor performance o JOB foi estruturado de forma a trabalhar com várias threads em paralelo, sendo uma thread para cada produto do Colaboração (NF-e, NFS-e, CT-e, Recebimento etc.).

Apenas as threads referentes aos produtos configurados para utilização por TOTVS Colaboração 2.00 (VDP10076) são ativadas para execução .

Cada thread irá buscar os arquivos correspondentes ao produto que está sendo processado, utilizando como filtro o código identificador definido pela NeoGrid. Exemplo: Para NF-e serão filtrados todos os arquivos iniciados por “170”.

Em cada thread há a chamada de função específica responsável por abrir os arquivos, buscar as informações de retorno necessárias, atualizar a tabela de monitoramento obf_monitor_tc e mover o arquivo. Quando os arquivos forem processados com sucesso eles serão movidos para a pasta correspondente ao produto que está sendo processado, já com o nome padrão que utilizamos atualmente. Caso o arquivo esteja com problemas ou não seja encontrado um documento correspondente ao ERP (no caso de emissão de documentos), estes serão movidos para o diretório de erros configurado no LOG1120, conforme explicaremos abaixo.

No caso de recebimento, onde não há a necessidade de efetuar uma solicitação prévia à NeoGrid, as funções referentes ao Recebimento de Documentos e EDI Mercantil irão monitorar a subpasta IN, processar os arquivos e movê-los para os diretórios correspondentes ao armazenamento SUP34201 renomeando-os com o nome padrão.

Ao instalar este JOB, além da pasta appserver padrão do LOGIX também deve ter uma pasta appserver_job onde estarão os arquivos necessários para a execução do JOB de integração do TOTVS Colaboração. Tanto na pasta appserver quanto na appserver_job, os parâmetros LICENSECOMPANYID e LICENSEUSERID devem estar configurados e em ambos os arquivos a configuração deve ser igual. Isso se faz necessário para que seja possível buscar, no LOGIX e no JOB, o mesmo caminho de instalação do Client NeoGrid. Estes parâmetros correspondem ao código da empresa e ao código do usuário padrão, respectivamente e serão utilizados no LOG1120.

No arquivo TotvsAppServer.ini, da pasta appserver_job, deve existir os seguintes comandos:

;******** JOBS ********;

[logixscheduler]

VerifyJobInterval=3               (Intervalo entre a execução do JOB, em segundos)

LICENSECOMPANYID=34   (Código da empresa padrão. Deve ser igual ao informado no .ini do LOGIX)

LICENSEUSERID=admlog   (Código do usuário padrão. Deve ser igual ao informado no .ini do LOGIX)

[ONSTART]

Jobs=4GLJOB1

[4GLJOB1]

Environment=Logix1002tORA34

Main=jobTotvsColab           (Deve ser utilizado sempre a denominação ‘jobTotvsColab’)

No arquivo totvsprofile.pro, da pasta appserver_job, pode ser parametrizado a geração do debug.

Para ativar o debug o parâmetro logix.debug deve estar preenchido com 1. (logix.debug = 1).

A geração do debug pode ser ativada por thread (recomendado). Neste caso, apenas as threads que estiverem com o valor igual a 1 irão gerar o debug.

Ao mudar o parâmetro não há necessidade de reiniciar o JOB.

logix.debug = 1                                (1- indica que o modo debug está ativo, 0 - indica que não está ativo o debug)

logix.source.obf90001.debug = 0    (1-ativa o debug da thread da NF-e/CC-e/Cancelamento/Inutilização)

logix.source.obf90002.debug = 0    (1-ativa o debug da thread da MDF-e)

logix.source.obf90003.debug = 0    (1-ativa o debug da thread da MD-e)

logix.source.obf90004.debug = 0    (1-ativa o debug da thread da Consulta da Chave de Acesso)

logix.source.sup13429.debug = 0    (1-ativa o debug da thread do Recebimento e EDI Mercantil)

logix.source.obf90006.debug = 0    (1-ativa o debug da thread da NFS-e)

logix.source.tms90001.debug = 0    (1-ativa o debug da thread do CT-e)

logix.source.obf90010.debug = 0     (1-ativa o debug do JOB de processamento manual)

logix.source.obf90000.debug = 0     (1-ativa o debug do JOB principal)

LOG1120 – Caminhos de Relatórios por Usuário

No LOG1120 devem ser informados :

• diretório onde o Client NeoGrid está instalado;
  Informar o caminho completo até a pasta anterior as pastas OUT/IN onde o Client está instalado.     
  No campo Sistema do Programa informar a literal “TCI” (TOTVS Colaboração Integração).
• diretório onde os arquivos com erro serão movidos.
  Informar um diretório onde deverão ser movidos os arquivos da pasta IN que não forem processados (arquivo corrompido, documento não encontrado na  base de dados etc).
  No campo Sistema do Programa deve ser informada a literal “TCE” (TOTVS Colaboração Erros).

Importante:
Utilizar a empresa padrão informada no TotvsAppServer.ini do JOB, no parâmetro LICENSECOMPANYID e o usuário padrão informando no parâmetro LICENSEUSERID, ambos no grupo [logixscheduler].

VDP10076 – Configuração Documentos Eletrônicos 

• Na tela de Configuração Inicial do VDP10076 é necessário assinalar a campo Utilizar TOTVS Colaboração e também no campo Versão TOTVS Colaboração selecionar a opção “2.00”.
• Na tela do TOTVS Colaboração é necessário os produtos do TOTVS Colaboração que estão sendo utilizados.
  Importante: Selecoine somente os produtos que realmente serão utilizados para otimizar o funcionamento do JOB de integração do TOTVS Colaboração.

Quando a empresa utilizar somente a solução TOTVS Colaboração 2.00 não há necessidade de configuração da tela Certificado Digital e Configuração e-mail.

Fluxo das Informações

Abaixo será descrito os serviços disponíveis pelo TOTVS Colaboração 2.0 e o fluxo básico de comunicação. 

Na emissão do documento, e ao selecionar a opção de menu Transmitir, o programa gerará o arquivo XML no diretório configurado nos respectivos programas de configuração do documento no diretório de saída (OUT), no leiaute padrão da Sefaz e com a nomenclatura definida pela NeoGrid.

NFe - Nota Fiscal Eletrônica

No XML da NF-e deve estar informado o campo de versão do layout (2.0 ou 3.10 por exemplo), pois de acordo com a versão informada será realizado o envio para o ambiente correspondente da Sefaz. No NeoGrid é necessário configurar qual a versão do leiaute o cliente utiliza. Ou seja, se estiver configurado para trafegar versão 3.10 e o NeoGrid receber uma NF-e com versão 2.0, o documento será rejeitado.

O Client NeoGrid lê o arquivo do diretório de saída (OUT) e envia para a NeoGrid. O NeoGrid NF-e realiza a pré-validação da mensagem XML com base nos schemas da Sefaz, a assinatura digital do XML, associação a um lote e envio das informações à Sefaz. O processo de envio de NF-es é assíncrono por definição do projeto, ou seja, a realização do envio de uma NF-e à Sefaz não recebe a autorização de uso no mesmo instante.

O NeoGrid NF-e controla automaticamente a busca pelo resultado do processamento dos lotes de NF-e na Sefaz. Ao receber o resultado, os retornos são disponibilizados pelo Client NeoGrid no diretório para consumo pelo ERP.

O JOB de integração monitora automaticamente o diretório de entrada (IN) do Client NeoGrid. Quando houver documentos a serem processados, estes serão lidos para buscar as seguintes informações:

• chNFe: Chave de Acesso da NF-e.
• nProt: Número do Protocolo informado pela Sefaz para a NF-e.
• dhRecbto: Data e Hora de Recebimento.
• cStat: Código que informa o status da NF-e que retornou da Sefaz ou da solução NeoGrid NF-e no caso de uma pré-validação ou status intermediário.
• xMotivo: Descrição relacionada ao código de status retornado no arquivo.

Quando os documentos forem processados com sucesso serão atualizadas as tabelas de Nota Fiscal Eletrônica (obf_nf_eletr) e de Monitoramento do Totvs Colaboração (obf_monitor_tc) e os arquivos serão renomeados para o padrão Logix (chave de acesso + ‘-nfe_vis.xml) e movidos para o diretório configurado no VDP10076 (aba NF-e).

Quando não for possível processar o documento (arquivo corrompido, documento não encontrado no banco de dados), o arquivo será movido para o diretório de erros. Arquivos que não iniciarem com os códigos dos documentos processados pelo TOTVS Colaboração não serão processados.

Anexos

Tabelas criadas para o projeto

Para o desenvolvimento desse projeto foram criadas/alteradas as seguintes tabelas: 

• obf_par_totvs_colab: tabela de parâmetros para o TOTVS Colaboração
• obf_monitor_tc: tabela de monitoramento das emissões do TOTVS Colaboração (Fiscal)
• obf_retorno_consulta_tc: tabela de monitoramento da Consulta da chave de Acesso
• sup_audit_arq_xml: tabela de monitoramento do recebimento de documentos pelo TOTVS Colaboração (Suprimentos)

Para criação/atualização das tabelas é necessário executar o conversor OBF00374.cnv, o qual será liberado no chamado TPZGSF. 

Principais diferenças entre as formas de integração do TOTVS Colaboração

Testes

Para o desenvolvimento desse projeto foram disponibilizados CNPJs fictícios para que todas as marcas realizassem os testes necessários para a liberação do projeto.

Esses CNPJs fictícios são utilizados apenas para testes com o ambiente de simulação da NeoGrid, ou seja, os documentos não são efetivamente enviados para a Sefaz e sim para um simulador.

Para realização dos testes de algumas funcionalidades como por exemplo MD-e e Contingência, os testes podem ser realizados somente com um CNPJ oficial.

Quando houver necessidade de alteração de configuração de algum dos CNPJs oficiais da TOTVS, é importante validar essa alteração com as demais marcas.

Importante: Entrar em contato com a equipe de TSS-SP, pois atualmente eles gerenciam essas alterações.