API documentadaCritérioObrigatório
Possui documentação pública com finalidade, sintaxe, parâmetros, retorno e condições de uso. Deve ser a primeira escolha em customizações.
GOVERNANçA TéCNICAPublicado
Uso de recursos internos no Protheus: riscos e boas práticas
API documentada → contrato público | Recurso interno → sem garantia de compatibilidadeOriente decisões sobre funções, classes e variáveis internas do Protheus sem transformar recursos não documentados em recomendação de uso.
Visão geral
Esta página não recomenda o uso de recursos internos. Seu objetivo é ajudar a analisar riscos quando um identificador aparece em código legado, exemplos antigos, fontes de terceiros, includes, rotinas padrão ou documentação histórica. Nem todo recurso tecnicamente existente representa uma API pública. A TOTVS alerta que funções, classes e variáveis internas ou não documentadas não fazem parte do suporte padrão, podem mudar de comportamento e podem ser bloqueadas ou descontinuadas sem aviso. A decisão mais segura é preferir APIs documentadas, registrar exceções e revisar dependências internas antes de atualizações de release.
Sintaxe
API documentada → contrato público | Recurso interno → sem garantia de compatibilidadeParâmetros
Recurso internoCritérioObrigatório
Existe para uso do próprio produto, pode depender de contexto implícito e não oferece contrato público de compatibilidade.
Recurso legadoCritérioOpcional
Pode aparecer em fontes ou materiais antigos, mas precisa ser confirmado no release atual antes de qualquer reaproveitamento.
Exceção controladaDecisão técnicaOpcional
Uso temporário e documentado, com responsável, motivo, alternativa avaliada, testes, risco aceito e plano de substituição.
Retorno
A página orienta uma decisão técnica: usar recurso documentado, substituir a dependência interna, isolar uma exceção temporária ou registrar a necessidade em canais oficiais.
Preferir uma alternativa documentada
#Include "TOTVS.ch"
User Function ExDecisaoTecnica()
Local cMensagem := "Processamento concluído"
// Prefira recursos públicos e documentados.
MsgInfo(cMensagem, "Resultado")
ReturnResultado esperado
O exemplo usa uma função pública documentada. Em uma migração real, substitua a chamada interna por uma API oficial equivalente ou por uma implementação própria testada.
Checklist para decidir sobre um recurso interno
// Antes de usar:
// 1. Existe documentação oficial?
// 2. A documentação vale para a release usada?
// 3. Há API pública equivalente?
// 4. A rotina roda em interface, job ou serviço?
// 5. O risco foi registrado?
// 6. Existe teste de regressão?
// 7. Há plano de substituição?Resultado esperado
Se as respostas não forem claras, o uso deve ser evitado ou tratado como exceção técnica temporária.
Registro mínimo de exceção
Recurso: <identificador>
Motivo: <necessidade atendida>
Alternativa avaliada: <API pública ou implementação própria>
Release testada: <versão>
Responsável: <nome/área>
Evidência: <teste, chamado, homologação>
Revisar em: <data>Resultado esperado
O registro deixa claro que se trata de exceção consciente, não de recomendação geral para novos desenvolvimentos.
- Pesquise o identificador no TDN e na Central de Atendimento antes de usá-lo.
- Confirme se a documentação encontrada corresponde à release, ao módulo e ao contexto de execução usados pela customização.
- Quando um recurso aparecer apenas em código-fonte, exemplo de terceiros ou material histórico, trate-o como não suportado até prova em documentação oficial.
- Prefira APIs documentadas, pontos de entrada documentados, classes públicas do Framework ou implementação própria.
- Se a dependência interna já existe em produção, registre onde ela aparece, por que foi usada, qual risco oferece e qual será o caminho de substituição.
- Inclua essa verificação em revisões de release, auditorias de customizações, análise de incidentes e saneamento técnico.
- Um recurso interno pode funcionar em uma release e falhar em outra sem que isso seja tratado como quebra de contrato público.
- Código padrão do produto pode depender de estado interno, ordem de execução, variáveis privadas ou contexto que uma customização não possui.
- Jobs, web services, rotinas automáticas e interfaces podem reagir de forma diferente ao mesmo recurso interno.
- Encapsular uma chamada interna reduz espalhamento, mas não transforma o recurso em API suportada.
- StaticCall() e PTInternal() são exemplos citados pela TOTVS em alerta de propriedade interna, com restrições de compilação a partir da release 12.1.33.
- Listas copiadas de materiais antigos podem envelhecer; a fonte oficial e o release homologado continuam sendo a referência de validação.
Comentários
Ainda não há comentários aprovados.
Entre com Google ou Microsoft para comentar.