Versioni dell'API

Come cambia l'API, che cosa non cambia mai, e come vieni a saperlo prima che sparisca qualcosa da cui dipendi.

Che cosa promette /api/v1

Ogni indirizzo inizia con /api/v1. All'interno della versione 1 una modifica è additiva: nuovi endpoint, nuovi campi facoltativi in una richiesta, nuovi campi in una risposta, nuovi valori in un elenco che dichiara di poter crescere. La tua integrazione continua a funzionare senza che tu debba cambiare nulla, purché:

• ignori i campi di una risposta che non conosce;
• decida in base al code o al number di un errore, mai al message, che può essere riformulato;
• tratti un valore sconosciuto di un elenco aperto (un tipo di evento, un codice di avviso) come qualcosa da registrare nel log, non come un errore.

Che cosa non cambia mai

Elemento	Promessa
Codici e numeri di errore	Un codice mantiene il suo nome e il suo numero. Un numero non viene mai riutilizzato per altro, nemmeno dopo che un codice è stato ritirato. Vedi Esiti e codici di errore.
La forma della risposta	Un solo oggetto output con una sezione per prodotto (compose, sign, flow); un errore ha sempre la stessa struttura con code, number, message e retryable.
Idempotenza	La stessa Idempotency-Key con lo stesso corpo non esegue mai il lavoro, né lo addebita, due volte.

Quando qualcosa viene deprecato

A volte un modo migliore ne sostituisce uno vecchio. Il vecchio modo diventa allora deprecato: continua a funzionare esattamente come prima, e lo dichiara.

1. Annunciato nelle note di rilascio e nella pagina della guida che lo descrive, insieme a che cosa usare al suo posto.
2. Segnalato in ogni risposta. Una chiamata a un indirizzo deprecato porta gli header standard Deprecation (la data della deprecazione, RFC 9745) e Link: <the new address>; rel="successor-version". Un campo deprecato in una risposta è indicato nella guida.
3. Rimosso solo in una nuova versione principale (/api/v2 o la 2.0 del prodotto), mai all'interno della versione 1, e mai prima di sei mesi dall'annuncio. Da quel momento le risposte portano anche Sunset con la data (RFC 8594), e scriviamo agli indirizzi di ogni organizzazione.

Deprecato oggi

Vecchio	Usa invece	Dal
/api/v1/documents/*	/api/v1/compose/documents/*	2026-09-19
/api/v1/templates/*	/api/v1/compose/templates/*	2026-09-19
/api/v1/signatures/*	/api/v1/sign/*	2026-09-19
organisation.deliveryMode, thisMonth.documentsSucceeded, thisMonth.documentsFailed in GET /api/v1/usage	Vedi Tracciare una chiamata e tenere d'occhio i consumi	1.1

Nessuno di questi ha una data di rimozione: spariranno con la versione 2, che non è in programma.

Come vieni a sapere di una modifica

• Le note di rilascio elencano ogni modifica che un cliente può notare, con la versione in cui è uscita (MAJOR.MINOR.PATCH: una patch corregge, una minor aggiunge, una major può rimuovere).
• Il riferimento generato, /openapi.json, descrive sempre la versione corrente; gli indirizzi deprecati non vi compaiono.
• Una modifica che richiede un intervento da parte tua viene anche inviata per email agli indirizzi della tua organizzazione.