Ponto de entrada no Protheus: o que é e como usar sem quebrar o sistema

Ponto de entrada é a forma prevista pela TOTVS para mudar o comportamento do Protheus sem alterar o código padrão. Em momentos definidos de uma rotina, o sistema verifica se existe uma função com um nome combinado e, se existir, executa essa função.

É por meio deles que a empresa bloqueia uma nota com dado faltando, grava um campo extra no pedido ou dispara uma integração depois de um lançamento. Também é por meio deles que muita customização esquecida passa a travar o faturamento sem ninguém saber o motivo.

Como o Protheus chama um ponto de entrada

Dentro da rotina padrão, a chamada segue um padrão parecido com este:

If ExistBlock("NOMEDOPE")
    lRet := ExecBlock("NOMEDOPE", .F., .F., aParametros)
EndIf

• ExistBlock verifica se a função de usuário com aquele nome está compilada no repositório (RPO).
• ExecBlock executa a função e devolve o retorno para a rotina padrão.
• Os parâmetros chegam na sua função pela variável PARAMIXB, normalmente um array lido por posição.

O nome, o momento da chamada, os parâmetros e o tipo de retorno são definidos pela TOTVS e ficam na documentação de cada ponto de entrada no TDN. Não existe regra geral: cada um tem o seu contrato.

Exemplo: validar a inclusão da nota de entrada

O MT100TOK é chamado na validação da inclusão do documento de entrada (rotina MATA103). Se a função devolver .F., a nota não é gravada.

#Include "Protheus.ch"

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

    // Regra ilustrativa: troque pela validação da sua empresa
    If !U_NotaValida()
        Help( , , "MT100TOK", , "A nota não atende à regra de entrada definida pela empresa.", 1, 0)
        lRet := .F.
    EndIf

Return lRet

Dois detalhes deste exemplo valem para qualquer ponto de entrada:

• A regra fica em uma função separada (U_NotaValida, aqui ilustrativa). O ponto de entrada só decide se chama a regra, o que facilita testar e reaproveitar.
• A mensagem usa Help, e não uma janela de confirmação. A mesma rotina pode rodar sem tela, por execução automática (ExecAuto) ou por uma integração. Uma mensagem que espera clique trava esse processamento.

Outros exemplos comuns

Alguns pontos de entrada aparecem em quase todo ambiente:

• MT100GE2: complementa a gravação dos títulos a pagar gerados pelo documento de entrada.
• MTA410I: executado durante a gravação do pedido de venda, depois de atualizar cada item.

Repare no segundo: ele roda uma vez por item. Uma consulta pesada dentro dele, em um pedido com 300 itens, vira 300 consultas. É um dos motivos mais comuns de lentidão na gravação de pedidos.

E nas rotinas em MVC?

Rotinas construídas em MVC funcionam de outro jeito. Em vez de vários pontos de entrada com nomes diferentes, existe um ponto de entrada com o nome do ID do modelo. Ele é chamado em vários momentos, e o momento atual chega em PARAMIXB, com identificadores como MODELPOS (validação do modelo) ou FORMLINEPOS (validação de linha).

Na prática, a função precisa testar qual é o momento antes de agir. Esquecer esse teste faz a regra rodar em momentos que ninguém previu.

Cuidados que evitam problema em produção

Só existe uma função com cada nome. Se dois fornecedores ou duas áreas precisam do mesmo ponto de entrada, o código tem que ser unificado em um fonte só. Dois fontes com a mesma função de usuário geram conflito na compilação, e o que fica no RPO pode não ser o que você espera.

Mantenha uma lista dos pontos de entrada ativos. Para cada um: o que faz, quem pediu e qual processo afeta. Sem essa lista, ninguém consegue avaliar o impacto de uma atualização.

Confira o contrato a cada atualização. Parâmetros e momentos de chamada podem mudar entre releases. Antes de atualizar o ambiente, revise no TDN os pontos de entrada que você usa e teste em homologação.

Não faça tudo no ponto de entrada. Integrações demoradas, envio de e-mail e chamadas externas deixam a gravação lenta e podem falhar no meio da transação. Quando possível, registre o que precisa ser feito e processe depois, fora da tela do usuário.

Pense na Reforma Tributária. Pontos de entrada que mexem em impostos, títulos ou documentos fiscais estão entre os primeiros a revisar. Veja o que revisar no Protheus para IBS e CBS.

Quando o problema é herdado

Se o Protheus da sua empresa tem dezenas de pontos de entrada sem documentação, o primeiro passo não é escrever mais um. É levantar o que existe, entender o que cada um faz e decidir o que manter. Esse inventário é parte da nossa consultoria Protheus, e o desenvolvimento de novos pontos de entrada está em desenvolvimento ADVPL e TLPP.

Este texto foi escrito em novembro de 2026. A referência final para cada ponto de entrada é sempre a documentação da TOTVS no TDN.