# Idempotenza (https://docs.getbeel.com/it/api/idempotency)

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 [#come-funziona]

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

```bash
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 [#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](/it/api/errors).

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](/it/api/sdi-lifecycle#inviare-due-volte-non-crea-un-duplicato).
