Passar para o conteúdo principal

TOTVS Protheus: Instalação e configuração do Qive Conexões Totvs

Este manual tem como objetivo orientar detalhadamente o processo de instalação e configuração do Qive Conexões para Totvs Protheus.

Escrito por Gilson Medeiros Correa

O Qive Conexões é desenvolvido em linguagem ADVPL e atua como uma ponte inteligente entre o portal Qive e o seu Protheus, permitindo a geração de documentos de entrada conforme as regras de negócio da sua empresa.

1. Aplicação do pacote técnico

O primeiro passo é realizar o download e a aplicação do pacote de atualização. Você pode encontrar o pacote mais recente clicando no botão abaixo:

Pacote de atualização Qive Conexões

A aplicação do pacote pode ser realizada tanto em ambiente de produção quanto de homologação. É fundamental que o repositório esteja em acesso exclusivo durante este processo. Para empresas que utilizam o servidor na nuvem (Tcloud Totvs), a aplicação pode ser feita via portal; para servidores locais, utilize o VS Code (Visual Studio Code).

2. Configurações iniciais e dicionário de dados

Após a aplicação do pacote, acesse o SmartClient do Protheus e execute o compatibilizador U_CXNFACI ou U_IMPXACI em modo exclusivo. Este comando abrirá o Assistente de Configuração.

O assistente guiará você pela configuração das tabelas sem modificar o dicionário de dados padrão do Protheus. Siga as etapas abaixo:

  1. Selecione a empresa e a filial para abertura do ambiente.

  2. Informe o portal da Qive (URL da API) para a captura dos XMLs.

  3. Configure os nomes das tabelas de usuário (SZ? ou Z??) que serão utilizadas pelo importador.

    1. Tabelas Principais:

      1. MV_XGTTAB1: nome da tabela contendo o cabeçalho das informações no XML.

      2. MV_XGTTAB2: nome da tabela contendo os itens do XML.

      3. 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.

      4. 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.

      5. MV_XGTTAB6: nome da tabela que contém a relação produto x fornecedor/cliente.

      6. 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”.

      7. MV_XGTTAB8: nome da tabela que contém a configuração das regras de lançamento automático.

      8. MV_XGTTABA: nome da tabela das notas de origem

      9. MV_XGTTABB: nome da tabela para gravação de logs de ações do usuário

      10. MV_XGTTABC: nome da tabela genérica das variações de pedidos de compra, esta tabela é referente a SX5 do Protheus, utilize 2 caracteres.

  4. 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.

  5. 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:

    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.

  6. 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.

  7. Copie o texto apresentado dos pontos de entrada e cole em um bloco de notas para ser acessado posteriormente.

  8. 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.

  9. 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

Para que o Qive Conexões interaja corretamente com as rotinas padrão do Protheus (como a MATA103), é necessário compilar os pontos de entrada. Se a sua empresa já utiliza algum desses pontos, você deve mesclar o código da Qive com a sua regra atual.

Clique aqui para baixar os pontos de entrada

Importante: A chamada da função da Qive deve ser, preferencialmente, a última instrução em pontos de retorno de valores e a primeira em pontos de validação inicial.

Estruturas para adaptação (Exemplos de código)

