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

Ako importovať výsledky laboratórnych testov do FHIR záznamu

Návod: importujte laboratórnu správu ako CSV a ako HL7 v2 ORU^R01 do FHIR R4 Observations s kódmi LOINC a referenčnými rozsahy, spracujte nemapované markery a opätovne odoslané správy a sledujte každý výsledok do jeho laboratória.

Tento tutoriál berie laboratórnu správu ako súbor CSV a ako HL7 v2 ORU^R01 správu, importuje ju do HL7 FHIR R4 záznamu pacienta v každom prípade jedným požiadavkom a ukazuje, čo dostanete späť: laboratórne Observation zdroje s LOINC kódmi, referenčnými rozsahami a pôvodom. Pokrýva tiež dva problémy, s ktorými sa stretáva každá laboratórna integrácia: markery, ktoré sa nedajú automaticky namapovať, a správy, ktoré sa posielajú dvakrát. Všetko beží na bezplatnom sandboxe so syntetickým pacientom.

Prečo je ukladanie laboratórnych výsledkov náročné

Laboratórna správa vyzerá jednoducho: marker, hodnota, jednotka, referenčný rozsah, dátum. V praxi si každý laboratórny ústav pomenúva markery po svojom („Hemoglobina glicozilata“, „HbA1c“, „Glycated haemoglobin“), používa čiarky alebo bodky pre desatinné miesta, píše rozsahy ako 4,0-5,6, <5 alebo >3.5 a pri zlyhaní posiela tú istú správu znova. Ak sú výsledky uložené ako voľný text, nemožno ich porovnávať v priebehu času, graficky zobrazovať, zdieľať s inou aplikáciou ani s istotou odovzdať modelu AI.

Záznam FHIR ukladá každý výsledok ako Observation s kódom LOINC, jednotkou UCUM, hodnotou, referenčným rozsahom a dátumom a uchováva informáciu o tom, kto ho poslal, v zdroji Provenance. Laboratórny konektor vykonáva túto konverziu 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

Pred začiatkom

