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

API pre výsledky laboratórnych testov: HL7 v2, FHIR a LOINC

Ako cestujú výsledky laboratórnych testov ako dáta HL7 v2 a FHIR R4, čo musí jeden výsledok niesť a ako prijímať laboratórne správy do FHIR záznamu, s reálnym príkladom.

API pre laboratórne výsledky doručuje laboratórne výsledky ako štruktúrované dáta — kód testu, hodnota, jednotka, referenčný rozsah, stav a čas — namiesto PDF, takže ich softvér môže ukladať, porovnávať, graficky zobrazovať a zdieľať. Dnes tieto dáta cestujú v troch formách: správy HL7 v2 ORU^R01 (stále chrbtica medzi laboratóriami a nemocnicami), zdroje HL7 FHIR R4 Observation a DiagnosticReport (formát moderných API) a exporty CSV, JSON alebo PDF špecifické pre laboratórium. Táto stránka vysvetľuje, ako do seba zapadajú jednotlivé časti, čo musí dobré API pre laboratórne výsledky obsahovať a ako prijímať laboratórne dáta do záznamu FHIR pacienta pomocou Anpheros.

Kto si vymieňa laboratórne výsledky a v akom formáte

Smer je dôležitý: laboratórny informačný systém (LIS) je zdrojom pravdy pre výsledok a každý nadväzujúci systém si uchováva kópiu. Dôveryhodnosť kópií zabezpečuje, že každý z nich uchováva kód, jednotku, rozsah a pôvod hodnoty.

Čo potrebuje jeden laboratórny výsledok

Výsledok, ktorý hovorí iba „Glukóza 126“, sa nedá bezpečne interpretovať. Kompletný výsledok obsahuje:

• Štandardný kód. LOINC identifikuje analyt, vzorku a metódu: 2345-7 je glukóza v sére alebo plazme, 2339-0 je glukóza v plnej krvi. Vedľa neho môže cestovať aj vlastný kód laboratória.
• Hodnota s jednotkou. Ideálne jednotka UCUM (mg/dL, mmol/L, 10*3/uL), aby sa hodnoty z dvoch laboratórií dali previesť a porovnať.
• Referenčný rozsah, ktorý laboratórium použilo, a interpretačná značka (H, L, N…), ak ju laboratórium poskytuje.
• Stav: predbežný, konečný, opravený alebo doplnený. Opravy sa stávajú; API vám musí umožniť vidieť novú verziu bez straty starej.
• Časy: kedy bola vzorka odobratá (effectiveDateTime) a kedy bol výsledok vydaný (issued).
• Pôvod: ktoré laboratórium ho vyprodukovalo a k akej správe alebo objednávke patrí.

Vo FHIR R4 je každý výsledok jeden Observation s category = laboratory a správa, ktorá ich zoskupuje, je DiagnosticReport, ktorá uvádza Pozorovania v result. Platné príklady oboch, s chybami, ktoré validátory hlásia najčastejšie, sú v Príkladoch FHIR R4 JSON — pozri tiež Príklad DiagnosticReport.

HL7 v2 a FHIR vedľa seba

Ten istý výsledok lipidového panelu, tak ako ho dnes posiela väčšina laboratórií a tak, ako by ho mal API uložiť:

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

Konverzia medzi týmito dvoma je väčšinou mapovanie polí. Ťažké časti sú inde: laboratóriá, ktoré posielajú vlastné kódy namiesto LOINC, čísla napísané ako text ("6,4", "<5"), rozsahy v niekoľkých notáciách a správy, ktoré sa po uplynutí časového limitu posielajú znova. Ako normalizovať lekárske dáta sa týmto podrobne venuje.

Prijímanie laboratórnych výsledkov do FHIR záznamu s Anpheros

Anpheros ukladá záznam každého pacienta ako HL7 FHIR R4 a má laboratórny konektor: jedna požiadavka prijme celú správu ako HL7 v2, CSV alebo JSON a vráti laboratórne pozorovania (Observations) s LOINC kódmi, referenčnými rozsahmi, interpretáciou a pôvodom (provenance).

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

Pre trojriadkový lipidový panel (cholesterol, HDL, triglyceridy) je odpoveď z lokálneho spustenia platformy:

{
  "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"}
  ]
}

Každý uložený výsledok je štandardné FHIR R4 Observation, čitateľné akýmkoľvek FHIR klientom:

{
  "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"}}]
}

Opätovné odoslanie tej istej správy nevytvorí nič nové ("created": 0, "skipped": 3): každý riadok získa stabilný identifikátor z ID správy, kódu, dátumu a hodnoty. Značky, ktoré platforma nedokáže namapovať na LOINC, si ponechajú kód laboratória a vrátia sa v unmapped, takže môžete mapovanie opraviť pri zdroji.

Čítanie výsledkov späť je štandardné FHIR vyhľadávanie:

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

Ďalšie spôsoby vstupu a výstupu rovnakých údajov:

