Compatibilidad
Compatibilidad
Qué podemos cambiar en v1 sin aviso y qué exigiría una nueva versión mayor. Se enuncia como lista enumerada y no como promesa, para que una integración pueda blindarse exactamente contra el conjunto correcto.
Las rutas, los métodos, los ámbitos, los nombres de campo, los códigos de error y los nombres de las reglas de validación se publican en inglés, porque el inglés es el idioma de la propia interfaz: es lo que quien llama escribe o compara. Lo mismo ocurre con cada ejemplo de código, cada carga JSON y la frase exacta que lleva una respuesta de error: /v1 no lee Accept-Language, y traducir lo que la API envía realmente sería describirla mal. Todo lo que se escribe sobre ello sigue el idioma de esta página.
La revisión actual es 2026-08-01. La ruta sigue siendo /v1; la revisión identifica el documento que la describe.
Cambios que no haremos en v1
Estos exigen una nueva versión mayor. Si alguna vez necesitáramos una, las versiones existentes seguirían respondiendo durante la migración.
- Eliminar una operación.
- Eliminar o renombrar un parámetro, o un campo de una respuesta.
- Añadir un parámetro obligatorio nuevo.
- Convertir en obligatorio un parámetro que antes era opcional.
- Cambiar el tipo de un parámetro o de un campo de respuesta.
- Eliminar un valor de una enumeración.Un cliente que ramifica según ese valor no tiene ninguna rama para su ausencia, así que falla del modo en que su lenguaje falle ante un caso no contemplado.
- Añadir una regla de validación nueva a un parámetro existente.Una solicitud que ayer funcionaba empezaría a fallar, y eso es una retirada de capacidad disfrazada de corrección de errores.
- Cambiar los requisitos de autenticación o de autorización, incluido el ámbito que exige una operación.
Cambios que podemos hacer en cualquier momento
Su integración debe tolerarlos todos. Van a ocurrir, y no se anunciarán.
- Añadir una operación nueva.
- Añadir un parámetro opcional nuevo.
- Añadir una cabecera de solicitud opcional nueva.
- Añadir un campo nuevo a una respuesta.Interprete las respuestas con tolerancia: un cliente que rechace campos desconocidos se romperá con la primera adición que hagamos.
- Añadir una cabecera de respuesta nueva.
- Añadir un valor a una enumeración.Trate un valor no reconocido como un caso por defecto y no como un error. Aparecerán categorías de pasaporte nuevas y tipos de evento nuevos.
- Subdividir un código de error en otros más precisos, pero solo cuando el original no podía resolverse con lógica en tiempo de ejecución, como un reintento.Dividir un código por el que un cliente RAMIFICA es un cambio incompatible; dividir uno que solo se registra en el log, no. La distinción está en si el comportamiento dependía de él.
- Hacer obligatorio un campo a partir de una fecha que el esquema anuncia en `required_from`.Publicamos esa fecha lo antes posible, normalmente con al menos 60 días de antelación; cuando un reglamento fija o cambia una fecha con menos antelación, el campo sigue al reglamento.
Lo que su cliente debe tolerar
Cada uno de estos puntos corresponde a un cambio de los de arriba que nos reservamos el derecho de hacer. Un cliente que incumpla alguno se romperá con algo que nosotros consideramos rutina.
- Ignore los campos de respuesta que no reconozca, en lugar de rechazar la respuesta.
- Trate un valor de enumeración no reconocido como un caso por defecto, no como un error.
- Trate los identificadores como cadenas opacas; nunca los interprete ni los compare con un patrón.
- No dependa del ORDEN de los campos dentro de un objeto JSON ni de la redacción exacta de un mensaje de error legible por personas. Ramifique por el código de error legible por máquina.
- Reintente ante un 429 y ante cualquier otro rechazo que lleve una cabecera Retry-After, esperando el tiempo que indique. No es una cabecera exclusiva del 429: un 409 resource_busy, un 503 storage_unavailable y un 503 entitlement_unavailable también la llevan, porque en ellos reintentar es la solución.
- Reintente un 5xx con una Idempotency-Key NUEVA. Una clave que registró un error del servidor reproduce ese error durante toda la ventana de retención, y lo hace a propósito: el fallo pudo ser una respuesta perdida de una escritura que SÍ funcionó, y reutilizar la clave es lo que impide que una escritura fallida acabe siendo dos.
- Reintente una escritura condicional rechazada con una Idempotency-Key NUEVA. Un precondition_failed queda registrado con la clave que lo recibió y se reproduce durante todo el periodo de retención: releer el pasaporte y reintentar con la MISMA clave devuelve el rechazo original, con los números de versión que vio el PRIMER intento. El registro es deliberado: es lo que hace seguro un reintento tras una respuesta perdida. Esto vale solo para el 412. Un 400 por una cabecera mal formada se rechaza antes de reclamar ninguna clave y nunca se registra: corrija la cabecera y reintente con la MISMA clave, su resultado original sigue ahí.
- Vigile las cabeceras de respuesta Deprecation y Sunset, y el Link: rel="successor-version" que las acompaña. Así se anuncia la retirada de un endpoint, y llega mucho antes de que el endpoint deje de responder.
Trate cada identificador como una cadena opaca de 255 caracteres como máximo. No los interprete, no valide su formato y no dé por hecho que son UUID: el formato puede cambiar sin aviso.
Obsolescencia
Un endpoint destinado a desaparecer responde con cabeceras Deprecation y Sunset, además de una cabecera Link que nombra a su sucesor. Llegan mucho antes de que el endpoint deje de responder. Vigílelas.
Registro de cambios
— Para todas las credenciales, los estados de batería se limitan a original, repurposed, re-used, remanufactured y waste. Ya no se aceptan otros textos de estado.