# Aggiornamenti dell'API Tieni traccia delle modifiche e degli upgrade dell'API Stripe. > [Gli eventi sottili](https://docs.stripe.com/event-destinations.md#thin-events) per le risorse dell’API v1 sono disponibili in anteprima privata. Può utilizzarli per semplificare gli aggiornamenti dell’integrazione senza modificare la configurazione dei webhook. In precedenza, gli eventi sottili accettavano solo le risorse dell’API v2. [Per saperne di più e richiedere l’accesso](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog). La tua versione dell’API controlla il comportamento dell’API e dei webhook che vedi, ad esempio quali parametri puoi includere nelle richieste, quali proprietà vedi nelle risposte e così via. La versione viene impostata alla tua prima richiesta API. Ogni versione principale, come [Acacia](https://docs.stripe.com/changelog/acacia.md), include modifiche che non sono compatibili con le versioni precedenti. L’aggiornamento a una nuova versione principale può richiedere aggiornamenti al codice esistente. Ogni versione mensile include solo modifiche compatibili con le versioni precedenti e utilizza lo stesso nome dell’ultima versione principale. Puoi eseguire l’aggiornamento a una nuova versione mensile in tutta sicurezza senza compromettere il codice esistente. Per eseguire l’upgrade della tua versione dell’API, segui [questi passaggi](https://docs.stripe.com/upgrades.md#how-can-i-upgrade-my-api). Quando una piattaforma [Connect](https://stripe.com/connect) effettua richieste per conto di account connessi senza specificare una versione dell’API, Stripe utilizza sempre la versione dell’API della piattaforma. Indipendentemente dalla versione dell’API di un account connesso, le richieste che la piattaforma invia per suo conto restituiscono sempre risposte corrispondenti alla versione API della richiesta. ## Modifiche compatibili con le versioni precedenti Stripe considera retrocompatibili le seguenti modifiche: - Aggiunta di nuove risorse API. - Aggiunta di nuovi parametri di richiesta opzionali ai metodi API esistenti. - Aggiunta di nuove proprietà a risposte API esistenti. - Modifica dell’ordine delle proprietà in risposte API esistenti. - Modifica della lunghezza o del formato di stringhe opache, come gli ID degli oggetti, i messaggi di errore e altre stringhe leggibili dall’uomo. - Questo include l’aggiunta o la rimozione di prefissi fissi (come `ch_` per gli ID di addebito). - Assicurati che la tua integrazione sia in grado di gestire gli ID oggetto generati da Stripe, che possono contenere fino a 255 caratteri. Ad esempio, se stai usando MySQL, memorizza gli ID in una colonna `VARCHAR(255) COLLATE utf8_bin` (la configurazione `COLLATE` offre la capacità di distinguere tra maiuscole e minuscole nelle ricerche). - Aggiunta di nuovi tipi di evento. - Accertati che il tuo listener di webhook gestisca normalmente tipi di eventi non noti. ## Aggiorna la tua versione API Se stai utilizzando una versione precedente dell’API, aggiornala alla versione più recente per sfruttare le nuove caratteristiche e le funzionalità avanzate. L’aggiornamento della versione API avrà effetti su: - Le chiamate API effettuate senza un’intestazione `Stripe-Version`: i parametri che puoi inviare e la struttura degli oggetti restituiti. - La struttura degli oggetti ricevuti con le modalità [Stripe.js](https://docs.stripe.com/payments/elements.md) come [confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment). - La struttura degli oggetti inviati ai tuoi endpoint del webhook (sia dell’account che [Connect](https://docs.stripe.com/connect/webhooks.md)). Tuttavia, se su un endpoint è impostata una versione esplicita, utilizza sempre quella versione. - Le operazioni di addebito automatico eseguite da Stripe (ad esempio, generazione di una *fattura* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) per un nuovo periodo di abbonamento) usano la versione API predefinita del tuo account. Per informazioni su come la tua versione API predefinita influenza queste operazioni, consulta il log delle modifiche API. ### Visualizza la tua versione API e l’ultimo aggiornamento disponibile in Workbench. Visualizza la [versione API utilizzata dalle richieste recenti](https://docs.stripe.com/workbench/guides.md#view-api-versions) sul tuo account e l’ultimo aggiornamento disponibile dalla scheda [Panoramica](https://dashboard.stripe.com/workbench/overview) in Workbench. Durante l’aggiornamento dell’API, specifica sempre la versione che stai integrando nel codice, evitando di fare affidamento sulla versione predefinita del tuo account. Per testare una versione più recente per le chiamate API, imposta l’intestazione `Stripe-Version` (in ambienti live o di test). Scopri come gestire il controllo delle versioni nei nostri [SDK lato server](https://docs.stripe.com/sdks.md#server-side-libraries). ### Aggiorna e testa i tuoi webhook Consulta la nostra guida su [come gestire le versioni dei webhook](https://docs.stripe.com/webhooks/versioning.md). ### Esegui l’aggiornamento Quando sei sicuro che il tuo codice è in grado di gestire l’ultima versione dell’API, esegui l’aggiornamento utilizzando Workbench: 1. Apri la scheda [Panoramica](https://dashboard.stripe.com/workbench/overview) in Workbench. 1. Nella sezione **Versioni API**, fai clic su **Aggiornamento disponibile**, visibile se è disponibile una versione API più recente. 1. Verifica quale versione dell’API verrà assegnata al tuo account e fai clic su **Aggiorna**- In questo modo cambia la versione utilizzata dalle chiamate API che non hanno l’intestazione `Stripe-Version` nonché la versione utilizzata per visualizzare gli oggetti inviati ai tuoi webhook. > La forma delle risorse negli [eventi recuperati dall’API](https://docs.stripe.com/api/events.md) è determinata dalla versione API predefinita del tuo account al momento in cui l’evento si è verificato. Se il tuo codice recupera eventi creati quando la tua versione API predefinita era diversa, deve tener conto di eventuali differenze nelle versioni degli eventi. ### Annulla l’upgrade della tua versione API Nelle 72 ore successive all’aggiornamento della tua versione API, puoi tranquillamente tornare alla versione precedente all’aggiornamento in Workbench. Dopo il ripristino, i webhook inviati con la nuova struttura dell’oggetto, e che non sono andati a buon fine, saranno riproposti con la vecchia struttura. ## Ricevi aggiornamenti Inviamo le informazioni relative ad aggiunte e modifiche dell’API e delle librerie dei linguaggi di Stripe nello Stripe Developer Digest. Assicurati di aver effettuato la [registrazione](https://go.stripe.global/dev-digest) per ricevere aggiornamenti. ## Versioni API > Questa sezione non viene più aggiornata. Per ulteriori informazioni sugli aggiornamenti dell’API Stripe, visita il nuovo [Registro delle modifiche](https://docs.stripe.com/changelog.md). Di seguito sono elencate tutte le [modifiche che provocano errori](https://docs.stripe.com/upgrades.md#breaking-change) all’API Stripe. Ogni data corrisponde a una nuova versione dell’API Stripe. Se stai cercando tutte le aggiunte e gli aggiornamenti dell’API, consulta il [log delle [modifiche API](https://docs.stripe.com/changelog.md). Se stai cercando nuove versioni del prodotto, consulta il [log delle modifiche del prodotto](https://stripe.com/blog/changelog).