Versionado y compatibilidad
La API no lleva versión en la URL
No hay /v1, ni header de versión, ni negociación por Accept. La ruta que integras hoy es la
ruta que seguirá existiendo: POST /rtu/nits es POST /rtu/nits.
La contrapartida es que la compatibilidad se sostiene por política, no por un número que puedas fijar. Esta página es esa política.
Qué se considera un cambio compatible
Estos cambios pueden ocurrir sin aviso previo, y tu cliente debe tolerarlos:
- Añadir un campo a un cuerpo de respuesta.
- Añadir un campo opcional a un cuerpo de petición.
- Añadir un endpoint, un valor nuevo a un enumerado, o una cabecera de respuesta.
- Cambiar el texto de un mensaje de error sin cambiar su status HTTP.
De ahí salen dos reglas para el cliente:
- Ignora los campos que no conoces. No uses parsers que fallen ante propiedades inesperadas.
- Ramifica por el status HTTP, no por el texto del mensaje. Los mensajes están en español y
son para personas; el status es el contrato. Lo mismo vale para el campo
error, que unas rutas envían y otras no — ver el catálogo de errores.
Qué se considera un cambio incompatible
Quitar o renombrar un campo o una ruta, cambiar el tipo de un campo, cambiar el status de una condición existente, o endurecer una validación. Estos cambios se anuncian en Cambios con antelación y aviso directo a las integraciones activas.
Lo que ya está congelado por el dominio
Buena parte de lo que devuelven estas consultas no puede moverse aunque quisiéramos: los códigos de SAT, sus descripciones y el vocabulario del RTU responden a los registros de SAT, no a una decisión de producto. Lo que sí es decisión nuestra es la forma en que se entregan, y eso es lo que fija el contrato de los catálogos.
Cómo se mantiene honesta esta documentación
La especificación OpenAPI de esta API vive en el mismo repositorio que el código que describe, y un comando de paridad compara las rutas declaradas con las rutas realmente registradas. Si alguien añade una ruta y no la documenta, o documenta una que ya no existe, ese comando falla.
Es el mecanismo que impide que este portal termine como la colección de Postman a la que sustituye: diez de sus rutas ya no existían, y nueve rutas del código no estaban en ninguna colección.
📄 Estado de verificación: política de compatibilidad, derivada de la forma actual de la API. No hay nada que ejercer contra el entorno desplegado.