Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card

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

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

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 — дивіться також приклад DiagnosticReport.

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"), діапазони у різних нотаціях та звіти, які надсилаються повторно після тайм-ауту. Як нормалізувати медичні дані детально розглядає ці питання.

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

Anpheros зберігає запис кожного пацієнта як HL7 FHIR R4 і має лабораторний конектор: один запит приймає повний звіт у форматі HL7 v2, CSV або JSON і повертає лабораторні спостереження (Observations) з кодами LOINC, референтними діапазонами, інтерпретацією та походженням даних.

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, тригліцериди) відповідь, отримана під час локального запуску платформи, виглядає так:

{
  "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 клієнтом:

{
  "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:

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 для кожного Observation, щоб клініка або додаток могли реагувати на надходження результатів.
Для людей та ШІ: пацієнт бачить результати у своєму додатку; додатки, яким він надає згоду, читають їх; POST /v1/context надає моделі ШІ резюме з позначенням джерела, яке включає останні лабораторні показники.
Походження даних: кожен імпортований результат записує author_type = import, вихідну систему та ідентифікатор звіту (походження медичних даних).

Повний огляд з використанням звіту CSV, повідомлення HL7 v2, незіставлених маркерів та повторно надісланих звітів для синтетичного пацієнта представлений у посібнику Як імпортувати лабораторні результати у запис FHIR.

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

Безкоштовний FHIR R4 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 лежить на стороні відправника, як описано в Як нормалізувати медичні дані.

Часті запитання

Що таке 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: відображення: кожен сегмент та поле OBX
Як імпортувати лабораторні результати до запису FHIR: покроковий посібник
Лабораторний конектор: довідник кінцевих точок
Як нормалізувати медичні дані: LOINC, UCUM, дати, діапазони та дублікати
Пояснення походження медичних даних
Системи кодування FHIR
Як інтегрувати клінічні системи з бекендом FHIR
FHIR проти HL7 v2: практичні відмінності
HL7 v2 та FHIR для клінічних інформаційних панелей: від лабораторного повідомлення до плитки на інформаційній панелі

Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card