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

API pro laboratorní výsledky: HL7 v2, FHIR a LOINC

Jak cestují laboratorní výsledky jako data HL7 v2 a FHIR R4, co musí jeden výsledek nést a jak přijímat laboratorní zprávy do FHIR záznamu, s reálným příkladem.

API pro laboratorní výsledky dodává laboratorní výsledky jako strukturovaná data — kód testu, hodnota, jednotka, referenční rozsah, stav a čas — namísto PDF, aby je software mohl ukládat, porovnávat, zobrazovat v grafech a sdílet. Dnes tato data cestují ve třech formách: zprávy HL7 v2 ORU^R01 (stále páteř mezi laboratořemi a nemocnicemi), zdroje HL7 FHIR R4 Observation a DiagnosticReport (formát moderních API) a exporty CSV, JSON nebo PDF specifické pro laboratoř. Tato stránka vysvětluje, jak do sebe jednotlivé části zapadají, co musí dobré API pro laboratorní výsledky obsahovat a jak přijímat laboratorní data do záznamu pacienta ve formátu FHIR pomocí Anpheros.

Kdo si vyměňuje laboratorní výsledky a v jakém formátu

Směr je důležitý: laboratorní informační systém (LIS) je zdro pravdy pro výsledek a každý navazující systém si uchovává jeho kopii. Důvěryhodnost kopií zajišťuje, že si každý z nich uchovává kód, jednotku, rozsah a původ hodnoty.

Co potřebuje jeden laboratorní výsledek

Výsledek, který říká pouze „Glukóza 126“, nelze bezpečně interpretovat. Kompletní výsledek obsahuje:

• Standardní kód. LOINC identifikuje analyt, vzorek a metodu: 2345-7 je glukóza v séru nebo plazmě, 2339-0 je glukóza v celé krvi. Vedle něj může cestovat i vlastní kód laboratoře.
• Hodnota s jednotkou. Ideálně jednotka UCUM (mg/dL, mmol/L, 10*3/uL), takže hodnoty ze dvou laboratoří lze převést a porovnat.
• Referenční rozsah, který laboratoř použila, a interpretační příznak (H, L, N…), pokud jej laboratoř poskytuje.
• Stav: předběžný, konečný, opravený nebo doplněný. Opravy se dějí; API musí umožnit vidět novou verzi bez ztráty té staré.
• Časy: kdy byl vzorek odebrán (effectiveDateTime) a kdy byl výsledek vydán (issued).
• Původ: která laboratoř jej vyprodukovala a ke které zprávě nebo objednávce patří.

Ve FHIR R4 je každý výsledek jeden Observation s category = laboratory a zpráva, která je seskupuje, je DiagnosticReport, která uvádí Observations v result. Platné příklady obou, s chybami, které validátory hlásí nejčastěji, jsou ve FHIR R4 JSON příkladech — viz také příklad DiagnosticReport.

HL7 v2 a FHIR vedle sebe

Stejný výsledek lipidového panelu, jak jej dnes většina laboratoří posílá a jak by jej API mělo ukládat:

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

Převod mezi těmito dvěma formáty je převážně mapování polí. Obtížné části jsou jinde: laboratoře, které posílají vlastní kódy místo LOINC, čísla zapsaná jako text ("6,4", "<5"), rozsahy v několika notacích a zprávy, které jsou po uplynutí časového limitu poslány znovu. Jak normalizovat lékařská data se těmito tématy podrobně zabývá.

Příjem laboratorních výsledků do záznamu FHIR s Anpheros

Anpheros ukládá záznam každého pacienta jako HL7 FHIR R4 a má konektor pro laboratoř: jeden požadavek přijme celou zprávu jako HL7 v2, CSV nebo JSON a vrátí laboratorní Observation s kódy LOINC, referenčními rozsahy, interpretací a původem dat.

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

Pro třířádkový lipidový panel (cholesterol, HDL, triglyceridy) je odpověď z lokálního běhu 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ýsledek je standardní FHIR R4 Observation, čitelný jakýmkoli FHIR klientem:

