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

# Створити запис

> Запланувати запис на забір крові для профілю в пункті здачі аналізів

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

> [!NOTE]
>
> Профіль може мати щонайбільше **один** запис на ту саму локацію й час. Спроба створити запис
> на слот, який профіль уже займає, повертає `409` із наявним `appointment_id` замість другого
> запису — тож повторний або випадково продубльований запит ніколи не створить дублікат.
> Див. [Дублікати записів](#dublikati-zapisiv).

Надішли необов’язковий заголовок `Idempotency-Key`, щоб зробити повторний запит на створення безпечним — повторення з тим самим ключем повертає початкову відповідь замість створення другого запису. Див. [Ідемпотентність](https://docs.anivahealth.com/uk/concepts/idempotency.md).

Потребує дозволу `appointments_schedule`.

## Запит

### Параметри тіла запиту

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

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

**location\_id** `string` *required*

UUID локації здачі аналізів, де відбудеться забір крові. Переглянь [Список
локацій](https://docs.anivahealth.com/uk/api/locations/list-locations.md), щоб знайти доступні ID локацій.

**scheduled\_at** `string` *required*

Дата й час запису у форматі ISO 8601 (наприклад, `2026-05-15T10:30:00Z` або
`2026-05-15T12:30:00+02:00`). **Має містити позначення часового поясу** — або `Z`, або явне
зміщення на кшталт `+02:00`; дати й час без часового поясу відхиляються. Має бути в майбутньому.

Має точно збігатися з початком слоту в сітці локації, а в слоті ще мають бути вільні місця — спершу
перевір [Отримати доступність](https://docs.anivahealth.com/uk/api/locations/get-availability.md). Час поза сіткою повертає `400`;
заповнений слот повертає `409`. У локаціях під управлінням Aniva час також має бути щонайменше за 12 годин — див.
[Мінімальний час до запису](#minimalniy-chas-do-zapisu).

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

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

**draw\_method** `string`

Спосіб забору крові: `capillary` або `venous`. Пропусти це поле, щоб використати
`default_draw_method` локації. Цей спосіб має бути в `draw_methods` локації, інакше повернеться `400`.

## Відповідь

У разі успіху API повертає `201 Created` із новим записом.

**id** `string` *required*

Унікальний ідентифікатор запису (UUID).

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

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

**location\_id** `string`

UUID локації тестування, де відбувається забір крові.

**scheduled\_at** `string`

Заплановані дата й час запису в UTC (ISO 8601 із суфіксом `Z`, наприклад
`2026-05-15T10:30:00Z`). Може бути `null`.

**status** `string` *required*

Поточний статус запису. Одне зі значень: `pending`, `confirmed`, `blood_drawn` або `cancelled`.
Детальний статус готовності результатів аналізів можна отримати з [Отримати результати](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). Після забору крові — це фактично використаний спосіб.

**profile** `object` *required*

Профіль пацієнта, пов’язаний із цим записом.

**profile**

**id** `string`

Унікальний ідентифікатор профілю (UUID).

**handle** `string`

Псевдонім профілю або ім’я користувача. Може бути `null`.

**first\_name** `string`

Ім’я. Може бути `null`.

**last\_name** `string`

Прізвище. Може бути `null`.

**email** `string`

Електронна адреса. Може бути `null`.

**phone** `string`

Номер телефону у форматі E.164. Може бути `null`.

**sex** `integer`

Біологічна стать за ISO/IEC 5218. Може бути `null`.

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

Дата народження у форматі `YYYY-MM-DD`. Може бути `null`.

**height** `number`

Зріст у сантиметрах. Може бути `null`.

**weight** `number`

Вага в кілограмах. Може бути `null`.

**language** `string`

Бажана мова: один із 32 кодів у [Створити профіль](https://docs.anivahealth.com/uk/api/profiles/create-profile.md).

**transactional\_emails\_enabled** `boolean`

Чи отримує цей профіль транзакційні (програмні) листи. Може бути `null`.

**panels** `AppointmentPanel[]` *required*

Панелі, які зараз додано до цього запису. Порожній масив для щойно створених записів — додай через
[Додати панелі](https://docs.anivahealth.com/uk/api/appointments/add-panels.md). Деталі панелей (назву, біомаркери) можна переглянути через
[Список панелей](https://docs.anivahealth.com/uk/api/panels/list-panels.md).

**Поля доданої панелі**

**panel\_id** `string`

UUID панелі — звіряй зі [Списком панелей](https://docs.anivahealth.com/uk/api/panels/list-panels.md).

**added\_at** `string`

Часова мітка ISO 8601 першого додавання панелі до цього запису.

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

Окремі біомаркери, додані до цього запису поза межами будь-якої панелі. Порожній масив для щойно створених
записів — додай через [Додати окремі біомаркери](https://docs.anivahealth.com/uk/api/appointments/add-individual-biomarkers.md).
Звір кожен `biomarker_id` через [Список біомаркерів](https://docs.anivahealth.com/uk/api/biomarkers/list-biomarkers.md),
щоб отримати дані для відображення.

**Поля окремого біомаркера**

**biomarker\_id** `integer`

Ідентифікатор біомаркера — звіряй зі
[Списком біомаркерів](https://docs.anivahealth.com/uk/api/biomarkers/list-biomarkers.md).

**added\_at** `string`

Часова мітка ISO 8601 першого додавання біомаркера до цього запису.

**shipments** `AppointmentShipmentLink[]` *required*

Відправлення, прив’язані до цього запису, у порядку прив’язування від найдавнішого. Порожній масив для щойно створених записів —
прив’яжи через [Створити відправлення](https://docs.anivahealth.com/uk/api/shipments/create-shipment.md) (з `appointment_id`) або
[Прив’язати записи до відправлення](https://docs.anivahealth.com/uk/api/shipments/attach-appointments-to-shipment.md).

**Поля прив’язки відправлення**

**id** `string`

Ідентифікатор посилання на відправлення — звіряй через
[Отримати відправлення](https://docs.anivahealth.com/uk/api/shipments/get-shipment.md).

**added\_at** `string`

Часова мітка ISO 8601 першої прив’язки відправлення до цього запису.

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

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

## Мінімальний час до запису

Записи в локаціях під управлінням Aniva потрібно бронювати щонайменше за **12 годин** наперед; бронювання
в межах цього вікна повертає `400`. [Отримати доступність](https://docs.anivahealth.com/uk/api/locations/get-availability.md) уже приховує
ці слоти, тож усе, що ти отримуєш із цієї сітки, доступне для запису.

Локації, якими ти керуєш самостійно, не мають мінімального часу до запису — запис у той самий день і на місці працює без змін.

## Дублікати записів

Профіль може мати щонайбільше один нескасований запис на локацію й момент часу — одній людині не можна
зробити забір крові двічі в одному місці в один і той самий момент, скільки б крісел не було в локації.

Спроба створити запис на слот, який профіль уже займає, повертає `409` із полем
`appointment_id`, що вказує на вже наявний запис:

```json theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```

Обробляй це так, ніби запит уже виконано: отримай запис через
[Отримати запис](https://docs.anivahealth.com/uk/api/appointments/get-appointment.md), перенеси його через
[Оновити запис](https://docs.anivahealth.com/uk/api/appointments/update-appointment.md) або скасуй через
[Скасувати запис](https://docs.anivahealth.com/uk/api/appointments/cancel-appointment.md). Не повторюй запит на створення — він і надалі
повертатиме `409`.

Це робить повторні запити на створення безпечними: запит, повторно надісланий після тайм-ауту, або двічі надіслана форма
не зможуть створити два записи для одного пацієнта на той самий час.

> [!NOTE]
>
> `appointment_id` присутнє лише у відповіді `409` про дублікат. Відповідь `409` через брак місць — коли слот заповнений,
> бо його зайняли *інші* пацієнти — повертає лише `error`, і правильна дія в такому разі — обрати
> інший слот через [Отримати доступність](https://docs.anivahealth.com/uk/api/locations/get-availability.md).

## Відповіді з помилками

| Статус | Опис |
| - | - |
| `400` | Помилка валідації — наприклад, `scheduled_at` у минулому, менше ніж за 12 годин у локації, якою керує Aniva, не збігається з точним початком слота в розкладі локації або в локації немає контейнерів для `draw_method`. |
| `403` | Доступ заборонено — твій API-ключ не має доступу до цієї операції або встановлено `results_ready_emails` без доступу `results_view` до пацієнта. |
| `404` | Профіль або локацію не знайдено, або локація неактивна. |
| `409` | У цього профілю вже є запис у цій локації на цей час (містить `appointment_id`), слот заповнений, локація зачинена в цю дату, або `Idempotency-Key` використано повторно з іншим тілом запиту, чи його початковий запит ще не завершився. |
| `500` | Внутрішня помилка сервера. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/appointments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-05-15T10:30:00Z"
  }'
```

```json 201 theme={null}
{
  "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
  "scheduled_at": "2026-05-15T10:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "profile": {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": null
  },
  "panels": [],
  "individual_biomarkers": [],
  "shipments": [],
  "lab_codes": []
}
```

```json 400 theme={null}
{
  "error": "Appointments must be booked at least 12 hours in advance. Please pick a later time."
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 409 theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```


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