User Function A103CND2() Local aDuplic := PARAMIXB If (Regra existente) [...] EndIf aDuplic := U_GTPE001() // Chamada Qive sempre como última instrução. Return aDuplic
User Function MT103FIM() U_GTPE002() // Chamada Qive sempre como primeira instrução. If (Regra existente) [...] EndIf Return Nil
User Function A140EXC() Local lRet := .T. lRet := U_GTPE003() // Chamada Qive sempre como primeira instrução. If (Regra existente) [...] EndIf Return lRet
User Function MT100LOK() Local lRet := .T. lRet := U_GTPE004() // Chamada Qive sempre como primeira instrução. 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. If !FwIsInCallStack('U_GATI001') .Or. IIf(Type('l103Auto') == 'U',.T.,!l103Auto) If (Regra existente) [...] EndIf EndIf If lRet lRet := U_GTPE005() // Chamada Qive sempre como última instrução. EndIf Return lRet
User Function MT103CWH() Local lRet := .T. If (Regra existente) [...] EndIf If lRet lRet := U_GTPE006() // Chamada Qive sempre como última instrução. EndIf Return lRet
User Function MT103IP2() U_GTPE007() // Chamada Qive sempre como primeira instrução. If (Regra existente) [...] EndIf Return Nil
User Function MT116GRV() If (Regra existente) [...] EndIf U_GTPE008() // Chamada Qive sempre como última instrução. Return Nil
User Function MT140CAB() Local lRet := .T. If (Regra existente) [...] EndIf If lRet lRet := U_GTPE009() // Chamada Qive sempre como última instrução. EndIf Return lRet
User Function MTA103MNU() If (Regra existente) [...] EndIf U_GTPE010() // Chamada Qive sempre como última instrução. Return Nil
User Function MT140TOK() Local lRet := .T. lRet := U_GTPE011() // Chamada Qive sempre como primeira instrução. If lRet .And. !FwIsInCallStack('U_GATI001') .Or. !l103Auto If (Regra existente) [...] EndIf EndIf Return lRet
User Function MT140LOK() Local lRet := .T. lRet := U_GTPE012() // Chamada Qive sempre como primeira instrução. If lRet .And. !FwIsInCallStack('U_GATI001') .Or. !l103Auto If (Regra existente) [...] EndIf EndIf Return lRet
User Function MTCOLSE2() Local aSE2 := ParamIXB[1] aSE2 := U_GTPE013() // Chamada Qive sempre como primeira instrução. If (Regra existente) [...] EndIf Return aSE2
User Function MA103BUT() Local aButtons := {} aButtons := U_GTPE014() // Chamada Qive sempre como primeira instrução. If (Regra existente) [...] EndIf Return aButtons
User Function MT140SAI() U_GTPE016() // Chamada Qive sempre como primeira instrução. If (Regra existente) [...] EndIf Return Nil
User Function M145ARDEL() Local lRet := .T. lRet := U_GTPE018() // Chamada Qive sempre como primeira instrução. If (Regra existente) [...] EndIf Return lRet
User Function MT103TPC() Local cTes := PARAMIXB[1] If (Regra existente) [...] EndIf U_GTPE019() // Chamada Qive sempre como última instrução. Return cTes
User Function MT140PC() Local lRet := PARAMIXB[1] If (Regra existente) [...] EndIf U_GTPE019() // Chamada Qive sempre como última instrução. Return lRet
User Function MT103CPS() U_GTPE022() // Chamada Qive sempre como primeira instrução. If (Regra existente) [...] EndIf Return
User Function MT116AGR() If (Regra existente) [...] EndIf U_GTPE021() // Chamada Qive sempre como última instrução. Return Nil
User Function MT100GE2() U_GTPE025() // Chamada Qive sempre como primeira instrução. If (Regra existente) [...] EndIf Return Nil

Nota: Repita o padrão de chamada U_GTPE conforme o manual técnico para os demais pontos: A140EXC, MT103CWH, MT103IP2, MT116GRV, MT140CAB, MTA103MNU, MT140TOK, MT140LOK, MTCOLSE2, MA103BUT, MT140SAI, M145ARDEL, MT103TPC, MT140PC, MT103CPS, MT116AGR e MT100GE2).

Relação de pontos de entrada e funções

  • A103CND2: Captura a condição de pagamento na importação de CT-e por lote.

  • MT103FIM: Atualiza o status da nota no Portal Qive na inclusão ou exclusão via MATA103 ou importador.

  • A140EXC: Apresenta mensagens de usuário durante a execução automática.

  • MT100LOK: Validações de usuário na execução automática.

  • MT100TOK: Valida se os totais do Protheus conferem com o XML e alerta divergências.

  • MT103CHW: Desabilita campos específicos (como fornecedor e emissão) para evitar alterações indevidas.

  • MT116GRV: Grava a chave do XML na importação de CT-e.

  • MT140CAB: Carrega totais de despesas, frete e seguro em pré-notas.

  • MTA103MNU: Adiciona a consulta de Cartas de Correção ao menu lateral.

  • MA103BUT: Cria o botão "Conferir Impostos" no lançamento ou classificação.

  • MT140SAI: Atualiza o status da pré-nota no Portal (inclusão/exclusão).

  • MT103CPS: Preenche a Natureza financeira vindo do Monitor Qive.

  • MT100GE2: Complementa a gravação de títulos no financeiro.

Pontos de entrada adicionais (Casos específicos)

  • MA103ATF: Utilizado na importação de pré-nota de Ativo Imobilizado para preencher Centro de Custo e Conta Contábil.

  • MT103BDP: Utilizado para manter o valor do frete conforme informado na pré-nota ao classificar com pedido de compra.

4. Criação da rotina no menu

Para que os usuários consigam acessar o painel de documentos, é necessário criar a chamada da rotina manualmente no configurador do Protheus. Utilize as seguintes características técnicas:

  • Descrição: Importador XML Qive (ou nome de sua preferência)

  • Programa: U_GATI001

  • Módulo: Compras (ou módulo de sua preferência)

  • Tipo: Função Protheus

Passo a passo para criação:

  1. Acesse o módulo Configurador (SIGACFG) do Protheus.

  2. No menu lateral, navegue até Ambiente > Cadastros > Menus.

  3. Na tela de Menus, selecione apenas o menu que deseja disponibilizar a rotina (recomendamos o menu de Compras) e clique em Ok para abrir a manutenção.

  4. Na tela de manutenção, clique no botão Adicionar >> para carregar as opções do menu da esquerda para a direita.

  5. Navegue pela árvore de menus no lado direito até a repartição Atualizações > Movimentos.

  6. Com a pasta "Movimentos" selecionada, clique no botão Novo Item.

  7. Preencha os campos com as características informadas no início desta seção (Descrição, Programa, Módulo e Tipo) e clique em Salvar.

  8. Ao finalizar, clique no botão Gerar para atualizar o menu existente no sistema.

  9. Na tela de geração, informe o nome SIGACOM (ou o nome correspondente ao módulo escolhido), sem a extensão .xnu, e confirme.

