Перейти к основному содержанию
После того как забор крови подтверждён, а лаборатория обработала образцы, результаты становятся доступны в записи. Результаты запрашиваются через 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 не сравнивает с ними результат и не выставляет по ним никаких флагов. reference_range_lab и оценка врача остаются стандартом для результата.
Правила для твоего продукта:
  • Показывай интервал 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. Оставляй открытую сторону открытой при отображении.

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

Когда показываешь результаты пациентам, используй поле 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 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. На ней нет файлов, чата и настроек.

Пример ответа с результатами