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

Jak importovat laboratorní výsledky do FHIR záznamu

Návod: import laboratorní zprávy jako CSV a jako HL7 v2 ORU^R01 do FHIR R4 Observations s LOINC kódy a referenčními rozsahy, zpracování nemapovaných markerů a opakovaných zpráv a sledování každého výsledku do jeho laboratoře.

Tento návod vezme laboratorní zprávu jako soubor CSV a jako zprávu HL7 v2 ORU^R01, importuje ji do HL7 FHIR R4 záznamu pacienta v každém případě jedním požadavkem a ukáže, co dostanete zpět: laboratorní Observation zdroje s LOINC kódy, referenčními rozsahy a původem. Pokrývá také dva problémy, se kterými se setká každá integrace laboratoře: markery, které nelze automaticky namapovat, a zprávy, které jsou odeslány dvakrát. Vše běží na bezplatném sandboxu se syntetickým pacientem.

Proč je ukládání laboratorních výsledků obtížné

Laboratorní zpráva vypadá jednoduše: značka, hodnota, jednotka, referenční rozmezí, datum. V praxi každá laboratoř pojmenovává značky svým vlastním způsobem ("Hemoglobina glicozilata", "HbA1c", "Glycated haemoglobin"), používá čárky nebo tečky pro desetinná místa, zapisuje rozmezí jako 4,0-5,6, <5 nebo >3.5 a při selhání opakovaně posílá stejnou zprávu. Pokud jsou výsledky uloženy jako volný text, nelze je porovnávat v čase, graficky zobrazovat, sdílet s jinou aplikací ani s jistotou předat modelu umělé inteligence.

Záznam FHIR ukládá každý výsledek jako Observation s kódem LOINC, jednotkou UCUM, hodnotou, referenčním rozmezím a datem a uchovává informaci o tom, kdo jej odeslal, v prostředku Provenance. Konektor pro laboratoře provádí tuto konverzi za vás.

 lab report (CSV, HL7 v2, JSON)
        │  POST /v1/patients/{id}/labs/import
        ▼
 ┌──────────────────────────────────────────────┐
 │ parse rows → map marker to LOINC → parse     │
 │ value, unit, range → stable id per row       │
 └──────────────────────────────────────────────┘
        │
        ▼
 Observation (category laboratory) + Provenance (author_type import, source system, report id)
        │
        ├─► the patient's app and every app they consented to
        └─► webhooks: resource.created per Observation

Než začnete

Potřebujete sandbox klíč (sk_test_…) z platform.anpheros.com/dashboard (Získat sandbox klíč). Příklady používají curl; SDK mají stejné volání (labs.importCsv, labs.importHl7, labs.importItems).

export BASE=https://platform.anpheros.com
export KEY=sk_test_…
# Elena Ionescu, a synthetic patient with type 2 diabetes
export PID=$(curl -s "$BASE/fhir/R4/Patient?identifier=https://anpheros.com/fhir/sid/sandbox-persona|p02" \
  -H "Authorization: Bearer $KEY" | jq -r '.entry[0].resource.id')

Krok 1: Import CSV zprávy

Takto může rumunská laboratoř exportovat zprávu: středníky, desetinné čárky, rumunské názvy sloupců a data jako DD.MM.YYYY. Konektor rozpoznává rumunské a anglické názvy sloupců.

cat > report.csv <<'EOF'
Analiza;Rezultat;UM;Interval de referinta;Data
Hemoglobina glicozilata (HbA1c);6,9;%;4,0-5,6;01.10.2026
Glicemie;131;mg/dL;70-100;01.10.2026
TSH;2,1;mUI/L;0,4-4,0;01.10.2026
Marker foarte rar;12;U/L;0-20;01.10.2026
EOF

curl -X POST "$BASE/v1/patients/$PID/labs/import" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: text/csv" -H "X-Anpheros-Source-System: labx" \
     -H "Idempotency-Key: report-2026-10-01-elena" --data-binary @report.csv

Odpověď (201):

{"created": 4, "skipped": 0, "unmapped": ["Marker foarte rar"], "warnings": [],
 "observations": [
  {"id": "ff0bbb44-…", "marker": "Hemoglobina glicozilata (HbA1c)", "code": "4548-4", "system": "http://loinc.org", "value": 6.9, "unit": "%", "date": "2026-10-01"},
  {"id": "ebe5522f-…", "marker": "Glicemie", "code": "2345-7", "system": "http://loinc.org", "value": 131.0, "unit": "mg/dL", "date": "2026-10-01"},
  {"id": "bace44a8-…", "marker": "TSH", "code": "3016-3", "system": "http://loinc.org", "value": 2.1, "unit": "mUI/L", "date": "2026-10-01"},
  {"id": "26fd2270-…", "marker": "Marker foarte rar", "code": "marker_foarte_rar", "system": "urn:anpheros:lab-code", "value": 12.0, "unit": "U/L", "date": "2026-10-01"}]}

