Actualizaciones de la API
Cómo gestionar versiones de API y manejar cambios disruptivos en versiones principales.
Tu versión de API controla el comportamiento que ves de la API y los webhooks (por ejemplo, qué parámetros puedes incluir en las solicitudes, qué propiedades ves en las respuestas, etc.). Tu versión se define la primera vez que haces una solicitud de la API. Cada versión principal, como Acacia, incluye cambios que no son compatibles con versiones anteriores. La actualización a una nueva versión principal puede requerir actualizaciones en el código existente. Cada versión mensual incluye solo cambios compatibles con versiones anteriores y utiliza el mismo nombre que la última versión principal. Puedes actualizar de forma segura a una nueva versión mensual sin romper ningún código existente. Para actualizar la versión de tu API, sigue estos pasos.
Cuando una plataforma de Connect hace solicitudes en nombre de cuentas conectadas sin especificar una versión de la API, Stripe utiliza siempre la versión de la API de la plataforma. Independientemente de la versión de API de una cuenta conectada, las solicitudes de la plataforma en su nombre siempre devuelven respuestas que coinciden con la versión de API de la solicitud.
Cambios compatibles con versiones anteriores
Stripe considera que los siguientes cambios son compatibles con versiones anteriores:
- Añadir nuevos recursos de API.
- Añadir nuevos parámetros de solicitud opcionales para los métodos actuales de API.
- Añadir nuevas propiedades a las respuestas actuales de API.
- Cambiar el orden de las propiedades en las respuestas actuales de API.
- Cambiar la longitud o formato de las cadenas opacas, como las ID de objeto, los mensajes de error y otras cadenas en lenguaje natural.
- Esto incluye añadir o quitar prefijos fijos (como
ch_en las ID de cargos). - Asegúrate de que tu integración pueda manejar ID de objetos generados por Stripe, que pueden contener hasta 255 caracteres. Por ejemplo, si utilizas MySQL, almacena los ID en una columna
VARCHAR(255) COLLATE utf8_(la configuraciónbin COLLATEdistingue entre mayúsculas y minúsculas durante las búsquedas).
- Esto incluye añadir o quitar prefijos fijos (como
- Añadir nuevos tipos de eventos.
- Asegúrate de que tu receptor de webhook maneja correctamente tipos de eventos desconocidos.
Actualiza tu versión de la API
Si usas una versión anterior de la API, actualízala a la versión más reciente para aprovechar las nuevas características y las funciones mejoradas.
La actualización de tu versión de API afecta a:
- Las llamadas API que hagas sin un encabezado
Stripe-Version: los parámetros que puedas enviar y la estructura de los objetos devueltos. - La estructura de los objetos recibidos con métodos de Stripe.js como confirmCardPayment.
- La estructura de los objetos enviados a tus puntos de conexión de webhook (tanto Account como Connect). Sin embargo, si un punto de conexión tiene una versión explícita establecida, siempre se usa esa versión.
- Las operaciones automáticas de Billing realizadas por Stripe (por ejemplo, la generación de una factura para un nuevo período de suscripción) utilizan la versión de API predeterminada de tu cuenta. Consulta el registro de cambios de la API para obtener detalles sobre cómo afecta tu versión predeterminada de la API a estas operaciones.
Ver tu versión de API y la última actualización disponible en Workbench
Consulta la versión de API utilizada por solicitudes recientes en tu cuenta y la última actualización disponible desde la pestaña Resumen en Workbench.
Al hacer una actualización de API, asegúrate de especificar la versión de API que estás integrando en tu código en lugar de confiar en la versión de API predeterminada de tu cuenta. Para probar una versión más reciente para las llamadas a la API, configura el encabezado Stripe-Version (en entornos activos o de prueba). Obtén más información sobre cómo gestionar las versiones en nuestros SDK del lado del servidor.
Actualiza y prueba tus webhooks
Versión beta privada
Los eventos ligeros para los recursos API v1 están disponibles en versión beta privada. Puedes usarlos para optimizar las actualizaciones de integración sin cambiar la configuración de tu webhook. Anteriormente, los eventos ligeros solo eran compatibles con recursos API v2. Obtén más información y solicita acceso.
Lee nuestra guía sobre cómo gestionar el control de versiones de webhooks.
Realizar la actualización
Cuando tengas la certeza de que tu código puede manejar la última versión de la API, realiza la actualización usando Workbench:
- Abre la pestaña Resumen en Workbench.
- En la sección Versiones de la API, haz clic en Actualización disponible, que es visible si hay disponible una versión más reciente de la API.
- Revisa qué versión de API se asignará a tu cuenta y haz clic en Actualizar.
Esto cambia la versión utilizada por las llamadas a la API sin el encabezado Stripe-Version y cambia también la versión utilizada para renderizar los objetos enviados a tus webhooks.
Precaución
La forma de los recursos dentro de los eventos recuperados de la API está definida por la versión de API predeterminada de tu cuenta en el momento en que se produjo el evento. Si el código recupera eventos creados cuando la versión predeterminada de la API era diferente, debe tener en cuenta las diferencias existentes en las versiones del evento.
Revertir tu versión de API
Durante las 72 horas posteriores a la actualización de la versión de la API, puedes volver con seguridad a la versión desde la que estabas actualizando en Workbench.
Una vez que hayas revertido la versión, los webhooks que se enviaron con la nueva estructura de objetos y que fallaron, se volverán a enviar con la estructura anterior.