Aggiornamento dell'API unificata: Gestione avanzata dell'idempotenza
Al centro di qualsiasi integrazione API robusta si trova l’idempotenza — un meccanismo che garantisce che riprovare una richiesta non produca effetti collaterali indesiderati.
Per fornire maggiore visibilità su come vengono gestite le vostre richieste, abbiamo introdotto un piccolo ma significativo miglioramento alle nostre intestazioni di risposta.
Questo aggiornamento si applica a tutti i servizi basati sull’API unificata — attualmente SIGN IT, SIGN FR e E-INVOICE.
La sfida: “Era una risposta ripetuta?”
Sezione intitolata “La sfida: “Era una risposta ripetuta?””Quando una richiesta viene riprovata utilizzando lo stesso X-Idempotency-Key, la nostra API restituisce correttamente la risposta memorizzata nella cache dell’operazione originale. Questo comportamento previene l’elaborazione duplicata ed è fondamentale per integrazioni affidabili.
Tuttavia, ciò può rendere il debug più difficile. In determinate situazioni — specialmente quando si analizzano casi limite — potrebbe non essere immediatamente chiaro se una risposta è stata generata di recente o servita dalla cache di idempotenza.
La soluzione: X-Idempotency-Replayed
Sezione intitolata “La soluzione: X-Idempotency-Replayed”Con l’ultima versione dell’API unificata del 18 marzo 2026, tutte le risposte POST e PATCH includono ora una nuova intestazione: X-Idempotency-Replayed.
Questa intestazione indica esplicitamente se una risposta è stata riprodotta dalla cache di idempotenza:
X-Idempotency-Replayed: "true"
La richiesta è stata identificata come un nuovo tentativo e la risposta è stata restituita dalla cache.
X-Idempotency-Replayed: "false"
La richiesta è stata elaborata come una nuova operazione e la risposta è stata generata normalmente.
Con questo aggiornamento, il comportamento dell’idempotenza diventa più trasparente — riducendo i tempi di debug e aiutandovi a costruire integrazioni più affidabili.
Was this page helpful?