Idempotenza

Ritentativi sulle scritture: stessa chiave, stessa risposta, nessuna duplicazione.

Il problema

Se una scrittura non riceve risposta (timeout, caduta di rete), il client non sa se è andata a buon fine: un ritentativo senza protezione può creare un duplicato.

La soluzione

Le scritture accettano l'intestazione Idempotency-Key: una stringa che identifica l'operazione (fino a 128 caratteri, per esempio un UUID).

curl -X POST https://tuaazienda.siriocloud.it/api/v1/documenti-vendita \
  -H 'Authorization: Bearer sc_live_LATUACHIAVE' \
  -H 'Idempotency-Key: ordine-negozio-58317' \
  -H 'Content-Type: application/json' \
  -d '{ … }'

Un ritentativo con la stessa chiave e lo stesso corpo non riesegue l'operazione: il server restituisce la risposta originale, marcata Idempotent-Replay: true. Le chiavi si conservano 24 ore.

I casi limite

Risposta	Significato
`409 idempotency_key_riusata`	Stessa chiave con corpo diverso: si tratta di un'altra operazione e richiede una chiave nuova.
`409 richiesta_in_corso`	La prima richiesta con quella chiave è ancora in esecuzione: attendere l'esito senza reinviare.

Indicazione operativa: una Idempotency-Key per ogni scrittura che non deve duplicarsi — documenti, movimenti, arrivi. Come chiave si usa l'identificativo dell'operazione nel sistema chiamante (numero d'ordine, riferimento della bolla).