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

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

Поле верхнього рівня status у відповіді з результатами вказує на загальний прогрес обробки: Окремі результати у відповіді мають власний статус (див. нижче), тому ти можеш показувати часткові результати, поки загальний статус ще in_progress. Щоб дізнаватися про зміни результатів, підпишись на вебхуки. 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. Див. Коли немає лабораторного діапазону.
  • 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 зафіксувала для цих значень. Список може бути порожнім.
Ці значення мають загальний інформаційний характер. Вони не є медичною порадою, діагнозом, медичним висновком чи оцінкою результату. 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 пояснює чому: Деякі лабораторії друкують цільове значення або рівень ризику замість референтного діапазону, наприклад Ziel: <200. >240 hoch або <5.7 neg >=6.5 pos. Вони не потрапляють у reference_range_lab, тому його межі мають значення null, а причина — lab_text_only. Показуй надрукований текст дослівно. Односторонній діапазон, як-от < 20, є діапазоном. Він надходить у reference_range_lab з однією межею null, а причина має значення null. Залишай відкриту сторону відкритою, коли показуєш його.

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

Коли показуєш результати пацієнтам, використовуй поле value напряму — воно вже містить виправлене значення, якщо таке є.
Ніколи не показуй результат зі статусом 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.

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

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

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

Кожен генетичний результат має масив 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 (завантажено тобою через Завантажити документ).
  • content_type — медіатип файлу (наприклад, application/pdf). Більшість звітів — це файли PDF. Завантажені скани можуть бути зображеннями або файлами CSV.
  • etag — версія вмісту файлу; змінюється щоразу, коли змінюються байти. Збережи її та завантажуй файл повторно лише після зміни. Це стандартний тег сутності HTTP, який використовують S3 або Google Cloud Storage.
  • size_bytes — розмір файлу в байтах.
  • lab_code — лабораторний код (штрихкод пробірки), до якого належить звіт; null, якщо лабораторія його не вказала.
Доступ до документів перевіряється за профілем, якому належить документ.

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

Ти можеш повідомити клієнта електронною поштою, що результати готові. Виклич Надіслати результати для запису або Надіслати результати для замовлення набору для домашнього тесту. Кожен виклик надсилає один лист. Виклики не дедуплікуються.
  • Лист надсилається на email профілю. Адреса-заглушка @aniva.email відхиляється.
  • У листі показано назву й логотип основної групи профілів для цього профілю.
  • Лист надсилається мовою language профілю, типово — англійською.
  • Задай для with_reports значення true, щоб прикріпити лабораторні звіти.
  • Додай note, щоб показати в листі особисту примітку до 1 000 символів.
Якщо в профілі вимкнено транзакційні листи, виклик повертає 409 із причиною unsubscribed. Щоб увімкнути їх знову, задай для transactional_emails_enabled значення true через Оновити профіль.

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

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

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

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

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