Idempotenza

Un timeout o un errore di rete durante l'invio di una fattura ti lascia in una posizione scomoda: la richiesta è arrivata al server e ha creato la fattura, oppure no? Rilanciarla alla cieca rischia di trasmettere due volte la stessa fattura a SDI.

Per evitarlo, gli endpoint di invio accettano l'header opzionale Idempotency-Key.

Come funziona

Genera una chiave univoca lato client (ad esempio un UUID) e passala nell'header Idempotency-Key insieme alla richiesta:

curl -u "LA TUA TEST API KEY (inizia con ik_test_)": \
  -H "Idempotency-Key: 3f8c1e9a-7b21-4c0d-9f6e-1a2b3c4d5e6f" \
  -F "file=@path/to/file/filename.xml" \
  https://api.invoicetronic.com/v1/send/file | jq

La prima richiesta con una data chiave viene elaborata normalmente e la sua risposta viene memorizzata.
Un eventuale rinvio con la stessa chiave restituisce la risposta originale senza creare una seconda fattura.

La chiave ha una validità di 24 ore: copre i retry realistici senza diventare una deduplicazione permanente.

Endpoint supportati

L'header è accettato su tutti gli endpoint di invio:

POST /send
POST /send/xml
POST /send/file
POST /send/json

Gli endpoint di sola validazione (POST /send/validate/*) non ne hanno bisogno: non creano nulla.

Comportamento

Situazione	Risposta
Prima richiesta con la chiave	Elaborata normalmente; la risposta viene memorizzata
Rinvio con la stessa chiave e stesso contenuto	Risposta originale rigiocata (nessun duplicato)
Richiesta con la stessa chiave ancora in corso	`409 Conflict`
Stessa chiave riutilizzata con un contenuto diverso	`422 Unprocessable Entity`

Il 409 protegge dalle richieste concorrenti: se due invii gemelli partono insieme, uno viene elaborato e l'altro riceve 409. Il 422 protegge da un errore di integrazione: una chiave di idempotenza deve identificare sempre la stessa richiesta, quindi riusarla per una fattura diversa è considerato un errore.

Buone pratiche

Genera una chiave nuova per ogni fattura distinta e riusa la stessa chiave solo quando ritenti l'invio della medesima fattura.
Conserva la chiave lato client finché non hai ricevuto una risposta definitiva, così puoi ritentare in sicurezza dopo un timeout.
L'header è opzionale: se non lo invii, il comportamento resta invariato.

Idempotenza e rate limiting

Il rinvio protetto da Idempotency-Key conta comunque ai fini dei limiti di frequenza. Rigiocare una risposta memorizzata è però molto più economico di un nuovo invio a SDI.