Seguir versiones y deprecaciones

/api/v1 es la única versión que vas a ver en la URL. No hay header de fecha, ni ?version=, ni dos rutas paralelas para lo mismo. Lo que versiona esta API es el nivel de cada operación.

Los tres niveles

Nivel	Qué promete	Dónde lo ves
`estable`	Una operación deprecada sigue funcionando 90 días, con headers `Deprecation` y `Sunset` desde el primer día. Sale de `estable` solo por deprecación: nunca baja a `beta`.	En la Referencia, junto a la operación.
`beta`	Publicada y usable, y puede cambiar en cualquier momento. Todo cambio que rompa queda en el registro de cambios, y avisamos por correo a quien haya llamado esa operación en los últimos 30 días.	Con la etiqueta Beta en la Referencia.
`interna`	No es parte de la API pública. No está documentada, no está en el `openapi.json` que publicamos y puede desaparecer sin aviso.	No la ves: por eso no está aquí.

El nivel viaja en el propio documento OpenAPI, como la extensión x-vitrina-tier.

Hoy ninguna operación está en estable

Todo lo publicado está en beta. Construye encima igual: beta no significa inestable. Significa que el aviso de un cambio te llega por el registro de cambios y por correo, en vez de llegarte con 90 días de reloj.

El registro de operaciones estables

Una operación sube de nivel con fecha y motivo, y esta tabla es ese registro. Mientras esté vacía, ninguna operación prometió los 90 días. La promoción llega cuando un integrador externo ya depende de la operación, o cuando esta sobrevivió una etapa completa sin cambios.

Fecha	Operaciones	Promovida por	Por qué
—	ninguna todavía; todo lo publicado está en `beta`	—	—

Qué pasa cuando algo se deprecia

Una operación estable que se va a retirar responde así, desde el día en que se anuncia y hasta el último:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT

Sunset es la fecha en que deja de responder, 90 días después como mínimo. Deprecation dice que el reloj ya empezó. Las dos son headers estándar (RFC 8594 y RFC 9745), así que la mayoría de los clientes HTTP ya saben leerlas. Si tu integración registra un aviso cuando aparecen, te enteras sin leer ningún correo.

Mientras corre ese plazo la operación funciona igual. No se degrada, no responde más lento y no devuelve menos campos.

Qué contamos como un cambio que rompe

Rompe:

quitar una operación, un campo de la respuesta o un valor de un enum;
hacer obligatorio un parámetro que no lo era;
cambiar el tipo de un campo, o el significado de uno que ya existía;
cambiar el código de error con el que falla un caso.

No rompe, y puede pasar cualquier día en cualquier nivel:

agregar una operación, un campo opcional a la respuesta o un valor nuevo a un enum;
agregar un parámetro opcional;
cambiar el texto de message en un error.

Por ejemplo, livemode se agregó a las API keys y a cada evento de webhook para distinguir un espacio de prueba de uno real (Sandbox). Es un campo opcional más, así que no rompe.

Para ver la diferencia entre code y message, estas dos fallas llegan de la misma API:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing bearer token",
    "requestId": "2bd4e229-842e-4e82-a0f2-4ff028c1e1fb"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required scope: webhooks:write",
    "requestId": "f7614421-ef08-4638-8524-2af320d1ab3c"
  }
}

code es el campo que ramificas, y cambiarlo te rompe la integración. message está escrito para quien lee logs, queda en inglés y puede cambiar de redacción cualquier día (Errores).

Trampa

Un campo nuevo no debería romperte

Agregamos campos a las respuestas sin aviso, en todos los niveles. Un parser estricto que rechaza lo que no conoce se cae con eso. Ignora los campos que no esperabas, en vez de fallar.

El primer cambio que rompe: los scopes solicitudes:*

POST /api-keys y POST /personal-tokens dejaron de aceptar solicitudes:read y solicitudes:write en scopes[]. La funcionalidad que esos permisos gobernaban se retiró del producto, así que no hay un scope de reemplazo que pedir en su lugar. Las credenciales que ya existen siguen funcionando; lo que falla con 400 es pedir esos dos valores al crear una nueva. Quítalos de la llamada y el resto de los scopes se emite igual que antes.

Cómo te enteramos

Un cambio en beta se marca como breaking en el registro de cambios, generado del spec. Si rompe, le llega un correo a quien haya llamado esa operación en los últimos 30 días. Esa lista sale del uso real de cada credencial: si tu key llamó la operación, te llega.
Un cambio en estable llega con Deprecation y Sunset en la respuesta misma, el canal que no depende de que alguien lea el correo correcto.
El openapi.json que publicamos es el mismo que genera el backend, así que la forma más confiable de saber qué cambió es diferenciarlo entre dos versiones.