Versioni

Cosa può cambiare nella v1

Solo cambiamenti additivi: nuove route, nuovi campi opzionali nelle richieste, nuovi campi nelle risposte, nuovi valori enum nelle risposte, nuovi motivi di errore, nuovi eventi webhook e campi di payload. Scrivi client che ignorano i campi sconosciuti e tollerano i valori enum sconosciuti.

Un cambiamento incompatibile è una nuova versione maggiore (/v2) servita accanto alla v1.

Deprecazione

Una route o un campo può essere deprecato, mai modificato sul posto. Dal giorno della deprecazione, ogni risposta che lo tocca riporta Deprecation: @<unix seconds> (RFC 9745), Sunset: <HTTP date> (RFC 8594) e un Link alla sua voce del changelog con rel="deprecation". Continua a funzionare per almeno 365 giorni dopo.

Registra o segnala l’header Deprecation e sarai informato di ogni deprecazione molto prima che conti. Ognuna è elencata nel changelog.

Payload dei webhook

I payload dei webhook sono versionati per data (oggi 2026-09-01). Ogni endpoint conserva la versione di payload con cui è stato creato, quindi un futuro cambiamento incompatibile di un payload raggiunge solo gli endpoint che lo scelgono.