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

# Idempotență

> Reîncearcă în siguranță orice operațiune de scriere, fără să creezi ceva de două ori

## Operații de scriere care modifică o resursă existentă

Nu este implicat niciun header. Acolo unde o repetare returna anterior o eroare, acum returnează starea curentă:

| Endpoint | Un apel repetat returnează |
| - | - |
| [Anulează programarea](https://docs.anivahealth.com/ro/api/appointments/cancel-appointment.md) | `200` cu programarea anulată |
| [Anulează expedierea](https://docs.anivahealth.com/ro/api/shipments/cancel-shipment.md) | `200` cu expedierea anulată |
| [Anulează comanda de kit de testare la domiciliu](https://docs.anivahealth.com/ro/api/home-kit-orders/cancel-home-kit.md) | `200` cu comanda anulată |
| [Activează comanda de kit de testare la domiciliu](https://docs.anivahealth.com/ro/api/home-kit-orders/activate-home-kit.md) | `200`, dacă momentul recoltării este același |
| Eliminarea panelurilor sau biomarkerilor | `200`, indiferent dacă mai erau sau nu atașate |

O repetare nu scrie nimic, iar răspunsul ei conține `Idempotent-Replayed: true` — prin acel header faci diferența între „am anulat-o eu” și „era deja anulată”.

Trei excepții returnează în schimb `409`:

* **Activarea cu un `activated_at` *diferit*.** Momentul recoltării apare pe raportul de laborator, așa că o reîncercare nu trebuie să îl suprascrie silențios.
* **Anularea unei programări deja anulate cu un `cancellation_reason` *diferit*.** Același raționament: motivul înregistrat poate să fi fost corectat între timp, iar o reîncercare nu trebuie să îl suprascrie. Retrimite motivul înregistrat sau omite-l.
* **Anularea după punctul fără întoarcere** — o recoltare de sânge confirmată, o expediere preluată, un kit expediat sau activat.

Trei endpoint-uri nu sunt în mod intenționat sigure la reîncercare:

* [Confirmă recoltarea de sânge](https://docs.anivahealth.com/ro/api/appointments/confirm-blood-draw.md) — un al doilea apel returnează `409`.
* [Trimite rezultatele pe e-mail](https://docs.anivahealth.com/ro/api/appointments/email-results.md) (`POST /v1/appointments/{id}/results/email`) și [Trimite rezultatele pe e-mail](https://docs.anivahealth.com/ro/api/home-kit-orders/email-results.md) (`POST /v1/home-kit-orders/{id}/results/email`) — fiecare apel trimite un e-mail. O reîncercare după un timeout sau un `5xx` poate trimite clientului un duplicat.

## Operații de scriere care creează ceva

Cinci endpoint-uri acceptă un header opțional `Idempotency-Key`, de cel mult 255 de caractere:

* [Creează profil](https://docs.anivahealth.com/ro/api/profiles/create-profile.md)
* [Creează programare](https://docs.anivahealth.com/ro/api/appointments/create-appointment.md)
* [Creează comandă de kit de testare la domiciliu](https://docs.anivahealth.com/ro/api/home-kit-orders/create-home-kit.md)
* [Creează expediere](https://docs.anivahealth.com/ro/api/shipments/create-shipment.md)
* [Încarcă document](https://docs.anivahealth.com/ro/api/documents/upload-document.md)

O cheie, patru încercări, o comandă — ce primești înapoi depinde de momentul în care reîncerci și dacă corpul cererii coincide:

![Diagramă de secvență: un duplicat trimis la 350 ms după prima cerere primește 409 cât timp acea cerere rulează încă, prima returnează 201, o reîncercare ulterioară cu aceeași cheie returnează aceeași comandă marcată cu Idempotent-Replayed, iar aceeași cheie cu un corp modificat returnează 409.](https://mintcdn.com/anivahealth/8KTut54iIoaIFYY2/images/idempotency-retry.svg?fit=max\&auto=format\&n=8KTut54iIoaIFYY2\&q=85\&s=617f6b19f473ee0fed9243004f932c19)

Cheile sunt limitate la cheia ta API **și** la endpoint, astfel încât nu intră niciodată în conflict cu cele ale altui partener sau cu aceeași cheie folosită în altă parte.

* **Aceeași cheie, același corp** → timp de 24 de ore primești înapoi răspunsul original, marcat cu `Idempotent-Replayed: true`. Ordinea câmpurilor și spațiile albe nu contează.
* **Aceeași cheie, corp diferit** → `409`.
* **Un `Idempotency-Key` gol** → `400`, în loc să fie ignorat.

### Când este eliberată cheia

Crearea **nu este atomică** — un `5xx` nu înseamnă că nu s-a scris nimic.

* **Cererea a eșuat înainte să se creeze ceva** → cheia este eliberată, așa că poți reîncerca folosind-o.
* **Cererea a eșuat după ce s-a creat ceva** sau **nu a returnat deloc un răspuns** → cheia rămâne rezervată, iar reîncercările primesc `409`. Preia resursa pentru a verifica dacă există, apoi folosește o cheie nouă dacă nu există.

> [!NOTE]
>
> O reluare returnează corpul răspunsului înregistrat la crearea resursei — un snapshot, nu o citire
> în timp real. Dacă resursa s-a modificat între timp, preia-o direct.

### Unele operații de creare au și o cheie naturală

Două endpoint-uri resping duplicatele de la sine, independent de orice header:

* [Creează programare](https://docs.anivahealth.com/ro/api/appointments/create-appointment.md) permite o singură programare per profil, locație și moment. O repetare returnează `409` cu `appointment_id`-ul existent.
* [Creează profil](https://docs.anivahealth.com/ro/api/profiles/create-profile.md) returnează `409` când `email` are deja un profil. Dacă omiți `email`, se generează un placeholder unic pentru fiecare cerere, așa că repetările *chiar* creează profiluri separate.

Când se aplică ambele, vei vedea codul `409` al cheii naturale și doar acesta conține câmpul suplimentar (`appointment_id` sau un discriminator `error_name`) — un `409` de idempotență conține doar `error`, așa că citește acele câmpuri defensiv.


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