> ## 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.

# Результаты

> Как работают лабораторные результаты и документы в API Aniva: значения биомаркеров, референсные интервалы, отчёты лаборатории и вебхуки результатов.

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

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

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

| Статус | Значение |
| - | - |
| `in_progress` | Часть заявок ещё обрабатывается лабораторией. |
| `completed` | Все заявки закрыты, и хотя бы по одной получены результаты. |
| `fault` | Все заявки завершились сбоем без передачи результатов. Ожидаемых результатов больше нет. |

У каждого результата в ответе есть собственный статус (см. ниже), поэтому ты можешь показывать частичные результаты, пока общий статус ещё `in_progress`.

Чтобы узнавать об изменении результатов, подпишись на [вебхуки](https://docs.anivahealth.com/ru/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`** — минимальные и максимальные границы нормы и оптимума, указанные лабораторией для этого результата и приведённые к той же шкале, что и `value`. Граница, оставленная лабораторией открытой, равна `null`, поэтому односторонний интервал вроде `< 50` приходит как `normal_min: null, normal_max: 50`. Каждый результат содержит тот интервал, относительно которого он измерялся, поэтому пациент с результатами из нескольких заборов крови или лабораторий получает правильный интервал для каждого результата.
* **`reference_range_lab_absent_reason`** — причина, по которой `reference_range_lab` равен `null`. Значение `null`, когда интервал присутствует, а также для результата `planned`. См. [Когда нет лабораторного интервала](#kogda-net-laboratornogo-intervala).
* **`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 для этих значений. Список может быть пустым.

> [!WARNING]
>
> Эти значения представляют собой общую информацию. Они не являются медицинской рекомендацией, диагнозом,
> медицинским заключением или оценкой результата. 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` объясняет причину:

| Значение | Описание | Что показывать |
| - | - | - |
| `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/ru/api/documents/upload-document.md)).
* **`content_type`** — медиатип файла (например, `application/pdf`). Большинство отчётов — это PDF. Загруженные сканы могут быть изображениями или CSV-файлами.
* **`etag`** — версия содержимого файла; она меняется при любом изменении байтов. Сохраняй её и скачивай файл повторно только при её изменении. Это стандартный HTTP entity tag, как в S3 или Google Cloud Storage.
* **`size_bytes`** — размер файла в байтах.
* **`lab_code`** — лабораторный код (штрихкод пробирки), к которому относится отчёт; `null`, если лаборатория его не указала.

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

## Отправка результатов клиенту по почте

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

* Письмо отправляется на `email` профиля. Адрес-заглушка `@aniva.email` отклоняется.
* В письме показаны название и логотип основной группы профилей этого профиля.
* Язык письма — `language` профиля, по умолчанию английский.
* Задай `true` для `with_reports`, чтобы прикрепить лабораторные отчёты.
* Добавь `note`, чтобы показать в письме личный комментарий, не более 1 000 символов.

Если в профиле отключены транзакционные письма, вызов вернёт `409` с причиной
`unsubscribed`. Чтобы снова их включить, установи `transactional_emails_enabled` в `true` через
[Обновить профиль](https://docs.anivahealth.com/ru/api/profiles/update-profile.md).

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

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

* Попроси нас задать адреса электронной почты по умолчанию для твоей группы профилей. Бронирование, созданное без
  `results_ready_emails`, получит их. Переданный список заменяет их для этого бронирования, поэтому включи в него
  адрес по умолчанию, чтобы сохранить его. При `[]` письма не отправляются.
* На каждый адрес приходит одно письмо, как только все лабораторные результаты по бронированию станут окончательными.
* Адрес, добавленный после того, как результаты стали окончательными, получает письмо сразу же.
* В письме есть ссылка на страницу результатов в панели администратора Aniva. Клиент это письмо не получает.
* Твоему ключу нужен доступ `results_view` к пациенту. Без него запрос вернёт `403`.

## Показ результатов в твоём приложении

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

* Твоему ключу нужны области доступа `embed` и `results_view` для пациента. Запроси доступ `embed`
  у Aniva.
* Вызывай метод со своего сервера каждый раз, когда пациент открывает результаты. 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.