Manual de instalação do Importador de XML Protheus

Confira os passos para aplicação de pacote, configuração de menu, dicionário de dados, pontos de entrada, autenticação do sistema e integração com o Portal da ConexãoNF-e.

O manual a seguir tem o propósito de instruir os passos para instalação do Importador de XML da ConexãoNF-e para o ERP Protheus. Ao término, é possível gerar um documento NF-e, CT-e, NFS-e ou CT-e OS a partir do XML conforme as parametrizações predefinidas do sistema.

1. Aplicação do pacote

O pacote está disponível na Central de Ajuda em Atualizações > Importador de XML Protheus > Pacote de Atualização.

A aplicação do pacote pode ser efetuada em base de produção ou homologação. Lembrando que para atualizações, o repositório precisa estar com acesso exclusivo.

2. Configurações

Saia do sistema e execute em modo exclusivo o programa U_CXNFACI (Assistente de Configuração do Importador), para iniciar a configuração do dicionário de dados e também dos parâmetros iniciais do sistema.

É apresentado o painel de boas-vindas do assistente de configuração, onde basta clicar em Avançar.

Selecione a empresa para abertura do ambiente e clique em Avançar:

Na próxima etapa é apresentado as ações necessárias para continuar com o processo, sendo elas, identificação do aplicativo de captura de XML, configuração do nome das tabelas, parâmetros iniciais e pontos de entrada em uso:

Preencha com conteúdo 1-ConexãoNFe, para que a origem dos dados seja suportada pelo portal da ConexãoNF-e.

1. Preencha o código das tabelas que ainda não estão em uso pelo sistema. Cada tabela informada corresponde a um parâmetro utilizado pelo importador. Os parâmetros têm por objetivo manter o dicionário flexível e devem ser preenchidos com o nome de tabelas de usuário (SZ?, Z?? com 3 caracteres alfanuméricos).

1. • MV_XGTTAB1: nome da tabela contendo o cabeçalho das informações no XML.
   • MV_XGTTAB2: nome da tabela contendo os itens do XML.
   • MV_XGTTAB3: nome da tabela responsável por armazenar os eventos de Carta de Correção, Cancelamento, Operação Não Realizada, Desconhecimento e Desacordo de CTe.
   • MV_XGTTAB4: nome da tabela com o cadastro da conversão de unidade de medida por produto. Este parâmetro não é obrigatório, mas é ideal para empresas com uma unidade de medida em seus pedidos de compra que recebem do fornecedor um produto com outra unidade de medida.
   • MV_XGTTAB5: nome da tabela que armazena os XMLs de notas fiscais de saída já extraídas do TSS. O nome da tabela informada neste parâmetro serve para capturar as notas emitidas do Protheus, que posteriormente serão enviadas ao Portal ConexãoNF-e para armazenamento em nuvem. Para entender melhor a configuração da extração de notas emitidas, consulte o Manual de Extração do XML de Notas de Saída.
   • MV_XGTTAB6: nome da tabela que contém a relação produto x fornecedor/cliente.
   • MV_XGTTAB7: nome da tabela que contém a relação CFOP x Tipo de Nota, utilizado para sugestão do campo "Tipo de Nota".
   • MV_XGTTAB8: nome da tabela que contém a configuração das regras de lançamento automático.
   • MV_XGTTAB9: nome da tabela para armazenar os marcadores configurados no portal da ConexãoNF-e, permitindo personalizar o comportamento no Protheus.ada nome de tabela informada corresponde a um parâmetro utilizado pelo importador. Os parâmetros têm por objetivo manter o dicionário flexível e devem ser preenchidos com o nome de tabelas de usuário (SZ?, Z?? com 3 caracteres alfanuméricos).
   • MV_XGTTABA: nome da tabela para armazenar a referência das notas fiscais de origem do XML, para NFe e CTe.
   • MV_XGTTABB: nome da tabela para armazenar registros de log de ações do usuário, criada cada vez que o usuário inicia uma importação.