HbA1c, glukóza a TSH byly namapovány na LOINC podle jejich názvů. Desetinné čárky se změnily na čísla a rozsahy se staly referenceRange. Jeden řádek se vrátil v unmapped. Stále je uložen pod vlastním kódem laboratoře (urn:anpheros:lab-code) s přesným textem ze zprávy, takže se nic neztratilo.

Krok 2: Zpracování nemapovaných značek

Některá jména vyžadují rozhodnutí. „Glicemie“ (hladina glukózy v krvi) je dobrým příkladem: LOINC má jeden kód pro glukózu v séru nebo plazmě (2345-7, vzorek odebraný v laboratoři z žíly) a druhý pro glukózu v celé krvi (2339-0, například z prstu). V laboratorní zprávě je holá „Glicemie“ mapována na sérum nebo plazmu. Název, který říká „capilar“, „capillary“ nebo „sânge integral“, je mapován na celou krev:

{"created": 1, "skipped": 0, "unmapped": [], "warnings": [],
 "observations": [{"id": "00480a6d-…", "marker": "Glicemie capilara", "code": "2339-0", "system": "http://loinc.org", "value": 140.0, "unit": "mg/dL", "date": "2026-10-02"}]}

Pro značky, které konektor nerozpozná, vyhledejte kód:

curl "$BASE/v1/terminology/loinc?q=glucose" -H "Authorization: Bearer $KEY"

{"data": [
  {"system": "http://loinc.org", "code": "2339-0", "display": "Glucose [Mass/volume] in Blood", "display_ro": "Glicemie (sânge)", "category": "laboratory", "unit": "mg/dL"},
  {"system": "http://loinc.org", "code": "2345-7", "display": "Glucose [Mass/volume] in Serum or Plasma", "display_ro": "Glicemie (ser)", "category": "laboratory", "unit": "mg/dL"}],
 "total": 2}

Poté odešlete kód ve sloupci LOINC. Kód ve zprávě má vždy přednost před názvem. Tuto mapu uchovávejte pro každé laboratoř na vaší straně a přidejte sloupec do každé zprávy z ní:

Analiza;Rezultat;UM;Interval de referinta;Data;LOINC
Glicemie;99;mg/dL;70-100;04.10.2026;2339-0

Značky, které LOINC vůbec nepokrývá, jako například smyšlený „Marker foarte rar“, mohou zůstat pod kódem laboratoře. Jsou zobrazeny pacientovi a zahrnuty do záznamu. Nelze je porovnávat s výsledky jiných laboratoří.

Krok 3: Odeslání stejné zprávy dvakrát

Laboratoře zasílají zprávy opakovaně. Každý řádek získá stabilní identifikátor sestavený z ID zprávy, kódu, data a hodnoty, takže druhý import stejné zprávy nic nevytvoří:

{"created": 0, "skipped": 4, "unmapped": ["Marker foarte rar"], "warnings": [], "observations": []}

Řádky, které se změnily, například opravená hodnota, jsou importovány jako nové výsledky. Hlavička Idempotency-Key přidává druhou záruku: síťové opakování se stejným klíčem vrátí první odpověď nezměněnou.

Krok 4: Import zprávy HL7 v2 ORU^R01

Většina laboratorních informačních systémů komunikuje pomocí HL7 v2. Odešlete zprávu tak, jak je (text ER7, segmenty oddělené CR nebo LF):

MSH|^~\&|LABX|LAB1|ANPHEROS|EHR|202610010930||ORU^R01|MSG00077|P|2.5.1
PID|1||12345||Ionescu^Elena||19850903|F
OBR|1||R-77|24331-1^Lipid panel^LN|||202610010800
OBX|1|NM|2093-3^Cholesterol [Mass/volume] in Serum or Plasma^LN||212|mg/dL|<200|H|||F|||202610010800
OBX|2|NM|2085-9^HDL Cholesterol^LN||52|mg/dL|>40|N|||F|||202610010800

curl -X POST "$BASE/v1/patients/$PID/labs/import" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: x-application/hl7-v2+er7" --data-binary @oru.hl7

{"created": 2, "skipped": 0, "unmapped": [], "warnings": [],
 "observations": [
  {"id": "b562045b-…", "marker": "Cholesterol [Mass/volume] in Serum or Plasma", "code": "2093-3", "system": "http://loinc.org", "value": 212.0, "unit": "mg/dL", "date": "2026-10-01T08:00:00Z"},
  {"id": "9b3274e4-…", "marker": "HDL Cholesterol", "code": "2085-9", "system": "http://loinc.org", "value": 52.0, "unit": "mg/dL", "date": "2026-10-01T08:00:00Z"}]}

OBX-3 se systémem kódování LN je použit přímo jako LOINC. OBX-7 se stává referenčním rozsahem a OBX-8 (H, N) interpretací. OBR-3 (R-77) je zachováno jako ID zprávy v původu (provenance). Pacientem je ten, který je v URL: segment PID se nepoužívá k nalezení pacienta, takže nesprávný PID nemůže připojit výsledky k někomu jinému.

