> ## 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/ru/api/appointments/cancel-appointment.md) | `200` с отменённой записью |
| [Отмена отправления](https://docs.anivahealth.com/ru/api/shipments/cancel-shipment.md) | `200` с отменённым отправлением |
| [Отмена заказа набора для домашнего теста](https://docs.anivahealth.com/ru/api/home-kit-orders/cancel-home-kit.md) | `200` с отменённым заказом |
| [Активация заказа набора для домашнего теста](https://docs.anivahealth.com/ru/api/home-kit-orders/activate-home-kit.md) | `200`, если время сбора то же самое |
| Удаление панелей или биомаркеров | `200`, независимо от того, были ли они ещё привязаны |

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

Три исключения вместо этого возвращают `409`:

* **Активация с *другим* `activated_at`.** Время сбора попадает в лабораторный отчёт, поэтому повторный запрос не должен незаметно его перезаписывать.
* **Отмена уже отменённой записи с *другим* `cancellation_reason`.** Логика та же: записанную причину с тех пор могли исправить, и повторный запрос не должен её перезаписывать. Отправь записанную причину ещё раз или не передавай её.
* **Отмена после точки невозврата** — подтверждённый забор крови, забранное отправление, отправленный или активированный набор.

Три эндпоинта намеренно не безопасны для повторных вызовов:

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

## Операции записи, которые что-то создают

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

* [Создание профиля](https://docs.anivahealth.com/ru/api/profiles/create-profile.md)
* [Создание записи](https://docs.anivahealth.com/ru/api/appointments/create-appointment.md)
* [Создание заказа набора для домашнего теста](https://docs.anivahealth.com/ru/api/home-kit-orders/create-home-kit.md)
* [Создание отправления](https://docs.anivahealth.com/ru/api/shipments/create-shipment.md)
* [Загрузка документа](https://docs.anivahealth.com/ru/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/ru/api/appointments/create-appointment.md) допускает одну запись на профиль, локацию и момент времени. Повторный запрос возвращает `409` с существующим `appointment_id`.
* [Создание профиля](https://docs.anivahealth.com/ru/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.