Histórico da Página
Integração TOTVS Colaboração NF-e/CT-e Logix
Contexto de negócio
TOTVS Colaboração
O TOTVS Colaboração é um projeto que permite a integração de cliente x fornecedor com os produtos TOTVS. A primeira fase disponibiliza o leiaute de importação de nota fiscal eletrônica (NF-e) e conhecimento de transporte eletrônico (CT-e), por meio da extensão XML, validado pela Secretaria da Fazenda (Sefaz).
O recebimento dos arquivos de entrada extensão XML pode ocorrer por ERP ou pelo produto da Neogrid, empresa parceira da TOTVS.
ERP
No modelo de gerenciamento dos arquivos extensão XML por ERP, o armazenamento dos arquivos é realizado na própria empresa, posteriormente enviados por JOB para validação da Sefaz e integrado para inclusão no sistema.
Neogrid
No modelo de gerenciamento dos arquivos extensão XML pela Neogrid, o armazenamento dos arquivos é realizado no banco da Neogrid. Os arquivos podem compor um grande volume e tratando-se de documentos legais, devem ser armazenados de forma que permita a localização rápida para uma auditoria, por exemplo.
Sistemas Envolvidos
ERP Logix;
TOTVS Service Sped (TSS);
Portal Neogrid;
ERP do fornecedor (pode ou não ser TOTVS).
Integração
Esta integração tem o objetivo de permitir que o cliente com ERP TOTVS realize o envio de NF-e e CT-e via TOTVS Colaboração. Permite também que um fornecedor com ERP TOTVS receba esses documentos automaticamente de clientes TOTVS Colaboração via integração de arquivo XML.
Escopo
A proposta do TOTVS Colaboração compreende toda a integração entre os ERPs TOTVS com a solução Neogrid. A responsabilidade do TOTVS Service SPED (TSS) no TOTVS Colaboração é de integrar os ERPs com a Neogrid, provendo serviços que possibilitem a comunicação e transmissão de documentos entre as partes, conforme pode ser visto na figura abaixo.
Pré-requisitos instalação/implantação/utilização
Os pré-requisitos (técnicos ou de negócio) para o funcionamento da integração são:
- Logix versão 10.02 ou superior instalado;
- Pacote de liberação 1/2012 instalado;
- Versão JAVANFE 4.7.7 ou superior, Jdom, Itext;
- TSS versão 2.04 ou superior com base de dados dedicada (ambiente homologação e produção);
- Neogrid NF-e com a configuração do TSS;
- Serviço do JOB Logix deve estar startado (JOB0003).
Instalação/Atualização
Este tópico tem por objetivo orientar a instalação da integração, visando o seu funcionamento completo.
Atualização do TSS
Para iniciar a atualização do TSS e da biblioteca Java será necessário efetuar o download no portal do cliente/Download (http://suporte.totvs.com/download).
Pesquisar pela Linha = Logix, Tipo = Outros e filtrar por nfe_ conforme tela abaixo:
Salvar o arquivo do TSS no C:/, do servidor onde será instalado o TSS.
Fazer backup da pasta atual do TSS. E descompactar o arquivo .ZIP baixado do portal do cliente/download.
Copiar a pasta “certs” e o arquivo “totvsappserver.ini” para a nova versão baixada.
No arquivo “TotvsAppServer.ini” no parâmetro “JOBS”, deverá ser acrescentado “JOBDOCSCOL” e definido esta seção para realizar o recebimento de XML.
Exemplo:
[ONSTART]
JOBS=JOB_WS,JOBNFE,JOBDOCSCOL
[JOBDOCSCOL]
main=DOCSWFCOL
environment=SPED
Se o cliente for emitir nota fiscal pelo TOTVS Colaboração, deverá ser alterado no parâmetro “JOBS” o “JOBNFE” por “JOBNFECOL” e definir este novo JOB.
Exemplo:
[ONSTART]
JOBS=JOB_WS, JOBNFECOL,JOBDOCSCOL
[JOBNFECOL]
main=SPEDWFCOL
environment=SPED
Na seção [sped] colocar o parâmetro “DOCS_WF_DEBUG=1” para exibir a execução dos “JOBS” do “JOBDOCSCOL” e verificar se há o parâmetro “NFESPED_WF=1”, se não, incluir para exibir a execução dos “JOBs” do “JOBNFE” ou “JOBNFECOL”.
Se o cliente for emitir conhecimento eletrônico pelo TOTVS Colaboração, deverá ser alterado o parâmetro “JOBS” o “CTEWF” por “JOBCTECOL” e definir este novo JOB.
Exemplo:
[ONSTART]
JOBS=JOB_WS, JOBCTECOL,JOBDOCSCOL
[JOBCTECOL]
main=CTEWFCOLAB
environment=SPED
Se o cliente for emitir nota fiscal de serviço pelo TOTVS Colaboração, deverá ser alterado o parâmetro “JOBS” o “NFSE_WF” por “JOBNFSECOL” e definir este novo JOB.
Exemplo:
[ONSTART]
JOBS=JOB_WS, JOBNFSECOL,JOBDOCSCOL
[JOBNFSECOL]
main=NFSEWFCOL
environment=SPED
Salvar os arquivos baixados do Java (JAVANFE 4.7.7, Jdom, Itext) na pasta de javanfe do servidor logix, pasta que está setada o classpath dentro do servidor de aplicação.
Para descobrir o local instalado:
Linux: ps -ef |grep JAVA ou ps -ef |grep CLASSPATH
Win: Ir nas variáveis de ambiente.
Como executar o TSS como console:
- Criar atalho do “Totvsappserver.exe” na área de trabalho;
- Acionar o botão direito do mouse e selecionar a opção “Propriedades”;
- Alterar o caminho do atalho incluindo a opção no final: “-console”.
Incluir os programas no menu na área de Recebimento:
- SUP34201 (Cadastro de processos NFE-Entrada);
- SUP34202 (Regras Dinâmicas NFE-Entrada);
- SUP34204 (Monitor de Notas NFE-Entrada);
- SUP20128 (Fornecedor EDI NFE-Entrada).
Como estes programas foram desenvolvidos na tecnologia metadados a execução processo no MEN0050 deverá ser 2 conforme tela abaixo:
Depois de cadastrar no menu deverá ser realizada a liberação dos programas para o usuário pelo MEN0060.
Parametrização do SUP34201 (Estrutura de diretórios por processo de importação) – Obrigatório
Os objetivos da parametrização do SUP34201 são:
- Identificar os processos que serão integrados;
- Indicar a forma de integração;
- Aproximar arquivos XML do documento;
- Permite desativar um determinado processo;
- Cadastrar NF-e e CT-e em diretórios diferentes.
Parametrização do VDP9109 (Parâmetros de Processamento da NF-e) – Obrigatório
Os objetivos da parametrização do VDP9109 são:
- Habilitar integração com Neogrid
- Determinar volume de retorno
Para efetuar a parametrização, deve-se acessar a opção de menu “tOtvs_colab” que exibirá a tela “Parâmetros Totvs Colaboração”.
Na tela abaixo, assinalar o campo “Utilizar TOTVS Colaboração”. Cadastrar o usuário, senha do repositório e o tipo do ambiente, conforme foram disponibilizados pela Neogrid.
O cadastro do usuário sempre deve estar no formato 99999999999999#tss, sendo “99999999999999” um CNPJ válido nos cadastros da Neogrid e “tss” o usuário disponilizado pela Neogrid.
A Neogrid trabalha apenas em ambiente de produção para realização do envio do XML para o ERP, pois sempre trabalha com NF-es válidas. Desta maneira, deverá sempre ser informado o ambiente NF-e e ambiente CT-e como “1”, que indica ser o ambiente de “Produção”.
O parâmetro “Produtos” serve para indicar se há emissão de algum documento eletrônico pelo TOTVS Colaboração. Quando o cliente tem apenas recebimento de XML este parâmetro deverá estar como “Nenhum”.
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 RM Conector e Backoffice Protheus estarão aptas a fazer a primeira análise e, quando necessário, repassar para a equipe mais adequada em cada caso.
Observação: Este modelo de suporte está sendo revisado pela TOTVS.
Transações/Entidades/Mensagens únicas
Apresente quais as transações/entidades que são trocadas e quem envia a informação para quem. Pode (e recomenda-se) ter um diagrama, uma tabela ou afins que apresente este fluxo.
Relacione quais são as mensagem únicas (TOTVSMessage) utilizadas e qual o seu relacionamento com as entidades já existentes do ERPs envolvidos.
Exemplos:
Método | ID | Descrição | Origem | Destino | XSD (versões podem variar) |
Cadastros | 01 | Cliente/Fornecedor | RM | Protheus | CustomerVendor_1_000.xsd |
02 | Moeda | RM | Protheus | Currency_1_000.xsd | |
03 | Unidade de Medida | RM | Protheus | UnitOfMeasure_1_000.xsd | |
04 | Produto | RM | Protheus | Item_?_000.xsd | |
05 | Centro de Custo | RM | Protheus | CostCenter_1_000.xsd | |
06 | Ativos | RM | Protheus | NOVA, Ativo fixo | |
07 | Funcionários | RM | Protheus | Employee_1_000.xsd | |
08 | Projeto | RM | Protheus | Project_1_000.xsd | |
09 | Obra | RM | Protheus | SubProject_1_000.xsd | |
10 | Tarefa | RM | Protheus | TaskProject_1_000.xsd | |
11 | Meio de Pagamento | RM | Protheus | ?????.xsd | |
12 | Condições de pagamento | RM | Protheus | PaymentCondition_1_000.xsd | |
13 | Coligada* | RM | Protheus | Company_1_000.xsd | |
14 | Filial* | RM | Protheus | Branch_2_000.xsd | |
Processos | 15 | Solicitações (compras/armazém) | Protheus | RM | Request_1_000.xsd |
16 | Cancelar movimento (solicitação, OS, etc) | Protheus | RM | CancelRequest_1_000.xsd | |
17 | Cancelar movimento (solicitação, OS, etc) | RM | Protheus | CancelRequest_1_000.xsd | |
18 | Baixa de estoque | Protheus | RM | Request_1_000.xsd | |
19 | Baixa de estoque | RM | Protheus | Request_1_000.xsd | |
20 | Consulta Saldo | Protheus | RM |
| |
21 | Apropriação de custos |
|
| Request _1_000.xsd | |
22 | Geração de OS |
|
|
| |
23 | Consulta de OS |
|
|
| |
24 | Ampliação patrimonial |
|
|
|
Fluxo das Informações
Para cada fluxo de informação descreva, se necessário, alterações de comportamento que o respectivo produto irá sofrer. Por exemplo: quando o Logix recebe o PEDIDO de OUTRO ERP, este pedido não poderá ser alterado no Logix.
Liste quais as entidades integradas e como é o mapeamento entre as diferentes estruturas. Por exemplo: Classe no sistema A vira categoria no sistema B, o campo X é refletido no campo Y etc.
Liste quais transações/operações a integração fará com as entidades relacionadas. Exemplo: Insert de PEDIDO, Insert, update de ITEM, buscar saldo em estoque do ITEM no dia X ou buscar dados do FUNCIONÁRIO.
Cadastros
Descreva características gerais do fluxo de informações e que serão comuns para este tipo de entidade. Características particulares para cada entidade deverão ser citadas em tópicos específicos de cada entidade.
Sempre que existir (a sugestão é sempre criar) e for agregador ao documento acrescentar aqui os diagramas/imagens ou até mesmo colocar tais diagramas diretamente na especificação dos processos
Em seguida faça uma descrição para cada um dos fluxos para cada entidade
<Transação/Entidade>
Identificador da Mensagem: <mensagem>
Versão: <versão>
Módulo <marca 1>: <BackOffice – Gestão xxxxxxx>
Módulo <marca 2>: <SIGAXXX>
Tipo de Envio: <Assíncrona/Síncrona>
Mensagem Padrão | PROTHEUS | RM | ||
Tabela | Campo | Tabela | Campo | |
Code | CTO990 | CTO_SIMB | GMOEDA | SIMBOLO * |
Description | CTO990 | CTO_DESC | GMOEDA | DESCRICAO |
Symbol | CTO990 | CTO_SIMB | GMOEDA | SIMBOLO |
Notas:
Observações sobre comportamento desta mensagem ou dos processos envolvidos nela/para ela
A seguir descrever as variações, particularidades da mensagem e processos (integração) de acordo com cada marca
Limitações/Restrições
Descreva limitações e restrições para a integração que está sendo descrita.
Processos
Descreva características gerais do fluxo de informações e que serão comuns para este tipo de entidade. Características particulares para cada entidade deverão ser citadas em tópicos específicos de cada entidade.
Sempre que existir (a sugestão é sempre criar) e for agregador ao documento acrescentar aqui os diagramas/imagens ou até mesmo colocar tais diagramas diretamente na especificação dos processos
Em seguida faça uma descrição para cada um dos fluxos para cada entidade
<Transação/Processo>
Tipo de Fluxo: Protheus -> RM
Mensagem: Request_1_000
Versão: 1.000
Descrição de todo o comportamento e funcionamento do processo. Breve contexto, origem, regras, integração (geração da mensagem, envio, recebimento no destino), o quê supostamente irá ocorrer no destino, retorno, impacto, consequências, o que foi afetado, como conferir, validar, etc o retorno.
Acrescentar um diagrama do processo.
A seguir descrever as variações, particularidades da mensagem e processos (desta integração) de acordo com cada marca
Notas:
Observações sobre comportamento desta mensagem ou dos processos envolvidos nela/para ela
Limitações/Restrições
Descreva limitações e restrições para a integração que está sendo descrita.
Limitações / Restrições Gerais
Descreva limitações e restrições para cada fluxo descrito no tópico anterior. Exemplo:
- ERP1 envia ITEM cadastrado para o ERP2
ERP1 somente enviará o ITEM se este estiver em uma das famílias cadastradas no parâmetro FAMILIA_INTEGRACAO.
Se o tipo de valorização do estoque for FIFO.
- ERP2 envia PEDIDO cadastrado para o ERP1
O pedido recebido no ERP1 vindo do ERP2 estará bloqueado para alteração.
Como fazer (opcional)
Descreva os passos que viabilizem a integração.
Exemplo:
Os passos para viabilizar a integração são:
- No Logix ou no Protheus efetue o cadastro das seguintes informações: Clientes, fornecedores, transportadores, cidades, cotação de moeda e unidades de medida.
- 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 Protheus 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 Protheus verificar se foi efetuado corretamente o relacionamento entre os dois documentos.
- No Logix efetuar um processo de expedição para o novo produto cadastrado, até o momento do envio da mensagem de integração de pedido de venda.
- No Protheus efetuar o faturamento do pedido de venda recebido.
- No Protheus verificar se a nota fiscal gerada contém todas as informações necessárias para o segmento de operador logístico (armazém geral).
- No Protheus efetuar a escrituração fiscal das notas fiscais, verificando se as regras da legislação deste segmento foram respeitadas.
- No Logix é possível consultar o número do pedido de venda gerado para as notas fiscais de retorno simbólico e conta/ordem no programa WMS6333 (Consulta de Documentos). Para os processos de faturamento de serviço o número do pedido está disponível no programa WMS6411 (Movimentos a Faturar).
Situações comuns (opcional)
Descreva situações problemáticas comuns que podem ocorrer durante o funcionamento da integração e como solucioná-los. Neste ponto também é importante dar instruções de como reconhecer e investigar problemas que podem vir a ocorrer durante a integração. Se houver, apresente tabelas de códigos e descrições de erros que a integração poderá apresentar.
Este tópico possivelmente será alimentado com as experiências durante o desenvolvimento da integração e poderá ser realimentado durante o uso da integração no cliente.
Exemplo 1:
Tratamento de erros de integração (Produto A)
Erro | Mensagem | Solução |
Código do erro | Mensagem exibida | Ação a ser tomada para resolução do erro. |
Tratamento de erros de integração (Produto B)
Erro | Mensagem | Solução |
Código do erro | Mensagem exibida | Ação a ser tomada para resolução do erro. |
Exemplo 2:
Quando uma mensagem é enviada do Logix para o Protheus, 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:
Erro ao enviar a mensagem de Cidade via Integração
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.
Checklist de suporte da aplicação
Crie um check-list de verificação de alguns pontos importantes para o funcionamento e atendimento da integração.
Instalação/Configuração
Relacione itens de verificação para garantir que a integração está corretamente instalada e configurada. Isto não pode ser uma cópia do procedimento de instalação/configuração, mas verificações pontuais que podem remeter aos itens da instalação.
Checklist de Verificações:
Relacione itens de verificações para que o atendente possa:
- Identificar o funcionamento da integração;
- Identificar a ocorrências de problemas;
- Coletar evidências do mau funcionamento relatado pelo cliente;
- Realizar possíveis ajustes na integração quanto à configuração ou negócio.
Parametrização do SUP20128 (Parâmetros por Fornecedor EDI/TOTVS Colaboração)
Os objetivos da parametrização do SUP20128 são:
- Identificar a forma da baixa de saldo no módulo de Compras;
- Flexibilizar as negociações com o fornecedor;
- Baixar pedido com programação própria.
Observação: Corresponde à parametrização do SUP9990 (Parâmetros EDI) da versão 10.02.
Parametrização do JOB0003 (Agendador de Tarefas Logix) - Opcional, mas importante
Os objetivos da parametrização do JOB0003 são:
- Permitir que todas as etapas de integração sejam automáticas isto é, sem a intervenção do usuário;
- Registrar as ações executadas no monitor de integração;
- Foco na gestão e no fluxo das informações.
Importante:
No JOB deve ser configurado o programa sup34203 para execução.
Para efetuar a parametrização no SUP34203 para execução via JOB, conforme documentação do TDN:
- Linha Logix > Agendador de Tarefas Logix > Anexos> AgendatorTarefasLogix.pdf.
Informar valor = empresa
Usuário informado no JOB
Para validar o cadastro de execução do JOB, acesse o JOB0005 e consulte pelo código de gatilho.
Parametrização do SUP34202 (Regras Dinâmicas) – Opcional, mas importante
Os objetivos da parametrização do SUP34202 são:
- Permitir maior liberdade na configuração do sistema;
- Minimizar impacto de implantação;
- Aumentar aderência de solução.
Variáveis
Regras
Retorno
Uso e Controle
Processo Monitor de NF-e de entrada:
Os objetivos do processo monitor de NF-e são:
Permite acompanhar todas as ações realizadas para o documento;
Registro dos erros durante o processo de integração.
Rastreabilidade
Os objetivos da rastreabilidade são:
Permitir acompanhar todas as ações realizadas para o documento;
Registro dos erros durante o processo de integração.
Funcionalidades
Integrações:
Suporte
Caso necessite de auxílio na configuração do TSS para conectar com a Neogrid e nas parametrizações do VDP9109 deverá ser aberto chamado para o produto Gestão Fiscal.
Auxilio na execução dos programas do SUP ou parametrização do JOB deverá ser aberto chamado para o produto Gestão de Materiais.
Fluxo das Informações
O fluxo de recebimento do XML dar-se-á da seguinte forma:
Fluxograma do Processo NF-e de entrada:
Situações comuns
- A mensagem de “Invalid HTTP Connection” no log do TSS (console.log) pode significar “Access Denied”, ou seja, o usuário que foi informado para autenticação HTTP, no portal da Neogrid pode estar inválido.
- A mensagem de “10060 : Connection timed out.” no log do TSS (console.log) significa que a URL de conexão com a Neogrid pode estar incorreta ou o serviço do portal da Neogrid não está disponível.
Checklist de suporte da aplicação
Abaixo está o check-list de verificação de alguns pontos importantes para o funcionamento e atendimento da integração.
Instalação/Configuração
1. Verificar se o serviço do TSS está disponível via HTTP (Navegador Web), normalmente a URL é “HTTP:\SERVIDOR:PORTA\SPED”;
2. Verificar se o serviço da Neogrid está disponível via HTTP (Navegador Web);
3. Verificar no log do TSS (console.log) se ocorrem mensagens de erro na execução dos JOBs;
4. Em caso de retorno negativo do TSS para o Logix a mensagem será exibida no relatório de erros do JOB.
5. Em caso de inconsistências da mensagem já no ERP elas poderão ser consultadas no monitor de integração Logix (SUP34204).
Checklist de Verificações de negócio:
1. Habilitar o parâmetro “Utiliza TOTVS Colaboração” no VDP9109, opção de menu opção “tOtvs_colab” ou LOG00087;
2. Parametrizar no VDP9109, opção de menu “tOtvs_colab”, o usuário, senha e o tipo do ambiente, e enviá-los ao TSS, opção “Configurar TSS”.
Anexos