# API лабораторных результатов: HL7 v2, FHIR и LOINC

> Как лабораторные результаты передаются в виде данных HL7 v2 и FHIR, что должен содержать один результат и как получать лабораторные отчеты в запись FHIR, с реальным примером.

Source: https://developers.anpheros.com/ru/guides/lab-results-api

**API лабораторных результатов доставляет результаты анализов в виде структурированных данных — код теста, значение, единица измерения, референсный диапазон, статус и время — вместо PDF, чтобы программное обеспечение могло их хранить, сравнивать, отображать на графиках и передавать.** Сегодня эти данные передаются в трех формах: сообщения HL7 v2 ORU^R01 (все еще основа взаимодействия между лабораториями и больницами), ресурсы HL7 FHIR R4 `Observation` и `DiagnosticReport` (формат современных API) и специфичные для лабораторий экспорты в форматах CSV, JSON или PDF. Эта страница объясняет, как все элементы сочетаются, что должен содержать хороший API лабораторных результатов и как получать лабораторные данные в запись FHIR пациента с помощью Anpheros.

## Кто обменивается лабораторными результатами и в каком формате

| От → Кому | Обычный формат сегодня | Примечания |
|---|---|---|
| Лаборатория → больничная или клиническая система | HL7 v2 ORU^R01 (в США часто согласно руководству HL7 v2.5.1 Laboratory Results Interface) | Заказы идут в обратном направлении как сообщения ORM/OML |
| Лаборатория → агентство общественного здравоохранения | Электронная отчетность по лабораторным исследованиям HL7 v2, все чаще FHIR | Только подлежащие отчетности состояния |
| Клиническая система → приложение для пациента | FHIR R4 через API для доступа пациентов | В США сертифицированные EHR предоставляют лабораторные результаты в формате FHIR (US Core); в ЕС European Health Data Space перечисляет лабораторные результаты среди своих приоритетных категорий данных |
| Лаборатория → пациент | PDF-отчет, портал, иногда CSV | Формат, который фактически получают большинство пациентов |
| Приложение → AI модель | Структурированный контекст, построенный на основе Observations | Требует кодов и единиц измерения для надежности |

Направление имеет значение: лабораторная информационная система (LIS) является источником истины для результата, и каждая последующая система хранит его копию. Достоверность копий обеспечивается тем, что каждая из них сохраняет код, единицу измерения, диапазон и источник значения.

## Что должен содержать один лабораторный результат

Результат, который гласит только "Глюкоза 126", не может быть безопасно интерпретирован. Полный результат содержит:

- **Стандартный код.** LOINC идентифицирует аналит, образец и метод: `2345-7` — глюкоза в сыворотке или плазме, `2339-0` — глюкоза в цельной крови. Собственный код лаборатории может сопровождать его.
- **Значение с единицей измерения.** В идеале — единица UCUM (`mg/dL`, `mmol/L`, `10*3/uL`), чтобы значения из двух лабораторий можно было конвертировать и сравнивать.
- **Диапазон референсных значений**, использованный лабораторией, и **флаг интерпретации** (H, L, N…), если лаборатория его предоставляет.
- **Статус:** предварительный, окончательный, исправленный или дополненный. Исправления случаются; API должен позволять видеть новую версию, не теряя старую.
- **Времена:** когда был собран образец (`effectiveDateTime`) и когда результат был опубликован (`issued`).
- **Источник:** какая лаборатория его произвела и к какому отчету или заказу он относится.

