Controllo delle versioni

Questa guida spiega come l'API Merchant gestisce il controllo delle versioni, le release e il ciclo di vita delle sue diverse versioni.

Schema di controllo delle versioni

L'API Merchant utilizza una strategia di controllo delle versioni a livello di sotto-API. Ciò significa che ogni API Merchant, ad esempio Prodotti all'interno dell'API Merchant, avrà il proprio ciclo di vita della versione.

Formato e presentazione del controllo delle versioni

• Versioni stabili delle sotto-API: se una sotto-API è in versione stabile, tutti i suoi metodi sono in versione stabile. Una versione stabile della sotto-API è rappresentata come vX (ad esempio, v1, v2). Queste sono le versioni principali pronte per la produzione.

• Versioni alpha delle sotto-API: se una sotto-API è in versione alpha, tutti i suoi metodi sono in versione alpha. Una versione alpha della sotto-API è rappresentata come vXalpha (ad esempio, v1alpha, v2alpha). Contengono funzionalità sperimentali in accesso anticipato destinate ai test e all'iterazione rapida. Le versioni alpha non hanno alcuna garanzia di stabilità, non hanno una durata definita e possono essere modificate o ritirate con un periodo di preavviso di 30 giorni.

Modifiche versione

• Incrementi della versione principale (ad esempio, da v1 a v2): indicano modifiche che provocano errori e non sono compatibili con le versioni precedenti, che richiedono l'intervento dello sviluppatore. Solo le modifiche che provocano errori delle sotto-API stabili avranno un nuovo numero di versione. Ad esempio, da v1 a v2.
• Modifiche secondarie: le aggiunte o le correzioni compatibili con le versioni precedenti vengono presentate come modifiche alla versione principale esistente. Queste modifiche verranno descritte in dettaglio nelle note di rilascio per la versione principale. Le aggiunte non che provocano errori a una sotto-API verranno rilasciate al canale alpha dell'ultima versione stabile o direttamente all'ultima versione stabile.

Norme relative al ritiro

Ritiriamo periodicamente le versioni precedenti delle sotto-API Merchant. Ci impegniamo a rispettare un periodo di ritiro di 12 mesi per le versioni principali stabili (vX), a partire dall'annuncio ufficiale del ritiro.

Ad esempio, se ritiriamo la versione v1 della sotto-API Prodotti il 15 gennaio 2026, verrà ritirata non prima del 15 gennaio 2027. Dopo questa data, la versione precedente della sotto-API non sarà più disponibile per l'uso.

Versione della sotto-API e stato del ciclo di vita

La tabella seguente elenca le versioni più recenti di ogni sotto-API dell'API Merchant:

Best practice

• Controlla regolarmente le note di rilascio e gli ultimi aggiornamenti per le nuove versioni, gli aggiornamenti principali, i miglioramenti e gli annunci relativi ai lanci e ai ritiri delle sotto-API.
• Se una sotto-API ha due o più versioni stabili, ti consigliamo di utilizzare sempre l'ultima versione.
• Progetta la tua applicazione in modo che gestisca correttamente vari errori delle sotto-API, inclusi problemi di rete, limiti di frequenza e i nuovi codici o messaggi di errore che potrebbero essere introdotti con le versioni più recenti delle sotto-API.
• Non aspettare che una versione della sotto-API stia per essere ritirata per iniziare a pianificare l'upgrade. Inizia a valutare e testare le nuove versioni non appena sono disponibili.
• Per richieste di funzionalità o dubbi sulla roadmap di una sotto-API, contattaci per domande o feedback. Per informazioni su come contattare il team dell'API Merchant per l'assistenza tecnica, consulta Richiedere assistenza per l'API Merchant.