AnpherosAnpheros PlatformDevelopers

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

Laboreredmények importálása FHIR rekordba

Oktatóanyag: importáljon laborjelentést CSV és HL7 v2 ORU^R01 formátumban FHIR R4 megfigyelésekbe (Observations) LOINC kódokkal és referencia tartományokkal, kezelje a nem leképezett markereket és az újra elküldött jelentéseket, és kövesse nyomon minden eredményt a laboratóriumáig.

Ez a tutorial egy laboratóriumi jelentést CSV fájlként és HL7 v2 ORU^R01 üzenetként kezel, minden esetben egy kéréssel importálja egy páciens HL7 FHIR R4 rekordjába, és megmutatja, mit kap vissza: laboratóriumi Observation erőforrásokat LOINC kódokkal, referenciatartományokkal és származási információkkal. Kitér továbbá két olyan problémára, amellyel minden laboratóriumi integráció szembesül: a nem automatikusan hozzárendelhető markerekre és az ismételten elküldött jelentésekre. Minden a díjmentes sandboxon fut, szintetikus pácienssel.

Miért nehéz laboreredményeket tárolni

Egy laboreredmény egyszerűnek tűnik: egy jelző, egy érték, egy mértékegység, egy referencia tartomány, egy dátum. A gyakorlatban minden laboratórium a saját módján nevezi el a jelzőket („Hemoglobina glicozilata”, „HbA1c”, „Glycated haemoglobin”), tizedesvesszőt vagy pontot használ a tizedesek jelölésére, a tartományokat 4,0-5,6, <5 vagy >3.5 formában írja, és ugyanazt a jelentést küldi el újra, ha valami meghibásodik. Szabad szövegként tárolva ezek az eredmények nem hasonlíthatók össze idővel, nem ábrázolhatók, nem oszthatók meg más alkalmazásokkal, és nem adhatók át magabiztosan egy AI modellnek.

Egy FHIR rekord minden eredményt Observation-ként tárol, LOINC kóddal, UCUM mértékegységgel, értékkel, referencia tartománnyal és dátummal, és a küldőt egy Provenance erőforrásban tartja nyilván. A labor csatlakozó elvégzi ezt az átalakítást az Ön számára.

 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

Kezdés előtt

