Este manual tem como objetivo orientar passo a passo o processo de instalação do Importador Qive Conexão Totvs Protheus, abrangendo desde os pré-requisitos até a finalização da instalação e a verificação de funcionamento.
O Importador XML Qive é uma solução desenvolvida na linguagem ADVPL, que permite integrar os xmls via API do portal da Qive com o Protheus, gerando documentos como 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.
O pacote pode ser aplicado pelo aplicativo VsCode - Visual Studio Code ou pelo portal Tcloud Totvs se a empresa utilizar o servidor na nuvem da Totvs.
2. Configurações
Após aplicar o pacote no SmartClient do Protheus execute o compatibilizador U_CXNFACI ou U_IMPXACI em modo exclusivo, em seguida será apresentado o Assistente de Configuração do Importador Qive.
Será apresentado o assistente de configuração do Importador XML Qive, essa rotina não modifica o dicionário de dados padrão, basta clicar em Avançar.
Selecione a empresa para abertura do ambiente e clique em Avançar.
Nessa etapa informe o portal da Qive para captura dos xmls.
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.
MV_XGTTABA: nome da tabela das notas de origem
MV_XGTTABB: nome da tabela para gravação de logs de ações do usuário
MV_XGTTABC: nome da tabela genérica das variações de pedidos de compra, esta tabela é referente a SX5 do Protheus, utilize 2 caracteres.
O botão Tabelas Em Uso serve para apresentar as tabelas 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. O 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.
4. O botão Pontos de Entrada serve para verificar os pontos de entrada em uso, onde posteriormente devem ser adaptados. O programa analisa o RPO e indica os pontos de entrada que já estão em uso pela empresa, mostrando como deve ser a estrutura do código.
Copie o texto apresentado dos pontos de entrada 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
USER FUNCTION MT103CPS()
// Ponto de chamada Qive sempre como primeira instrução.
U_GTPE022()
//If
// Regra existente
// [...] //
EndIf
Return
User Function MT116AGR()
If Regra existente
[...]
EndIf
// Ponto de chamada Qive sempre como última instrução.
U_GTPE021()
Return Nil
User Function MT100GE2()
// Ponto de chamada Qive sempre como primeira instrução
U_GTPE025()
//IF
//Regra existente
//[...]
//ENDIF
Return Nil
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). |
MT103CPS | Utilizado para preencher a Natureza vindo da tela inicial do Monitor. |
MT116AGR | Utilizado para abertura de tela de manipulação de informações quando o complemento de CTE é feito via MATA116. |
MT100GE2 | Utilizado para complementar a gravação de títulos no financeiro. |
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. |
4. Criação da rotina no menu
Crie a chamada da rotina no menu com as seguintes características:
Descrição: Importador XML Qive (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.
Acessar a rotina de 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 Qive 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 (Onstart ou Schedule) e siga conforme abaixo:
ONSTART
Copie uma pasta appserver e renomeie para appserver_Qive:
Copie também o repositório (RPO), o qual foi aplicado o pacote do importador nos passos anteriores, e renomeie para apo_qive:
Retorne a pasta appserver_qive 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 nome do serviço para ser instalado corretamente:
Adicione a seção [OnStart] conforme abaixo:
Abaixo o trecho da seção [OnStart] que pode ser copiado e colado no appserver.
[OnStart]
jobs=CXNFARQ,CXNFEMP
RefreshRate=120
[CXNFARQ]
Main=U_CXNFARQ
Environment=qive
NPARMS=2
PARM1=99
PARM2=01
[CXNFEMP]
Main=U_CXNFEMP
Environment=qive
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.
Se o servidor da empresa for local, após a execução do serviço, verifique se foi criado dentro da pasta protheus_data a pasta importador_xml/logs.
Caminho da pasta: >protheus_data>importador_xml>logs>cxnfarq
Verifique dentro da pasta cxnfarq se gerou um arquivo de log conforme abaixo:
Abra o arquivo cxnfarq e verifique se iniciou a leitura do endereço da api e a leitura dos arquivos dos xmls.
Se o servidor da empresa estiver hospedado no Tcloud da Totvs, os arquivos da pasta Protheus_Data, podem ser acessados pelo aplicativo filezilla ou pelo WinSCP, precisa ter um desses aplicativos instalado e configurado com as credenciais de acesso da Totvs para acessar a pasta >importador_xml>logs>cxnfarq
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:
Verifique se o Smart Scheduler está em execução.
Caso não tenha o agentes criado, na opção Agentes clicar em Outras Ações->Adicionar agentes padrão.
Agente adicionado.
Clicar nos 03 pontinhos e Iniciar agente
Agente padrão iniciado
Na opção Agendamentos, clicar em Novo para criar os serviços do Importador.
Serão criados 02 serviços conforme exemplo abaixo:
U_CXNFSCH(1,'99','01') - Serviço de Leitura dos XMLs Importação
U_CXNFSCH(2,'99','01') - Serviço de gerenciamento dos XMLs para validação/Importação Automática
Informe a função U_CXNFSCH(1,'99','01') e clique em avançar.
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.
Configure as opções abaixo e clique em Avançar.
Periocidade: Diária
Frequência=Sim
Minutos=5
Horário Inicial=00:00
Horário Final=23:59
Informe a empresa, no parâmetro da Filial informe apenas a primeira empresa e a primeira filial, pois as demais serão tratadas automaticamente na função U_CXNFSCH.
No parâmetro Módulo, informe o módulo 02-Compras e no campo Usuário, informe o usuário administrador
Informe a Descrição: Serviço de Leitura dos XMLs Importação
Clique em Concluir.
Clique em Confirmar.
Função U_CXNFSCH(1,'99','01') cadastrada.
Cadastre a segunda função U_CXNFSCH(2,'99','01') Serviço de gerenciamento dos XMLs para validação/Importação Automática
Informe as mesmas periocidades e frequência da função U_CXNFSCH(1,'99','01'), se preferir pode deixar uma periciocidade maior do que 5 minutos para o serviço U_CXNFSCH(2,'99','01').
Informe os parâmetros, lembrando que deve ser informado apenas a primeira empresa e a primeira filial.
Informe a descrição: Serviço de gerenciamento dos XMLs para validação/Importação Automática
Função U_CXNFSCH(1,'99','01') e U_CXNFSCH(2,'99','01') cadastrada.
No Monitor verifique se status dos serviços foram finalizados.
7. Definir a logomarca da empresa no Importador Qive.
Para definir a imagem da logomarca que aparecerá na tela inicial do programa do Importador Qive, acesse a pasta protheus_data/system, substitua o arquivo de nome “importador_sua_logo.png” que encontra-se na pasta \system\ pela logo da empresa.
Para definir uma imagem por grupo de empresa, basta adicionar o código da empresa 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 a tela do Documento de Entrada seja apresentada, tudo indica que a configuração foi realizada com sucesso!