Již máte zpracované výsledky? Odešlete JSON: {"date": "2026-10-01", "origin": "report-77", "items": [{"marker": "Ferritin", "value": 38, "unit": "ng/mL", "ref_low": 15, "ref_high": 150}]}. Ferritin je namapován na LOINC 2276-4.

Krok 5: čtení výsledků jako FHIR

curl "$BASE/fhir/R4/Observation?patient=$PID&code=http://loinc.org|4548-4&_sort=-date&_count=1" \
     -H "Authorization: Bearer $KEY"

Importovaný HbA1c, jak je uložen:

{
  "resourceType": "Observation",
  "id": "62b1b0c0-…",
  "meta": {"versionId": "1", "lastUpdated": "2026-10-12T20:05:57.011Z"},
  "identifier": [{"system": "urn:anpheros:lab-import", "value": "c52d3cd6449291d34f6bef1516d0ac05"}],
  "status": "final",
  "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "laboratory"}]}],
  "code": {"coding": [{"system": "http://loinc.org", "code": "4548-4", "display": "Hemoglobin A1c/Hemoglobin.total in Blood"}],
           "text": "Hemoglobina glicozilata (HbA1c)"},
  "subject": {"reference": "Patient/…"},
  "effectiveDateTime": "2026-10-01",
  "valueQuantity": {"value": 6.9, "unit": "%"},
  "referenceRange": [{"low": {"value": 4.0, "unit": "%"}, "high": {"value": 5.6, "unit": "%"}}]
}

LOINC display je standardní anglický název. code.text zachovává vlastní formulaci laboratoře, takže pacient stále vidí to, co bylo na papírové zprávě. Další informace o zdrojích a vyhledávání naleznete v příručce FHIR platform a FHIR code systems.

Krok 6: Kontrola odesílatele

curl "$BASE/v1/patients/$PID/provenance/Observation/62b1b0c0-…" -H "Authorization: Bearer $KEY"

{"data": [{"version": 1, "activity": "CREATE", "recorded": "2026-10-12T20:05:57.011000Z",
           "author_type": "import", "author": "proj_…", "source_system": "labx", "origin_id": null,
           "fhir": "Provenance/f15c4fee-…"}], "total": 1}

author_type: import a source_system: labx zůstávají s hodnotou. Když AI aplikace později tuto výsledek přečte prostřednictvím context API, je označen jako [import/labx], takže model dokáže rozlišit laboratorní výsledek od hodnoty zadané pacientem.

Co se děje dál

Pacient vidí výsledky ve své aplikaci. Jakákoli aplikace, ke které udělil souhlas, si je může přečíst v rámci svých rozsahů (model souhlasu a přístupu).
Pro každé Observation se spustí webhook resource.created, takže se panel kliniky nebo souhrn AI může aktualizovat bez nutnosti opakovaného dotazování.
POST /fhir/R4/Observation/$validate?profile=eu-lab hlásí, jak se výsledek měří podle profilu laboratorní zprávy HL7 Europe.
Až 500 řádků na požadavek; limity jsou uvedeny v Limity a rychlostní limity.

Často kladené dotazy

Jaké formáty laboratorních zpráv lze importovat do FHIR?

CSV s hlavičkovým řádkem (akceptuje se čárka, středník nebo tabulátor, desetinná čárka), zprávy HL7 v2 ORU^R01 a JSON. Zprávy PDF lze ukládat jako dokumenty; hodnoty z nich extrahované odkazují zpět na dokument.

Co se stane se značkami bez kódu LOINC?

Jsou uloženy pod vlastním kódem laboratoře s přesným textem ze zprávy a uvedeny v unmapped. Přidejte sloupec LOINC pro danou laboratoř a dojde k jejich mapování. Kód ve zprávě má vždy přednost před názvem.

Je bezpečné znovu odeslat zprávu?

Ano. Každý řádek má stabilní identifikátor vytvořený ze zprávy, kódu, data a hodnoty, takže již importované řádky jsou přeskočeny; změněné řádky jsou importovány jako nové výsledky.

Může laboratoř importovat výsledky pro libovolného pacienta?

Ne. Laboratoř importuje do pacientů, které její projekt vytvořil, nebo jejichž záznamy jí osoba sdílela prostřednictvím OAuth. Jiní pacienti pro ni neexistují (404).

Související

API pro laboratorní výsledky: HL7 v2 a FHIR vedle sebe a co musí jeden výsledek obsahovat
Konektor pro laboratoř: každý název sloupce, HL7 pole a pole odpovědi
Interoperabilita zdravotnických dat: proč kódy a původ činí vyměňovaná data použitelnými
Integrace zdravotnických zařízení: kliniky, laboratoře, zařízení a aplikace třetích stran
API pro lékařská data: zápis jednotlivých pozorování, stavů a léků
Jak vytvořit AI aplikaci pro zdravotnictví s FHIR backendem: použití těchto výsledků v AI odpovědi

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