Pontos de entrada no Protheus: como encontrar, usar e documentar

Contexto: Conceitos válidos para as releases atuais do Protheus. Nomes, parâmetros e retornos de cada ponto de entrada variam por rotina e release — confira sempre a documentação oficial no TDN.

Customizar um ERP sem alterar o código-fonte padrão é o que permite atualizar o sistema sem reescrever tudo a cada release. No Protheus, a principal ferramenta para isso é o ponto de entrada: um local previsto nas rotinas padrão onde o sistema verifica se existe uma função customizada e, se existir, a executa.

Bem usados, pontos de entrada resolvem a maioria das necessidades de adaptação. Mal usados, viram uma camada invisível de regras que ninguém sabe explicar — e que quebra justamente no dia da atualização. Este artigo mostra como trabalhar com eles de forma organizada.

Como um ponto de entrada funciona

Em determinados momentos de uma rotina padrão — antes de gravar, ao validar um campo, ao montar uma tela, depois de concluir um processo — o código padrão verifica se existe uma User Function compilada com um nome específico. Se existir, ela é executada.

O mecanismo, simplificado, é este:

// Trecho ilustrativo do que a rotina padrão faz internamente
If ExistBlock("NOMEDOPE")
    xRetorno := ExecBlock("NOMEDOPE", .F., .F., aParametros)
EndIf

Três consequências práticas:

• O nome é fixo. A função precisa ter exatamente o nome que a rotina espera.
• Os parâmetros são definidos pela rotina. Quando existem, chegam ao ponto de entrada pela variável PARAMIXB.
• O retorno tem um contrato. Alguns pontos de entrada esperam um valor lógico (permitir ou bloquear), outros um array, outros nenhum retorno. Devolver o tipo errado causa erro ou comportamento inesperado.

Como encontrar o ponto de entrada certo

Antes de escrever uma linha de código, é preciso descobrir onde a regra deve ser aplicada.

1. Identifique a rotina e o momento exato. “Validar o documento de entrada antes de gravar” é muito mais útil do que “mexer na nota de entrada”. O nome da rotina aparece no menu e na barra de status do sistema.
2. Pesquise no TDN (TOTVS Developer Network). A documentação oficial lista os pontos de entrada de cada rotina, com descrição, momento da chamada, parâmetros e retorno esperado. Buscar por “ponto de entrada” junto com o nome ou código da rotina costuma levar direto à página certa.
3. Leia a página inteira. Confira em que momento o ponto é chamado, o que vem em PARAMIXB, qual retorno é esperado e se há observações sobre releases.
4. Confirme no ambiente de testes. Um ponto de entrada mínimo, que apenas registra uma mensagem no log, confirma que ele é chamado no momento que você imagina.

Se nenhum ponto de entrada atende ao momento exato, desconfie da solução antes de partir para alternativas mais invasivas. Muitas vezes a necessidade pode ser atendida por parâmetros, gatilhos, validações de campo ou por um processo complementar, sem alterar o comportamento padrão.

Um exemplo comentado

O ponto de entrada MT100TOK é chamado na validação da inclusão do documento de entrada e espera um retorno lógico: verdadeiro permite seguir, falso impede a gravação. Uma implementação organizada fica assim:

#Include "Protheus.ch"

/*/{Protheus.doc} MT100TOK
Valida o documento de entrada antes da gravação.
Regra: descrita no chamado/requisito de origem.
@type    User Function
@author  Alan Cardoso
@since   10/2026
@return  logical, .T. permite a gravação; .F. bloqueia
@see     https://tdn.totvs.com/x/GNtc
/*/
User Function MT100TOK()
    Local aArea := GetArea()
    Local lRet  := .T.

    // A regra fica em uma função própria: mais fácil de testar e reaproveitar
    lRet := U_QVNFEntr()

    RestArea(aArea)
Return lRet

Repare em três cuidados:

• A regra de negócio não fica dentro do ponto de entrada. Ele apenas chama uma função própria. Isso facilita testes, reaproveitamento e manutenção — e evita que um único arquivo concentre regras de várias áreas.
• A área de trabalho é salva e restaurada com GetArea e RestArea, para não alterar o posicionamento de tabelas que a rotina padrão continua usando depois.
• O cabeçalho documenta o propósito, o autor, a data, o retorno e o link para a documentação oficial.

Quando o ponto de entrada recebe parâmetros, copie PARAMIXB para variáveis locais com nomes claros logo no início, conforme a ordem descrita na documentação. Isso evita confusão e facilita a leitura.

Boas práticas de implementação

• Um ponto de entrada, um arquivo. Facilita localizar, versionar e revisar.
• Mantenha o ponto de entrada enxuto. Ele é chamado dentro do fluxo padrão; processamento pesado ali deixa a rotina inteira lenta.
• Evite interação com o usuário quando possível. Mensagens e telas dentro de pontos de entrada podem travar processamentos automáticos, rotinas executadas por job e integrações.
• Considere a execução automática. Muitas rotinas também são chamadas por integrações e processos sem tela. Teste o ponto de entrada nesses cenários.
• Trate o retorno com rigor. Sempre devolva o tipo esperado, inclusive nos caminhos de erro.
• Não dependa de variáveis privadas sem necessidade. Elas podem mudar entre releases. Prefira o que a documentação garante.

Documente para a próxima atualização

O maior risco dos pontos de entrada não aparece no dia em que são criados, e sim meses depois, na atualização de release. Para reduzir esse risco, mantenha um inventário de customizações com, no mínimo:

Com esse inventário, a homologação de uma nova release deixa de ser uma caça ao tesouro: basta percorrer a lista, verificar se cada ponto de entrada ainda existe com os mesmos parâmetros e executar o teste previsto.

Checklist rápido

• Momento exato da regra identificado na rotina
• Ponto de entrada confirmado na documentação oficial
• Parâmetros e retorno esperados conferidos
• Regra de negócio isolada em função própria
• Área de trabalho preservada
• Testado com e sem interface (job, integração)
• Cabeçalho de documentação preenchido
• Registrado no inventário de customizações

Ponto de entrada é a forma mais segura de adaptar o Protheus — desde que seja tratado como parte do produto, com critério, documentação e testes. É essa disciplina que transforma customização em vantagem, e não em dívida técnica.