> ## 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.

# Idempotència

> Reintenta qualsevol escriptura de manera segura, sense crear res dues vegades

## Escriptures que modifiquen un recurs existent

No intervé cap capçalera. Allà on una repetició abans retornava un error, ara retorna l'estat actual:

| Endpoint | Una crida repetida retorna |
| - | - |
| [Cancel·la la cita](https://docs.anivahealth.com/ca/api/appointments/cancel-appointment.md) | `200` amb la cita cancel·lada |
| [Cancel·la l'enviament](https://docs.anivahealth.com/ca/api/shipments/cancel-shipment.md) | `200` amb l'enviament cancel·lat |
| [Cancel·la la comanda de kit de prova a casa](https://docs.anivahealth.com/ca/api/home-kit-orders/cancel-home-kit.md) | `200` amb la comanda cancel·lada |
| [Activa la comanda de kit de prova a casa](https://docs.anivahealth.com/ca/api/home-kit-orders/activate-home-kit.md) | `200`, si l'hora de recollida és la mateixa |
| Eliminar panells o biomarcadors | `200`, tant si encara estaven vinculats com si no |

Una repetició no escriu res, i la seva resposta porta `Idempotent-Replayed: true` — aquesta capçalera et permet distingir "l'he cancel·lat jo" de "ja estava cancel·lat".

En canvi, tres excepcions retornen `409`:

* **Activar amb un `activated_at` *diferent*.** L'hora de recollida és la que apareix a l'informe del laboratori, així que un reintent no l'ha de sobreescriure silenciosament.
* **Cancel·lar una cita ja cancel·lada amb un `cancellation_reason` *diferent*.** El mateix raonament: el motiu registrat pot haver estat corregit mentrestant, i un reintent no l'ha de sobreescriure. Torna a enviar el motiu registrat o omet-lo.
* **Cancel·lar després del punt de no retorn** — una extracció de sang confirmada, un enviament recollit, un kit expedit o activat.

Hi ha tres endpoints que deliberadament no són segurs per a reintents:

* [Confirma l'extracció de sang](https://docs.anivahealth.com/ca/api/appointments/confirm-blood-draw.md) — una segona crida retorna `409`.
* [Envia els resultats per correu electrònic](https://docs.anivahealth.com/ca/api/appointments/email-results.md) (`POST /v1/appointments/{id}/results/email`) i [Envia els resultats per correu electrònic](https://docs.anivahealth.com/ca/api/home-kit-orders/email-results.md) (`POST /v1/home-kit-orders/{id}/results/email`) — cada crida envia un correu electrònic. Un reintent després d'un temps d'espera esgotat o un `5xx` pot enviar un duplicat al client.

## Escriptures que creen alguna cosa

Cinc endpoints accepten una capçalera opcional `Idempotency-Key`, de com a màxim 255 caràcters:

* [Crea un perfil](https://docs.anivahealth.com/ca/api/profiles/create-profile.md)
* [Crea una cita](https://docs.anivahealth.com/ca/api/appointments/create-appointment.md)
* [Crea una comanda de kit de prova a casa](https://docs.anivahealth.com/ca/api/home-kit-orders/create-home-kit.md)
* [Crea un enviament](https://docs.anivahealth.com/ca/api/shipments/create-shipment.md)
* [Puja un document](https://docs.anivahealth.com/ca/api/documents/upload-document.md)

Una clau, quatre intents, una comanda — el que reps depèn de quan facis el reintent i de si el cos coincideix:

![Diagrama de seqüència: un duplicat enviat 350 ms després de la primera sol·licitud rep un 409 mentre aquesta sol·licitud encara està en curs, la primera retorna 201, un reintent posterior amb la mateixa clau retorna la mateixa comanda marcada com a Idempotent-Replayed, i la mateixa clau amb un cos modificat retorna 409.](https://mintcdn.com/anivahealth/8KTut54iIoaIFYY2/images/idempotency-retry.svg?fit=max\&auto=format\&n=8KTut54iIoaIFYY2\&q=85\&s=617f6b19f473ee0fed9243004f932c19)

Les claus estan limitades a la teva clau d'API **i** a l'endpoint, així que no col·lideixen mai amb les d'un altre soci ni amb la mateixa clau feta servir en un altre lloc.

* **Mateixa clau, mateix cos** → durant 24 hores reps la resposta original, marcada amb `Idempotent-Replayed: true`. L'ordre dels camps i els espais en blanc no importen.
* **Mateixa clau, cos diferent** → `409`.
* **Una `Idempotency-Key` buida** → `400`, en lloc d'ignorar-se.

### Quan s'allibera la clau

La creació **no és atòmica** — un `5xx` no vol dir que no s'hagi escrit res.

* **La sol·licitud ha fallat abans de crear res** → la clau s'allibera, així que pots tornar-ho a intentar amb la mateixa clau.
* **La sol·licitud ha fallat després de crear alguna cosa**, o **no ha retornat cap resposta** → la clau continua reservada i els reintents reben `409`. Consulta el recurs per comprovar si existeix i, si no existeix, fes servir una clau nova.

> [!NOTE]
>
> Una repetició retorna el cos de la resposta registrat quan es va crear el recurs — una instantània,
> no una lectura en temps real. Si el recurs ha canviat des de llavors, consulta'l directament.

### Algunes creacions també tenen una clau natural

Dos endpoints rebutgen duplicats per si sols, independentment de qualsevol capçalera:

* [Crea una cita](https://docs.anivahealth.com/ca/api/appointments/create-appointment.md) permet una cita per perfil, ubicació i instant. Una repetició retorna `409` amb l'`appointment_id` existent.
* [Crea un perfil](https://docs.anivahealth.com/ca/api/profiles/create-profile.md) retorna `409` quan `email` ja té un perfil. Si omets `email`, es genera un valor provisional únic per sol·licitud, així que les repeticions *sí* que creen perfils separats.

Quan s'apliquen totes dues, veuràs el `409` de la clau natural, i només aquest inclou el camp addicional (`appointment_id`, o un discriminador `error_name`) — un `409` d'idempotència només porta `error`, així que llegeix aquests camps de manera defensiva.


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