API documentadaCriterioObligatorio
Tiene documentación pública con finalidad, sintaxis, parámetros, retorno y condiciones de uso. Debe ser la primera opción en personalizaciones.
GOBERNANZA TéCNICAPublicado
Uso de recursos internos en Protheus: riesgos y buenas prácticas
API documentada → contrato público | Recurso interno → sin garantía de compatibilidadOrienta decisiones sobre funciones, clases y variables internas de Protheus sin presentar recursos no documentados como APIs recomendadas.
Descripción general
Esta página no recomienda el uso de recursos internos. Su objetivo es apoyar el análisis de riesgo cuando un identificador aparece en código legado, ejemplos antiguos, fuentes de terceros, includes, rutinas estándar o documentación histórica. No todo recurso técnicamente disponible es una API pública. TOTVS advierte que las funciones, clases y variables internas o no documentadas están fuera del soporte estándar, pueden cambiar de comportamiento y pueden ser bloqueadas o descontinuadas sin aviso. La decisión más segura es preferir APIs documentadas, registrar excepciones y revisar dependencias internas antes de actualizar releases.
Sintaxis
API documentada → contrato público | Recurso interno → sin garantía de compatibilidadParámetros
Recurso internoCriterioObligatorio
Existe para uso del producto, puede depender de contexto implícito y no ofrece contrato público de compatibilidad.
Recurso legadoCriterioOpcional
Puede aparecer en fuentes o materiales antiguos, pero debe confirmarse en la release actual antes de reutilizarlo.
Excepción controladaDecisión técnicaOpcional
Uso temporal documentado, con responsable, motivo, alternativa evaluada, pruebas, riesgo aceptado y plan de sustitución.
Retorno
La página orienta una decisión técnica: usar recurso documentado, sustituir la dependencia interna, aislar una excepción temporal o registrar la necesidad en canales oficiales.
Preferir una alternativa documentada
#Include "TOTVS.ch"
User Function ExDecisionTecnica()
Local cMensaje := "Procesamiento finalizado"
// Prefiere recursos públicos y documentados.
MsgInfo(cMensaje, "Resultado")
ReturnResultado esperado
El ejemplo utiliza una función pública documentada. En una migración real, sustituye la llamada interna por una API oficial equivalente o por una implementación propia probada.
Checklist antes de usar un 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
Si las respuestas no son claras, evita el uso o trátalo como excepción técnica temporal.
Registro mínimo de excepción
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
Documenta recurso usado, motivo, alternativa evaluada, impacto esperado, responsable, versión probada, evidencia de homologación y fecha de revisión.
- Busca el identificador en TDN y en la Central de Atención TOTVS antes de usarlo.
- Confirma que la documentación coincida con la release, el módulo y el contexto de ejecución.
- Trata recursos encontrados solo en código fuente, ejemplos de terceros o material histórico como no soportados hasta que la documentación oficial indique lo contrario.
- Prefiere APIs documentadas, puntos de entrada documentados, clases públicas del Framework o implementación propia.
- Para dependencias ya existentes en producción, registra ubicación, motivo, riesgo y camino de sustitución.
- Incluye esta verificación en revisiones de release, auditorías de personalización, análisis de incidentes y saneamiento técnico.
- Un recurso interno puede funcionar en una release y fallar en otra sin que eso sea una ruptura de contrato público.
- El código estándar del producto puede depender de estado interno, orden de ejecución, variables privadas o contexto inexistente en una personalización.
- Jobs, servicios web, rutinas automáticas e interfaces pueden reaccionar de forma distinta al mismo recurso interno.
- Encapsular una llamada interna limita la dispersión, pero no la convierte en soportada.
- StaticCall() y PTInternal() son ejemplos citados por TOTVS en una alerta de propiedad interna, con restricciones de compilación desde la release 12.1.33.
- Las listas copiadas de materiales antiguos pueden quedar desactualizadas; la fuente oficial y la release homologada siguen siendo la referencia de validación.
Comentarios
Todavía no hay comentarios aprobados.
Inicia sesión con Google o Microsoft para comentar.