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,
429e5xx. Un4xxva 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.