• Priamo FHIR: POST /fhir/R4/Observation, alebo transakčný Bundle s DiagnosticReport a jeho Observations spolu.
• Udalosti: resource.created webhook na jedno Observation, takže klinika alebo aplikácia môže reagovať, keď výsledky dorazia.
• Pre ľudí a AI: pacient vidí výsledky vo svojej aplikácii; aplikácie, ktorým dá súhlas, si ich prečítajú; POST /v1/context poskytuje modelu AI súhrn označený zdrojom, ktorý zahŕňa nedávne laboratórne hodnoty.
• Pôvod (Provenance): každý importovaný výsledok zaznamenáva author_type = import, zdrojový systém a ID správy (pôvod lekárskych údajov).

Kompletný návod s CSV správou, HL7 v2 správou, nemapovanými značkami a opätovne odoslanými správami na syntetickom pacientovi je v návode Ako importovať laboratórne výsledky do FHIR záznamu.

Skontrolujte výsledky pred ich odoslaním

Bezplatný FHIR R4 validátor kontroluje štruktúru Observation a požadované hodnotové sady. S profilom eu-lab tiež kontroluje, čo by mal laboratórny výsledok obsahovať: kategóriu laboratory, LOINC kód, subjekt, stav final-type, čas, hodnotu, UCUM jednotku a referenčný rozsah. Rovnaké kontroly prebiehajú na platforme prostredníctvom POST /fhir/R4/Observation/$validate?profile=eu-lab.

Výber API pre laboratórne výsledky: kontrolný zoznam

• Ukladá výsledky ako FHIR R4 Observations s LOINC kódmi, alebo ako riadky vo vlastnej schéme?
• Dokáže prijať formáty, ktoré vaše laboratóriá skutočne posielajú (HL7 v2 vo väčšine nemocníc, CSV alebo PDF z menších laboratórií)?
• Čo sa stane so značkou, ktorú nedokáže namapovať: je odmietnutá, ignorovaná alebo ponechaná s kódom laboratória?
• Sú opätovné pokusy bezpečné, alebo duplicitný report vytvorí duplikáty?
• Sú opravené výsledky verzované, pričom skoršia hodnota je stále čitateľná?
• Je pôvod každej hodnoty zaznamenaný a viditeľný pre pacienta?
• Kto môže čítať výsledky a rozhoduje o tom súhlas pacienta?

Čo Anpheros nerobí

Anpheros nie je laboratórny informačný systém a nie je pripojený k komerčným laboratórnym sieťam: správu posiela laboratórium, klinika alebo aplikácia pacienta. Nerieši laboratórne objednávky, nečíta PDF správy prostredníctvom tohto API (aplikácia Anpheros Daily extrahuje výsledky z fotografií a PDF na strane pacienta) a klinicky neinterpretuje výsledky. Jednotky sa ukladajú tak, ako ich posiela laboratórium; ich konverzia na kódy UCUM je na strane odosielateľa, ako je popísané v Ako normalizovať lekárske údaje.

Často kladené otázky

Čo je API pre laboratórne výsledky?

Rozhranie, ktoré umožňuje softvéru posielať alebo prijímať laboratórne výsledky ako štruktúrované údaje — kódovaný test, hodnotu s jednotkou, referenčný rozsah, stav a čas — namiesto dokumentu. Moderné API pre laboratórne výsledky používajú zdroje HL7 FHIR R4 Observation a DiagnosticReport; väčšina laboratórií stále emituje správy HL7 v2 ORU^R01.

Ktorý kódovací systém identifikuje laboratórne testy?

LOINC. Každý LOINC kód pomenúva analyt, vzorku a často aj metódu, takže 2345-7 (glukóza v sére alebo plazme) a 2339-0 (glukóza v celej krvi) sú rôzne výsledky. Jednotky je najlepšie vyjadriť v UCUM.

Aký je rozdiel medzi Observation a DiagnosticReport?

Observation je jeden výsledok, napríklad cholesterol 212 mg/dL. DiagnosticReport je celá správa — panel, ktorý bol objednaný, kto ju vydal a kedy — a uvádza svoje Observations v result.

Môžem importovať HL7 v2 laboratórne správy na FHIR server?

Áno. Každý segment OBX sa mapuje na jedno Observation (OBX-3 na code, OBX-5 a OBX-6 na valueQuantity, OBX-7 na referenceRange, OBX-8 na interpretation). Konektor laboratória Anpheros to robí v jednom požiadavke a uchováva ID správy laboratória v Provenance.

Ako sa vyhnúť duplicitným laboratórnym výsledkom, keď je správa odoslaná znova?

Každému výsledku priraďte stabilný identifikátor odvodený zo správy, testu, času a hodnoty a preskočte riadky, ktorých identifikátor už existuje. Konektor laboratória Anpheros to robí automaticky a hlási počet ako skipped.

Súvisiace

• Mapovanie HL7 v2 na FHIR: každý segment a pole OBX
• Ako importovať laboratórne výsledky do záznamu FHIR: podrobný návod
• Lab connector: referenčný dokument koncového bodu
• Ako normalizovať lekárske údaje: LOINC, UCUM, dátumy, rozsahy a duplicity
• Vysvetlenie pôvodu lekárskych údajov
• Kódové systémy FHIR
• Ako integrovať klinické systémy s backendom FHIR
• FHIR vs HL7 v2: praktické rozdiely
• HL7 v2 a FHIR pre klinické dashboardy: od laboratórnej správy k dlaždici dashboardu

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