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, якщо твій ключ не має scopeaniva_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, ти робиш це від власного імені та під власну відповідальність.
- Показуй повідомлення зі своєї угоди з Aniva скрізь, де показуєш діапазон Aniva.
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. Залишай відкриту сторону відкритою, коли показуєш його.
Статуси клінічних результатів
Генетичні результати
Генетичні результати — це дані на рівні генів, отримані з аналізу ДНК. Кожен результат відповідає певному гену (наприклад, 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. На ній немає файлів, чату й налаштувань.