# Laboreredmény API: HL7 v2, FHIR és LOINC

> Hogyan utaznak a laboreredmények HL7 v2 és FHIR R4 adatként, mit kell tartalmaznia egy eredménynek, és hogyan fogadhatunk laborjelentéseket FHIR rekordba, valós példával.

Source: https://developers.anpheros.com/hu/guides/lab-results-api

**A laboreredmény API strukturált adatként – tesztkód, érték, mértékegység, referenciatartomány, státusz és időpont – szolgáltatja a laboreredményeket PDF helyett, így a szoftverek tárolhatják, összehasonlíthatják, ábrázolhatják és megoszthatják azokat.** Ma ez az adat három formában utazik: HL7 v2 ORU^R01 üzenetek (még mindig a laborok és kórházak közötti gerinc), HL7 FHIR R4 `Observation` és `DiagnosticReport` erőforrások (a modern API-k formátuma), valamint labor-specifikus CSV, JSON vagy PDF exportok. Ez az oldal elmagyarázza, hogyan illeszkednek össze az elemek, mit kell tartalmaznia egy jó laboreredmény API-nak, és hogyan fogadhatunk laboradatokat egy páciens FHIR rekordjába az Anpheros segítségével.

## Kik cserélnek laboreredményeket, és milyen formátumban

| Feladó → Címzett | Jelenlegi szokásos formátum | Megjegyzések |
|---|---|---|
| Laboratórium → kórházi vagy klinikai rendszer | HL7 v2 ORU^R01 (az USA-ban gyakran az HL7 v2.5.1 Laboratory Results Interface guide szerint) | A rendelések a másik irányba mennek ORM/OML üzenetekként |
| Laboratórium → közegészségügyi ügynökség | HL7 v2 elektronikus laborjelentés, egyre inkább FHIR | Csak jelentendő állapotok |
| Klinikai rendszer → betegalkalmazás | FHIR R4 beteg-hozzáférésű API-n keresztül | Az USA-ban a tanúsított EHR-ek laboreredményeket FHIR (US Core) formátumban tesznek elérhetővé; az EU-ban az European Health Data Space a laboreredményeket prioritási adatkategóriák közé sorolja |
| Laboratórium → beteg | PDF jelentés, portál, néha CSV | A formátum, amit a legtöbb beteg ténylegesen kap |
| Alkalmazás → AI modell | Megfigyelésekből (Observations) felépített strukturált kontextus | Megbízhatósághoz kódokra és mértékegységekre van szükség |

Az irány számít: a laboratóriumi információs rendszer (LIS) az eredmények igazságforrása, és minden utána következő rendszer egy másolatot tart fenn. A másolatok megbízhatóságát az biztosítja, hogy mindegyik megőrzi az érték kódját, mértékegységét, tartományát és eredetét.

## Mit kell tartalmaznia egy laboreredménynek

Egy olyan eredmény, amely csak annyit mond, hogy "Glükóz 126", nem értelmezhető biztonságosan. Egy teljes eredmény tartalmazza:

- **Szabványos kód.** A LOINC az analitot, a mintát és a módszert azonosítja: a `2345-7` a szérumban vagy plazmában lévő glükóz, a `2339-0` a teljes vérben lévő glükóz. A labor saját kódja mellette utazhat.
- **Érték egységgel.** Ideális esetben UCUM egység (`mg/dL`, `mmol/L`, `10*3/uL`), így két labor értékei konvertálhatók és összehasonlíthatók.
- **A labor által használt referenciatartomány** és egy **értelmezési** jelző (H, L, N…), ha a labor ad ilyet.
- **Állapot:** előzetes, végleges, javított vagy módosított. Előfordulnak javítások; egy API-nak lehetővé kell tennie az új verzió megtekintését anélkül, hogy az előzőt elveszítené.
- **Időpontok:** mikor gyűjtötték a mintát (`effectiveDateTime`) és mikor tették közzé az eredményt (`issued`).
- **Eredet:** melyik laboratórium állította elő és melyik jelentéshez vagy rendeléshez tartozik.

