> ## 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 API: значення біомаркерів, референтні діапазони, лабораторні звіти та вебхуки результатів.

Після підтвердження забору крові та обробки зразків у лабораторії результати стають доступними в записі. Результати можна отримати через `GET /api/v1/appointments/{id}/results`, і вони містять клінічні результати біомаркерів, генетичні результати біомаркерів і документи лабораторних звітів для завантаження.

## Статус результатів

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

| Статус | Значення |
| - | - |
| `in_progress` | Деякі заявки ще обробляються в лабораторії. |
| `completed` | Усі заявки закрито, і щонайменше за однією надійшли результати. |
| `fault` | Усі заявки завершилися з помилкою без результатів. Більше результатів не очікується. |

Окремі результати у відповіді мають власний статус (див. нижче), тому ти можеш показувати часткові результати, поки загальний статус ще `in_progress`.

Щоб дізнаватися про зміни результатів, підпишись на [вебхуки](https://docs.anivahealth.com/uk/concepts/webhooks.md). `appointment.results.updated` спрацьовує щоразу при зміні тіла результатів, а `appointment.results.completed` — коли статус верхнього рівня переходить у `completed`. Замовлення наборів для домашнього тесту надсилають ті самі події з префіксом `home_kit_order.`. Кожна подія містить URL для завантаження результатів. Ти все одно можеш опитувати цей ендпоінт для звіряння.

Масив `submissions` деталізує статус верхнього рівня для кожного лабораторного направлення. Забір крові, що охоплює кілька пробірок або кілька лабораторій, має кілька елементів, кожен зі своїм `lab_code` (штрихкодом пробірки), під яким його подано, та власним статусом `in_progress` / `completed` / `fault`. Елемент зі статусом `fault` був відхилений або скасований у лабораторії й ніколи не поверне результатів: часто зразок передають до іншої лабораторії, яка створює власний елемент. Статус верхнього рівня стає `completed`, коли кожен елемент закрито і щонайменше один повернув результати. Кожен отриманий результат і кожен документ містить той самий `lab_code`, тож ти можеш визначити, з якої пробірки надійшло значення.

## Клінічні результати

Клінічні результати — це стандартні вимірювання біомаркерів крові, як-от рівень вітаміну D, холестерин, гормони щитоподібної залози тощо.

Кожен клінічний результат містить:

* **`id`** — ідентифікатор рядка лабораторного результату. Він залишається незмінним, коли лабораторія виправляє цей рядок, тож використовуй його для upsert. `null` для результату зі статусом `planned`.
* **`biomarker_name`** і **`category`** — що вимірювалося та його група (наприклад, вітаміни, гормони).
* **`lab_code`** — лабораторний код (штрихкод пробірки), під яким подано результат; один із лабораторних кодів замовлення. `null` для результату зі статусом `planned` і для результатів, які лабораторія передала без коду.
* **`value`** і **`value_operator`** — фактичне вимірювання. Оператор має значення `eq` (дорівнює) для точних значень або `lt`/`gt`, коли лабораторія повідомляє значення нижче чи вище діапазону вимірювання.
* **`unit`** — одиниця вимірювання (наприклад, ng/mL, µIU/mL).
* **`reference_range_lab`** — нормальні та оптимальні межі min/max, які повідомила лабораторія для цього результату, переведені в ту саму шкалу, що й `value`. Межа, яку лабораторія залишає відкритою, має значення `null`, тому односторонній інтервал, як-от `< 50`, надходить як `normal_min: null, normal_max: 50`. Кожен результат містить інтервал, за яким його вимірювали, тож пацієнт із результатами з кількох заборів крові чи лабораторій отримує правильний інтервал для кожного результату.
* **`reference_range_lab_absent_reason`** — причина, чому `reference_range_lab` має значення `null`. Має значення `null`, коли діапазон наявний, а також для результату зі статусом `planned`. Див. [Коли немає лабораторного діапазону](#koli-nemaye-laboratornogo-diapazonu).
* **`aniva_range`** — значення для порівняння, які зібрала Aniva, у тій самій шкалі, що й `value`. Вони залежать від віку, статі та тижня вагітності. `normal_*` — це загальний діапазон. `optimal_*` — вужчий діапазон. Ці значення мають лише інформаційний характер. Вони не є медичною порадою, діагнозом чи оцінкою результату. Aniva не встановлює позначок щодо них. Використовуй `reference_range_lab` як стандарт для результату. `null`, якщо твій ключ не має scope `aniva_ranges_view` або в Aniva немає значень для цього біомаркера.
* **`tested_at`** — дата проведення аналізу.
* **`comment`** — текстова примітка лабораторії у довільній формі до цього конкретного результату (наприклад, пояснення щодо референтного діапазону, попередження про якість зразка). `null`, якщо лабораторія її не додала.
* **`status_reason`** — чому результат зі статусом `likely_wrong` є сумнівним або результат зі статусом `fault` чи `undeliverable` непридатний. `null` для всіх інших статусів. Відрізняється від `comment`, який є власною приміткою лабораторії й часто порожній для результатів із помилкою.
* **`origin`** — хто надав документ, із якого взято значення; ті самі значення, що й для `origin` документа нижче. Значення із завантаженого документа (`member_upload`, `staff_upload`, `partner_upload`) отримано шляхом зчитування файлу системою Aniva, а не з лабораторного звіту: звір його з файлом перед клінічним використанням. `null` для результату зі статусом `planned`.
* **`lab_reported`** — власний рядок звіту лабораторії-виконавця, дослівно та без конвертації. Див. нижче.

### Діапазони Aniva

`aniva_range` містить значення для порівняння, які Aniva зібрала з опублікованих джерел та
власного відбору. Діапазони залежать від віку, статі та тижня вагітності.
`sources` перелічує опубліковані джерела, які Aniva зафіксувала для цих значень. Список може бути порожнім.

> [!WARNING]
>
> Ці значення мають загальний інформаційний характер. Вони не є медичною порадою, діагнозом,
> медичним висновком чи оцінкою результату. Aniva не надає їх як медичний
> виріб. Aniva не порівнює з ними результати й не встановлює щодо них жодних позначок.
> Стандартом для результату залишаються `reference_range_lab` та оцінка лікаря.

Правила для твого продукту:

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

Щоб отримати доступ, підпиши коротку угоду щодо діапазонів Aniva. Після цього ми додамо
scope `aniva_ranges_view` до твого ключа. Значення можуть змінюватися без попередження.

### Нормалізовані значення порівняно з власним рядком лабораторії

`value`, `unit` і `reference_range_lab` нормалізовано: ми переводимо кожне вимірювання в канонічну одиницю біомаркера та передаємо його під власною назвою біомаркера, щоб той самий аналіт можна було порівнювати між лабораторіями й у часі. Це те, що тобі потрібно для відстеження динаміки та порівняння між лабораторіями, і водночас це не те, що лікар бачить у PDF-звіті лабораторії — лужна фосфатаза, надрукована як `48 U/l (40 - 129)`, надходить до тебе як `0.8 µkat/L`.

`lab_reported` містить цей надрукований рядок поруч: назву та код аналіту від лабораторії, значення й одиницю вимірювання в тому вигляді, як їх надруковано, референтний інтервал у вигляді тексту (`< 50`, `> 55`, `40 - 129`) і як власні неконвертовані межі лабораторії, а також позначку відхилення, статус результату та примітку.

Використовуй `lab_reported`, коли людина звіряє твої дані з лабораторним звітом, а канонічні поля — для всіх обчислень. Заповнюються лише ті поля, які лабораторія справді надіслала; у `lab_reported` нічого не визначається автоматично, не підставляється за замовчуванням і не конвертується, а весь об’єкт має значення `null`, якщо ми не маємо вихідного запису для результату.

### Коли немає лабораторного діапазону

Коли `reference_range_lab` має значення `null`, поле `reference_range_lab_absent_reason` пояснює чому:

| Значення | Опис | Що показувати |
| - | - | - |
| `not_provided` | Діапазону немає. Лабораторія не надіслала жодного. | «Не застосовується» |
| `lab_text_only` | Лабораторія надрукувала лише текст, наприклад цільове значення, рівень ризику чи діапазон для певного етапу життя. | Текст із `lab_reported.reference_range` |
| `not_measured` | Результат має статус `undeliverable`, тому немає значення для порівняння. | Значення `status_reason` |

Деякі лабораторії друкують цільове значення або рівень ризику замість референтного діапазону, наприклад
`Ziel: <200. >240 hoch` або `<5.7 neg >=6.5 pos`. Вони не потрапляють у `reference_range_lab`, тому його
межі мають значення `null`, а причина — `lab_text_only`. Показуй надрукований текст дослівно.

Односторонній діапазон, як-от `< 20`, є діапазоном. Він надходить у `reference_range_lab` з однією межею
`null`, а причина має значення `null`. Залишай відкриту сторону відкритою, коли показуєш його.

### Статуси клінічних результатів

| Статус | Значення |
| - | - |
| `planned` | Аналіз замовлено, але результати з лабораторії ще не надійшли. |
| `received` | Лабораторія повернула результат. |
| `corrected` | Фахівець переглянув і виправив значення, передане лабораторією. |
| `likely_wrong` | Автоматична перевірка Aniva або учасник сумнівається у значенні. Не підтверджено: не показуй його як висновок без перевірки. Див. `status_reason`. |
| `fault` | Лабораторія передала результат, помилковість якого підтверджено — **не використовуй клінічно**. `value` досі містить хибне число; див. `status_reason`. |
| `undeliverable` | Лабораторія не змогла отримати значення. Поле `value` дорівнює `null`; див. `status_reason`. |

> [!TIP]
>
> Коли показуєш результати пацієнтам, використовуй поле `value` напряму — воно вже містить
> виправлене значення, якщо таке є.

> [!WARNING]
>
> Ніколи не показуй результат зі статусом `fault` як висновок — його поле `value` заповнене, але підтверджено хибне.

## Генетичні результати

Генетичні результати — це дані на рівні генів, отримані з аналізу ДНК. Кожен результат відповідає певному гену (наприклад, APOE, MTHFR) і містить:

* **`id`** — ідентифікатор рядка лабораторного результату. Він залишається незмінним, коли лабораторія виправляє цей рядок, тож використовуй його для upsert. `null` для результату зі статусом `planned`.
* **`gene`** — символ гена.
* **`lab_code`** — лабораторний код (штрихкод пробірки), під яким подано результат. `null` для результату зі статусом `planned` і для результатів, які лабораторія передала без коду.
* **`genotype`** — виявлений генотип (наприклад, E3/E4).
* **`clinical_significance`** — класифікація результату за критеріями ACMG.
* **`risk_description`** — зрозуміле пояснення того, що означає генотип.
* **`comment`** — текстова примітка лабораторії у довільній формі до цього конкретного результату. `null`, якщо лабораторія її не додала.
* **`status_reason`** — чому результат зі статусом `likely_wrong` є сумнівним або результат зі статусом `fault` чи `undeliverable` непридатний. `null` для всіх інших статусів.
* **`origin`** — хто надав документ, із якого взято значення, як і в клінічних результатах.
* **`variants`** — конкретні виявлені генетичні варіанти, кожен із деталізацією на рівні SNV.

### Значення клінічної значущості

| Значення | Категорія |
| - | - |
| `pathogenic`, `likely_pathogenic` | Спричиняє захворювання або ймовірно спричиняє захворювання |
| `uncertain` | Варіант невизначеного значення (VUS) |
| `likely_benign`, `benign` | Не спричиняє захворювання |
| `high_risk`, `moderate_risk`, `low_risk` | Класифікація рівня ризику |
| `protective` | Захисний варіант |
| `drug_response`, `poor_metabolizer`, `rapid_metabolizer` | Фармакогеномні дані |

### Статуси генетичних результатів

| Статус | Значення |
| - | - |
| `planned` | Аналіз замовлено, але результати ще не надійшли. |
| `received` | Лабораторія надіслала результат. |
| `likely_wrong` | Автоматична перевірка Aniva або учасник сумнівається в генотипі. Не підтверджено. Див. `status_reason`. |
| `fault` | Лабораторія надіслала підтверджено хибний результат — **не використовуй у клінічній практиці**. Див. `status_reason`. |
| `undeliverable` | Лабораторія не змогла визначити генотип. Див. `status_reason`. |

### Структура варіанта

Кожен генетичний результат має масив `variants`. Кожен варіант містить:

* **`name`** — поширена назва (наприклад, APOE E4).
* **`clinical_significance`** — значущість на рівні варіанта (може відрізнятися від значущості на рівні гена).
* **`conditions`** — пов’язані захворювання/стани з описами.
* **`snvs`** — базові однонуклеотидні варіанти, кожен із `rs_id`, `allele`, `reference_allele` та необов’язковою нотацією HGVS.

## Документи

Масив `documents` у відповіді з результатами містить посилання на файли лабораторних звітів для завантаження. Кожен документ має:

* **`id`** — UUID файлу. Передай його в `GET /api/v1/documents/{id}`, щоб завантажити файл.
* **`file_name`** — назва файлу, та сама, що надсилається під час завантаження (наприклад, `20260405 - Quade Befund - 7642001234.pdf`).
* **`original_file_name`** — назва файлу точно в тому вигляді, як її передала лабораторія або той, хто завантажив файл (наприклад, `7642001234_B0012_FA_E.pdf`).
* **`origin`** — хто передав файл: `lab`, `member_upload`, `staff_upload` або `partner_upload` (завантажено тобою через [Завантажити документ](https://docs.anivahealth.com/uk/api/documents/upload-document.md)).
* **`content_type`** — медіатип файлу (наприклад, `application/pdf`). Більшість звітів — це файли PDF. Завантажені скани можуть бути зображеннями або файлами CSV.
* **`etag`** — версія вмісту файлу; змінюється щоразу, коли змінюються байти. Збережи її та завантажуй файл повторно лише після зміни. Це стандартний тег сутності HTTP, який використовують S3 або Google Cloud Storage.
* **`size_bytes`** — розмір файлу в байтах.
* **`lab_code`** — лабораторний код (штрихкод пробірки), до якого належить звіт; `null`, якщо лабораторія його не вказала.

> [!NOTE]
>
> Доступ до документів перевіряється за профілем, якому належить документ.

## Надсилання результатів клієнту електронною поштою

Ти можеш повідомити клієнта електронною поштою, що результати готові. Виклич
[Надіслати результати](https://docs.anivahealth.com/uk/api/appointments/email-results.md) для запису або
[Надіслати результати](https://docs.anivahealth.com/uk/api/home-kit-orders/email-results.md) для замовлення набору для домашнього тесту. Кожен виклик надсилає один лист.
Виклики не дедуплікуються.

* Лист надсилається на `email` профілю. Адреса-заглушка `@aniva.email` відхиляється.
* У листі показано назву й логотип основної групи профілів для цього профілю.
* Лист надсилається мовою `language` профілю, типово — англійською.
* Задай для `with_reports` значення `true`, щоб прикріпити лабораторні звіти.
* Додай `note`, щоб показати в листі особисту примітку до 1 000 символів.

Якщо в профілі вимкнено транзакційні листи, виклик повертає `409` із причиною
`unsubscribed`. Щоб увімкнути їх знову, задай для `transactional_emails_enabled` значення `true` через
[Оновити профіль](https://docs.anivahealth.com/uk/api/profiles/update-profile.md).

## Листи про готовність результатів

Ти можеш отримувати лист, коли результати бронювання готові. Вкажи в `results_ready_emails` до 5
адрес під час виклику [Створити запис](https://docs.anivahealth.com/uk/api/appointments/create-appointment.md) або
[Створити замовлення набору для домашнього тесту](https://docs.anivahealth.com/uk/api/home-kit-orders/create-home-kit.md). Пізніше список можна змінити через
[Оновити запис](https://docs.anivahealth.com/uk/api/appointments/update-appointment.md) або
[Оновити замовлення набору для домашнього тесту](https://docs.anivahealth.com/uk/api/home-kit-orders/update-home-kit.md); `[]` вимикає надсилання листів.

* Попроси нас налаштувати стандартні електронні адреси для твоєї групи профілів. Бронювання, створене без
  `results_ready_emails`, отримає саме їх. Переданий список замінює їх для цього бронювання, тож додай свою
  стандартну адресу, щоб зберегти її. `[]` не надсилає жодного листа.
* Кожна адреса отримує один лист, щойно всі лабораторні результати бронювання стануть остаточними.
* Адреса, додана після того, як результати стали остаточними, отримує лист одразу.
* У листі є посилання на сторінку результатів в адмінпанелі Aniva. Клієнт його не отримує.
* Твоєму ключу потрібен доступ `results_view` до пацієнта. Без нього запит повертає `403`.

## Відображення результатів у твоєму застосунку

[Створити сесію вбудовування](https://docs.anivahealth.com/uk/api/profiles/create-embed-session.md) повертає одноразовий URL для сторінки
результатів лише для читання. Відкрий його у WebView свого застосунку, щоб пацієнт бачив результати без входу.

* Твоєму ключу потрібні права доступу `embed` і `results_view` для пацієнта. Запитай у Aniva право доступу
  `embed`.
* Викликай його зі свого сервера щоразу, коли пацієнт відкриває результати. URL діє один раз протягом
  5 хвилин, а після цього сторінка утримує сесію протягом 60 хвилин.
* `route` відкриває одну зі сторінок, які ми надаємо: список біомаркерів, один біомаркер або 3D Twin.
* `appearance` задає тему, колір кнопок і посилань, а також те, чи відображається твій логотип.
* `report` обмежує сторінку одним записом, одним замовленням набору для домашнього тесту або одним лабораторним звітом,
  завантаженим через `POST /api/v1/documents`. Тоді пацієнт бачить результати лише цього звіту.
* Сторінка показує лише лабораторні результати, як і цей API. На ній немає файлів, чату й налаштувань.

## Приклад відповіді з результатами

```json theme={null}
{
  "status": "in_progress",
  "submissions": [
    {
      "lab_code": "7642001234",
      "status": "in_progress"
    }
  ],
  "clinical_results": [
    {
      "id": "3f2b8c1e-5d4a-4e7b-9a6c-2d1f0e8b7a54",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 104,
      "biomarker_name": "Vitamin D",
      "category": "Vitamins",
      "value": 38.5,
      "value_operator": "eq",
      "unit_id": 1,
      "unit": "ng/mL",
      "reference_range_lab": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": null,
        "optimal_max": null
      },
      "reference_range_lab_absent_reason": null,
      "aniva_range": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": 30,
        "optimal_max": 60,
        "sources": [
          {
            "title": "Example source title",
            "url": "https://example.com/source"
          }
        ]
      },
      "tested_at": "2026-04-05",
      "comment": null,
      "origin": "lab",
      "lab_reported": {
        "name": "Vitamin D (25-OH)",
        "code": "vitd",
        "category": "Endokrinologie",
        "value": "38.5",
        "unit": "ng/ml",
        "reference_range": "30 - 100",
        "reference_range_min": 30,
        "reference_range_max": 100,
        "flag": "normal",
        "result_status": "final",
        "comment": null
      }
    },
    {
      "id": null,
      "status": "planned",
      "status_reason": null,
      "lab_code": null,
      "biomarker_id": 79,
      "biomarker_name": "Thyroid-Stimulating Hormone (TSH)",
      "category": "Hormones",
      "value": null,
      "value_operator": null,
      "unit_id": null,
      "unit": null,
      "reference_range_lab": null,
      "reference_range_lab_absent_reason": null,
      "aniva_range": null,
      "tested_at": null,
      "comment": null,
      "origin": null,
      "lab_reported": null
    }
  ],
  "genetic_results": [
    {
      "id": "b7e41d09-2c6f-4a83-8f15-6e9d3a0c4b21",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 348,
      "gene": "APOE",
      "genotype": "E3/E4",
      "clinical_significance": "moderate_risk",
      "risk_description": "Carriers of one APOE E4 allele have a moderately increased risk of Alzheimer's disease.",
      "tested_at": "2026-04-05",
      "comment": null,
      "origin": "lab",
      "variants": [
        {
          "name": "APOE E4",
          "clinical_significance": "moderate_risk",
          "description": "The E4 allele is associated with increased Alzheimer's risk.",
          "hgvs_c": "c.388T>C",
          "hgvs_p": "p.Cys130Arg",
          "conditions": [
            {
              "condition": "Alzheimer's disease",
              "association_description": "Increased risk with one E4 allele",
              "badge": "Moderate Risk"
            }
          ],
          "snvs": [
            {
              "rs_id": "rs429358",
              "allele": "C",
              "reference_allele": "T",
              "hgvs_c": "c.388T>C",
              "hgvs_p": "p.Cys130Arg"
            }
          ]
        }
      ]
    }
  ],
  "documents": [
    {
      "id": "f8a1b2c3-d4e5-4f6a-7b8c-9d0e1f2a3b4c",
      "file_name": "20260405 - Quade Befund - 7642001234.pdf",
      "original_file_name": "7642001234_B0012_FA_E.pdf",
      "origin": "lab",
      "content_type": "application/pdf",
      "etag": "56104b36f860cfd5b41efc716fdf7b6f",
      "size_bytes": 258341,
      "lab_code": "7642001234"
    }
  ]
}
```


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