Estandar de APIs externas

Requisitos obligatorios

1. Namespace con version mayor, por ejemplo /api/external/v1.
2. Autenticacion de service principal con scopes minimos.
3. Tenant derivado del token, nunca de headers arbitrarios.
4. DTO cerrados, validacion estricta y respuestas tipadas.
5. Idempotency-Key en todas las mutaciones repetibles.
6. X-Correlation-Id en solicitudes y respuestas.
7. Problem Details con codigos de error estables.
8. Paginacion acotada para colecciones.
9. OpenAPI versionado y verificado contra breaking changes.
10. Guia Docusaurus, ejemplos sinteticos y changelog en el mismo cambio.

Compatibilidad

Los cambios aditivos permanecen en la version actual. Un cambio que elimina, renombra, restringe o altera semantica observable requiere una nueva version mayor o un periodo formal de deprecacion.

Datos protegidos

La documentacion y los ejemplos nunca deben contener pacientes reales, documentos clinicos, credenciales, URLs internas, claves de idempotencia productivas ni identificadores que permitan reconstruir PII.