A FHIR R4-ben minden eredmény egy `Observation`, `category = laboratory`-tal, és a csoportosító jelentés egy `DiagnosticReport`, amely felsorolja az `result`-ban lévő megfigyeléseket. Mindkettő érvényes példája, a leggyakrabban előforduló hibákkal, amelyeket a validátorok jelentenek, a [FHIR R4 JSON példákban](https://developers.anpheros.com/tools/fhir-examples/observation-lab-result) található — lásd még a [DiagnosticReport példát](https://developers.anpheros.com/tools/fhir-examples/diagnostic-report).

## HL7 v2 és FHIR egymás mellett

Ugyanaz a lipid panel eredmény, ahogyan a legtöbb labor ma küldi, és ahogyan egy API-nak tárolnia kellene:

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

| HL7 v2 mező | Jelentés | FHIR R4 Observation elem |
|---|---|---|
| OBX-3 `2093-3^Cholesterol^LN` | Teszt, LOINC kódolással | `code.coding` (rendszer `http://loinc.org`) |
| OBX-5 `212`, OBX-2 `NM` | Numerikus érték | `valueQuantity.value` |
| OBX-6 `mg/dL` | Egység | `valueQuantity.unit` |
| OBX-7 `<200` | Referenciatartomány | `referenceRange.high` |
| OBX-8 `H` | Eltérés jelző | `interpretation` |
| OBX-11 `F` | Végeredmény | `status = final` |
| OBX-14 | Megfigyelés ideje | `effectiveDateTime` |

A kettő közötti konverzió többnyire mező-hozzárendelés. A nehéz részek máshol vannak: olyan laborok, amelyek a LOINC helyett saját kódokat küldenek, számok szövegként írva (`"6,4"`, `"<5"`), többféle jelölésű tartományok, és olyan jelentések, amelyeket időtúllépés után újra elküldenek. [Az orvosi adatok normalizálása](https://developers.anpheros.com/hu/guides/normalize-medical-data) részletesen tárgyalja ezeket.

## Laboreredmény fogadása FHIR rekordba az Anpheros segítségével

Az Anpheros minden páciens rekordját HL7 FHIR R4 formátumban tárolja, és rendelkezik egy [laborkapcsolattal](https://developers.anpheros.com/hu/guides/lab-connector): egyetlen kérés képes fogadni egy teljes jelentést HL7 v2, CSV vagy JSON formátumban, és laboratóriumi megfigyeléseket (Observations) ad vissza LOINC kódokkal, referenciatartományokkal, értelmezéssel és származással.

```bash
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
```

Egy háromsoros lipidpanel (koleszterin, HDL, triglicerid) esetében a válasz, a platform helyi futtatásából:

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

Minden tárolt eredmény egy standard FHIR R4 Observation, amely bármely FHIR kliens által olvasható:

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

Ugyanazon üzenet ismételt elküldése nem hoz létre újat (`"created": 0, "skipped": 3`): minden sorhoz egy stabil azonosító tartozik a jelentés azonosítójából, a kódjából, a dátumból és az értékből. Azok a jelölők, amelyeket a platform nem tud a LOINC-hoz hozzárendelni, megtartják a labor kódját, és a `unmapped`-ben térnek vissza, így Ön kijavíthatja a hozzárendelést a forrásnál.

Az eredmények visszaolvasása egy standard FHIR keresés:

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

Más módszerek az adatok be- és kivitelére:

- **Közvetlenül FHIR-en keresztül:** `POST /fhir/R4/Observation`, vagy egy tranzakciós Bundle a `DiagnosticReport`-cel és annak megfigyeléseivel együtt.
- **Események:** `resource.created` [webhook](https://developers.anpheros.com/hu/guides/webhooks) minden egyes megfigyeléshez, így egy klinika vagy egy alkalmazás reagálhat, amikor eredmények érkeznek.
- **Embereknek és AI-nak:** a páciens látja az eredményeket az alkalmazásában; az alkalmazások, amelyekhez hozzájárul, elolvashatják őket; a `POST /v1/context` egy AI modell számára egy forrás-címkézett összefoglalót biztosít, amely tartalmazza a legutóbbi laborértékeket.
- **Származás (Provenance):** minden importált eredmény rögzíti a `author_type = import`-t, a forrásrendszert és a jelentés azonosítóját ([orvosi adatok származása](https://developers.anpheros.com/hu/guides/medical-data-provenance)).

A teljes bemutató, egy CSV jelentéssel, egy HL7 v2 üzenettel, nem hozzárendelt jelölőkkel és ismételten elküldött jelentésekkel egy szintetikus páciensen, a [Hogyan importáljunk laboreredményeket FHIR rekordba](https://developers.anpheros.com/hu/guides/import-lab-results-fhir) című oktatóanyagban található.

## Eredmények ellenőrzése küldés előtt

Az ingyenes [FHIR R4 validator](https://developers.anpheros.com/tools/fhir-validator) ellenőrzi egy Observation szerkezetét és a kötelező értékkészleteket, a `eu-lab` profillal pedig azt is ellenőrzi, hogy egy laboratóriumi eredménynek mit kell tartalmaznia: a `laboratory` kategóriát, egy LOINC kódot, egy alanyt, egy végső típusú státuszt, egy időpontot, egy értéket, egy UCUM egységet és egy referenciatartományt. Ugyanezek az ellenőrzések futnak a platformon keresztül a `POST /fhir/R4/Observation/$validate?profile=eu-lab` segítségével.

## Laboratóriumi eredmények API kiválasztása: ellenőrzőlista

- Az eredményeket FHIR R4 Observations formátumban, LOINC kódokkal tárolja, vagy saját sémájában sorokként?
- El tudja fogadni azokat a formátumokat, amelyeket a laboratóriumok valójában küldenek (HL7 v2 a legtöbb kórházban, CSV vagy PDF kisebb laboroktól)?
- Mi történik egy olyan markerrel, amelyet nem tud leképezni: elutasítják, elvetik, vagy megtartják a labor kódjával?
- Biztonságosak az újrapróbálkozások, vagy egy újra elküldött jelentés kettős bejegyzéseket hoz létre?
- A javított eredmények verziózottak, az előző érték még olvasható?
- Minden érték eredete rögzítve van és látható a beteg számára?
- Ki olvashatja az eredményeket, és ezt a beteg beleegyezése határozza meg?

## Amit az Anpheros nem csinál

Az Anpheros nem egy laboratóriumi információs rendszer, és nem kapcsolódik kereskedelmi laboratóriumi hálózatokhoz: a jelentést a laboratórium, a klinika vagy a páciens alkalmazása küldi el. Nem továbbítja a laboratóriumi rendeléseket, nem olvas PDF jelentéseket ezen az API-n keresztül (az Anpheros Daily alkalmazás a páciens oldalán fényképekből és PDF-ekből vonja ki az eredményeket), és nem értelmezi klinikailag az eredményeket. Az egységek úgy vannak tárolva, ahogy a laboratórium küldi őket; az UCUM kódokra való átalakítás a küldő feladata, ahogy az a [Hogyan normalizáljuk az orvosi adatokat](https://developers.anpheros.com/hu/guides/normalize-medical-data) részben le van írva.

## Gyakran ismételt kérdések

### Mi az a laboreredmény API?
Egy interfész, amely lehetővé teszi a szoftverek számára laboreredmények küldését vagy fogadását strukturált adatként – kódolt teszt, érték egységgel, referencia tartomány, státusz és idő –, nem pedig dokumentumként. A modern laboreredmény API-k HL7 FHIR R4 Observation és DiagnosticReport erőforrásokat használnak; a legtöbb laboratórium még mindig HL7 v2 ORU^R01 üzeneteket generál.

### Melyik kódrendszer azonosítja a laboratóriumi teszteket?
LOINC. Minden LOINC kód megnevezi az analitot, a mintát és gyakran a módszert, így a `2345-7` (glükóz szérumban vagy plazmában) és a `2339-0` (glükóz teljes vérben) különböző eredmények. Az egységeket UCUM-ban érdemes kifejezni.

### Mi a különbség az Observation és a DiagnosticReport között?
Az Observation egyetlen eredmény, például koleszterin 212 mg/dL. A DiagnosticReport maga a jelentés egésze – a megrendelt panel, ki állította ki és mikor –, és felsorolja az Observation-jeit a `result`-ban.

### Importálhatok HL7 v2 laborüzeneteket FHIR szerverre?
Igen. Minden OBX szegmens egy Observation-höz rendelődik (OBX-3 a `code`-hez, OBX-5 és OBX-6 a `valueQuantity`-hez, OBX-7 a `referenceRange`-hez, OBX-8 a `interpretation`-hez). Az Anpheros labor csatlakozó ezt egyetlen kérésre elvégzi, és a jelentés azonosítóját a Provenance-ben tárolja.

### Hogyan kerülhetem el az ismétlődő laboreredményeket, ha egy jelentést újra elküldenek?
Minden eredményhez adjon egy stabil azonosítót, amely a jelentésből, a tesztből, az időből és az értékből származik, és hagyja ki azokat a sorokat, amelyek azonosítója már létezik. Az Anpheros labor csatlakozó ezt automatikusan megteszi, és az eredmények számát `skipped`-ként jelenti.

## Kapcsolódó

- [HL7 v2 és FHIR leképezés](https://developers.anpheros.com/hu/guides/hl7-v2-to-fhir-mapping): minden szegmens és OBX mező
- [Laboreredmények importálása FHIR rekordba](https://developers.anpheros.com/hu/guides/import-lab-results-fhir): lépésről lépésre útmutató
- [Lab connector](https://developers.anpheros.com/hu/guides/lab-connector): az endpoint referencia
- [Orvosi adatok normalizálása](https://developers.anpheros.com/hu/guides/normalize-medical-data): LOINC, UCUM, dátumok, tartományok és ismétlődések
- [Orvosi adatok eredetének magyarázata](https://developers.anpheros.com/hu/guides/medical-data-provenance)
- [FHIR kódrendszerek](https://developers.anpheros.com/hu/guides/fhir-code-systems)
- [Klinikai rendszerek integrálása FHIR backenddel](https://developers.anpheros.com/hu/guides/integrate-clinic-systems-fhir)
- [FHIR vs HL7 v2: gyakorlati különbségek](https://developers.anpheros.com/hu/guides/fhir-vs-hl7-v2)
- [HL7 v2 és FHIR klinikai irányítópultokhoz](https://developers.anpheros.com/hu/guides/clinical-dashboard-hl7-fhir): laborüzenettől az irányítópult csempéjéig