O manual a seguir tem o propósito de instruir os passos para instalação do Importador de XML para o ERP Protheus. Ao término, é possível gerar um documento NFe, CTe, NFSe ou CTe-OS a partir do XML conforme as parametrizações predefinidas do sistema.
1. Aplicação do pacote
O pacote está disponível para download em Pacote de atualização do Monitor DFe. A aplicação 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_IMPXACI (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, configuração do nome das tabelas, parâmetros iniciais e pontos de entrada em uso:
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).
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_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.
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:
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:
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;
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;
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;
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);
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.
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 ser apresentado o resumo das alterações do dicionário de dados.
Clique no botão Concluir para finalizar o processo e realizar a geração do dicionário de dados.
3. Configuração dos pontos de entrada
Baixe 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.
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 do Importador de XML sempre como última instrução.
aDuplic := U_GTPE001()
Return aDuplic
User Function MT103FIM()
// Ponto de chamada do Importador de XML sempre como primeira instrução.
U_GTPE002()
If
Regra existente
[...]
EndIf
Return Nil
User Function A140EXC()
Local lRet := .T.
// Ponto de chamada do Importador de XML sempre como primeira instrução.
lRet := U_GTPE003()
If
Regra existente
[...]
EndIf
Return lRet
User Function MT100LOK()
Local lRet := .T.
// Ponto de chamada do Importador de XML sempre como primeira instrução.
lRet := U_GTPE004()
// Restrição para validações não serem chamadas duas vezes ao utilizar o importador,
// 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,
// mantendo a chamada apenas no final do processo, quando a variavel 103Auto estiver .F.
If !FwIsInCallStack('U_GATI001') .Or. IIf(Type('l103Auto') == 'U',.T.,!l103Auto)
If
Regra existente
[...]
EndIf
EndIf
If lRet
// Ponto de chamada do Importador de XML 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 do Importador de XML sempre como última instrução.
lRet := U_GTPE006()
EndIf
Return lRet
User Function MT103IP2()
// Ponto de chamada do Importador de XML sempre como primeira instrução.
U_GTPE007()
If
Regra existente
[...]
EndIf
Return Nil
User Function MT116GRV()
If
Regra existente
[...]
EndIf
// Ponto de chamada do Importador de XML sempre como última instrução.
U_GTPE008()
Return Nil
User Function MT140CAB()
Local lRet := .T.
If
Regra existente
[...]
EndIf
// Ponto de chamada do Importador de XML sempre como última instrução.
If lRet
lRet := U_GTPE009()
EndIf
Return lRet
User Function MTA103MNU()
If
Regra existente
[...]
EndIf
// Ponto de chamada do Importador de XML sempre como última instrução.
U_GTPE010()
Return Nil
User Function MT140TOK()
Local lRet := .T.
// Ponto de chamada do Importador de XML sempre como primeira instrução.
lRet := U_GTPE011()
// Restrição para validações não serem chamadas duas vezes ao utilizar o importador,
// 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 do Importador de XML sempre como primeira instrução.
lRet := U_GTPE012()
// Restrição para validações não serem chamadas duas vezes ao utilizar o importador,
// 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 do Importador de XML sempre como primeira instrução.
aSE2 := U_GTPE013()
If
Regra existente
[...]
EndIf
Return aSE2
User Function MA103BUT()
Local aButtons := {}
// Ponto de chamada do Importador de XML sempre como primeira instrução.
aButtons := U_GTPE014()
If
Regra existente
[...]
EndIf
Return aButtons
User Function MT140SAI()
// Ponto de chamada do Importador de XML sempre como primeira instrução.
U_GTPE016()
If
Regra existente
[...]
EndIf
Return Nil
User Function M145ARDEL()
Local lRet := .T.
// Ponto de chamada do Importador de XML 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 do Importador de XML sempre como última instrução.
U_GTPE019()
Return cTes
User Function MT140PC()
Local lRet := PARAMIXB[1]
If
Regra existente
[...]
EndIf
// Ponto de chamada do Importador de XML sempre como última instrução.
U_GTPE019()
Return lRet
Código | Descrição |
A103CND2 | Utilizado na importação de CT-e por lote para pegar a condição de pagamento. Usado somente quando o parâmetro MV_XGTCOLT (quando ativo abre tela do documento de entrada), estiver desativado. |
MT103FIM | Na inclusão de uma nota tanto pelo documento de entrada (MATA103) quanto pelo importador (GATI001), ele gerará um arquivo para integração com o Portal atualizando o status da nota. Na exclusão de um documento de entrada fará a geração de arquivo para atualizar o status do XML. Também volta a situação do XML para ficar disponível para nova importação. |
A140EXC | Utilizado para apresentar as mensagens de usuário durante a execução automática. |
MT100LOK | Utilizado para apresentar as mensagens de usuário durante a execução automática. |
MT100TOK | Quando confirma o documento de entrada gerado pelo importador, valida se os valores totais estão iguais aos do XML, caso negativo apresentará mensagem sobre a divergência. |
MT103CHW | Tem por função quando utilizado o importador desabilitar alguns campos para alteração na tela do documento de entrada (F1_TIPO, F1_FORMUL, F1_DOC, F1_SERIE, F1_FORNECE, F1_LOJA, F1_EMISSAO, F1_ESPECIE, F1_EST). |
MT103IP2 | Utilizado para apresentar as mensagens de usuário durante a execução automática. |
MT116GRV | Na importação de CT-e carrega a informação da chave do XML para ser gravada. |
MT140CAB | Quando a importação do XML for de pré-nota, carrega as informações dos campos de totais de despesas, frete e seguro. |
MTA103MNU | Insere no menu do documento de entrada a consulta das cartas de correção. |
MT140TOK | Altera a variável l103Auto com valor "falso", para que ao confirmar a inclusão da pré-nota, realize todas as validações do padrão. |
MT140LOK | Utilizado para apresentar as mensagens de usuário durante a execução automática. |
MTCOLSE2 | Chamado na importação de CT-e por lote, onde força a atualização da data de vencimento preenchida em tela. |
MA103BUT | Criação do botão "Conferir Impostos" durante o lançamento da nota ou classificação da pré-nota. |
MT140SAI | Na inclusão de uma pré-nota tanto pelo manual (MATA140) quanto pelo importador (GATI001), ele gerará um arquivo para integração com o Portal atualizando o status da nota. Na exclusão de uma pré-nota fará a geração de arquivo para atualizar o status do XML. Também volta a situação do XML para ficar disponível para nova importação. |
M145ARDEL | Utilizado na exclusão de um aviso de recebimento, para retornar a situação do XML para pendente. |
MT103TPC | Utilizado para manipular a quantidade da tarefa do projeto e atribuir conforme escolhido pelo usuário (quantidade do XML), apenas quando utiliza integração com SIGAPMS. Na importação direta (MATA103). |
MT140PC | Utilizado para manipular a quantidade da tarefa do projeto e atribuir conforme escolhido pelo usuário (quantidade do XML), apenas quando utiliza integração com SIGAPMS. Na importação como pré-nota (MATA140). |
🔹 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:
Rotina | Ponto Adicional | Situação na qual se aplica |
Importação de pré-nota de produto com de ativo imobilizado. | MA103ATF | Utilizado para manipulação das informações na classificação de produto com Ativo Fixo, como preenchimento do Histórico, Centro de Custo e Conta Contábil. |
Classificação de pré-nota com pedido de compra e valor de frete informado | MT103BDP | Utilizado para manipular o valor do frete na classificação de uma pré-nota com pedido de compra, deixando conforme informado na pré-nota. |
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 4 e preencha o ID e a KEY da API.
Após isso 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.
Verifique também um possível bloqueio do domínio da API.
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”. Escolha um das opções e siga conforme abaixo:
🔹 ONSTART
Copie uma pasta appserver e renomeie para appserver_job_importador:
Copie também o repositório (RPO), o qual foi aplicado o pacote do importador nos passos anteriores, e renomeie para apo_job_importador:
Retorne a pasta appserver_job_importador 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\importador\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\importador\logs\cxnfarq. Caso ele seja criado, o Schedule foi configurado com sucesso.
7. Definir logomarca para o painel de documentos pendentes de importação
Para definir a imagem da logomarca que aparecerá na tela inicial do programa, substitua o arquivo de nome “importador_sua_logo.png” que encontra-se na pasta \system\.
Para definir uma imagem por grupo de empresa, basta adicionar o código no final do nome do arquivo, por exemplo: “importador_sua_logo01.png”.
A imagem é inserida no topo superior esquerdo do painel de documentos pendentes de importação e documentos importados.
8. Primeiros passos para importação do XML
Se chegou nessa etapa, alguns dos XMLs já devem estar integrados com o Protheus por meio dos serviços configurados na etapa 6. Para certificar do sucesso das configurações, efetue uma importação de uma NFe. O teste deve chegar até a etapa onde é apresentado a tela do Documento de Entrada (MATA103), sem necessidade de efetivação da importação.
Acessando o importador, posicione em um registro de NFe, o qual contém o ícone de nota fiscal (1) e legenda verde (2) ou legenda numérica 1 (3).
Para habilitar as legendas numéricas, utilize o atalho F12 e procure por Acessibilidade. Certifique também que a NFe escolhida possua o campo Tipo de Nota igual a N - Normal Completo (4), localizado no topo da tela.
Posicionado na NFe desejada, clique no botão Importar, localizado no meio da tela, abaixo do título Documentos Pendentes de Importação.
Preencha os campos obrigatórios, sendo eles, Natureza, Condição de Pagamento, localizados no cabeçalho e, na seção de itens do XML, o código do produto e a TES.
Como o propósito é apenas testar as configurações, preencha os dados com qualquer informação válida.
Caso ocorra alguma mensagem, configura os dados informados ou os pontos de entrada que estão em uso.
Caso a tela do Documento de Entrada seja apresentada, tudo indica que a configuração foi realizada com sucesso!