2. Botão para apresentar as tabela de usuário que já estão em uso no sistema, para auxiliar na escolha do nome da tabela, sendo que não é permitido escolher um nome contido nessa lista. Ao clicar no botão, é apresentado lista conforme abaixo:
   
   
3. Botão para configuração dos parâmetros iniciais. Neste passo deve-se atentar ao processo de lançamento que a empresa já possui, respondendo às perguntas conforme imagem a seguir:
   
   
   

   1. Tamanho do campo que armazena o número da nota fiscal: escolha o tamanho utilizado nos lançamentos manuais ou importações por outra rotina. Por padrão o programa sugere o tamanho do campo F1_DOC.

   2. Considera zeros à esquerda no número da nota: escolha essa opção para indicar se o número de notas serão preenchidos com zeros na frente para completar o tamanho do campo. Por padrão SIM para preencher com zeros.

   3. Considera zeros à esquerda na série da nota: escolha essa opção para indicar se a série de notas serão preenchidas com zeros na frente para completar o tamanho do campo. Por padrão é indicado que escolha NÃO para manter igual à nota.

   4. Gera automaticamente o manifesto de confirmação para notas classificadas: essa opção indica se será realizado a manifestação para os documentos já classificados, considerando novos lançamentos e antigos (histórico).

   5. Possui alguma filial ligada a fazenda com CPF e Inscrição Estadual: responda como 'Sim' apenas se irá utilizar o importador para receber notas de um CPF com várias inscrições estaduais, caracterizando fazendas vinculadas a pessoa física.

4. Botão para verificar os pontos de entrada em uso, onde posteriormente devem ser adaptados. O programa analisa o RPO e indicar os pontos de entrada que já estão em uso, mostrando como deve ser a estrutura do código.
   
   
   
   Copie o texto apresentado e cole em um bloco de notas para ser acessado posteriormente na seção 3.

Após preencher as informações necessárias, clique em Avançar para que seja apresentado o resumo das alterações do dicionário de dados.

Clique no botão Concluir para finalizar o processo realizar a geração do dicionário de dados.

3. Configuração dos pontos de entrada

Baixe os pontos de entrada por meio do link: Pontos de Entrada ConexãoNF-e

No link é disponibilizado os pontos de entrada utilizados pelo importador. Cada ponto de entrada está em um arquivo-fonte diferente e eles devem ser compilados antes da utilização do sistema.

Caso algum dos pontos de entrada já esteja em uso pela empresa, deve-se alterar o arquivo-fonte para deixá-lo conforme a estrutura indicada abaixo. Se surgir dúvidas quanto ao processo, entre em contato com a equipe de suporte da ConexãoNF-e.

Os pontos de entrada devem ser compilados no mesmo ambiente em que foi aplicado o pacote no passo anterior.

PONTOS DE ENTRADA QUE NECESSITAM ADAPTAÇÃO:

User Function A103CND2()
Local aDuplic := PARAMIXB

    If
        Regra existente
        [...]
    EndIf

    // Ponto de chamada ConexãoNF-e sempre como última instrução.
    aDuplic := U_GTPE001()

Return aDuplic

User Function MT103FIM()

    // Ponto de chamada ConexãoNF-e sempre como primeira instrução.
    U_GTPE002()

    If
        Regra existente
        [...]
    EndIf

Return Nil

User Function A140EXC()
Local lRet := .T.

    // Ponto de chamada ConexãoNF-e sempre como primeira instrução.
    lRet := U_GTPE003()

    If
        Regra existente
        [...]
    EndIf

Return lRet

User Function MT100LOK()
Local lRet := .T.

    // Ponto de chamada ConexãoNF-e sempre como primeira instrução.
    lRet := U_GTPE004()

    // Restrição para validações não serem chamadas duas vezes ao utilizar o importador da ConexãoNF-e,
    // mantendo a chamada apenas no final do processo, quando a variavel l103Auto estiver .F.
    If lRet .And. !FwIsInCallStack('U_GATI001') .Or. IIf(Type('l103Auto') == 'U',.T.,!l103Auto)
        If
            Regra existente
            [...]
        EndIf
    EndIf

