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

# Записи

> Как работают записи на забор крови в API Aniva для лабораторных анализов: бронирование, панели, биомаркеры, смена статусов и отмена.

Запись — это запланированный забор крови для профиля пациента в физической локации для сдачи анализов, который проводит медицинский специалист. Наборы, отправленные пациенту по почте, не являются записями — см. [Заказы наборов для домашнего теста](https://docs.anivahealth.com/ru/concepts/home-kit-orders.md).

## Поля

**id** `string` *required*

UUID, автоматически сгенерированный Aniva. Используй его, чтобы добавлять панели, подтверждать забор крови и получать результаты.

**profile\_id** `string` *required*

UUID профиля, к которому относится эта запись.

**location\_id** `string`

UUID локации для сдачи анализов, где пройдет забор крови. Наборы для домашнего теста не являются
записями — см. [Заказы наборов для домашнего теста](https://docs.anivahealth.com/ru/concepts/home-kit-orders.md).

**scheduled\_at** `string`

Запланированные дата и время забора крови в формате ISO 8601. Всегда возвращается в UTC с
суффиксом `Z` (например, `2026-04-15T08:30:00Z`). При создании или обновлении значение **должно
содержать обозначение часового пояса** (`Z` или явное смещение вроде `+02:00`) — даты и время без
часового пояса отклоняются. Время должно быть в будущем, а в локациях под управлением Aniva — не
менее чем за 12 часов ([минимальный срок до записи](https://docs.anivahealth.com/ru/api/appointments/create-appointment.md#minimalniy-srok-do-zapisi)).

**status** `string` *required*

Текущий статус жизненного цикла. Одно из значений: `pending`, `confirmed`, `blood_drawn` или `cancelled`. См.
[Жизненный цикл](#zhiznenniy-tsikl) ниже. Подробный статус готовности лабораторных результатов (`in_progress` или `completed`)
определяется через [Получить результаты](https://docs.anivahealth.com/ru/api/appointments/get-results.md); более детальный статус отправления (в пути,
доставлено и т. д.) — по каждому элементу встроенного массива `shipments` в
[Получить отправление](https://docs.anivahealth.com/ru/api/shipments/get-shipment.md).

**cancellation\_reason** `string`

Причина в свободной форме, указанная при отмене записи (например, неявка, поздняя отмена,
«Не удалось. Требуется повтор»). Имеет значение `null`, если `status` не равен `cancelled`.

**results\_ready\_emails** `string[]` *required*

Адреса в нижнем регистре, на каждый из которых приходит одно письмо, когда все результаты
лаборатории готовы. Пустой список, если отключено. См.
[Письма о готовности результатов](https://docs.anivahealth.com/ru/concepts/results.md#pisma-o-gotovnosti-rezultatov).

**draw\_method** `string` *required*

Способ забора крови: `capillary` (из пальца или плеча в микротейнеры) или `venous` (из вены
в пробирки). Используется способ, заданный для записи, иначе `default_draw_method` её
[локации](https://docs.anivahealth.com/ru/concepts/locations.md). После забора крови здесь указан фактически использованный способ.

**created\_at** `string` *required*

Временная метка создания записи в формате ISO 8601.

**updated\_at** `string`

Временная метка последнего обновления в формате ISO 8601. Null, если запись ни разу не обновлялась.

**lab\_codes** `string[]` *required*

Лабораторные коды (штрихкоды пробирок), записанные через [Подтвердить забор крови](https://docs.anivahealth.com/ru/api/appointments/confirm-blood-draw.md),
в порядке сканирования. Пусто, пока забор крови не подтвержден. При венозном заборе один код
напечатан на каждой пробирке; при капиллярном — свой код на каждом микротейнере. Результаты и
документы ссылаются на них через `lab_code`.

**panels** `object[]` *required*

Панели, добавленные к этой записи, в виде элементов `{ panel_id, added_at }`. См.
[Добавление панелей](#dobavlenie-paneley).

**individual\_biomarkers** `object[]` *required*

Отдельные биомаркеры, добавленные к этой записи, в виде элементов `{ biomarker_id, added_at }`. См.
[Отдельные биомаркеры](#otdelnye-biomarkery).

**shipments** `object[]` *required*

Отправления, привязанные к этой записи, в виде элементов `{ id, added_at }`, начиная с самой ранней привязки. См.
[Привязка отправлений](#privyazka-otpravleniy).

**profile** `object` *required*

Полный объект профиля пациента, встроенный в каждый ответ по записи. Ниже показана только часть
полей. Все поля перечислены в [Получить запись](https://docs.anivahealth.com/ru/api/appointments/get-appointment.md).

**свойства**

**id** `string`

UUID связанного профиля.

**first\_name** `string`

Имя пациента.

**last\_name** `string`

Фамилия пациента.

**email** `string`

Адрес электронной почты пациента.

**date\_of\_birth** `string`

Дата рождения в формате `YYYY-MM-DD`.

**sex** `integer`

Биологический пол по ISO/IEC 5218.

## Жизненный цикл

У записей есть четыре состояния жизненного цикла:

```
pending → confirmed → blood_drawn
   │          │             │
   └──────────┴─────────────┴──→ cancelled
```

| Статус | Значение |
| - | - |
| `pending` | Запись запланирована и ожидает подтверждения. Ее можно [обновить](https://docs.anivahealth.com/ru/api/appointments/update-appointment.md) или [отменить](https://docs.anivahealth.com/ru/api/appointments/cancel-appointment.md). |
| `confirmed` | Запись подтверждена (например, клиникой), но забор крови еще не проведен. Запись все еще можно обновить или отменить. |
| `blood_drawn` | Лабораторные коды переданы через [Подтвердить забор крови](https://docs.anivahealth.com/ru/api/appointments/confirm-blood-draw.md), и процесс лабораторного заказа запущен. Панели зафиксированы, запись нельзя перенести или отменить. |
| `cancelled` | Запись отменена. Конечный статус — дальнейшие переходы невозможны. |

> [!NOTE]
>
> Статус записи намеренно укрупнен — более детальный прогресс доступен
> через отдельные эндпоинты:
>
> * **Готовность лабораторных результатов** →
>   [Получить результаты](https://docs.anivahealth.com/ru/api/appointments/get-results.md) — поле `status` верхнего уровня имеет
>   значение `in_progress` или `completed`.
> * **Ход доставки отправления** (в пути, доставлено и т. д.) → перейди по каждому элементу
>   встроенного массива `shipments` в записи к [Получить отправление](https://docs.anivahealth.com/ru/api/shipments/get-shipment.md) —
>   у каждого отправления есть собственный `status` и журнал событий `status_updates`.
>
> Каждое изменение статуса отправляет [вебхук](https://docs.anivahealth.com/ru/concepts/webhooks.md) вида `appointment.*`, например
> `appointment.confirmed`. Новое время или локация отправляет `appointment.rescheduled`.

> [!WARNING]
>
> Подтверждение записи (перевод в статус `blood_drawn`) **необратимо**. Как только ты передашь
> лабораторный код (или коды), процесс лабораторного заказа запускается и отменить его нельзя.
> Обновление и отмена возможны только пока запись находится в статусе `pending` или `confirmed`.

## Список записей

Получи все записи, доступные твоему API-ключу:

```
GET /api/v1/appointments
```

При необходимости передай `?profile_id={uuid}`, чтобы отфильтровать по конкретному профилю. Без этого параметра применяется временное окно по умолчанию (за последние 2 месяца и на 1 месяц вперед).

## Обновление записи

До подтверждения забора крови ты можешь перенести запись или изменить локацию сдачи анализов:

```
PATCH /api/v1/appointments/{id}
```

Передай для обновления любую комбинацию полей `scheduled_at`, `location_id`, `draw_method` и `results_ready_emails`. Указывай только те поля, которые хочешь изменить.

## Способ забора крови

У каждой записи есть поле `draw_method`: `capillary` (из пальца или плеча в микротейнеры) или
`venous` (из вены в пробирки). Оно относится только к забору крови. Моча, мазки и другие
образцы, кроме крови, собираются одинаково при любом способе.

По умолчанию используется значение `default_draw_method` локации. Задай `draw_method` при создании или обновлении,
чтобы выбрать другой способ, или передай `null`, чтобы вернуться к значению локации по умолчанию. Этот способ должен
быть указан в `draw_methods` локации, а выбранные анализы должны быть с ним совместимы, иначе запрос вернет `400`.
После забора крови изменить его нельзя. После забора крови в `draw_method` хранится фактически использованный способ.

## Одна запись на профиль, локацию и время

У профиля может быть не более одной неотмененной записи на каждую пару `(location_id, scheduled_at)` —
у одного человека нельзя взять кровь дважды в одном месте и в одно время, независимо от того, сколько
параллельных записей принимает локация.

И [Создать запись](https://docs.anivahealth.com/ru/api/appointments/create-appointment.md), и
[Обновить запись](https://docs.anivahealth.com/ru/api/appointments/update-appointment.md) проверяют это правило и возвращают `409` с
полем `appointment_id`, указывающим на уже существующую запись. Воспринимай этот ответ как «запись
уже существует», а не как ошибку для повторной попытки: получи, перенеси или отмени указанную запись.

На практике это значит, что повторные запросы на создание безопасны. Запрос, который ты повторно отправляешь после сетевого таймаута
или который пользователь запускает дважды, сводится к одной записи вместо двух — так что тебе
никогда не придётся разбираться с дублями записей для одного и того же пациента постфактум.

> [!NOTE]
>
> Изменения разрешены только до забора крови — то есть пока запись находится в статусе `pending`
> или `confirmed`. Как только запись переходит в `blood_drawn` или отменена (`cancelled`), её
> уже нельзя изменить. Единственное исключение — `results_ready_emails`: ты всё ещё можешь
> изменить это поле отдельно после забора крови.

## Отмена записи

Отмени запись, которая больше не нужна:

```
DELETE /api/v1/appointments/{id}
```

Это переводит запись в статус `cancelled`. В ответе возвращается отменённая запись.

При желании передай в теле запроса `cancellation_reason` (до 500 символов), чтобы указать причину. Она
сохраняется в записи и возвращается как `cancellation_reason` при последующем чтении.

> [!NOTE]
>
> Отмена разрешена только до забора крови — то есть пока запись находится в статусе `pending` или
> `confirmed`. Записи, которые уже перешли в `blood_drawn`, отменить нельзя.

## Добавление панелей

Перед подтверждением забора крови добавь панели анализов крови, которые ты хочешь выполнить, вызвав:

```
POST /api/v1/appointments/{id}/panels
```

Передай массив UUID панелей в поле `panel_ids`. Идентификаторы панелей предоставляет Aniva для твоего партнёрского аккаунта.

> [!NOTE]
>
> Панели нужно добавить до забора крови — то есть пока запись находится в статусе `pending` или
> `confirmed`. После того как запись перейдёт в `blood_drawn`, ты уже не сможешь добавлять или
> менять панели.

## Удаление панелей

Если тебе нужно удалить панели до забора крови, вызови:

```
DELETE /api/v1/appointments/{id}/panels
```

Передай массив UUID панелей в поле `panel_ids`. Удаление идемпотентно: панель, которая не привязана, игнорируется.

> [!NOTE]
>
> Как и добавление панелей, удаление разрешено только до забора крови — то есть пока запись
> находится в статусе `pending` или `confirmed`. После того как запись перейдёт в `blood_drawn`,
> удалить панели уже нельзя.

## Отдельные биомаркеры

Ты можешь привязать к записи отдельные биомаркеры как самостоятельные анализы, вне готовых панелей. Это удобно, когда специалисту нужен индивидуальный набор вместо готового пакета. Привязанные биомаркеры возвращаются в ответе записи в виде массива `individual_biomarkers` (на одном уровне с `panels`). Решения по маршрутизации принимаются дальше в конвейере логистики заказов на основе сопоставления каждого биомаркера с лабораториями.

Добавь биомаркеры (идемпотентно — уже привязанные биомаркеры сохраняются):

```
PATCH /api/v1/appointments/{id}/biomarkers
```

Удали биомаркеры (идемпотентно — непривязанные биомаркеры игнорируются):

```
DELETE /api/v1/appointments/{id}/biomarkers
```

Оба эндпоинта принимают массив `biomarker_ids` и проверяют итоговый набор по правилам полноты каждой лаборатории — заказ, который нельзя корректно оформить (например, соотношение CRP/HDL без CRP и HDL), возвращает `400` с биомаркерами, которые тебе нужно добавить, и ничего не сохраняет. Используй [Список биомаркеров](https://docs.anivahealth.com/ru/api/biomarkers/list-biomarkers.md), чтобы узнать идентификаторы биомаркеров.

> [!NOTE]
>
> Как и изменения панелей, отдельные биомаркеры можно добавлять или удалять только до забора
> крови — то есть пока запись находится в статусе `pending` или `confirmed`. Как только запись
> переходит в `blood_drawn`, пользовательский снимок фиксируется.

## Предпросмотр необходимых контейнеров

После добавления панелей или отдельных биомаркеров посмотри физические контейнеры для биоматериала, которые понадобятся для сбора образцов:

```
GET /api/v1/appointments/{id}/preview
```

Массив `containers` в ответе содержит тип, название, цвет крышки, объём, артикул производителя и количество для каждого необходимого контейнера. Это помогает специалистам подготовить нужные материалы перед забором крови. Ответ также содержит объект `pricing` — общий счёт по всей корзине записи (сработавшие позиции, привязанные панели и по одной строке на каждый предоставляемый биомаркер с ценой по твоему тарифу и розничной ценой рядом; см. [Ценообразование](https://docs.anivahealth.com/ru/concepts/pricing.md)), который заполняется, когда к записи привязаны анализы и у твоего ключа есть разрешение `prices_view`, иначе `null`. Поле `routing` намеренно никогда не раскрывается и всегда равно `null`.

> [!NOTE]
>
> Предпросмотр отражает привязанные на данный момент панели и биомаркеры. Если ты добавишь или
> удалишь панели после предпросмотра, вызови эндпоинт предпросмотра снова, чтобы получить обновлённый
> список необходимых контейнеров.

## Подтверждение забора крови

После забора крови отправь лабораторные коды (штрихкоды пробирок), чтобы запустить конвейер лабораторных заказов:

```
POST /api/v1/appointments/{id}/confirm
```

Отправь `lab_code`, если на каждой пробирке напечатан один и тот же код (венозный забор), или
`lab_codes` с одним элементом на каждый код — для каждого с теми `panel_ids`, которые он охватывает —
если каждая панель собирается в отдельные пробирки со своим кодом (капиллярный забор). Тогда каждая
панель становится отдельным направлением в лабораторию под своим кодом. Коды возвращаются в поле
`lab_codes` записи.

При капиллярном заборе кровь распределяется по микротейнерам. Сначала идут панели в порядке
бронирования. Затем отдельные биомаркеры заполняют свободное место в микротейнерах панелей.
Если им нужно больше места, открываются новые микротейнеры. Мы распределяем их равномерно.
Каждый микротейнер вмещает не более 150 µl отдельных биомаркеров. Запросы на изменение панелей
или биомаркеров возвращают `400`, если итоговый набор нарушает это правило.

Это переводит запись в статус `blood_drawn` и запускает лабораторную обработку. Это действие необратимо.

## Забор отправления

> [!WARNING]
>
> Эндпоинт `POST /api/v1/appointments/pickup` **удалён** вместе со статусом записи
> `shipment_picked_up`. Теперь он возвращает `405 Method Not Allowed`, потому что этот путь
> попадает на маршрут получения записи по идентификатору. На последнем этапе этот эндпоинт работал
> как заглушка, которая принимала запрос и ничего не делала, поэтому его удаление не меняет
> поведения, на которое ты рассчитывал.

Чтобы отслеживать дальнейшие этапы после забора крови, переходи по каждому элементу встроенного
массива `shipments` записи в [Получение отправления](https://docs.anivahealth.com/ru/api/shipments/get-shipment.md) — у каждого
отправления есть собственный `status` и история `status_updates`.

## Привязка отправлений

Запись может быть связана с одним или несколькими отправлениями (и наоборот — это связь
многие ко многим). Текущий набор связей возвращается напрямую с обеих сторон:

* в записи — как массив `shipments` с элементами `{ id, added_at }`;
* в отправлении — как массив `appointments` с элементами `{ id, added_at }`.

В обоих массивах первыми идут самые ранние связи. Каждый `id` ссылается на канонический эндпоинт
с подробной информацией ([Получение отправления](https://docs.anivahealth.com/ru/api/shipments/get-shipment.md) /
[Получение записи](https://docs.anivahealth.com/ru/api/appointments/get-appointment.md)) для получения полного объекта.

Отправления привязываются при создании через поле `appointment_id` в эндпоинте
[Создание отправления](https://docs.anivahealth.com/ru/api/shipments/create-shipment.md). После создания управляй связями со стороны
отправления через эндпоинты [Привязка записей к отправлению](https://docs.anivahealth.com/ru/api/shipments/attach-appointments-to-shipment.md) и
[Отвязка записей от отправления](https://docs.anivahealth.com/ru/api/shipments/detach-appointments-from-shipment.md); каждый из них
возвращает обновлённый список записей для этого отправления. Чтобы получить полные данные по
посылкам записи, используй [Список отправлений](https://docs.anivahealth.com/ru/api/shipments/list-shipments.md) с `?appointment_id=`.

Правило изменения: связи можно создавать или удалять, если ЛИБО

* по записи уже прошёл забор крови (`blood_drawn`), либо
* отправление было создано менее 24 часов назад.

Вне этого окна связь заблокирована, чтобы исторические данные оставались неизменными.

## Получение лабораторных результатов

Когда лаборатория обработает образцы крови, получи клинические и генетические результаты:

```
GET /api/v1/appointments/{id}/results
```

Ответ содержит запланированные тесты (статус `planned`) наряду с полученными результатами, поэтому ты можешь
отслеживать, что еще ожидается. Поле верхнего уровня `status` остается `in_progress`, пока не закроются все заявки,
а затем меняется на `completed` (или `fault`, если ни по одной из них не пришли данные) — используй его, чтобы определить,
завершена ли лабораторная работа по записи. [Вебхук](https://docs.anivahealth.com/ru/concepts/webhooks.md) `appointment.results.completed`
сообщит тебе, когда это произойдет, поэтому опрашивать API не нужно. Массив
`submissions` разбивает эти данные по каждому лабораторному направлению, и у каждого есть свой `lab_code`. Каждый
полученный результат и документ содержит `lab_code`, под которым он был оформлен. Ссылки на PDF-отчеты лаборатории
находятся в массиве `documents` — используй `GET /api/v1/documents/{id}`, чтобы скачать их.

## Пример записи

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "scheduled_at": "2026-04-15T08:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": null,
  "profile": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "handle": null,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1990-06-15",
    "height": 170,
    "weight": 62,
    "language": "en",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:55:00Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T10:05:00Z"
    }
  ],
  "individual_biomarkers": [
    {
      "biomarker_id": 42,
      "added_at": "2026-04-01T10:07:00Z"
    }
  ],
  "shipments": [
    {
      "id": "P2611194821",
      "added_at": "2026-04-15T07:00:00Z"
    }
  ],
  "lab_codes": []
}
```


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