Versiones de la API

El contrato de /v1 solo crece: aparecen endpoints, campos y valores nuevos, y nada de lo que tu integración ya usa desaparece ni cambia de significado. Cada cambio queda en el registro de cambios.

Cargando el índice de búsqueda…

Versiones de la API

Lo que nunca cambia en /v1

  • Los endpoints, campos, parámetros y encabezados no se eliminan ni se renombran.
  • Un campo mantiene su tipo y su formato, y un campo que siempre llegó sigue llegando.
  • Una solicitud que funcionaba sigue funcionando: no aparecen campos ni parámetros obligatorios nuevos, ni límites más estrictos en la entrada.
  • Los valores de type de los errores y sus estados HTTP no cambian.
  • Un endpoint no pasa a exigir otro scope.

La única excepción es un cambio que cierra una vulnerabilidad de seguridad o que exige la ley: puede llegar antes, y el registro de cambios lo anuncia lo antes posible.

Lo que puede aparecer sin aviso

Estos cambios no rompen un cliente escrito según las reglas de abajo, así que llegan a /v1 en cualquier momento y se anotan en el registro de cambios:

  • endpoints nuevos, parámetros y campos de solicitud opcionales nuevos;
  • campos nuevos en las respuestas y en los eventos de webhooks;
  • valores nuevos de enumeraciones en las respuestas, como los estados de pedido;
  • tipos de error nuevos, cada uno con su estado HTTP: mirá el catálogo de errores;
  • tipos de evento nuevos: un endpoint de webhooks recibe solo los que tiene suscritos.

Obsolescencia

Cuando un endpoint o un campo tiene un reemplazo mejor, se marca como obsoleto en la referencia, y el registro de cambios anuncia el reemplazo. Un endpoint o campo obsoleto sigue funcionando mientras funcione /v1.

Una versión nueva

Un cambio que rompería clientes —eliminar o renombrar algo, cambiar un tipo, una entrada obligatoria nueva— nunca se hace en /v1. Llega como /v2, publicada junto a /v1 con una guía de migración.

/v1 sigue funcionando al menos 12 meses después del lanzamiento de /v2. La fecha en que deja de funcionar se anuncia en el registro de cambios al lanzar /v2, y desde entonces cada respuesta de /v1 lleva los encabezados Deprecation (RFC 9745) y Sunset (RFC 8594) y un enlace al anuncio.

Cómo seguir los cambios

  • El registro de cambios lista cada cambio del contrato por fecha; su feed Atom los lleva a tu lector de feeds o al chat de tu equipo.
  • La referencia y el archivo OpenAPI describen siempre el contrato actual: regenerá tu cliente desde el archivo para tomar los campos nuevos.