# Actualizar tu integración Actualiza tu integración a la última versión de la API. Consulta el [Registro de cambios para desarrolladores](https://docs.stripe.com/changelog.md) para ver el historial completo de cambios en la API de Stripe. Para actualizar tu integración, completa los siguientes pasos. Busca en el [registro de cambios](https://docs.stripe.com/changelog.md?api_usage=true) información específica de tu integración. ## Definir la versión de destino para tu actualización Asegúrate de especificar en tu código la versión de la API con la que realizas la integración en lugar de depender de la versión de la 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). Descubre cómo [configurar una versión de la API en nuestros SDK de servidor](https://docs.stripe.com/upgrades.md#specify-sdk-api-version). Consulta qué versiones de la API utiliza tu integración en la pestaña [Resumen](https://dashboard.stripe.com/workbench/overview) de [Workbench](https://docs.stripe.com/workbench/overview.md). Revisa el [registro de cambios](https://docs.stripe.com/changelog.md) para encontrar la versión de destino para tu actualización. ## Especificar la versión de la API en tu SDK Tu cuenta tiene una *versión de API predeterminada* (If an API request doesn’t specify a version, Stripe uses your account’s default API version, which you can set in the Stripe Dashboard. We recommend specifying the version for each request (either with the Stripe-Version HTTP header or by using a pinned SDK) so your code determines the API version instead of your Dashboard settings) que define cómo llamas a la API, a qué funciones tienes acceso y la estructura de las respuestas de la API. Cuando usas un [SDK del lado del servidor](https://docs.stripe.com/sdks.md#server-side-libraries), tus llamadas a la API a Stripe usan la versión de la API que estaba vigente cuando se publicó el SDK. No puedes usar una versión de API diferente cuando usas un lenguaje de tipado estático, como Java, Go o .NET. #### Ruby La biblioteca [stripe-ruby](https://github.com/stripe/stripe-ruby) te permite establecer la versión de la API de forma global o por solicitud. Si no configuras ninguna versión de la API, las versiones recientes de stripe-ruby utilizan la versión de la API que era la más reciente en el momento en que se publicó tu versión de stripe-ruby. Las versiones de stripe-ruby anteriores a la [v9](https://github.com/stripe/stripe-ruby/blob/master/CHANGELOG.md#900---2023-08-16) utilizan la versión predeterminada de la API de tu cuenta. Para configurar la versión de la API **a nivel global** con el SDK, asigna la versión a la propiedad `Stripe.api_version`: ```ruby require 'stripe' # Don't put any keys in code. See /keys-best-practices. client = Stripe::StripeClient.new('<>', stripe_version: '2026-08-26.dahlia') ``` O bien configura la versión por petición: ```ruby require 'stripe' # Don't put any keys in code. See /keys-best-practices. client = Stripe::StripeClient.new('<>') intent = client.v1.payment_intents.retrieve( 'pi_1DlIVK2eZvKYlo2CW4yj5l2C', { stripe_version: '2026-08-26.dahlia', }, ) intent.capture ``` > Cuando anulas la versión a nivel global o por petición, los objetos de respuesta de la API también se devuelven en esa versión. #### Python La biblioteca [stripe-python](https://github.com/stripe/stripe-python) te permite establecer la versión de la API a nivel global o por solicitud. Si no configuras una versión de la API, las versiones recientes de stripe-python utilizan la versión de la API que era más reciente en el momento en que se publicó tu versión de stripe-python. Las versiones de stripe-python anteriores a la [v6](https://github.com/stripe/stripe-python/blob/master/CHANGELOG.md#600---2023-08-16) utilizan la versión predeterminada de la API de tu cuenta. Para configurar la versión de la API **a nivel global** con el SDK, asigna la versión a la propiedad `stripe.api_version`: ```python import stripe # Don't put any keys in code. See /keys-best-practices. stripe.api_key = <> stripe.api_version = '2026-08-26.dahlia' ``` O bien configura la versión por solicitud: ```python import stripe intent = stripe.PaymentIntent.retrieve( "pi_1DlIVK2eZvKYlo2CW4yj5l2C", stripe_version="2026-08-26.dahlia", ) intent.capture() ``` > Cuando anulas la versión a nivel global o por solicitud, los objetos de respuesta de la API también se devuelven en esa versión. #### PHP La biblioteca [stripe-php](https://github.com/stripe/stripe-php) te permite establecer la versión de la API a nivel global o por solicitud. Si no configuras ninguna versión de la API, las versiones recientes de stripe-php utilizan la versión de la API que era la más reciente en el momento en que se lanzó tu versión de stripe-php. Las versiones de stripe-php anteriores a la [v11](https://github.com/stripe/stripe-php/blob/master/CHANGELOG.md#1100---2023-08-16) utilizan la versión predeterminada de la API de tu cuenta. Para configurar la versión de la API **a nivel global** con el SDK, pasa la versión al método `\Stripe\Stripe::setApiVersion()`: ```php $stripe = new \Stripe\StripeClient([ // Don't put any keys in code. See /keys-best-practices. "api_key" => "<>", "stripe_version" => "2026-08-26.dahlia" ]); ``` O bien configura la versión por petición: ```php $intent = $stripe->paymentIntents->capture( 'pi_1DlIVK2eZvKYlo2CW4yj5l2C', [], ['stripe_version' => '2026-08-26.dahlia'] ); ``` > Cuando anulas la versión a nivel global o por petición, los objetos de respuesta de la API también se devuelven en esa versión. #### Java Dado que Java es un lenguaje de programación de tipado estático, la versión de la API utilizada en el SDK es *fija* y corresponde a la última versión de la API en el momento del lanzamiento del SDK. No recomendamos establecer una versión de la API diferente para los lenguajes de programación de tipado estático, ya que los objetos de respuesta podrían no coincidir con los tipos estáticos del SDK y provocar fallos en las solicitudes. Por ejemplo, si la versión de la API que estás utilizando requiere parámetros que no están presentes en los tipos del SDK, la solicitud falla. #### Node La biblioteca [stripe-node](https://github.com/stripe/stripe-node) te permite establecer la versión de la API de forma global o por solicitud. Si no configuras una versión de la API, las versiones recientes de stripe-node utilizarán la versión de la API que era más reciente en el momento de publicarse tu versión de stripe-node. Las versiones de stripe-node anteriores a [v12](https://github.com/stripe/stripe-node/blob/master/CHANGELOG.md#1200---2023-04-06) utilizan la versión de la API predeterminada de tu cuenta. Para configurar la versión de la API de forma **global** con el SDK, proporciona la opción `apiVersion`: ```javascript // Don't put any keys in code. See /keys-best-practices. const stripe = require('stripe')('<>', { apiVersion: '2026-08-26.dahlia', }); ``` O bien configura la versión por solicitud: ```javascript const intent = await stripe.paymentIntents.retrieve('pi_1DlIVK2eZvKYlo2CW4yj5l2C', { apiVersion: '2026-08-26.dahlia', }); ``` #### Uso de TypeScript Los tipos de TypeScript reflejan la última versión de la API en el momento de la publicación. Esta versión está codificada en el [archivo API_VERSION](https://github.com/stripe/stripe-node/blob/master/API_VERSION). Importa Stripe como importación predeterminada y crea una instancia como `new Stripe()` con la última versión de la API. ```javascript import Stripe from 'stripe'; const stripe = new Stripe('<>', { apiVersion: '2026-08-26.dahlia' }); ``` #### Go Dado que Go es un lenguaje de programación de tipado estático, la versión de la API utilizada en el SDK es *fija* y corresponde a la última versión de la API en el momento del lanzamiento del SDK. No recomendamos establecer una versión de la API diferente para los lenguajes de programación de tipado estático, ya que los objetos de respuesta podrían no coincidir con los tipos estáticos del SDK y provocar fallos en las solicitudes. Por ejemplo, si la versión de la API que estás utilizando requiere parámetros que no están presentes en los tipos del SDK, la solicitud falla. #### .NET Dado que C# es un lenguaje de programación de tipado estático, la versión de la API utilizada en el SDK .NET es *fija* y corresponde a la última versión de la API en el momento del lanzamiento del SDK. No recomendamos establecer una versión de la API diferente para los lenguajes de programación de tipado estático, ya que los objetos de respuesta podrían no coincidir con los tipos estáticos del SDK y provocar fallos en las solicitudes. Por ejemplo, si la versión de la API que estás utilizando requiere parámetros que no están presentes en los tipos del SDK, la solicitud falla. #### cURL ```sh curl https://api.stripe.com/v1/charges \ -u <>: \ -H "Stripe-Version: 2026-08-26.dahlia" ``` #### CLI de Stripe ```sh stripe charges create --stripe-version 2026-08-26.dahlia ``` ## Actualizar tu código para gestionar los cambios de la API Revisa tus peticiones más importantes y actualiza tu código para gestionar los cambios en la respuesta. Para cada petición, revisa los [cambios incompatibles relevantes en el registro de cambios](https://docs.stripe.com/changelog.md?api_usage=true) para entender los cambios necesarios para adoptar tu versión de destino. Consulta tus solicitudes de la API en la [pestaña Resumen](https://dashboard.stripe.com/workbench/overview) de [Workbench](https://docs.stripe.com/workbench/overview.md). ## Actualiza tus destinos de eventos > Los [eventos ligeros](https://docs.stripe.com/event-destinations.md#thin-events) para los recursos de la API v1 están disponibles en versión beta privada. Puedes usarlos para agilizar las actualizaciones de la integración sin cambiar tu configuración de webhook. Anteriormente, los eventos ligeros solo admitían recursos de la API v2. [Obtén más información y solicita acceso](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog). Revisa cada destino de eventos que recibe eventos de resumen, incluidos los puntos de conexión de webhook y los destinos en la nube para Amazon EventBridge y Azure Event Grid. Para los eventos de resumen, la propiedad [snapshot_api_version](https://docs.stripe.com/api/v2/core/event-destinations/object.md#v2_event_destination_object-snapshot_api_version) del destino controla la versión de la API que se utiliza para renderizar la carga útil del evento. Esta configuración es independiente de la versión de la API que usa tu SDK en el servidor. Las cargas útiles de los eventos ligeros no tienen versión. Solo puedes configurar `snapshot_api_version` cuando creas un destino de eventos. Para usar una versión de la API diferente, crea y prueba un destino configurado con esa versión antes de eliminar el destino existente. Si ambos destinos están activos durante la migración, tu controlador de eventos debe ser idempotente porque Stripe entrega los eventos suscritos a ambos destinos. ## Actualizar tus puntos de conexión de webhook Para actualizar tus puntos de conexión de webhook, tienes que [validar las firmas de webhook entrantes](https://docs.stripe.com/webhooks.md#verify-events) y permitir el tráfico desde las [direcciones IP públicas](https://docs.stripe.com/ips.md) de Stripe. También tienes que crear nuevos puntos de conexión, redirigir el tráfico hacia ellos y, a continuación, desactivar los puntos de conexión antiguos. #### Crear nuevos puntos de conexión de webhook desactivados Crea un nuevo punto de conexión de webhook con los siguientes parámetros: - `url`: la misma URL que tu punto de conexión de webhook original, pero añade un parámetro de consulta para distinguir entre los eventos enviados a los dos puntos de conexión diferentes. Por ejemplo, `https://example.com/webhooks?version=2024-04-10`. - `enabled_events`: los mismos eventos que tu punto de conexión de webhook original. - `api_version`: la versión de la API que deseas obtener tras la actualización. Si vas a actualizar a la última versión de la API, puedes usar el Dashboard o la API para crear el punto de conexión. Para otras versiones, usa la API para establecer una versión específica. Después de crear el nuevo punto de conexión de webhook, desactívalo. Lo volverás a activar en el siguiente paso. ![Dos puntos de conexión, pero solo el antiguo envía eventos](https://b.stripecdn.com/docs-statics-srv/assets/diagram-1.ac21ab637180179813f503649b543e99.png) #### Actualizar tu código de webhook para ignorar los eventos que se envían al nuevo punto de conexión Actualiza tu código de procesamiento de eventos: - Si el parámetro de consulta es para la versión antigua de la API, procésalo como de costumbre. - Si el parámetro de consulta es para la nueva versión de la API, ignora el evento y emite una respuesta 200 para evitar los reintentos de entrega. A continuación, activa el nuevo punto de conexión del webhook que creaste en el paso anterior. En este momento, cada evento se envía dos veces: una con la versión antigua de la API y otra con la nueva. ![Dos puntos de conexión enviando eventos, pero solo se procesa el antiguo](https://b.stripecdn.com/docs-statics-srv/assets/diagram-2.f6b4d3cc0c78971b721fe173f19d5e28.png) #### Actualizar tu código de webhook para procesar eventos para los nuevos puntos de conexión Actualizar tu código de procesamiento de eventos: - Si el parámetro de consulta corresponde a la versión anterior, ignora el evento. Te recomendamos devolver un código de estado 400 para que Stripe vuelva a intentar entregar el evento automáticamente. De este modo, si necesitas revertir el cambio, los eventos se volverán a enviar al punto de conexión de webhook anterior. - Si el parámetro de consulta corresponde a la nueva versión, procésalo. ![Dos puntos de conexión envían eventos, pero solo el nuevo procesa](https://b.stripecdn.com/docs-statics-srv/assets/diagram-3.8a8b9da70ed66eca60434d406c82f476.png) #### Supervisar tus puntos de conexión de webhook Supervisa el tráfico de los nuevos puntos de conexión de webhook para confirmar que procesan los eventos correctamente. Si tu nuevo código no gestiona correctamente los eventos, prueba lo siguiente: 1. Vuelve a la versión anterior de tu código. 2. Desactiva temporalmente el nuevo punto de conexión de webhook. 3. Procesa los eventos fallidos (si has devuelto un estado 400 como se describe en el paso anterior, Stripe reenvía automáticamente todos los eventos). 4. Investiga y soluciona el problema. 5. Activa el nuevo punto de conexión de webhook y reanuda la monitorización. #### Desactiva el punto de conexión de webhook antiguo Una vez realizada la actualización correctamente, desactiva el antiguo punto de conexión del webhook para evitar que tu servidor devuelva un estado `400`. Si no lo desactivas, podrían surgir problemas con las integraciones que dependen de una respuesta `200`. Después de desactivar el antiguo punto de conexión del webhook, Stripe no volverá a entregar los eventos que devolvieron una respuesta `400`. ![Dos puntos de conexión, pero solo el nuevo envía eventos](https://b.stripecdn.com/docs-statics-srv/assets/diagram-4.907bbd1016f9fbe79283e8c35be7f3cd.png) ## Probar y controlar tu integración [Prueba tu integración](https://docs.stripe.com/testing.md) en un [entorno de prueba](https://docs.stripe.com/sandboxes.md) para confirmar que gestiona la nueva versión como se espera. Además de las directrices generales sobre pruebas, sigue las directrices de los productos y recursos que utiliza tu integración: - [Billing](https://docs.stripe.com/billing/testing.md): utiliza [relojes de simulación](https://docs.stripe.com/billing/testing/test-clocks.md) para [simular suscripciones](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md). - [Invoicing](https://docs.stripe.com/invoicing/integration/testing.md): prueba las notificaciones de webhook, los pagos fallidos y otras situaciones. - [Connect](https://docs.stripe.com/connect/testing.md): crea [cuentas de prueba](https://docs.stripe.com/connect/testing.md?accounts-namespace=v2#creating-accounts) y utilízalas para [pruebas de verificación](https://docs.stripe.com/connect/testing-verification.md). - [Terminal](https://docs.stripe.com/terminal/references/testing.md): prueba las [actualizaciones de lectores simulados](https://docs.stripe.com/terminal/references/testing.md?terminal-card-present-integration=terminal#simulated-reader-updates). - [Payment Intents](https://docs.stripe.com/payments/quickstart-payment-intents.md#test-payment): crea objetos PaymentIntent y utiliza números de tarjeta de prueba para simular pagos.