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

> Як лабораторні результати передаються у вигляді даних HL7 v2 та FHIR, що повинен містити один результат, і як отримувати лабораторні звіти до запису FHIR, з реальним прикладом.

Source: https://developers.anpheros.com/uk/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/uk/guides/normalize-medical-data) детально розглядає ці питання.

## Отримання результатів лабораторних досліджень у запис FHIR за допомогою Anpheros

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

```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
```

Для трирядкової ліпідної панелі (холестерин, HDL, тригліцериди) відповідь, отримана під час локального запуску платформи, виглядає так:

```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 разом.
- **Події:** `resource.created` [webhook](https://developers.anpheros.com/uk/guides/webhooks) для кожного Observation, щоб клініка або додаток могли реагувати на надходження результатів.
- **Для людей та ШІ:** пацієнт бачить результати у своєму додатку; додатки, яким він надає згоду, читають їх; `POST /v1/context` надає моделі ШІ резюме з позначенням джерела, яке включає останні лабораторні показники.
- **Походження даних:** кожен імпортований результат записує `author_type = import`, вихідну систему та ідентифікатор звіту ([походження медичних даних](https://developers.anpheros.com/uk/guides/medical-data-provenance)).

Повний огляд з використанням звіту CSV, повідомлення HL7 v2, незіставлених маркерів та повторно надісланих звітів для синтетичного пацієнта представлений у посібнику [Як імпортувати лабораторні результати у запис FHIR](https://developers.anpheros.com/uk/guides/import-lab-results-fhir).

## Перевірка результатів перед надсиланням

Безкоштовний [FHIR R4 validator](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/uk/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/uk/guides/hl7-v2-to-fhir-mapping): кожен сегмент та поле OBX
- [Як імпортувати лабораторні результати до запису FHIR](https://developers.anpheros.com/uk/guides/import-lab-results-fhir): покроковий посібник
- [Лабораторний конектор](https://developers.anpheros.com/uk/guides/lab-connector): довідник кінцевих точок
- [Як нормалізувати медичні дані](https://developers.anpheros.com/uk/guides/normalize-medical-data): LOINC, UCUM, дати, діапазони та дублікати
- [Пояснення походження медичних даних](https://developers.anpheros.com/uk/guides/medical-data-provenance)
- [Системи кодування FHIR](https://developers.anpheros.com/uk/guides/fhir-code-systems)
- [Як інтегрувати клінічні системи з бекендом FHIR](https://developers.anpheros.com/uk/guides/integrate-clinic-systems-fhir)
- [FHIR проти HL7 v2: практичні відмінності](https://developers.anpheros.com/uk/guides/fhir-vs-hl7-v2)
- [HL7 v2 та FHIR для клінічних інформаційних панелей](https://developers.anpheros.com/uk/guides/clinical-dashboard-hl7-fhir): від лабораторного повідомлення до плитки на інформаційній панелі