> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotenza

> Riprova qualsiasi operazione di scrittura in sicurezza, senza creare nulla due volte

## Scritture che modificano una risorsa esistente

Non serve alcun header. Dove prima una ripetizione restituiva un errore, ora restituisce lo stato attuale:

| Endpoint | Una chiamata ripetuta restituisce |
| - | - |
| [Annulla appuntamento](https://docs.anivahealth.com/it/api/appointments/cancel-appointment.md) | `200` con l'appuntamento annullato |
| [Annulla spedizione](https://docs.anivahealth.com/it/api/shipments/cancel-shipment.md) | `200` con la spedizione annullata |
| [Annulla ordine kit domiciliare](https://docs.anivahealth.com/it/api/home-kit-orders/cancel-home-kit.md) | `200` con l'ordine annullato |
| [Attiva ordine kit domiciliare](https://docs.anivahealth.com/it/api/home-kit-orders/activate-home-kit.md) | `200`, se l'orario di raccolta è lo stesso |
| Rimozione di pannelli o biomarcatori | `200`, che fossero ancora associati o meno |

Una ripetizione non scrive nulla e la sua risposta contiene `Idempotent-Replayed: true` — quell'header ti permette di distinguere "l'ho annullato io" da "era già annullato".

Tre eccezioni restituiscono invece `409`:

* **Attivazione con un `activated_at` *diverso*.** L'orario di raccolta è quello riportato sul referto di laboratorio, quindi un nuovo tentativo non deve sovrascriverlo silenziosamente.
* **Annullamento di un appuntamento già annullato con un `cancellation_reason` *diverso*.** Stesso ragionamento: il motivo registrato può essere stato corretto nel frattempo e un nuovo tentativo non deve sovrascriverlo. Invia di nuovo il motivo registrato oppure omettilo.
* **Annullamento oltre il punto di non ritorno** — un prelievo di sangue confermato, una spedizione ritirata, un kit spedito o attivato.

Tre endpoint non sono volutamente sicuri in caso di ripetizione:

* [Conferma prelievo di sangue](https://docs.anivahealth.com/it/api/appointments/confirm-blood-draw.md) — una seconda chiamata restituisce `409`.
* [Invia risultati via email](https://docs.anivahealth.com/it/api/appointments/email-results.md) (`POST /v1/appointments/{id}/results/email`) e [Invia risultati via email](https://docs.anivahealth.com/it/api/home-kit-orders/email-results.md) (`POST /v1/home-kit-orders/{id}/results/email`) — ogni chiamata invia un'email. Un nuovo tentativo dopo un timeout o un `5xx` può inviare un duplicato al cliente.

## Scritture che creano qualcosa

Cinque endpoint accettano un header `Idempotency-Key` opzionale, di massimo 255 caratteri:

* [Crea profilo](https://docs.anivahealth.com/it/api/profiles/create-profile.md)
* [Crea appuntamento](https://docs.anivahealth.com/it/api/appointments/create-appointment.md)
* [Crea ordine kit domiciliare](https://docs.anivahealth.com/it/api/home-kit-orders/create-home-kit.md)
* [Crea spedizione](https://docs.anivahealth.com/it/api/shipments/create-shipment.md)
* [Carica documento](https://docs.anivahealth.com/it/api/documents/upload-document.md)

Una chiave, quattro tentativi, un ordine — ciò che ricevi dipende da quando riprovi e se il body corrisponde:

![Diagramma di sequenza: un duplicato inviato 350 ms dopo la prima richiesta riceve 409 mentre quella richiesta è ancora in esecuzione, la prima restituisce 201, un tentativo successivo con la stessa chiave restituisce lo stesso ordine contrassegnato come Idempotent-Replayed e la stessa chiave con un body modificato restituisce 409.](https://mintcdn.com/anivahealth/8KTut54iIoaIFYY2/images/idempotency-retry.svg?fit=max\&auto=format\&n=8KTut54iIoaIFYY2\&q=85\&s=617f6b19f473ee0fed9243004f932c19)

Le chiavi sono associate alla tua chiave API **e** all'endpoint, quindi non entrano mai in conflitto con quelle di un altro partner o con la stessa chiave usata altrove.

* **Stessa chiave, stesso body** → per 24 ore ricevi di nuovo la risposta originale, contrassegnata con `Idempotent-Replayed: true`. L'ordine dei campi e gli spazi bianchi non contano.
* **Stessa chiave, body diverso** → `409`.
* **Un `Idempotency-Key` vuoto** → `400`, invece di essere ignorato.

### Quando la chiave viene rilasciata

La creazione **non è atomica** — un `5xx` non significa che non sia stato scritto nulla.

* **La richiesta è fallita prima che venisse creato qualcosa** → la chiave viene rilasciata, quindi puoi riprovare usandola.
* **La richiesta è fallita dopo che è stato creato qualcosa**, oppure **non ha mai restituito risposta** → la chiave resta riservata e i nuovi tentativi ricevono `409`. Recupera la risorsa per verificare se esiste, poi usa una nuova chiave in caso contrario.

> [!NOTE]
>
> Una ripetizione restituisce il body della risposta registrato al momento della creazione della
> risorsa — uno snapshot, non una lettura in tempo reale. Se la risorsa è cambiata nel frattempo,
> recuperala direttamente.

### Alcune creazioni hanno anche una chiave naturale

Due endpoint rifiutano i duplicati autonomamente, indipendentemente da qualsiasi header:

* [Crea appuntamento](https://docs.anivahealth.com/it/api/appointments/create-appointment.md) consente un appuntamento per profilo, sede e istante. Una ripetizione restituisce `409` con l'`appointment_id` esistente.
* [Crea profilo](https://docs.anivahealth.com/it/api/profiles/create-profile.md) restituisce `409` quando `email` ha già un profilo. Se ometti `email`, viene generato un segnaposto univoco per ogni richiesta, quindi le ripetizioni creano *effettivamente* profili separati.

Quando si applicano entrambi, vedi il `409` della chiave naturale, ed è l'unico a contenere il campo extra (`appointment_id`, o un discriminatore `error_name`) — un `409` di idempotenza contiene solo `error`, quindi leggi questi campi in modo difensivo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.