Return lRet

User Function MT100TOK()
Local lRet := .T.

    // Restrição para validações não serem chamadas duas vezes ao utilizar o importador da ConexãoNF-e,
    // mantendo a chamada apenas no final do processo, quando a variavel l103Auto estiver .F.
    If !FwIsInCallStack('U_GATI001') .Or. IIf(Type('l103Auto') == 'U',.T.,!l103Auto)
        If
            Regra existente
            [...]
        EndIf
    EndIf

    If lRet
        // Ponto de chamada ConexãoNF-e sempre como última instrução.
        lRet := U_GTPE005()
    EndIf

Return lRet

User Function MT103CWH()
Local lRet := .T.

    If
        Regra existente
        [...]
    EndIf

    If lRet
        // Ponto de chamada ConexãoNF-e sempre como última instrução.
        lRet := U_GTPE006()
    EndIf

Return lRet

User Function MT103IP2()

    // Ponto de chamada ConexãoNF-e sempre como primeira instrução.
    U_GTPE007() 

    If
        Regra existente
        [...]
    EndIf

Return Nil

User Function MT116GRV()

    If
        Regra existente
        [...]
    EndIf

    // Ponto de chamada ConexãoNF-e sempre como última instrução.
    U_GTPE008()

Return Nil

User Function MT140CAB()
Local lRet := .T.

    If
        Regra existente
        [...]
    EndIf

    // Ponto de chamada ConexãoNF-e sempre como última instrução.
    If lRet
        lRet := U_GTPE009()
    EndIf

Return lRet

User Function MTA103MNU()

    If
        Regra existente
        [...]
    EndIf

    // Ponto de chamada ConexãoNF-e sempre como última instrução.
    U_GTPE010()

Return Nil

User Function MT140TOK()
Local lRet := .T.

    // Ponto de chamada ConexãoNF-e sempre como primeira instrução.
    lRet := U_GTPE011()

    // Restrição para validações não serem chamadas duas vezes ao utilizar o importador da ConexãoNF-e,
    // mantendo a chamada apenas no final do processo, quando a variavel l103Auto estiver .F.
    If lRet .And. !FwIsInCallStack('U_GATI001') .Or. !l103Auto
        If
            Regra existente
            [...]
        EndIf
    EndIf

Return lRet

User Function MT140LOK()
Local lRet := .T.

    // Ponto de chamada ConexãoNF-e sempre como primeira instrução.
    lRet := U_GTPE012()

    // Restrição para validações não serem chamadas duas vezes ao utilizar o importador da ConexãoNF-e,
    // mantendo a chamada apenas no final do processo, quando a variavel l103Auto estiver .F.
    If lRet .And. !FwIsInCallStack('U_GATI001') .Or. !l103Auto
        If
            Regra existente
            [...]
        EndIf
    EndIf

Return lRet

User Function MTCOLSE2()
Local aSE2 := ParamIXB[1]

    // Ponto de chamada ConexãoNF-e sempre como primeira instrução.
    aSE2 := U_GTPE013()

    If
        Regra existente
        [...]
    EndIf

Return aSE2

User Function MA103BUT()
Local aButtons := {}

    // Ponto de chamada ConexãoNF-e sempre como primeira instrução.
    aButtons := U_GTPE014()

    If
        Regra existente
        [...]
    EndIf

Return aButtons

User Function MT140SAI()

    // Ponto de chamada ConexãoNF-e sempre como primeira instrução.
    U_GTPE016()

    If
        Regra existente
        [...]
    EndIf

Return Nil

User Function M145ARDEL() 
Local lRet := .T.
    
    // Ponto de chamada ConexãoNF-e sempre como primeira instrução. 
    lRet := U_GTPE018() 

    If 
        Regra existente 
        [...] 
    EndIf 

Return lRet

User Function MT103TPC()        
Local cTes := PARAMIXB[1]

    If
      Regra existente
      [...]
    EndIf

    // Ponto de chamada ConexãoNF-e sempre como última instrução.
    U_GTPE019()