A partir deste momento, a rotina estará disponível para uso no módulo 02 - Compras. Caso sua empresa utilize menus personalizados por usuário, lembre-se de realizar este processo em cada menu correspondente.


​

5. Autenticação e SSL

Ao acessar a rotina pela primeira vez, o sistema solicitará o ID e a KEY da API Qive. Esses dados são encontrados nas configurações de integração do seu portal Qive.

Atenção: Caso receba uma mensagem de "Acesso Negado", verifique se o seu Application Server está configurado para suportar conexões SSL. Certifique-se também de que o domínio da API Qive não esteja bloqueado pelo seu Firewall/Proxy.

6. Configuração dos jobs de leitura (Automação)

Nesta etapa, configuramos os Jobs responsáveis pela identificação de novos XMLs recebidos e pela gravação automática no banco de dados do Protheus. Existem duas formas de realizar essa configuração: via OnStart (serviço dedicado) ou via Schedule.

Opção 1: Configuração via ONSTART

Este método cria um serviço específico no servidor para processar os arquivos continuamente.

  1. Preparação de pastas: Copie a pasta do seu appserver e renomeie para appserver_Qive. Faça o mesmo com a pasta do repositório (RPO), renomeando para apo_qive.

  2. Edição do appserver.ini: Na pasta appserver_qive, abra o arquivo appserver.ini e realize os seguintes ajustes:

    1. Repositório: Aponte o caminho para a nova pasta apo_qive.

    2. Porta: Altere para um número de porta disponível (ex: 1234).

    3. Nome do Serviço: Renomeie o serviço para algo identificável, como Totvs_Qive.

  3. Inclusão da Seção OnStart: Copie e cole o trecho abaixo ao final do seu arquivo appserver.ini:

    1. [OnStart] jobs=CXNFARQ,CXNFEMP RefreshRate=120

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

    3. [CXNFEMP] Main=U_CXNFEMP Environment=qive NPARMS=2 PARM1=99 PARM2=01

      Nota: Substitua '99' pelo código da sua empresa e '01' pela filial correspondente

  4. Teste e instalação:

    1. Crie um atalho do appserver.exe, adicione o comando -console nas propriedades e execute para verificar se há erros de porta.

    2. Se funcionar, altere o comando para -install e execute como administrador para criar o serviço no Windows.

  5. Verificação de logs: Após iniciar o serviço, verifique se a pasta protheus_data/importador_xml/logs/cxnfarq foi criada com os arquivos de log de leitura.

Opção 2: Configuração via SCHEDULE

Ideal para ambientes hospedados na nuvem (TCloud) ou onde já existe uma estrutura de agendamentos.

  1. Acesso: No SIGACFG, acesse Ambiente > Schedule > Schedule.

  2. Agentes: Verifique se o Smart Scheduler está ativo. Caso não existam agentes, clique em Outras Ações > Adicionar agentes padrão e inicie-os. [INSERIR PRINT DO SMART SCHEDULER ATIVO]

  3. Agendamentos: Você deve criar dois novos agendamentos:

    1. Serviço 1 (Leitura): Função U_CXNFSCH(1,'99','01').

    2. Serviço 2 (Gerenciamento): Função U_CXNFSCH(2,'99','01').

  4. Configurações de Recorrência:

    1. Periodicidade: Diária.

    2. Frequência: Sim.

    3. Intervalo: 5 minutos.

    4. Horário: Das 00:00 às 23:59.

  5. Parâmetros Finais: Informe a Empresa e apenas a primeira Filial (o sistema tratará as demais automaticamente). Selecione o módulo 02-Compras e o usuário admin.

  6. Confirmação: Clique em Concluir e verifique no Monitor do Schedule se o status está como "Finalizado" ou "Aguardando Execução".

7. Personalização de Logomarca

Para facilitar a identificação visual, você pode inserir a logo da sua empresa no painel da Qive.

  • Salve o arquivo em formato PNG na pasta protheus_data/system.

  • Nomeie o arquivo como importador_sua_logo.png.

  • Para logos por empresa específica, use o sufixo do código da empresa: importador_sua_logo01.png.

8. Teste de funcionamento (Primeiros passos)

Com tudo configurado, realize um teste funcional:

  1. Acesse o Importador XML Qive no menu de Compras.

  2. Localize uma nota com legenda verde (pendente).

  3. Clique em Importar.

  4. Preencha campos básicos de teste (Natureza, Condição de Pagamento, Produto e TES).

  5. Se o sistema abrir a tela padrão do Documento de Entrada (MATA103) preenchida com os dados do XML, sua instalação foi concluída com sucesso.

Em caso de dúvidas técnicas durante a compilação, entre em contato com nosso time através do e-mail suporte@qive.com.br.


​

Artigos relacionados
Respondeu à sua pergunta?