Szüksége van egy sandbox kulcsra (sk_test_…) a következő helyről: platform.anpheros.com/dashboard (Sandbox kulcs igénylése). A példák a curl használják; az SDK-k ugyanazokat a hívásokat tartalmazzák (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')

1. lépés: CSV jelentés importálása

Így exportálhat egy jelentést egy romániai laboratórium: pontosvesszők, tizedesvesszők, román oszlopnevek és dátumok, mint a DD.MM.YYYY. A csatlakozó felismeri a román és angol oszlopneveket.

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

A válasz (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"}]}

Az HbA1c, a glükóz és a TSH a nevük alapján a LOINC-hoz lettek hozzárendelve. A tizedesvesszők számokká váltak, a tartományok pedig referenceRange lettek. Egy sor érkezett vissza a unmapped-ben. Ez továbbra is tárolva van a laboratórium saját kódja alatt (urn:anpheros:lab-code) a jelentés pontos szövegével, így semmi sem vész el.

2. lépés: Nem hozzárendelt jelölők kezelése

Egyes nevek döntést igényelnek. A "Glicemie" (vércukor) jó példa erre: a LOINC rendelkezik egy kóddal a szérumban vagy plazmában lévő glükózra (2345-7, laboratóriumban vett vénás minta), és egy másikkal a teljes vérben lévő glükózra (2339-0, például ujjbegyből vett vércsepp). Laboratóriumi jelentésen a csupasz "Glicemie" a szérumhoz vagy plazmához van hozzárendelve. A "capilar", "capillary" vagy "sânge integral" nevű jelölők a teljes vérhez vannak hozzárendelve:

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

Azoknál a jelölőknél, amelyeket a csatlakozó nem ismer fel, keresse meg a kódot:

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}

Ezután küldje el a kódot egy LOINC oszlopban. A jelentésben szereplő kód mindig felülírja a nevet. Tartsa meg ezt a hozzárendelést laboratóriumonként az Ön oldalán, és adja hozzá az oszlopot minden onnan származó jelentéshez:

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

Azok a jelölők, amelyeket a LOINC egyáltalán nem fed le, mint például a kitalált "Marker foarte rar", a laboratórium kódja alatt maradhatnak. Ezek megjelennek a beteg számára, és bekerülnek a rekordba. Nem hasonlíthatók össze más laboratóriumok eredményeivel.

3. lépés: Ugyanazon jelentés kétszeri elküldése

A laboratóriumok újra elküldik a jelentéseket. Minden sorhoz egy stabil azonosító tartozik, amely a jelentés azonosítójából, a kódjából, a dátumából és az értékéből épül fel, így ugyanazon jelentés második importálása semmit sem hoz létre:

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

A megváltozott sorok, például egy javított érték, új eredményekként kerülnek importálásra. A Idempotency-Key fejléc további garanciát nyújt: az azonos kulccsal végrehajtott hálózati újrapróbálkozás változatlanul az első választ adja vissza.

4. lépés: HL7 v2 ORU^R01 üzenet importálása

A legtöbb laboratóriumi információs rendszer HL7 v2 nyelven kommunikál. Küldje el az üzenetet a jelenlegi formájában (ER7 szöveg, szegmensek CR vagy LF karakterekkel elválasztva):

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

A OBX-3 kódrendszerrel ellátott LN a LOINC kódként kerül felhasználásra. A OBX-7 lesz a referenciatartomány, a OBX-8 (H, N) pedig az interpretáció. A OBR-3 (R-77) az eredetben jelentésazonosítóként kerül megőrzésre. A páciens az URL-ben található személy: a PID szegmens nem kerül felhasználásra a páciens azonosítására, így egy helytelen PID nem tud eredményeket valaki máshoz csatolni.

Már rendelkezik feldolgozott eredményekkel? Küldjön JSON formátumban: {"date": "2026-10-01", "origin": "report-77", "items": [{"marker": "Ferritin", "value": 38, "unit": "ng/mL", "ref_low": 15, "ref_high": 150}]}. A Ferritin a LOINC 2276-4 kódhoz van hozzárendelve.

5. lépés: Az eredmények FHIR formátumban történő olvasása

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

Az importált HbA1c, ahogy tárolva van:

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

A LOINC kijelző a standard angol név. code.text megőrzi a laboratórium saját megfogalmazását, így a beteg továbbra is azt látja, ami a papírjelentésen szerepelt. Az erőforrásokkal és a kereséssel kapcsolatos további információkért tekintse meg a FHIR platform útmutatót és a FHIR kódrendszereket.

6. lépés: Ellenőrizze, ki küldte

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}

A author_type: import és a source_system: labx az értékkel marad. Amikor egy AI alkalmazás később ezen eredményt a context API segítségével olvassa, az [import/labx]-ként lesz címkézve, így a modell meg tudja különböztetni a laboratóriumi eredményt attól az értéktől, amelyet a beteg maga írt be.

Mi történik ezután

Gyakran ismételt kérdések

Milyen laboratóriumi jelentésformátumok importálhatók a FHIR-be?

CSV fejléc sorral (vessző, pontosvessző vagy tabulátor, tizedesvessző elfogadott), HL7 v2 ORU^R01 üzenetek és JSON. A PDF jelentések dokumentumként tárolhatók; az azokból kinyert értékek a dokumentumra mutatnak vissza.

Mi történik a LOINC kód nélküli markerekkel?

Ezek a laboratórium saját kódja alatt tárolódnak a jelentés pontos szövegével, és a unmapped listában szerepelnek. Adjon hozzá egy LOINC oszlopot az adott laboratóriumhoz, és azok hozzárendelésre kerülnek. A jelentésben szereplő kód mindig elsőbbséget élvez a névvel szemben.

Biztonságos egy jelentés újraküldése?

Igen. Minden sor egy stabil azonosítóval rendelkezik, amely a jelentésből, kódból, dátumból és értékből épül fel, így az már importált sorok kihagyásra kerülnek; a megváltozott sorok új eredményekként kerülnek importálásra.

Importálhat-e egy laboratórium eredményeket bármely páciens számára?

Nem. Egy laboratórium csak az általa létrehozott projektbe vagy olyan páciensekhez importálhat, akiknek az adatait az illető megosztotta vele OAuth-on keresztül. Más páciensek nem léteznek számára (404).

Kapcsolódó

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

Product updates by email

New features, guides and the end of the beta. One email a month at most.

Send me occasional Anpheros Platform updates by email (new features, API changes, guides). I'll confirm by email and can unsubscribe in one click from any email. Privacy