Return cTes

User Function MT140PC()
Local lRet := PARAMIXB[1]

    If
      Regra existente
      [...]
    EndIf

    // Ponto de chamada ConexãoNF-e sempre como última instrução.
    U_GTPE019()

Return lRet

User Function MT116AGR()

   If
      Regra existente
      [...]
   EndIf

   // Ponto de chamada ConexãoNF-e sempre como última instrução.

   U_GTPE021()

Return Nil

 User Function MT103CPS()

  // Ponto de chamada ConexãoNF-e sempre como primeira instrução.
  U_GTPE022()
  
  If
    Regra existente
    [...]
  EndIf

Return Nil

Pontos de entrada adicionais

Os pontos de entrada adicionais são funções de contorno a situações específicas de importação do XML. Devem ser considerados caso a rotina abaixo seja utilizada:

Os pontos de entrada adicionais podem ser baixados através desse link: pontos de entrada adicionais

4. Criação da rotina no menu

Crie a chamada da rotina no menu com as seguintes características:

• Descrição: Importador XML (ou qualquer nome desejado)
• Programa: U_GATI001
• Módulo: Compras (ou qualquer módulo desejado)
• Tipo: Função Protheus

Acesse o Protheus via SIGACFG, em Ambiente > Cadastros > Menus.

Selecione apenas o menu desejado para disponibilização da rotina, recomendado Compras.

Após selecionar, clique em Ok para abrir a manutenção do menu.

Clique em Adicionar >> para carregar todo o menu da esquerda para direita.

Clique em Novo Item na repartição Atualizações > Movimentos.

Informe os dados conforme imagem e salve.

Ao finalizar, clique em Gerar para atualizar o menu existente e informe o nome SIGACOM, sem extensão.

A partir de então, a rotina estará disponibilizada no módulo 02 - Compras. Caso possua menus separadas por usuário, você deverá realizar este passo no menu correspondente e informar o nome correspondente também.

5. Autenticação do sistema

Para habilitar o acesso do importador, entre no Protheus, acesse a rotina do Importador de XML no menu criado no passo 3 e preencha o ID de integração da sua conta.

Para obter o ID de integração, acesse sua conta no menu Administrar > Usuários.

Crie um usuário chamado Integrador, escolha o perfil como Administrador e preencha todas as informações. O e-mail pode ser fictício. Após criar o usuário clique em Salvar para efetivação do registro.

Em seguida, acesse novamente o usuário pelo botão Editar, selecione acesso a todas as empresas e clique em Gerar para obter o ID de integração, copie e salve a alteração.

O usuário Integrador ficará responsável por manter a autenticação com o Protheus.

Em seguida informe o código copiado na mensagem no importador para liberação da rotina. O acesso é concedido a todas as filiais as quais o CNPJ esteja devidamente cadastrado no Portal ConexãoNF-e.

Lembrando que a cada criação de um novo CNPJ, é preciso liberar a permissão no usuário Integrador para habilitar a utilização no Protheus.

Após efetuar os passos acima e caso esteja apresentando a mensagem de acesso negado, certifique que o ambiente esteja devidamente configurado conforme a Configuração SSL no TOTVS | Application Server.

6. Configuração do job de leitura de arquivos

Nessa etapa é preciso configurar o Job para leitura dos arquivos XML e também o Job de gerenciamento dos XMLs.

Eles são responsáveis pela identificação de novos XMLs recebidos pelos CNPJs e pela gravação no banco de dados do Protheus.

Podem ser chamados diretamente via appserver na seção [OnStart] ou via Schedule, disponível no módulo de configuração SIGACFG, em "Ambiente → Schedule → Schedule".

ONSTART

• Copie uma pasta appserver e renomeie para appserver_job_conexaonfe:

• Copie também o repositório (RPO), o qual foi aplicado o pacote do importador nos passos anteriores, e renomeie para apo_job_conexaonfe:

• Retorne a pasta appserver_job_conexaonfe recém-criada e edite o arquivo de configuração appserver.ini:

• Renomeie o caminho do repositório recém-criado:

• Troque a porta para um número disponível:

• Renomeie o serviço para ser instalado corretamente:

• Adicione a seção [OnStart] conforme abaixo:

[OnStart]
jobs=CXNFARQ,CXNFEMP
RefreshRate=120

[CXNFARQ]
Main=U_CXNFARQ
Environment=LOBO
NPARMS=2
PARM1=99
PARM2=01

[CXNFEMP]
Main=U_CXNFEMP
Environment=LOBO
NPARMS=2
PARM1=99
PARM2=01

Para verificar se as configurações foram realizadas corretamente, inicie o appserver.exe em modo console e acompanhe se ocorre alguma mensagem de porta já utilizada ou erro na execução.

Caso apresente alguma inconsistência, revise os passos anteriores e veja se pulou alguma configuração. Caso for executado com sucesso, realize a instalação do appserver como serviço e inicie normalmente.

Para iniciar em modo console, crie um atalho do arquivo appserver.exe e adicione o comando -console nas propriedades do aplicativo:

• Execute e verifique se apresenta alguma mensagem de erro:

Para instalar como um serviço, basta trocar o comando -console para -install e executar o atalho como administrador:

• Será criado um serviço em services.msc conforme definido no arquivo de configuração appserver.ini.

Após a execução do serviço verifique a pasta protheus_data\conexaonfe\logs\cxnfarq, caso um arquivo seja criado com a data atual significa que o serviço foi configurado com sucesso.

SCHEDULE

Geralmente o Protheus possui uma porta específica para o Schedule, com nome WF/Schedule.

Caso possua o Protheus hospedado no TCloud (nuvem da TOTVS) o nome do ambiente é wf. Caso possua servidor próprio é recomendado a criação de uma porta separada do balanceamento de carga, conforme instruções disponíveis em: Schedule - Como agendar a execução de rotinas.

• Acesse o configurador SIGACFG no menu Ambiente > Schedule > Schedule:

• Inicie os serviços Task Manager e Queue Manager, caso estejam parados:

• Cadastre o Agent caso não tenha cadastrado, clicando no ícone de radar no canto superior direito da tela:

• Altere o Agent para utilizar apenas duas (2) threads, conforme abaixo (Caso o Agent já esteja iniciado, será preciso pará-lo):

• Inicie o Agent:

• Cadastre a rotina no menu Agendamento conforme informações abaixo:

• Atenção aos campos Usuário e Rotina: eles devem ser preenchidos respectivamente com o código de usuário do Administrador e com os códigos de empresa e filial apenas de uma empresa.

No exemplo abaixo, 99 é o código da empresa e 01 o código da filial, mas essa informação varia de acordo com seu ambiente.

Lembrando que é necessário configurar apenas para uma empresa/filial, pois as restantes serão tratadas automaticamente na função U_CXNFSCH(1,'99','01').

• Configure a recorrência conforme necessidade.

No exemplo abaixo a função será chamada a cada 5 minutos. É importante marcar a função para Descartar tarefas atrasadas, pois não pode haver mais de uma thread executando esse processo (n.º de execuções: 0288 e Intervalo: 00:05):

• Configure a segunda função, mudando apenas o primeiro parâmetro, U_CXNFSCH(2,'99','01'), conforme abaixo:

Após as criações dos dois agendamentos, o Protheus irá começar a montar a fila de execuções conforme a recorrência cadastrada, no caso a cada 5 minutos a partir do horário 00:00.

Para executar como teste é preciso apertar o botão verde (iniciar), forçando a execução para o horário atual, dessa forma não é preciso esperar até o término de criação das filias.

Após o iniciar o primeiro Job criado (U_CXNFSCH(1,'99','01')), crie um arquivo com nome cxnfarq na pasta protheus_data\conexaonfe\logs\cxnfarq. Caso ele seja criado, o Schedule foi configurado com sucesso.

7. Integração do Portal ConexãoNF-e de captura com o Importador de XML no Protheus

