> ## 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/uk/concepts/home-kit-orders.md).

## Поля

**id** `string` *required*

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

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

UUID профілю, до якого належить цей запис.

**location\_id** `string`

UUID локації тестування, де відбудеться забір крові. Набори для домашнього тесту не є записами —
див. [Замовлення наборів для домашнього тесту](https://docs.anivahealth.com/uk/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/uk/api/appointments/create-appointment.md#minimalniy-chas-do-zapisu)).

**status** `string` *required*

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

**cancellation\_reason** `string`

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

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

Електронні адреси в нижньому регістрі, на кожну з яких надходить один лист, коли всі лабораторні результати стають остаточними. Порожньо, якщо вимкнено. Див.
[Листи про готовність результатів](https://docs.anivahealth.com/uk/concepts/results.md#listi-pro-gotovnist-rezultativ).

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

Спосіб забору крові: `capillary` (із пальця або плеча в мікротейнери) або `venous` (із вени
у пробірки). Це спосіб, указаний у записі, або `default_draw_method` його
[локації](https://docs.anivahealth.com/uk/concepts/locations.md). Після забору крові — це фактично використаний спосіб.

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

Часова мітка ISO 8601 створення запису.

**updated\_at** `string`

Позначка часу ISO 8601 останнього оновлення. Null, якщо запис ніколи не оновлювався.

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

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

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

Панелі, додані до цього запису, у вигляді елементів `{ panel_id, added_at }`. Див.
[Додавання панелей](#dodavannya-paneley).

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

Окремі біомаркери, додані до цього запису, у вигляді елементів `{ biomarker_id, added_at }`. Див.
[Окремі біомаркери](#okremi-biomarkeri).

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

Відправлення, пов’язані з цим записом, у вигляді елементів `{ id, added_at }`, спочатку найдавніший
зв’язок. Див. [Пов’язування відправлень](#priv-yazuvannya-vidpravlen).

**profile** `object` *required*

Повний об’єкт профілю пацієнта, вбудований у кожну відповідь запису. Нижче наведено лише частину
полів. Повний список є в [Отримати запис](https://docs.anivahealth.com/uk/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/uk/api/appointments/update-appointment.md) або [скасувати](https://docs.anivahealth.com/uk/api/appointments/cancel-appointment.md). |
| `confirmed` | Час запису підтверджено (наприклад, медичною практикою), але забір крові ще не проведено. Усе ще можна оновити або скасувати. |
| `blood_drawn` | Лабораторні коди передано через [Підтвердити забір крові](https://docs.anivahealth.com/uk/api/appointments/confirm-blood-draw.md), і процес лабораторного замовлення запущено. Панелі зафіксовано, а запис не можна перенести або скасувати. |
| `cancelled` | Запис скасовано. Кінцевий стан — подальших переходів немає. |

> [!NOTE]
>
> Набір статусів запису навмисно узагальнений — детальніші етапи доступні через окремі
> ендпоінти:
>
> * **Готовність лабораторних результатів** →
>   [Отримати результати](https://docs.anivahealth.com/uk/api/appointments/get-results.md) — поле `status` верхнього рівня має
>   значення `in_progress` або `completed`.
> * **Етапи відправлення** (у дорозі, доставлено тощо) → перейди за кожним елементом вбудованого
>   масиву `shipments` у записі до [Отримати відправлення](https://docs.anivahealth.com/uk/api/shipments/get-shipment.md) — кожне
>   відправлення має власний `status` і журнал подій `status_updates`.
>
> Кожна зміна статусу надсилає [вебхук](https://docs.anivahealth.com/uk/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/uk/api/appointments/create-appointment.md), і для
[Оновити запис](https://docs.anivahealth.com/uk/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`. ID панелей надає 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/uk/api/biomarkers/list-biomarkers.md), щоб знайти ID біомаркерів.

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

## Попередній перегляд вимог до контейнерів

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

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

Масив `containers` у відповіді містить тип, назву, колір кришки, об’єм, артикул виробника та кількість для кожного потрібного контейнера. Це допомагає фахівцям підготувати правильні матеріали перед забором крові. Відповідь також містить об’єкт `pricing` — повний рахунок за весь кошик запису (позиції, що спрацювали, прикріплені панелі та по одному рядку на кожен наданий біомаркер із ціною за твоїм прайсом і роздрібною ціною поруч; див. [Ціноутворення](https://docs.anivahealth.com/uk/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`, оскільки шлях потрапляє на маршрут запису за ID.
> На останньому етапі цей ендпоінт працював як заглушка, що приймала виклик і нічого не робила,
> тож його видалення не змінює жодної поведінки, на яку ти покладаєшся.

Щоб відстежувати перебіг після забору крові, перейди за кожним елементом із вбудованого масиву
`shipments` у записі до [Отримати відправлення](https://docs.anivahealth.com/uk/api/shipments/get-shipment.md) — кожне відправлення
має власний `status` та історію `status_updates`.

## Прив’язування відправлень

Запис можна прив’язати до одного або кількох відправлень (і навпаки — зв’язок має тип
багато-до-багатьох). Поточний набір зв’язків відображається безпосередньо з обох боків:

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

Обидва масиви відсортовані від найдавнішого зв’язку до найновішого. Кожен `id` посилається на
канонічний ендпоінт із деталями ([Отримати відправлення](https://docs.anivahealth.com/uk/api/shipments/get-shipment.md) /
[Отримати запис](https://docs.anivahealth.com/uk/api/appointments/get-appointment.md)) для отримання повних даних.

Відправлення прив’язуються під час створення через поле `appointment_id` у
[Створити відправлення](https://docs.anivahealth.com/uk/api/shipments/create-shipment.md). Після створення керуй зв’язками з боку
відправлення за допомогою [Прив’язати записи до відправлення](https://docs.anivahealth.com/uk/api/shipments/attach-appointments-to-shipment.md)
та [Відв’язати записи від відправлення](https://docs.anivahealth.com/uk/api/shipments/detach-appointments-from-shipment.md); кожен із
них повертає оновлений список записів для цього відправлення. Щоб прочитати повні дані про посилки
запису, використовуй [Список відправлень](https://docs.anivahealth.com/uk/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/uk/concepts/webhooks.md)
`appointment.results.completed` повідомить тебе, коли це станеться, тож опитування не потрібне. Масив
`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.