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— минимальные и максимальные границы нормы и оптимума, указанные лабораторией для этого результата и приведённые к той же шкале, что и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, если у твоего ключа нет разрешения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, ты делаешь это от собственного имени и под собственную ответственность.
- Показывай уведомление из твоего соглашения с 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 entity tag, как в S3 или Google Cloud Storage.size_bytes— размер файла в байтах.lab_code— лабораторный код (штрихкод пробирки), к которому относится отчёт;null, если лаборатория его не указала.
Доступ к документам проверяется по профилю, которому принадлежит документ.
Отправка результатов клиенту по почте
Ты можешь сообщить клиенту по электронной почте, что его результаты готовы. Вызови Отправить результаты по почте для записи или Отправить результаты по почте для заказа набора для домашнего теста. Каждый вызов отправляет одно письмо. Вызовы не дедуплицируются.- Письмо отправляется на
emailпрофиля. Адрес-заглушка@aniva.emailотклоняется. - В письме показаны название и логотип основной группы профилей этого профиля.
- Язык письма —
languageпрофиля, по умолчанию английский. - Задай
trueдляwith_reports, чтобы прикрепить лабораторные отчёты. - Добавь
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для пациента. Запроси доступembedу Aniva. - Вызывай метод со своего сервера каждый раз, когда пациент открывает результаты. URL срабатывает один раз и действует 5 минут, после чего страница поддерживает 60-минутную сессию.
routeоткрывает одну из доступных страниц: список биомаркеров, один биомаркер или 3D Twin.appearanceзадаёт тему, цвет кнопок и ссылок, а также отображение твоего логотипа.reportограничивает страницу одной записью, одним заказом набора для домашнего теста или одним лабораторным отчётом, который ты загрузил черезPOST /api/v1/documents. Тогда пациент видит результаты только этого отчёта.- Страница показывает только лабораторные результаты, как и этот API. На ней нет файлов, чата и настроек.