A integração entre os dois sistemas pode ocorrer de duas formas:

• modo offline: ocorre por intermédio do integrador; 
• modo online: movimenta o XML puxando diretamente pelo Protheus por meio da API de captura.

O modo online é obrigatório para instâncias do Protheus hospedadas na nuvem da TOTVS, TCloud. Para servidores hospedados localmente ou em VMs, utilize o modo offline, pois nele é possível parametrizar dinamicamente como a integração irá ocorrer.

Modo Online

Caso no passo 3.2 tenha respondido que o Protheus está hospedado no TCloud, a sua configuração finaliza aqui, pois neste ponto já é possível visualizar as notas pendentes no painel inicial do importador. Do contrário, para habilitar o modo online, basta acessar a rotina do importador no menu Outras Ações > Parâmetros e habilitar conforme abaixo:

Após ativar o parâmetro, reinicie o appserver do Job ou Schedule para a função reconhecer a mudança de configuração.

Essa integração tem o comportamento de buscar todos os arquivos XMLs armazenados na sua conta da ConexãoNF-e, considerando XMLs de NFe recebidos, CTe recebidos e envolvidos, NFS-e recebidos, NF-e emitidos, CTe OS recebidos, eventos recebidos e emitidos, entre outros.

Contudo, o Job apenas grava no banco de dados os XMLs nos quais o CNPJ é destino/tomador. Os XMLs emitidos e CTes envolvidos serão desconsiderados.

A cada requisição de documentos, o sistema armazena o código do último documento baixado no parâmetro MV_CXNFCOD, começando pelo código 0.

Para começar a integração a partir de uma data, basta configurar o parâmetro, conforme imagem abaixo, em Outras Ações > Parâmetro e reiniciar novamente o Job ou Schedule. A alteração desse parâmetro deve ser efetuada na tela de parâmetros do importador para que, ao confirmar, o sistema atualize o código do último documento baixado.

Para acompanhar o funcionamento da integração o sistema, crie o log na pasta protheus_data\conexaonfe\logs\cxnfarq\ com as mensagens de cada XML integrado, gravando também a mensagem de erro caso ocorra alguma inconsistência no processo. Caso o log seja gravado, significa que a integração está rodando corretamente.

Modo Offline

No modo offline a integração ocorre por meio do integrador, aplicativo instalado diretamente no servidor do Protheus responsável por efetuar o download dos XMLs na pasta recebimento.

A pasta recebimento é criada na raiz do servidor em protheus_data\conexaonfe\, com outras pastas utilizadas para administrar os XMLs:

• recebimento: é responsável por receber todos os arquivos XMLs de todas as empresas monitoradas pelo Portal ConexãoNF-e.
• backup: serve de armazenamento dos XMLs já processados pelo Job.
• acoes: contém arquivos de extenção .json utilizados para atualizar as notas no Portal ConexãoNF-e. Essa atualização envolve a marcação do campo ERP e a indicação para executar o manifesto de confirmação para NFe.
• logs: armazena os logs de execução do Job de leitura de arquivos, importação automática, entre outros.

Para iniciar a instalação e configuração do integrador, siga os passos conforme abaixo:

• Instale o aplicativo e verifique a criação do serviço conforme instruções em Instalação do Integrador.
• Após finalizar a instalação, configure o integrador pelo Portal ConexãoNF-e, informando o caminho das pastas criadas em protheus_data\conexaonfe\. Para isso, acesse a conta e em seguida use o menu Integradores > Editar Configurações. 

• Em Baixa Automática, edite os CNPJs cadastrados e informe o caminho completo do diretório de recebimento.

• Ao retornar para o painel inicial com todos os CNPJs, informar o caminho da pasta acoes clicando em + Adicionar nova pasta.

Após concluir as configurações do integrador, os XMLs logo serão baixados para a pasta de recebimento e consequentemente lidos pelo Job.

A instalação finaliza aqui. Ao acessar a rotina basta clicar em Buscar Novos ou aguardar até que os XMLs apareçam em tela para importação.