Recurso documentadoCritérioObrigatório
Possui página oficial que descreve finalidade, sintaxe, parâmetros, retorno e condições de uso. É a primeira opção para customizações.
BOAS PRÁTICASPublicado
Recursos internos e não documentados no Protheus
API documentada → contrato público; recurso interno → implementação sem garantia de compatibilidadeEntenda por que funções, classes e variáveis internas do Protheus não devem fundamentar customizações e como substituir essas dependências.
Visão geral
Nem todo identificador encontrado em fontes, exemplos antigos ou no repositório do produto representa uma API pública. Segundo a TOTVS, funções, classes e variáveis restritas ou não documentadas não fazem parte do suporte padrão, podem mudar de comportamento ou ser descontinuadas sem aviso. A decisão segura é confirmar a documentação oficial antes de incorporar o recurso e, quando ele for interno, substituí-lo por uma API documentada ou por uma implementação própria.
Sintaxe
API documentada → contrato público; recurso interno → implementação sem garantia de compatibilidadeParâmetros
Recurso interno ou restritoCritérioObrigatório
Foi criado para uso do produto, pode ter escopo ou premissas implícitas e não oferece contrato público de compatibilidade.
Recurso apenas encontrado no fonteCritérioObrigatório
A existência técnica do identificador não comprova que ele seja público, suportado ou estável. Confirme-o na documentação oficial.
Retorno
A classificação orienta a decisão arquitetural: usar a API pública, substituir a dependência interna ou registrar a necessidade nos canais oficiais da TOTVS.
Preferir uma alternativa documentada
#Include "TOTVS.ch"
User Function ExRecursoDocumentado()
Local cMensagem := "Processamento concluído"
// Prefira uma função pública e documentada para a necessidade.
MsgInfo(cMensagem, "Resultado")
ReturnResultado esperado
O exemplo usa uma função pública documentada. Em uma migração real, substitua a chamada interna pela API oficial que atenda ao mesmo requisito e teste o comportamento na release homologada.
Roteiro de saneamento de uma dependência interna
Resultado esperado
1. Localize todas as chamadas. 2. Registre entradas, saídas e contexto. 3. Consulte a documentação oficial. 4. Escolha API pública ou implementação própria. 5. Crie testes de regressão. 6. Remova a dependência e valide na release de destino.
- Pesquise o identificador no TDN e na Central de Atendimento antes de utilizá-lo.
- Confirme se a documentação corresponde à release e ao ambiente usados pela customização.
- Encapsule integrações públicas em funções próprias quando isso facilitar testes e futuras substituições.
- Ao encontrar uma dependência interna existente, registre onde ela é usada, qual necessidade atende e qual alternativa será adotada.
- Se não houver API pública equivalente, desenvolva uma rotina própria ou registre a necessidade na Central Colaborativa para análise da TOTVS.
- Inclua a verificação de recursos internos no checklist de atualização de release.
- StaticCall() e PTInternal() são citados pela TOTVS como recursos internos com compilação bloqueada a partir da release 12.1.33.
- Outros recursos da relação oficial podem ainda compilar, mas permanecem sem suporte e podem mudar ou desaparecer.
- Código encontrado no fonte padrão pode depender de estado, escopo, ordem de execução ou contexto que não existe em uma customização.
- Jobs, serviços web e rotinas sem interface podem expor inconsistências quando o recurso interno foi concebido para outro contexto.
- Criar um wrapper em torno de um recurso interno reduz o espalhamento da dependência, mas não transforma o recurso em API suportada.
- Copiar uma lista estática sem consultar a fonte oficial pode ocultar inclusões, remoções ou mudanças posteriores.