{
  "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é odeslání stejné zprávy nevytvoří nic nového ("created": 0, "skipped": 3): každý řádek získá stabilní identifikátor z ID zprávy, kódu, data a hodnoty. Značky, které platforma nemůže namapovat na LOINC, si ponechají kód laboratoře a vrátí se v unmapped, takže můžete mapování opravit u zdroje.

Čtení výsledků zpět je standardní vyhledávání FHIR:

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

Další způsoby vstupu a výstupu stejných dat:

• Přímo FHIR: POST /fhir/R4/Observation, nebo transakční Bundle s DiagnosticReport a jeho Observation společně.
• Události: resource.created webhook pro každou Observation, takže klinika nebo aplikace může reagovat, když výsledky dorazí.
• Pro lidi a AI: pacient vidí výsledky ve své aplikaci; aplikace, kterým udělí souhlas, si je přečtou; POST /v1/context poskytuje modelu AI souhrn označený zdrojem, který zahrnuje nedávné laboratorní hodnoty.
• Původ dat: každý importovaný výsledek zaznamenává author_type = import, zdrojový systém a ID zprávy (původ lékařských dat).

Kompletní návod s CSV zprávou, HL7 v2 zprávou, nenamapovanými značkami a opakovaně odeslanými zprávami u syntetického pacienta je v tutoriálu Jak importovat laboratorní výsledky do záznamu FHIR.

Zkontrolujte výsledky před odesláním

Bezplatný FHIR R4 validátor kontroluje strukturu Observation a požadované hodnotové sady. S profilem eu-lab také kontroluje, co by laboratorní výsledek měl obsahovat: kategorii laboratory, kód LOINC, subjekt, stav final-type, čas, hodnotu, jednotku UCUM a referenční rozsah. Stejné kontroly probíhají na platformě prostřednictvím POST /fhir/R4/Observation/$validate?profile=eu-lab.

Výběr API pro laboratorní výsledky: kontrolní seznam

• Ukládá výsledky jako FHIR R4 Observations s kódy LOINC, nebo jako řádky ve vlastním schématu?
• Dokáže přijímat formáty, které vaše laboratoře skutečně posílají (HL7 v2 ve většině nemocnic, CSV nebo PDF z menších laboratoří)?
• Co se stane se značkou, kterou nelze namapovat: je odmítnuta, vynechána nebo ponechána s kódem laboratoře?
• Jsou opakované pokusy bezpečné, nebo opakovaně odeslaná zpráva vytvoří duplikáty?
• Jsou opravené výsledky verzovány, přičemž dřívější hodnota je stále čitelná?
• Je původ každé hodnoty zaznamenán a viditelný pro pacienta?
• Kdo může číst výsledky a je to rozhodnuto souhlasem pacienta?

Co Anpheros nedělá

Anpheros není laboratorní informační systém a není připojen k komerčním laboratorním sítím: zprávu zasílá laboratoř, klinika nebo aplikace pacienta. Nerozesílá laboratorní objednávky, nečte PDF zprávy prostřednictvím tohoto API (aplikace Anpheros Daily extrahuje výsledky z fotografií a PDF na straně pacienta) a neinterpretuje výsledky klinicky. Jednotky jsou ukládány tak, jak je laboratoř pošle; jejich převod na kódy UCUM je na straně odesílatele, jak je popsáno v Jak normalizovat lékařská data.

Často kladené dotazy

Co je API pro laboratorní výsledky?

Rozhraní, které umožňuje softwaru odesílat nebo přijímat laboratorní výsledky ve strukturovaných datech — kódovaný test, hodnota s jednotkou, referenční rozsah, stav a čas — namísto dokumentu. Moderní API pro laboratorní výsledky používají zdroje HL7 FHIR R4 Observation a DiagnosticReport; většina laboratoří stále vydává zprávy HL7 v2 ORU^R01.

Který kódovací systém identifikuje laboratorní testy?

LOINC. Každý kód LOINC pojmenovává analyt, vzorek a často metodu, takže 2345-7 (glukóza v séru nebo plazmě) a 2339-0 (glukóza v celé krvi) jsou různé výsledky. Jednotky jsou nejlépe vyjádřeny v UCUM.

Jaký je rozdíl mezi Observation a DiagnosticReport?

Observation je jeden výsledek, například cholesterol 212 mg/dL. DiagnosticReport je zpráva jako celek — panel, který byl objednán, kdo jej vydal a kdy — a uvádí své Observation v result.

Mohu importovat HL7 v2 laboratorní zprávy na FHIR server?

Ano. Každý segment OBX se mapuje na jedno Observation (OBX-3 na code, OBX-5 a OBX-6 na valueQuantity, OBX-7 na referenceRange, OBX-8 na interpretation). Anpheros lab connector to provádí jedním požadavkem a uchovává ID laboratorní zprávy v Provenance.

Jak se vyhnout duplicitním laboratorním výsledkům, když je zpráva znovu odeslána?

Každému výsledku přiřaďte stabilní identifikátor odvozený ze zprávy, testu, času a hodnoty a přeskočte řádky, jejichž identifikátor již existuje. Anpheros lab connector to provádí automaticky a hlásí počet jako skipped.

Související

• Mapování HL7 v2 na FHIR: každý segment a pole OBX
• Jak importovat laboratorní výsledky do záznamu FHIR: podrobný návod
• Lab connector: reference koncového bodu
• Jak normalizovat lékařská data: LOINC, UCUM, data, rozsahy a duplicity
• Vysvětlení původu lékařských dat
• Kódovací systémy FHIR
• Jak integrovat klinické systémy s backendem FHIR
• FHIR vs HL7 v2: praktické rozdíly
• HL7 v2 a FHIR pro klinické dashboardy: od laboratorní zprávy k dlaždici dashboardu

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