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

# Створити замовлення набору для домашнього тесту

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

Оформи замовлення набору для домашнього тесту для профілю пацієнта. Таке замовлення передбачає доставку поштою набору для самостійного тестування — Aniva надсилає набір на адресу доставки, пацієнт самостійно збирає зразок удома й відправляє його назад поштою. Це відрізняється від [запису](https://docs.anivahealth.com/uk/api/appointments/create-appointment.md), який є венозним забором крові в пункті тестування.

**Потрібна рівно одна панель.** Набір для домашнього тесту відповідає фізичному набору у співвідношенні 1:1 — панель і є цим набором — і замовлення потрапляє в чергу на пакування одразу після створення, тому склад має бути остаточним із самого початку. Ти все ще можеш змінити панель через [Оновлення замовлення набору для домашнього тесту](https://docs.anivahealth.com/uk/api/home-kit-orders/update-home-kit.md), поки замовлення має статус `pending`.

## Набори на заміну

Коли набір не може дати результатів — пацієнт не зміг заповнити пробірку, зразок надійшов із замалою кількістю матеріалу, лабораторія не змогла його проаналізувати — замов **заміну**, передавши `replaces_home_kit_order_id`.

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

Із цього випливають дві речі:

* **Панель успадковується.** Не передавай `panel_id`, і заміна отримає панель замовлення, яке вона замінює — саме те, що купив пацієнт, і те, як брендована коробка.
* **Ти обираєш, що повторити.** Передай `biomarker_ids` із маркерами, які не вдалося дослідити, і лабораторія повторить лише їх, тож у наборі надішлють тільки потрібні пробірки. Не передавай це поле, щоб повторити всю панель.

Маркери повторюються групами в межах панелі, а не по одному. Якщо вказати один маркер із групи, повториться вся група, адже неможливо оформити лабораторне замовлення, яке видає більше результатів, ніж було замовлено. Тому заміна для одного маркера може містити більше ніж один результат, а кількість пробірок може бути більшою, ніж можна очікувати за списком маркерів.

Одночасно в дорозі може бути лише одна заміна для одного набору.

> [!NOTE]
>
> Якщо твоя інтеграція створена до появи цих полів, Aniva також зчитує `metadata.original_kit_id` і
> `metadata.replacement_reason` під час створення та обробляє замовлення як заміну. Це єдине місце,
> де метадані інтерпретуються; це зроблено лише для підтримки тієї ранішої інтеграції, а поля вище
> завжди мають пріоритет. Передавай ці поля.

Статус `201` означає, що замовлення зафіксоване та буде передане на виконання — тобі більше нічого не потрібно робити, щоб набір спакували й відправили.

Потребує області доступу `home_kit_orders_manage`.

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

## Запит

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

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

UUID профілю пацієнта, для якого створюється замовлення набору для домашнього тесту.

**panel\_id** `string` *required*

UUID панелі з каталогу для замовлення. Рівно одна — набір для домашнього тесту відповідає фізичному
набору у співвідношенні 1:1, тож панель і є цим набором. Ідентифікатори панелей надає Aniva для
твого партнерського акаунта; див. [Список панелей](https://docs.anivahealth.com/uk/api/panels/list-panels.md). Необов’язкове поле для
заміни: типово використовується панель замовлення, яке ти замінюєш.

**replaces\_home\_kit\_order\_id** `string`

UUID замовлення набору для домашнього тесту, яке замінює це замовлення. Якщо передати це поле,
замовлення стане набором на заміну — див. [Набори на заміну](#nabori-na-zaminu) вище. Замовлення має
належати тому самому профілю й не повинно вже мати заміни в дорозі.

**replacement\_reason** `string`

Причина заміни одним реченням (наприклад, `Zu wenig Material, HbA1c nicht
    auswertbar`). Обов’язково, якщо ти передаєш `replaces_home_kit_order_id`, інакше ігнорується.
Щонайбільше 500 символів.

**biomarker\_ids** `integer[]`

Для заміни — маркери, які лабораторія повторює; зазвичай ті, за якими перший набір не зміг дати
результатів. Кожен має входити до складу замовлення, яке ти замінюєш; звірся зі [Списком
біомаркерів](https://docs.anivahealth.com/uk/api/biomarkers/list-biomarkers.md) із параметром `home_kit=true`. Не передавай це поле,
щоб повторити всю панель. Приймається лише разом із `replaces_home_kit_order_id` і не приймається
разом з іншим `panel_id`. Для цього не потрібен додатковий дозвіл: повторне дослідження маркерів,
які пацієнт уже оплатив, не є індивідуальним вибором.

**metadata** `object`

Твої власні пари ключ/значення, які повертаються без змін під час кожного читання й ніколи не
інтерпретуються Aniva. Використовуй це поле для зберігання власного номера замовлення, щоб
зіставляти дані без збереження наших ідентифікаторів. Щонайбільше 20 ключів; ключі мають
відповідати `[A-Za-z0-9_-]` і містити до 40 символів; значення — рядок, число або булеве значення,
рядки — до 500 символів; загалом до 16 384 байтів у серіалізованому вигляді. Ключі, що
починаються з `aniva_`, зарезервовані. Ніколи не додавай персональні або клінічні дані в
`metadata` — це поле не обробляється як дані пацієнта.

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

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

**delivery\_address** `object` *required*

Адреса для доставки набору поштою — один із двох форматів: `{ location_id }` із посиланням на відомий пункт тестування або вбудовані поля адреси (`name`, `street`, `city`, `postal_code`, `country_code`; необов’язкові — `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email`, ті самі поля, що й в API локацій). Передай рівно один варіант — посилання на локацію або вбудовану адресу, не обидва разом.

**адреса доставки**

> [tab] Посилання на локацію
>
> **location\_id** `string` *required*
>
> UUID відомого пункту тестування, куди потрібно доставити набір. Звірся зі [Списком
> локацій](https://docs.anivahealth.com/uk/api/locations/list-locations.md).

> [tab] Вбудована адреса
>
> **name** `string` *required*
>
> Ім’я отримувача, назва компанії або локації.
>
> **company\_name** `string`
>
> Компанія, яка приймає посилку для отримувача — сторона `c/o` або відділ.
>
> **street** `string` *required*
>
> Назва вулиці без номера будинку (наприклад, `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Номер будинку (наприклад, `118` або `12a`).
>
> **address\_line\_2** `string`
>
> Корпус, під’їзд або поверх.
>
> **city** `string` *required*
>
> **state** `string`
>
> Земля, штат або область. Необов’язково.
>
> **postal\_code** `string` *required*
>
> Поштовий індекс. Для німецької адреси (`country_code` `DE`) потрібно рівно 5 цифр, наприклад `10117`.
>
> **country\_code** `string` *required*
>
> Код ISO 3166-1 alpha-2 (дві літери, наприклад `DE`). Малі літери приймаються та зберігаються у
> верхньому регістрі.
>
> **phone** `string`
>
> Номер телефону отримувача з кодом країни (наприклад, `+4791234567`). Перевізник використовує його,
> щоб повідомити отримувача про посилку, наприклад що вона чекає у пункті видачі. Якщо не
> передати поле, перевізник не отримає номер телефону.
>
> **email** `string`
>
> Електронна адреса отримувача. Перевізник використовує її так само, як `phone`. Якщо не передати
> поле, перевізник не отримає електронної адреси.

> [!NOTE]
>
> **Packstation або Postfiliale (лише для Німеччини):** вкажи в `street` значення `Packstation`
> або `Postfiliale`, у `house_number` — тризначний номер станції, а в `address_line_2` — DHL
> Postnummer отримувача (6–10 цифр, пробіли дозволені). Без Postnummer посилку неможливо
> оформити. Postfach не підтримується.

## Відповідь

У разі успіху API повертає `201 Created` із новим замовленням набору для домашнього тесту.

**id** `string` *required*

Унікальний ідентифікатор замовлення набору для домашнього тесту (UUID).

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

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

**status** `string` *required*

Поточний статус замовлення набору для домашнього тесту. Одне зі значень: `pending`, `dispatched`,
`activated` або `cancelled`. Щойно створене замовлення починається зі статусу `pending`.

**delivery\_address** `object` *required*

Адреса для надсилання набору поштою — один із двох форматів: або `{ location_id }` із посиланням на відому локацію тестування, або вбудовані поля адреси (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` необов’язкові — ті самі поля, що й у API локацій). Укажи рівно один варіант — посилання на локацію або вбудовану адресу, не обидва.

**адреса доставки**

> [tab] Посилання на локацію
>
> **location\_id** `string` *required*
>
> UUID локації тестування, куди відправляється набір.

> [tab] Вбудована адреса
>
> **name** `string` *required*
>
> Ім’я отримувача, назва компанії або локації.
>
> **company\_name** `string`
>
> Компанія, що приймає посилку для отримувача — сторона `c/o` або відділ.
>
> **street** `string` *required*
>
> Назва вулиці без номера будинку (наприклад, `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Номер будинку (наприклад, `118` або `12a`).
>
> **address\_line\_2** `string`
>
> Корпус, під’їзд або поверх.
>
> **city** `string` *required*
>
> **state** `string`
>
> Штат або провінція. Необов’язково.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> Код ISO 3166-1 alpha-2 (дві літери, наприклад `DE`).
>
> **phone** `string`
>
> **email** `string`

**metadata** `object` *required*

Передані тобою пари ключ/значення. Завжди присутнє — `{}`, якщо нічого не вказано.

**replaces\_home\_kit\_order\_id** `string`

Замовлення набору для домашнього тесту, яке замінює це замовлення. `null` для звичайного замовлення.

**replacement\_reason** `string`

Передана тобою причина. `null` для звичайного замовлення.

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

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

**lab\_code** `string`

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

**activated\_at** `string` *required*

Часова позначка збору зразка, передана через [Активацію](https://docs.anivahealth.com/uk/api/home-kit-orders/activate-home-kit.md).
`null`, доки набір не активовано.

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

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

**updated\_at** `string`

Часова мітка ISO 8601 останнього оновлення. Може бути `null`.

**profile** `object` *required*

Профіль пацієнта, пов’язаний із цим замовленням набору для домашнього тесту.

**Профіль**

**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`.

**created\_at** `string`

Часова мітка ISO 8601 створення профілю.

**updated\_at** `string`

Часова мітка ISO 8601 останнього оновлення профілю. Може бути `null`.

**panels** `HomeKitOrderPanel[]` *required*

Панель, прив’язана до цього замовлення набору для домашнього тесту — та, яку ти передаєш у `panel_id`,
із позначкою часу створення замовлення. Завжди рівно одна. Деталі панелі (назву, біомаркери) дивись
у [Списку панелей](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** `HomeKitOrderIndividualBiomarker[]` *required*

Біомаркери, додані поза панеллю. Порожній список під час звичайного створення — набори для домашнього
тесту замовляються за панелями, а подальше редагування цього списку потребує дозволу
`home_kit_orders_individual_biomarker_selection`. У разі заміни містить передані тобою
`biomarker_ids`, які лабораторія виконує повторно.

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

**biomarker\_id** `integer`

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

**added\_at** `string`

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

**shipments** `HomeKitOrderShipmentLink[]` *required*

Посилки, пов’язані з цим замовленням набору для домашнього тесту, від найстарішої прив’язки до
найновішої. Завжди порожній список під час створення — отримуй повні дані про посилки через
[Список відправлень](https://docs.anivahealth.com/uk/api/shipments/list-shipments.md) із параметром `?home_kit_order_id=`.

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

**id** `string`

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

**added\_at** `string`

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

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

| Статус | Опис |
| - | - |
| `400` | Помилка валідації — наприклад, у `delivery_address` бракує поля або німецький поштовий індекс складається не з 5 цифр, `panel_id` не є коректним UUID, або для заміни не вказано `replacement_reason`. |
| `403` | Доступ заборонено — твій API-ключ не має доступу до цієї операції, профіль поза межами твоїх прав доступу або задано `results_ready_emails` без доступу `results_view` до пацієнта. |
| `404` | Профіль, панель або замовлення набору для домашнього тесту для заміни не знайдено. |
| `409` | Конфлікт — ключ `Idempotency-Key` уже використовувався з іншим тілом запиту, початковий запит ще не завершився або для набору, який ти замінюєш, уже в дорозі є заміна. |
| `422` | Панель не можна замовити як набір для домашнього тесту — для неї не налаштовано фізичний набір для відправлення. Для заміни: замовлення, яке ти замінюєш, належить іншому профілю, елемент `biomarker_ids` не входив до початкового замовлення або маркери передано разом з іншим `panel_id`. |
| `500` | Внутрішня помилка сервера. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
    "metadata": { "your_order_ref": "ORD-10482", "priority": true },
    "delivery_address": {
      "name": "Maria Schmidt",
      "company_name": "c/o Weber",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE",
      "phone": "+4930123456789",
      "email": "maria.schmidt@example.com"
    }
  }'
```

```bash Replacement kit theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "replaces_home_kit_order_id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
    "replacement_reason": "Too little material, HbA1c could not be analysed",
    "biomarker_ids": [103],
    "metadata": { "your_order_ref": "ORD-10482-R1" },
    "delivery_address": {
      "name": "Maria Schmidt",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE"
    }
  }'
```

```json 201 theme={null}
{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "status": "pending",
  "delivery_address": {
    "name": "Maria Schmidt",
    "company_name": "c/o Weber",
    "address_line_2": null,
    "street": "Friedrichstraße",
    "house_number": "123",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "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": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T09:45:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": { "your_order_ref": "ORD-10482", "priority": true },
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": null,
  "activated_at": null,
  "shipments": []
}
```

```json 400 theme={null}
{
  "error": "panel_id: panel_id must be a valid UUID"
}
```

```json 404 theme={null}
{
  "error": "Profile not found"
}
```

```json 409 theme={null}
{
  "error": "Idempotency-Key \"ORD-10482\" was already used with a different request body. Use a new key for a different request, or resend the original body to read back its result."
}
```


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