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

# Ідемпотентність

> Безпечно повторюй будь-яку операцію запису, не створюючи нічого двічі

## Операції запису, що змінюють наявний ресурс

Жоден заголовок не потрібен. Там, де повторний запит раніше повертав помилку, тепер він повертає поточний стан:

| Ендпоїнт | Повторний виклик повертає |
| - | - |
| [Скасувати запис](https://docs.anivahealth.com/uk/api/appointments/cancel-appointment.md) | `200` зі скасованим записом |
| [Скасувати відправлення](https://docs.anivahealth.com/uk/api/shipments/cancel-shipment.md) | `200` зі скасованим відправленням |
| [Скасувати замовлення набору для домашнього тесту](https://docs.anivahealth.com/uk/api/home-kit-orders/cancel-home-kit.md) | `200` зі скасованим замовленням |
| [Активувати замовлення набору для домашнього тесту](https://docs.anivahealth.com/uk/api/home-kit-orders/activate-home-kit.md) | `200`, якщо час збору зразка той самий |
| Видалення панелей або біомаркерів | `200`, незалежно від того, чи були вони ще прив’язані |

Повторний запит нічого не записує, а його відповідь містить `Idempotent-Replayed: true` — цей заголовок дозволяє відрізнити «я це скасував» від «це вже було скасовано».

Натомість три винятки повертають `409`:

* **Активація з *іншим* `activated_at`.** Час збору зразка потрапляє до лабораторного звіту, тому повторна спроба не повинна непомітно його перезаписувати.
* **Скасування вже скасованого запису з *іншим* `cancellation_reason`.** Та сама логіка: записану причину могли вже виправити, і повторна спроба не повинна її перезаписувати. Надішли записану причину ще раз або пропусти це поле.
* **Скасування після точки неповернення** — підтверджений забір крові, забране відправлення, відправлений або активований набір.

Три ендпоїнти навмисно не є безпечними для повторних спроб:

* [Підтвердити забір крові](https://docs.anivahealth.com/uk/api/appointments/confirm-blood-draw.md) — другий виклик повертає `409`.
* [Надіслати результати електронною поштою](https://docs.anivahealth.com/uk/api/appointments/email-results.md) (`POST /v1/appointments/{id}/results/email`) і [Надіслати результати електронною поштою](https://docs.anivahealth.com/uk/api/home-kit-orders/email-results.md) (`POST /v1/home-kit-orders/{id}/results/email`) — кожен виклик надсилає один лист. Повторна спроба після таймауту або `5xx` може надіслати клієнту дублікат.

## Операції запису, що щось створюють

П’ять ендпоїнтів приймають необов’язковий заголовок `Idempotency-Key`, до 255 символів:

* [Створити профіль](https://docs.anivahealth.com/uk/api/profiles/create-profile.md)
* [Створити запис](https://docs.anivahealth.com/uk/api/appointments/create-appointment.md)
* [Створити замовлення набору для домашнього тесту](https://docs.anivahealth.com/uk/api/home-kit-orders/create-home-kit.md)
* [Створити відправлення](https://docs.anivahealth.com/uk/api/shipments/create-shipment.md)
* [Завантажити документ](https://docs.anivahealth.com/uk/api/documents/upload-document.md)

Один ключ, чотири спроби, одне замовлення — відповідь залежить від того, коли ти повторюєш запит і чи збігається його тіло:

![Діаграма послідовності: дублікат, надісланий через 350 ms після першого запиту, отримує відповідь 409, поки той ще виконується; перший повертає 201; пізніша повторна спроба з тим самим ключем повертає те саме замовлення з позначкою Idempotent-Replayed; а той самий ключ зі зміненим тілом запиту повертає 409.](https://mintcdn.com/anivahealth/8KTut54iIoaIFYY2/images/idempotency-retry.svg?fit=max\&auto=format\&n=8KTut54iIoaIFYY2\&q=85\&s=617f6b19f473ee0fed9243004f932c19)

Ключі прив’язані до твого API-ключа **та** до ендпоїнта, тому вони ніколи не конфліктують із ключами іншого партнера або з тим самим ключем, використаним в іншому місці.

* **Той самий ключ, те саме тіло** → протягом 24 годин ти отримуєш початкову відповідь із позначкою `Idempotent-Replayed: true`. Порядок полів і пробіли не мають значення.
* **Той самий ключ, інше тіло** → `409`.
* **Порожній `Idempotency-Key`** → `400`, а не ігнорування.

### Коли ключ звільняється

Створення **не є атомарним** — `5xx` не означає, що нічого не було записано.

* **Запит завершився помилкою до того, як щось було створено** → ключ звільняється, тож ти можеш повторити спробу з ним.
* **Запит завершився помилкою після того, як щось було створено**, або **взагалі не повернув відповіді** → ключ залишається зайнятим, а повторні спроби отримують `409`. Отримай ресурс, щоб перевірити, чи він існує, а якщо ні — використай новий ключ.

> [!NOTE]
>
> Повторна відповідь повертає тіло відповіді, записане під час створення ресурсу — це знімок, а не
> актуальні дані. Якщо ресурс відтоді змінився, отримай його напряму.

### Деякі операції створення також мають природний ключ

Два ендпоїнти відхиляють дублікати самостійно, незалежно від заголовків:

* [Створити запис](https://docs.anivahealth.com/uk/api/appointments/create-appointment.md) дозволяє один запис на профіль, локацію та момент часу. Повторний запит повертає `409` із наявним `appointment_id`.
* [Створити профіль](https://docs.anivahealth.com/uk/api/profiles/create-profile.md) повертає `409`, якщо для `email` уже існує профіль. Якщо пропустити `email`, для кожного запиту генерується унікальний заповнювач, тому повторні запити *дійсно* створюють окремі профілі.

Коли спрацьовують обидва механізми, ти отримаєш відповідь `409` за природним ключем, і лише вона містить додаткове поле (`appointment_id` або дискримінатор `error_name`) — `409` через ідемпотентність містить лише `error`, тому читай ці поля обережно.


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