GetbeelDocs

Idempotenza

Ripeti in sicurezza le richieste che creano o inviano fatture con l'header Idempotency-Key.

Una rete instabile può farti perdere la risposta a una richiesta andata a buon fine. Se la ripeti senza protezione rischi di creare due bozze o, peggio, di inviare due volte la stessa fattura. L'header Idempotency-Key lo evita.

Come funziona

Manda un valore unico (consigliamo un UUID v4) nell'header Idempotency-Key di ogni POST che crea o invia:

curl -X POST https://www.getbeel.com/api/v1/invoices/INVOICE_ID/send \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: 9f1c2a4e-7b3d-4e8a-a1f2-3c5d7e9b0a12"
  • La prima richiesta con una chiave viene eseguita e la risposta viene memorizzata per 24 ore.
  • Se ripeti la stessa richiesta con la stessa chiave, ricevi la risposta memorizzata e l'operazione non viene ripetuta.
  • Se riusi la chiave per una richiesta diversa (altro endpoint o altro corpo), ricevi un errore invece di una risposta sbagliata.

Si applica a POST /invoices e POST /invoices/{id}/send.

Buone pratiche

  • Genera la chiave quando decidi di fare l'operazione e salvala insieme all'operazione, così un nuovo tentativo dopo un crash usa la stessa.
  • Usa una chiave nuova per ogni operazione diversa: due fatture, due chiavi.
  • Ritenta solo errori di rete, 429 e 5xx. Un 4xx va corretto, non ripetuto.

Gli errori: 409 idempotency_key_in_use (una richiesta con la stessa chiave è ancora in corso: riprova tra poco con la stessa chiave), 422 idempotency_key_reused (chiave già usata per una richiesta diversa: usane una nuova), 400 parameter_invalid con param: "Idempotency-Key" (la chiave deve avere da 1 a 255 caratteri ASCII visibili). Vedi Errori.

Anche senza chiave, una bozza si invia una volta sola: un secondo invio riceve 409 invoice_send_in_progress o 409 invoice_not_draft prima di qualsiasi chiamata allo SDI. Vedi ciclo di vita SDI.

In questa pagina