Versiones y compatibilidad

La API tiene una versión mayor, /v1, y solo crece. Una integración escrita hoy sigue funcionando a medida que llegan funciones nuevas: nada de lo que usa cambia de nombre, se elimina ni adquiere un significado nuevo.

El número de versión

La API tiene un número de versión como 1.62.0. Cambia con cada publicación:

• el número de versión menor, cuando se añade algo: un endpoint, un campo, un evento;
• el número de parche, cuando se corrige una descripción o el texto de un mensaje y no cambia nada más.

Puede leer en cualquier momento la versión que sirve una dirección:

GET /v1/health también tiene version, pero es la versión de Sursa que sirve la dirección, no la versión de la API.

No elige una versión menor: cada solicitud la atiende la versión actual. Gracias a las reglas siguientes, esto no supone ningún riesgo.

Qué puede cambiar en /v1

Estos cambios pueden llegar en cualquier versión menor. Escriba su integración de forma que no la rompan:

• Endpoints nuevos.
• Parámetros y campos de solicitud nuevos opcionales. Las solicitudes sin ellos se comportan como antes.
• Campos nuevos en las respuestas, los objetos y los eventos.
• Valores nuevos de enumeraciones en las respuestas, como un estado nuevo de tarjeta o un tipo de evento nuevo.
• Códigos de error nuevos y encabezados de respuesta nuevos.
• Límites que se vuelven menos estrictos: una longitud máxima mayor, un rango más amplio.
• Textos message de los errores y descripciones redactados de otra manera.

Qué debe tolerar su código

• Ignore los campos que no conoce. No falle cuando una respuesta tenga más campos de los que espera ni use esquemas estrictos que los rechacen.
• Acepte los valores de enumeración que no conoce. Cualquier enumeración de una respuesta puede crecer. Trate un valor desconocido como «otro», no como un error.
• Omita los tipos de evento que no conoce, tanto en los webhooks como en los flujos.
• Trate los códigos de error desconocidos según su estado HTTP: consulte Errores.
• No dependa del orden de los campos en los objetos JSON ni del texto exacto de los mensajes.

Qué no cambia nunca en /v1

• Una ruta, un parámetro, un campo o un valor de enumeración nunca cambia de nombre ni se elimina.
• El tipo de un campo nunca cambia, y un campo nunca adquiere un significado nuevo, como otras unidades.
• Una solicitud que se acepta hoy no se rechaza más adelante.
• El código de estado de una respuesta correcta sigue siendo el mismo.
• Los códigos de error conservan su significado, y el campo detail de las respuestas de error conserva su forma.
• Los tipos de evento nunca cambian de nombre ni se eliminan, y su data solo gana campos.

Cambios incompatibles

Si alguna vez hace falta un cambio incompatible, se publica como una versión mayor nueva, como /v2, junto a /v1. /v1 sigue funcionando sin cambios, y las dos funcionan en paralelo.

Cuando se va a retirar una ruta:

1. Se marca como deprecated en la especificación y se incluye en el registro de cambios con la fecha en que se desactivará.
2. Sus respuestas llevan los encabezados Deprecation: true y Sunset: <date>.
3. Sigue funcionando al menos 180 días después del anuncio. Las organizaciones cuyas claves de API la usan reciben un aviso por escrito con al menos 90 días de antelación.
4. Después de la fecha de retirada, responde 410 con el código api.gone durante otros 90 días.

Vigile el encabezado Deprecation en sus registros o en su supervisión: es la señal más temprana de que una ruta que usa va a desaparecer.

Mantenerse informado

El registro de cambios de este portal enumera cada publicación con lo que se añadió y lo que quedó obsoleto. Antes de actualizar su propia integración, compare su código con las entradas publicadas desde la versión con la que la creó.