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

# Idempotentność

> Bezpiecznie ponawiaj dowolny zapis, nie tworząc niczego dwa razy

## Operacje zapisu, które zmieniają istniejący zasób

Nie jest tu potrzebny żaden nagłówek. Tam, gdzie powtórzenie wcześniej zwracało błąd, teraz zwraca bieżący stan:

| Endpoint | Powtórne wywołanie zwraca |
| - | - |
| [Anuluj wizytę](https://docs.anivahealth.com/pl/api/appointments/cancel-appointment.md) | `200` z anulowaną wizytą |
| [Anuluj przesyłkę](https://docs.anivahealth.com/pl/api/shipments/cancel-shipment.md) | `200` z anulowaną przesyłką |
| [Anuluj zamówienie domowego zestawu testowego](https://docs.anivahealth.com/pl/api/home-kit-orders/cancel-home-kit.md) | `200` z anulowanym zamówieniem |
| [Aktywuj zamówienie domowego zestawu testowego](https://docs.anivahealth.com/pl/api/home-kit-orders/activate-home-kit.md) | `200`, jeśli czas pobrania jest taki sam |
| Usuwanie paneli lub biomarkerów | `200`, niezależnie od tego, czy były jeszcze przypisane |

Powtórzenie niczego nie zapisuje, a odpowiedź zawiera nagłówek `Idempotent-Replayed: true` — dzięki niemu odróżnisz „anulowano teraz” od „było już anulowane”.

Trzy wyjątki zwracają zamiast tego `409`:

* **Aktywacja z *innym* `activated_at`.** Czas pobrania trafia na raport laboratoryjny, więc ponowna próba nie może go po cichu nadpisać.
* **Anulowanie już anulowanej wizyty z *innym* `cancellation_reason`.** Ten sam powód: zapisana przyczyna mogła zostać w międzyczasie poprawiona i ponowna próba nie może jej nadpisać. Wyślij ponownie zapisaną przyczynę albo ją pomiń.
* **Anulowanie po punkcie bez powrotu** — potwierdzone pobranie krwi, odebrana przesyłka, wysłany lub aktywowany zestaw.

Trzy endpointy celowo nie są bezpieczne do ponawiania:

* [Potwierdź pobranie krwi](https://docs.anivahealth.com/pl/api/appointments/confirm-blood-draw.md) — drugie wywołanie zwraca `409`.
* [Wyślij wyniki e-mailem](https://docs.anivahealth.com/pl/api/appointments/email-results.md) (`POST /v1/appointments/{id}/results/email`) oraz [Wyślij wyniki e-mailem](https://docs.anivahealth.com/pl/api/home-kit-orders/email-results.md) (`POST /v1/home-kit-orders/{id}/results/email`) — każde wywołanie wysyła jednego e-maila. Ponowna próba po przekroczeniu czasu oczekiwania lub błędzie `5xx` może wysłać klientowi duplikat.

## Operacje zapisu, które coś tworzą

Pięć endpointów akceptuje opcjonalny nagłówek `Idempotency-Key` o długości maksymalnie 255 znaków:

* [Utwórz profil](https://docs.anivahealth.com/pl/api/profiles/create-profile.md)
* [Utwórz wizytę](https://docs.anivahealth.com/pl/api/appointments/create-appointment.md)
* [Utwórz zamówienie domowego zestawu testowego](https://docs.anivahealth.com/pl/api/home-kit-orders/create-home-kit.md)
* [Utwórz przesyłkę](https://docs.anivahealth.com/pl/api/shipments/create-shipment.md)
* [Prześlij dokument](https://docs.anivahealth.com/pl/api/documents/upload-document.md)

Jeden klucz, cztery próby, jedno zamówienie — to, co otrzymasz, zależy od momentu ponowienia i tego, czy treść żądania jest taka sama:

![Diagram sekwencji: duplikat wysłany 350 ms po pierwszym żądaniu otrzymuje odpowiedź 409, gdy to żądanie wciąż trwa, pierwsze zwraca 201, późniejsze ponowienie z tym samym kluczem zwraca to samo zamówienie oznaczone Idempotent-Replayed, a ten sam klucz ze zmienioną treścią żądania zwraca 409.](https://mintcdn.com/anivahealth/8KTut54iIoaIFYY2/images/idempotency-retry.svg?fit=max\&auto=format\&n=8KTut54iIoaIFYY2\&q=85\&s=617f6b19f473ee0fed9243004f932c19)

Klucze są przypisane do twojego klucza API **oraz** do endpointu, więc nigdy nie kolidują z kluczami innego partnera ani z tym samym kluczem użytym gdzie indziej.

* **Ten sam klucz, ta sama treść** → przez 24 godziny otrzymujesz pierwotną odpowiedź oznaczoną `Idempotent-Replayed: true`. Kolejność pól i białe znaki nie mają znaczenia.
* **Ten sam klucz, inna treść** → `409`.
* **Pusty `Idempotency-Key`** → `400` zamiast zignorowania.

### Kiedy klucz jest zwalniany

Tworzenie **nie jest atomowe** — błąd `5xx` nie oznacza, że nic nie zostało zapisane.

* **Żądanie nie powiodło się, zanim cokolwiek utworzono** → klucz jest zwalniany, więc możesz ponowić próbę z tym samym kluczem.
* **Żądanie nie powiodło się po tym, jak coś utworzono**, lub **w ogóle nie zwróciło odpowiedzi** → klucz pozostaje zajęty, a ponowne próby zwracają `409`. Pobierz zasób, aby sprawdzić, czy istnieje, a jeśli nie, użyj nowego klucza.

> [!NOTE]
>
> Powtórzenie zwraca treść odpowiedzi zapisaną w momencie utworzenia zasobu — migawkę, a nie bieżący
> odczyt. Jeśli zasób od tego czasu się zmienił, pobierz go bezpośrednio.

### Niektóre operacje tworzenia mają też klucz naturalny

Dwa endpointy odrzucają duplikaty samodzielnie, niezależnie od nagłówka:

* [Utwórz wizytę](https://docs.anivahealth.com/pl/api/appointments/create-appointment.md) pozwala na jedną wizytę dla danego profilu, lokalizacji i terminu. Powtórzenie zwraca `409` z istniejącym `appointment_id`.
* [Utwórz profil](https://docs.anivahealth.com/pl/api/profiles/create-profile.md) zwraca `409`, gdy dla `email` istnieje już profil. Jeśli pominiesz `email`, dla każdego żądania generowana jest unikalna wartość zastępcza, więc powtórzenia *faktycznie* tworzą osobne profile.

Gdy zadziałają oba mechanizmy, otrzymasz `409` z klucza naturalnego i tylko ta odpowiedź zawiera dodatkowe pole (`appointment_id` lub wyróżnik `error_name`) — `409` z idempotentności zawiera wyłącznie `error`, więc odczytuj te pola defensywnie.


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