В FHIR R4 каждый результат — это один `Observation` с `category = laboratory`, а отчет, который их группирует, — это `DiagnosticReport`, перечисляющий Observations в `result`. Действительные примеры обоих, с ошибками, которые валидаторы сообщают чаще всего, находятся в [Примерах FHIR R4 JSON](https://developers.anpheros.com/tools/fhir-examples/observation-lab-result) — см. также [Пример DiagnosticReport](https://developers.anpheros.com/tools/fhir-examples/diagnostic-report).

## HL7 v2 и FHIR: параллельное сравнение

Тот же результат липидного профиля, как большинство лабораторий отправляют его сегодня и как API должен его хранить:

```
OBX|1|NM|2093-3^Cholesterol^LN||212|mg/dL|<200|H|||F|||20261002074500
```

| Поле HL7 v2 | Значение | Элемент FHIR R4 Observation |
|---|---|---|
| OBX-3 `2093-3^Cholesterol^LN` | Тест, закодированный в LOINC | `code.coding` (система `http://loinc.org`) |
| OBX-5 `212`, OBX-2 `NM` | Числовое значение | `valueQuantity.value` |
| OBX-6 `mg/dL` | Единица измерения | `valueQuantity.unit` |
| OBX-7 `<200` | Референсный диапазон | `referenceRange.high` |
| OBX-8 `H` | Флаг аномалии | `interpretation` |
| OBX-11 `F` | Окончательный результат | `status = final` |
| OBX-14 | Время наблюдения | `effectiveDateTime` |

Конвертация между ними в основном сводится к сопоставлению полей. Сложности возникают в других местах: лаборатории, которые отправляют свои собственные коды вместо LOINC, числа, записанные в виде текста (`"6,4"`, `"<5"`), диапазоны в различных обозначениях и отчеты, которые отправляются повторно после истечения времени ожидания. [Как нормализовать медицинские данные](https://developers.anpheros.com/ru/guides/normalize-medical-data) подробно рассматривает эти вопросы.

## Получение лабораторных результатов в запись FHIR с помощью Anpheros

Anpheros хранит запись каждого пациента в формате HL7 FHIR R4 и имеет [коннектор для лабораторий](https://developers.anpheros.com/ru/guides/lab-connector): один запрос принимает полный отчет в формате HL7 v2, CSV или JSON и возвращает лабораторные наблюдения (Observations) с кодами LOINC, референсными диапазонами, интерпретацией и происхождением данных (provenance).

```bash
curl -s -X POST "https://platform.anpheros.com/v1/patients/$PID/labs/import" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: x-application/hl7-v2+er7" \
  -H "X-Anpheros-Source-System: springfield-lis" \
  --data-binary @lipid-panel.hl7
```

Для трехкомпонентной липидной панели (холестерин, ЛПВП, триглицериды) ответ, полученный при локальном запуске платформы, выглядит следующим образом:

```json
{
  "created": 3, "skipped": 0, "unmapped": [], "warnings": [],
  "observations": [
    {"id": "26ed9219-…", "marker": "Cholesterol", "code": "2093-3", "system": "http://loinc.org",
     "value": 212.0, "unit": "mg/dL", "date": "2026-10-02T07:45:00Z"},
    {"id": "2633d1d4-…", "marker": "HDL cholesterol", "code": "2085-9", "system": "http://loinc.org",
     "value": 48.0, "unit": "mg/dL", "date": "2026-10-02T07:45:00Z"},
    {"id": "a02520bb-…", "marker": "Triglyceride", "code": "2571-8", "system": "http://loinc.org",
     "value": 165.0, "unit": "mg/dL", "date": "2026-10-02T07:45:00Z"}
  ]
}
```

Каждый сохраненный результат представляет собой стандартное FHIR R4 Observation, доступное для чтения любым FHIR-клиентом:

```json
{
  "resourceType": "Observation",
  "status": "final",
  "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "laboratory"}]}],
  "code": {"coding": [{"system": "http://loinc.org", "code": "2093-3",
                        "display": "Cholesterol [Mass/volume] in Serum or Plasma"}], "text": "Cholesterol"},
  "subject": {"reference": "Patient/4c3062d9-…"},
  "effectiveDateTime": "2026-10-02T07:45:00Z",
  "valueQuantity": {"value": 212.0, "unit": "mg/dL"},
  "interpretation": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation", "code": "H"}]}],
  "referenceRange": [{"high": {"value": 200.0, "unit": "mg/dL"}}]
}
```

Повторная отправка того же сообщения ничего нового не создает (`"created": 0, "skipped": 3`): каждая строка получает стабильный идентификатор из идентификатора отчета, кода, даты и значения. Маркеры, которые платформа не может сопоставить с LOINC, сохраняют код лаборатории и возвращаются в `unmapped`, чтобы вы могли исправить сопоставление в источнике.

Чтение результатов обратно выполняется стандартным поиском FHIR:

```bash
curl -s "https://platform.anpheros.com/fhir/R4/Observation?patient=$PID&category=laboratory&code=http://loinc.org|2093-3" \
  -H "Authorization: Bearer $KEY"
```

Другие способы ввода и вывода тех же данных:

- **Напрямую через FHIR:** `POST /fhir/R4/Observation` или транзакционный Bundle, содержащий `DiagnosticReport` и соответствующие ему Observations.
- **События:** [вебхук](https://developers.anpheros.com/ru/guides/webhooks) `resource.created` для каждого Observation, позволяющий клинике или приложению реагировать на поступление результатов.
- **Для людей и ИИ:** пациент видит результаты в своем приложении; приложения, которым он дал согласие, читают их; `POST /v1/context` предоставляет модели ИИ сводку с указанием источника, включающую недавние лабораторные значения.
- **Происхождение данных (Provenance):** каждый импортированный результат записывает `author_type = import`, исходную систему и идентификатор отчета ([происхождение медицинских данных](https://developers.anpheros.com/ru/guides/medical-data-provenance)).

Полное пошаговое руководство с отчетом в формате CSV, сообщением HL7 v2, несопоставленными маркерами и повторно отправленными отчетами для синтетического пациента содержится в учебном пособии [Как импортировать лабораторные результаты в запись FHIR](https://developers.anpheros.com/ru/guides/import-lab-results-fhir).

## Проверка результатов перед отправкой

Бесплатный [валидатор FHIR R4](https://developers.anpheros.com/tools/fhir-validator) проверяет структуру Observation и обязательные наборы значений. С профилем `eu-lab` он также проверяет, что лабораторный результат должен содержать: категорию `laboratory`, код LOINC, субъект, статус final-type, время, значение, единицу UCUM и диапазон значений. Те же проверки выполняются на платформе через `POST /fhir/R4/Observation/$validate?profile=eu-lab`.

## Выбор API лабораторных результатов: контрольный список

- Хранит ли он результаты в виде FHIR R4 Observations с кодами LOINC или в виде строк в собственной схеме?
- Может ли он принимать форматы, которые фактически отправляют ваши лаборатории (HL7 v2 в большинстве больниц, CSV или PDF из небольших лабораторий)?
- Что происходит с маркером, который он не может сопоставить: отклоняется ли он, отбрасывается или сохраняется с кодом лаборатории?
- Безопасны ли повторные попытки, или повторно отправленный отчет создает дубликаты?
- Версионируются ли исправленные результаты, с возможностью чтения предыдущего значения?
- Записывается ли происхождение каждого значения и видимо ли оно пациенту?
- Кто может читать результаты, и решается ли это согласием пациента?

## Что Anpheros не делает

Anpheros не является лабораторной информационной системой и не подключен к коммерческим лабораторным сетям: отчет отправляет лаборатория, клиника или приложение пациента. Он не маршрутизирует лабораторные заказы, не читает PDF-отчеты через этот API (приложение Anpheros Daily извлекает результаты из фотографий и PDF на стороне пациента) и не интерпретирует результаты клинически. Единицы измерения хранятся так, как их отправляет лаборатория; их преобразование в коды UCUM лежит на отправителе, как описано в [Как нормализовать медицинские данные](https://developers.anpheros.com/ru/guides/normalize-medical-data).

## Часто задаваемые вопросы

### Что такое API лабораторных результатов?
Интерфейс, который позволяет программному обеспечению отправлять или получать лабораторные результаты в виде структурированных данных — закодированный тест, значение с единицей измерения, диапазон ссылок, статус и время — а не в виде документа. Современные API лабораторных результатов используют ресурсы HL7 FHIR R4 Observation и DiagnosticReport; большинство лабораторий по-прежнему выдают сообщения HL7 v2 ORU^R01.

### Какая кодовая система идентифицирует лабораторные тесты?
LOINC. Каждый код LOINC называет аналит, образец и часто метод, поэтому `2345-7` (глюкоза в сыворотке или плазме) и `2339-0` (глюкоза в цельной крови) являются разными результатами. Единицы измерения лучше всего выражать в UCUM.

### В чем разница между Observation и DiagnosticReport?
Observation — это один результат, например, холестерин 212 мг/дл. DiagnosticReport — это отчет в целом — панель, которая была заказана, кто ее выдал и когда — и перечисляет свои Observations в `result`.

### Могу ли я импортировать сообщения HL7 v2 в FHIR-сервер?
Да. Каждый сегмент OBX отображается на один Observation (OBX-3 на `code`, OBX-5 и OBX-6 на `valueQuantity`, OBX-7 на `referenceRange`, OBX-8 на `interpretation`). Коннектор лаборатории Anpheros делает это за один запрос и сохраняет идентификатор отчета лаборатории в Provenance.

### Как избежать дублирования лабораторных результатов при повторной отправке отчета?
Присвойте каждому результату стабильный идентификатор, полученный из отчета, теста, времени и значения, и пропускайте строки, идентификатор которых уже существует. Коннектор лаборатории Anpheros делает это автоматически и сообщает количество как `skipped`.

## Связанные материалы

- [Сопоставление HL7 v2 с FHIR](https://developers.anpheros.com/ru/guides/hl7-v2-to-fhir-mapping): каждый сегмент и поле OBX
- [Как импортировать лабораторные результаты в запись FHIR](https://developers.anpheros.com/ru/guides/import-lab-results-fhir): пошаговое руководство
- [Лабораторный коннектор](https://developers.anpheros.com/ru/guides/lab-connector): справочник по конечным точкам
- [Как нормализовать медицинские данные](https://developers.anpheros.com/ru/guides/normalize-medical-data): LOINC, UCUM, даты, диапазоны и дубликаты
- [Объяснение происхождения медицинских данных](https://developers.anpheros.com/ru/guides/medical-data-provenance)
- [Системы кодирования FHIR](https://developers.anpheros.com/ru/guides/fhir-code-systems)
- [Как интегрировать клинические системы с бэкендом FHIR](https://developers.anpheros.com/ru/guides/integrate-clinic-systems-fhir)
- [FHIR против HL7 v2: практические различия](https://developers.anpheros.com/ru/guides/fhir-vs-hl7-v2)
- [HL7 v2 и FHIR для клинических панелей мониторинга](https://developers.anpheros.com/ru/guides/clinical-dashboard-hl7-fhir): от лабораторного сообщения до плитки на панели мониторинга