Potrebujete sandbox kľúč (sk_test_…) z platform.anpheros.com/dashboard (Získať sandbox kľúč). Príklady používajú curl; SDK majú rovnaké volania (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 reportu

Takto môže rumunské laboratórium exportovať report: bodkočiarky, desatinné čiarky, rumunské názvy stĺpcov a dátumy ako DD.MM.YYYY. Konektor rozpoznáva rumunské a anglické názvy stĺpcov.

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

Odpoveď (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 boli namapované na LOINC z ich názvov. Desatinné čiarky sa stali číslami a rozsahy sa stali referenceRange. Jeden riadok sa vrátil v unmapped. Stále je uložený pod vlastným kódom laboratória (urn:anpheros:lab-code) s presným textom z reportu, takže sa nič nestratilo.

Krok 2: spracovanie nemapovaných značiek

Niektoré názvy si vyžadujú rozhodnutie. "Glicemie" (glukóza v krvi) je dobrým príkladom: LOINC má jeden kód pre glukózu v sére alebo plazme (2345-7, odber vzorky žilovej krvi v laboratóriu) a druhý pre glukózu v celej krvi (2339-0, napríklad odber z prsta). V laboratórnej správe sa holá "Glicemie" mapuje na sérum alebo plazmu. Názov, ktorý hovorí "capilar", "capillary" alebo "sânge integral", sa mapuje na celú krv:

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

Pre značky, ktoré konektor nerozpoznáva, vyhľadajte 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}

Potom odošlite kód v stĺpci LOINC. Kód v správe má vždy prednosť pred názvom. Uchovajte si toto mapovanie na laboratórium na svojej strane a pridajte stĺpec do každej správy z neho:

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

Značky, ktoré LOINC vôbec nepokrýva, ako napríklad vymyslený "Marker foarte rar", môžu zostať pod kódom laboratória. Zobrazujú sa pacientovi a sú zahrnuté v zázname. Nemožno ich porovnať s výsledkami iných laboratórií.

Krok 3: Odoslanie tej istej správy dvakrát

Laboratóriá opätovne posielajú správy. Každý riadok dostane stabilný identifikátor vytvorený z ID správy, kódu, dátumu a hodnoty, takže druhé importovanie tej istej správy nič nevytvorí:

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

Riadky, ktoré sa zmenili, napríklad opravená hodnota, sa importujú ako nové výsledky. Hlavička Idempotency-Key pridáva druhú záruku: sieťové opätovné pokusy s tým istým kľúčom vrátia prvú odpoveď nezmenenú.

Krok 4: import správy HL7 v2 ORU^R01

Väčšina laboratórnych informačných systémov komunikuje pomocou HL7 v2. Pošlite správu tak, ako je (text ER7, segmenty oddelené CR alebo 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 so systémom kódovania LN sa používa priamo ako LOINC. OBX-7 sa stáva referenčným rozsahom a OBX-8 (H, N) interpretáciou. OBR-3 (R-77) sa uchováva ako ID správy v pôvode. Pacient je ten z URL: segment PID sa nepoužíva na vyhľadanie pacienta, takže nesprávny PID nemôže priložiť výsledky niekomu inému.

Už máte spracované výsledky? Pošlite JSON: {"date": "2026-10-01", "origin": "report-77", "items": [{"marker": "Ferritin", "value": 38, "unit": "ng/mL", "ref_low": 15, "ref_high": 150}]}. Ferritín je namapovaný na LOINC 2276-4.

Krok 5: čítanie výsledkov ako FHIR

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

Importovaný HbA1c, ako 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 štandardný anglický názov. code.text zachováva vlastné formulácie laboratória, takže pacient stále vidí to, čo bolo na papierovom hlásení. Viac informácií o zdrojoch a vyhľadávaní nájdete v príručke FHIR platform a FHIR code systems.

Krok 6: Kontrola odosielateľa

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 zostávajú s hodnotou. Keď AI aplikácia neskôr prečíta tento výsledok prostredníctvom context API, je označený ako [import/labx], aby model mohol rozlíšiť laboratórny výsledok od hodnoty zadanej pacientom.

Čo sa stane ďalej

Pacient vidí výsledky vo svojej aplikácii. Každá aplikácia, ku ktorej súhlasil, si ich môže prečítať v rámci svojich rozsahov (model súhlasu a prístupu).
Pre každé Observation sa spustí webhook resource.created, takže dashboard kliniky alebo AI zhrnutie sa môže aktualizovať bez potreby opakovaného dotazovania (polling).
POST /fhir/R4/Observation/$validate?profile=eu-lab hlási, ako sa výsledok porovnáva s profilom laboratórnej správy HL7 Europe.
Až 500 riadkov na požiadavku; limity sú uvedené v časti Limity a obmedzenia rýchlosti.

Často kladené otázky

Aké formáty laboratórnych správ je možné importovať do FHIR?

CSV s hlavičkou (akceptované sú čiarka, bodkočiarka alebo tabulátor, desatinná čiarka), správy HL7 v2 ORU^R01 a JSON. PDF správy je možné uložiť ako dokumenty; hodnoty z nich extrahované odkazujú späť na dokument.

Čo sa stane so značkami bez LOINC kódu?

Ukladajú sa pod vlastným kódom laboratória s presným textom zo správy a sú uvedené v unmapped. Pridajte stĺpec LOINC pre dané laboratórium a budú namapované. Kód v správe má vždy prednosť pred názvom.

Je bezpečné opätovne poslať správu?

Áno. Každý riadok má stabilný identifikátor vytvorený zo správy, kódu, dátumu a hodnoty, takže už importované riadky sa preskočia; zmenené riadky sa importujú ako nové výsledky.

Môže laboratórium importovať výsledky pre akéhokoľvek pacienta?

Nie. Laboratórium importuje do pacientov, ktorých projekt vytvorilo, alebo ktorých záznamy mu osoba zdieľala prostredníctvom OAuth. Iní pacienti preň neexistujú (404).

Súvisiace

API pre laboratórne výsledky: HL7 v2 a FHIR vedľa seba a čo musí jeden výsledok obsahovať
Konektor pre laboratórne dáta: každý názov stĺpca, HL7 pole a pole odpovede
Interoperabilita zdravotníckych dát: prečo kódy a pôvod robia vymenené dáta použiteľnými
Integrácie v zdravotníctve: kliniky, laboratóriá, zariadenia a aplikácie tretích strán
API pre medicínske dáta: písanie jednotlivých pozorovaní, diagnóz a liekov
Ako vytvoriť AI aplikáciu pre zdravotníctvo s FHIR backendom: použitie týchto výsledkov v AI odpovedi

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