# Aggiorna l'integrazione Aggiorna la tua integrazione all'ultima versione dell'API. Consulta il [registro delle modifiche per gli sviluppatori](https://docs.stripe.com/changelog.md) per un elenco completo delle modifiche apportate all’API di Stripe. Per aggiornare l’integrazione, completa i seguenti passaggi. Cerca le informazioni specifiche per la tua integrazione nel [log delle modifiche](https://docs.stripe.com/changelog.md?api_usage=true). ## Definisci la versione di destinazione per l'aggiornamento Assicurati di specificare nel tuo codice la versione API con cui esegui l’integrazione anziché affidarti alla versione API predefinita del tuo account. Per testare una versione più recente per le chiamate API, imposta l’intestazione `Stripe-Version` (negli ambienti live o di test). Scopri come [impostare una versione API nei nostri SDK lato server](https://docs.stripe.com/upgrades.md#specify-sdk-api-version). Visualizza quali versioni dell’API utilizza la tua integrazione nella scheda [Panoramica](https://dashboard.stripe.com/workbench/overview) di [Workbench](https://docs.stripe.com/workbench/overview.md). Esamina il [log delle modifiche](https://docs.stripe.com/changelog.md) per trovare la versione di destinazione per il tuo aggiornamento. ## Specifica la versione dell'API nel tuo SDK Il tuo account ha una *versione API predefinita* (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) che definisce come chiami l’API, a quali funzionalità hai accesso e la struttura delle risposte API. Quando utilizzi un [SDK lato server](https://docs.stripe.com/sdks.md#server-side-libraries), le tue chiamate API a Stripe utilizzano la versione API corrente al momento del rilascio dell’SDK. Non puoi specificare una versione API diversa quando utilizzi un linguaggio fortemente tipizzato, come Java, Go o .NET. #### Ruby La libreria [stripe-ruby](https://github.com/stripe/stripe-ruby) ti consente di impostare la versione dell’API a livello globale o per singola richiesta. Se non imposti una versione dell’API, le versioni recenti di stripe-ruby utilizzano la versione dell’API più recente al momento del rilascio della tua versione di stripe-ruby. Le versioni di stripe-ruby precedenti alla [v9](https://github.com/stripe/stripe-ruby/blob/master/CHANGELOG.md#900---2023-08-16) utilizzano la versione dell’API predefinita del tuo account. Per impostare la versione dell’API **a livello globale** con l’SDK, assegna la versione alla proprietà `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') ``` Oppure imposta la versione per ogni richiesta: ```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 ``` > Quando sovrascrivi la versione a livello globale o per ogni richiesta, anche gli oggetti della risposta dell’API vengono restituiti in quella versione. #### Python La libreria [stripe-python](https://github.com/stripe/stripe-python) ti consente di impostare la versione dell’API a livello globale o per singola richiesta. Se non imposti una versione dell’API, le versioni recenti di stripe-python utilizzano la versione dell’API più recente al momento del rilascio della tua versione di stripe-python. Le versioni di stripe-python precedenti alla [v6](https://github.com/stripe/stripe-python/blob/master/CHANGELOG.md#600---2023-08-16) utilizzano la versione dell’API predefinita del tuo account. Per impostare la versione dell’API **a livello globale** con l’SDK, assegna la versione alla proprietà `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' ``` Oppure imposta la versione per ogni richiesta: ```python import stripe intent = stripe.PaymentIntent.retrieve( "pi_1DlIVK2eZvKYlo2CW4yj5l2C", stripe_version="2026-08-26.dahlia", ) intent.capture() ``` > Quando sovrascrivi la versione a livello globale o per ogni richiesta, anche gli oggetti della risposta dell’API vengono restituiti in quella versione. #### PHP Con la libreria [stripe-php](https://github.com/stripe/stripe-php) puoi impostare la versione dell’API a livello globale o per singola richiesta. Se non imposti una versione dell’API, le versioni recenti di stripe-php utilizzano la versione dell’API più recente al momento del rilascio della tua versione di stripe-php. Le versioni di stripe-php precedenti alla [v11](https://github.com/stripe/stripe-php/blob/master/CHANGELOG.md#1100---2023-08-16) utilizzano la versione dell’API predefinita del tuo account. Per impostare la versione dell’API **a livello globale** con l’SDK, indica la versione al metodo `\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" ]); ``` Oppure imposta la versione per ogni richiesta: ```php $intent = $stripe->paymentIntents->capture( 'pi_1DlIVK2eZvKYlo2CW4yj5l2C', [], ['stripe_version' => '2026-08-26.dahlia'] ); ``` > Quando sovrascrivi la versione a livello globale o per ogni richiesta, anche gli oggetti della risposta dell’API vengono restituiti in quella versione. #### Java Poiché Java è un linguaggio di programmazione fortemente tipizzato, la versione API utilizzata nell’SDK è *fissa* ed è la versione API più recente al momento del rilascio dell’SDK. Sconsigliamo di impostare una versione API diversa per i linguaggi di programmazione fortemente tipizzati, in quanto gli oggetti della risposta potrebbero non corrispondere ai tipi forti nell’SDK e causare errori della richiesta. Ad esempio, se la versione API specificata richiede parametri non presenti nei tipi dell’SDK, la richiesta fallisce. #### Nodo Con la libreria [stripe-node](https://github.com/stripe/stripe-node) puoi impostare la versione dell’API a livello globale o per singola richiesta. Se non imposti una versione dell’API, le versioni recenti di stripe-node utilizzano la versione dell’API più recente al momento del rilascio della tua versione di stripe-node. Le versioni di stripe-node precedenti alla [v12](https://github.com/stripe/stripe-node/blob/master/CHANGELOG.md#1200---2023-04-06) utilizzano la versione dell’API predefinita del tuo account. Per impostare la versione dell’API **a livello globale** con l’SDK, fornisci l’opzione `apiVersion`: ```javascript // Don't put any keys in code. See /keys-best-practices. const stripe = require('stripe')('<>', { apiVersion: '2026-08-26.dahlia', }); ``` Oppure imposta la versione per ogni richiesta: ```javascript const intent = await stripe.paymentIntents.retrieve('pi_1DlIVK2eZvKYlo2CW4yj5l2C', { apiVersion: '2026-08-26.dahlia', }); ``` #### Utilizzo di Typescript I tipi TypeScript riflettono l’ultima versione dell’API al momento del rilascio. Questa versione è codificata nel [file API_VERSION](https://github.com/stripe/stripe-node/blob/master/API_VERSION). Importa Stripe come importazione predefinita e crea un’istanza come `new Stripe()` con l’ultima versione dell’API. ```javascript import Stripe from 'stripe'; const stripe = new Stripe('<>', { apiVersion: '2026-08-26.dahlia' }); ``` #### Vai alla pagina Poiché Go è un linguaggio di programmazione fortemente tipizzato, la versione API utilizzata nell’SDK è *fissa* ed è la versione API più recente al momento del rilascio dell’SDK. Sconsigliamo di impostare una versione API diversa per i linguaggi di programmazione fortemente tipizzati, in quanto gli oggetti della risposta potrebbero non corrispondere ai tipi forti nell’SDK e causare errori della richiesta. Ad esempio, se la versione API specificata richiede parametri non presenti nei tipi dell’SDK, la richiesta fallisce. #### .NET Poiché C# è un linguaggio di programmazione fortemente tipizzato, la versione API utilizzata nell’SDK .NET è *fissa* ed è la versione API più recente al momento del rilascio dell’SDK. Sconsigliamo di impostare una versione API diversa per i linguaggi di programmazione fortemente tipizzati, in quanto gli oggetti della risposta potrebbero non corrispondere ai tipi forti nell’SDK e causare errori della richiesta. Ad esempio, se la versione API specificata richiede parametri non presenti nei tipi dell’SDK, la richiesta fallisce. #### cURL ```sh curl https://api.stripe.com/v1/charges \ -u <>: \ -H "Stripe-Version: 2026-08-26.dahlia" ``` #### CLI di Stripe ```sh stripe charges create --stripe-version 2026-08-26.dahlia ``` ## Aggiorna il codice per gestire le modifiche all'API Esamina le richieste più importanti e aggiorna il codice per gestire le modifiche apportate alla risposta. Per ciascuna richiesta, consulta le [relative modifiche incompatibili presenti nel registro delle modifiche](https://docs.stripe.com/changelog.md?api_usage=true) per capire quali aggiornamenti sono necessari per adottare la versione di destinazione. Visualizza le richieste API nella [scheda Panoramica](https://dashboard.stripe.com/workbench/overview) di [Workbench](https://docs.stripe.com/workbench/overview.md). ## Aggiorna le destinazioni degli eventi > Gli [eventi leggeri](https://docs.stripe.com/event-destinations.md#thin-events) per le risorse API v1 sono disponibili in anteprima privata. Puoi utilizzarli per semplificare gli aggiornamenti dell’integrazione senza modificare la configurazione dei webhook. In precedenza, gli eventi sottili supportavano solo le risorse API v2. [Scopri di più e richiedi l’accesso](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog). Esamina ogni destinazione di eventi che riceve eventi salienti, inclusi gli endpoint webhook e le destinazioni cloud per Amazon EventBridge e Azure Event Grid. Per gli eventi snapshot, la proprietà [snapshot_api_version](https://docs.stripe.com/api/v2/core/event-destinations/object.md#v2_event_destination_object-snapshot_api_version) della destinazione controlla la versione API utilizzata per eseguire il rendering del payload dell’evento. Questa impostazione è indipendente dalla versione API utilizzata dal tuo SDK lato server. I payload degli eventi leggeri non hanno versione. Puoi impostare `snapshot_api_version` solo quando crei una destinazione di eventi. Per utilizzare una versione API diversa, crea e testa una destinazione configurata con tale versione prima di eliminare la destinazione esistente. Se entrambe le destinazioni sono attive durante la migrazione, il tuo gestore di eventi deve essere idempotente perché Stripe invia gli eventi sottoscritti a entrambe le destinazioni. ## Aggiorna gli endpoint webhook Per aggiornare gli endpoint webhook, devi [verificare le firme dei webhook in entrata](https://docs.stripe.com/webhooks.md#verify-events) e consentire il traffico dagli [indirizzi IP pubblici](https://docs.stripe.com/ips.md) di Stripe. Devi inoltre creare nuovi endpoint, reindirizzare il traffico verso di essi, quindi disattivare i vecchi endpoint. #### Crea nuovi endpoint webhook disattivati Crea un nuovo endpoint webhook con i seguenti parametri: - `url`: lo stesso URL dell’endpoint webhook originale, ma con l’aggiunta di un parametro di query per distinguere tra gli eventi inviati ai due diversi endpoint. Ad esempio `https://example.com/webhooks?version=2024-04-10`. - `enabled_events`: gli stessi eventi del tuo endpoint webhook originale. - `api_version`: la versione dell’API a cui vuoi eseguire l’upgrade. Se esegui l’upgrade alla versione più recente dell’API, puoi creare l’endpoint tramite la Dashboard o l’API. Per le altre versioni, usa l’API per impostare una versione specifica. Dopo aver creato il nuovo endpoint webhook, disabilitalo. Lo riabiliterai nel passaggio successivo. ![Due endpoint, ma solo quello vecchio invia eventi](https://b.stripecdn.com/docs-statics-srv/assets/diagram-1.ac21ab637180179813f503649b543e99.png) #### Aggiorna il codice del webhook per ignorare gli eventi inviati al nuovo endpoint Aggiorna il codice di elaborazione degli eventi: - Se il parametro della query è per la versione precedente dell’API, elaboralo come al solito. - Se il parametro della query è per la nuova versione dell’API, ignora l’evento e restituisci una risposta 200 per evitare nuovi tentativi di consegna. Quindi, abilita il nuovo endpoint webhook che hai creato nel passaggio precedente. A questo punto ogni evento viene inviato due volte: una volta con la vecchia versione dell’API e una volta con quella nuova. ![Due endpoint che inviano eventi, ma che elaborano solo quello precedente](https://b.stripecdn.com/docs-statics-srv/assets/diagram-2.f6b4d3cc0c78971b721fe173f19d5e28.png) #### Aggiorna il codice del webhook per elaborare gli eventi per i nuovi endpoint Aggiorna il codice di elaborazione degli eventi: - Se il parametro della query si riferisce alla versione precedente, ignora l’evento. Ti consigliamo di restituire un codice di stato 400 per consentire a Stripe di ritentare automaticamente a inviare l’evento. In questo modo, se devi ripristinare la versione precedente, gli eventi verranno inviati nuovamente all’endpoint webhook precedente. - Se il parametro della query è per la nuova versione, elaboralo. ![Due endpoint che inviano eventi, ma elaborano solo quello nuovo](https://b.stripecdn.com/docs-statics-srv/assets/diagram-3.8a8b9da70ed66eca60434d406c82f476.png) #### Monitora gli endpoint webhook Monitora il traffico verso i nuovi endpoint webhook per confermare che elaborano correttamente gli eventi. Se gli eventi non vengono gestiti correttamente dal tuo nuovo codice, prova quanto segue: 1. Ripristina la versione precedente del tuo codice. 2. Disattiva temporaneamente il nuovo endpoint webhook. 3. Elabora gli eventi non riusciti (se hai restituito uno stato 400 come descritto nel passaggio precedente, Stripe invia di nuovo automaticamente tutti gli eventi). 4. Analizza e risolvi il problema. 5. Attiva il nuovo endpoint webhook e riprendi il monitoraggio. #### Disattiva il vecchio endpoint webhook Una volta completato l’aggiornamento, disabilita il vecchio endpoint webhook per impedire al tuo server di restituire lo stato `400`. Se non lo disabiliti, potrebbero verificarsi problemi con le integrazioni che si basano su una risposta `200`. Dopo aver disabilitato il vecchio endpoint webhook, Stripe non recapiterà nuovamente gli eventi che hanno restituito un `400`. ![Due endpoint, ma solo quello nuovo invia eventi](https://b.stripecdn.com/docs-statics-srv/assets/diagram-4.907bbd1016f9fbe79283e8c35be7f3cd.png) ## Testa e monitora l'integrazione [Testa l’integrazione](https://docs.stripe.com/testing.md) in una [sandbox](https://docs.stripe.com/sandboxes.md) per confermare che gestisca la nuova versione come previsto. Oltre alle indicazioni generali per i test, segui le linee guida per i prodotti e le risorse utilizzate dalla tua integrazione: - [Billing](https://docs.stripe.com/billing/testing.md): usa i [clock di test](https://docs.stripe.com/billing/testing/test-clocks.md) per [simulare gli abbonamenti](https://docs.stripe.com/billing/testing/test-clocks/simulate-subscriptions.md). - [Invoicing](https://docs.stripe.com/invoicing/integration/testing.md): testa le notifiche dei webhook, gli errori di pagamento e altri scenari. - [Connect](https://docs.stripe.com/connect/testing.md): crea [account di test](https://docs.stripe.com/connect/testing.md?accounts-namespace=v2#creating-accounts) e usali per i [test di verifica](https://docs.stripe.com/connect/testing-verification.md). - [Terminal](https://docs.stripe.com/terminal/references/testing.md): testa gli [aggiornamenti simulati del lettore](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 oggetti PaymentIntent e usa numeri di carta di test per simulare i pagamenti.