Referencia

Versionado

Una sola versión, v1, bajo /v1. Solo crece: nada de lo que contiene cambia ni desaparece sin un año de aviso.

Qué puede cambiar en v1

Solo cambios aditivos: rutas nuevas, campos de solicitud opcionales nuevos, campos de respuesta nuevos, valores de enumeración nuevos en las respuestas, motivos de error nuevos, eventos de webhook y campos de carga útil nuevos. Escribe clientes que ignoren los campos desconocidos y toleren los valores de enumeración desconocidos.

Un cambio incompatible es una versión mayor nueva (/v2) que se sirve junto a v1.

Obsolescencia

Una ruta o un campo puede quedar obsoleto, pero nunca se cambia en su sitio. Desde el día en que queda obsoleto, cada respuesta que lo toca lleva Deprecation: @<unix seconds> (RFC 9745), Sunset: <HTTP date> (RFC 8594) y un Link a su entrada del registro de cambios con rel="deprecation". Sigue funcionando al menos 365 días después.

Registra o alerta sobre la cabecera Deprecation y te enterarás de cada obsolescencia mucho antes de que importe. Todas figuran en el registro de cambios.

Cargas útiles de webhook

Las cargas útiles de webhook se versionan por fecha (2026-09-01 hoy). Cada endpoint conserva la versión de carga útil con la que se creó, así que un futuro cambio incompatible en una carga útil solo llega a los endpoints que decidan adoptarlo.