# API pre laboratórne výsledky: HL7 v2, FHIR a LOINC

> Ako cestujú laboratórne výsledky ako dáta HL7 v2 a FHIR, čo musí jeden výsledok obsahovať a ako prijímať laboratórne správy do záznamu FHIR, s reálnym príkladom.

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

**API pre laboratórne výsledky doručuje laboratórne výsledky ako štruktúrované dáta — kód testu, hodnota, jednotka, referenčný rozsah, stav a čas — namiesto PDF, takže ich softvér môže ukladať, porovnávať, graficky zobrazovať a zdieľať.** Dnes tieto dáta cestujú v troch formách: správy HL7 v2 ORU^R01 (stále chrbtica medzi laboratóriami a nemocnicami), zdroje HL7 FHIR R4 `Observation` a `DiagnosticReport` (formát moderných API) a exporty CSV, JSON alebo PDF špecifické pre laboratórium. Táto stránka vysvetľuje, ako do seba zapadajú jednotlivé časti, čo musí dobré API pre laboratórne výsledky obsahovať a ako prijímať laboratórne dáta do záznamu FHIR pacienta pomocou Anpheros.

## Kto si vymieňa laboratórne výsledky a v akom formáte

| Od → do | Bežný formát dnes | Poznámky |
|---|---|---|
| Laboratórium → nemocničný alebo klinický systém | HL7 v2 ORU^R01 (v USA často podľa príručky HL7 v2.5.1 Laboratory Results Interface guide) | Požiadavky idú opačným smerom ako správy ORM/OML |
| Laboratórium → agentúra verejného zdravia | Elektronické hlásenie laboratórnych výsledkov HL7 v2, čoraz častejšie FHIR | Len hlásiteľné ochorenia |
| Klinický systém → pacientska aplikácia | FHIR R4 prostredníctvom API na prístup pacienta | V USA certifikované EHR vystavujú laboratórne výsledky ako FHIR (US Core); v EÚ Európsky priestor pre zdravotné údaje uvádza laboratórne výsledky medzi svoje prioritné dátové kategórie |
| Laboratórium → pacient | PDF správa, portál, niekedy CSV | Formát, ktorý väčšina pacientov skutočne dostáva |
| Aplikácia → AI model | Štrukturovaný kontext vytvorený z Observations | Potrebuje kódy a jednotky, aby bol spoľahlivý |

Smer je dôležitý: laboratórny informačný systém (LIS) je zdrojom pravdy pre výsledok a každý nadväzujúci systém si uchováva kópiu. Dôveryhodnosť kópií zabezpečuje, že každý z nich uchováva kód, jednotku, rozsah a pôvod hodnoty.

## Čo potrebuje jeden laboratórny výsledok

Výsledok, ktorý hovorí iba „Glukóza 126“, sa nedá bezpečne interpretovať. Kompletný výsledok obsahuje:

- **Štandardný kód.** LOINC identifikuje analyt, vzorku a metódu: `2345-7` je glukóza v sére alebo plazme, `2339-0` je glukóza v plnej krvi. Vedľa neho môže cestovať aj vlastný kód laboratória.
- **Hodnota s jednotkou.** Ideálne jednotka UCUM (`mg/dL`, `mmol/L`, `10*3/uL`), aby sa hodnoty z dvoch laboratórií dali previesť a porovnať.
- **Referenčný rozsah**, ktorý laboratórium použilo, a **interpretačná** značka (H, L, N…), ak ju laboratórium poskytuje.
- **Stav:** predbežný, konečný, opravený alebo doplnený. Opravy sa stávajú; API vám musí umožniť vidieť novú verziu bez straty starej.
- **Časy:** kedy bola vzorka odobratá (`effectiveDateTime`) a kedy bol výsledok vydaný (`issued`).
- **Pôvod:** ktoré laboratórium ho vyprodukovalo a k akej správe alebo objednávke patrí.

Vo FHIR R4 je každý výsledok jeden `Observation` s `category = laboratory` a správa, ktorá ich zoskupuje, je `DiagnosticReport`, ktorá uvádza Pozorovania v `result`. Platné príklady oboch, s chybami, ktoré validátory hlásia najčastejšie, sú v [Príkladoch FHIR R4 JSON](https://developers.anpheros.com/tools/fhir-examples/observation-lab-result) — pozri tiež [Príklad DiagnosticReport](https://developers.anpheros.com/tools/fhir-examples/diagnostic-report).

## HL7 v2 a FHIR vedľa seba

Ten istý výsledok lipidového panelu, tak ako ho dnes posiela väčšina laboratórií a tak, ako by ho mal API uložiť:

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

| Pole HL7 v2 | Význam | Element FHIR R4 Observation |
|---|---|---|
| OBX-3 `2093-3^Cholesterol^LN` | Test, kódovaný v LOINC | `code.coding` (systém `http://loinc.org`) |
| OBX-5 `212`, OBX-2 `NM` | Numerická hodnota | `valueQuantity.value` |
| OBX-6 `mg/dL` | Jednotka | `valueQuantity.unit` |
| OBX-7 `<200` | Referenčný rozsah | `referenceRange.high` |
| OBX-8 `H` | Abnormálna vlajka | `interpretation` |
| OBX-11 `F` | Konečný výsledok | `status = final` |
| OBX-14 | Čas pozorovania | `effectiveDateTime` |

Konverzia medzi týmito dvoma je väčšinou mapovanie polí. Ťažké časti sú inde: laboratóriá, ktoré posielajú vlastné kódy namiesto LOINC, čísla napísané ako text (`"6,4"`, `"<5"`), rozsahy v niekoľkých notáciách a správy, ktoré sa po uplynutí časového limitu posielajú znova. [Ako normalizovať lekárske dáta](https://developers.anpheros.com/sk/guides/normalize-medical-data) sa týmto podrobne venuje.

## Prijímanie laboratórnych výsledkov do FHIR záznamu s Anpheros

Anpheros ukladá záznam každého pacienta ako HL7 FHIR R4 a má [laboratórny konektor](https://developers.anpheros.com/sk/guides/lab-connector): jedna požiadavka prijme celú správu ako HL7 v2, CSV alebo JSON a vráti laboratórne pozorovania (Observations) s LOINC kódmi, referenčnými rozsahmi, interpretáciou a pôvodom (provenance).

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

Pre trojriadkový lipidový panel (cholesterol, HDL, triglyceridy) je odpoveď z lokálneho spustenia platformy:

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

Každý uložený výsledok je štandardné FHIR R4 Observation, čitateľné akýmkoľvek FHIR klientom:

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

Opätovné odoslanie tej istej správy nevytvorí nič nové (`"created": 0, "skipped": 3`): každý riadok získa stabilný identifikátor z ID správy, kódu, dátumu a hodnoty. Značky, ktoré platforma nedokáže namapovať na LOINC, si ponechajú kód laboratória a vrátia sa v `unmapped`, takže môžete mapovanie opraviť pri zdroji.

Čítanie výsledkov späť je štandardné FHIR vyhľadávanie:

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

Ďalšie spôsoby vstupu a výstupu rovnakých údajov:

- **Priamo FHIR:** `POST /fhir/R4/Observation`, alebo transakčný Bundle s `DiagnosticReport` a jeho Observations spolu.
- **Udalosti:** `resource.created` [webhook](https://developers.anpheros.com/sk/guides/webhooks) na jedno Observation, takže klinika alebo aplikácia môže reagovať, keď výsledky dorazia.
- **Pre ľudí a AI:** pacient vidí výsledky vo svojej aplikácii; aplikácie, ktorým dá súhlas, si ich prečítajú; `POST /v1/context` poskytuje modelu AI súhrn označený zdrojom, ktorý zahŕňa nedávne laboratórne hodnoty.
- **Pôvod (Provenance):** každý importovaný výsledok zaznamenáva `author_type = import`, zdrojový systém a ID správy ([pôvod lekárskych údajov](https://developers.anpheros.com/sk/guides/medical-data-provenance)).

Kompletný návod s CSV správou, HL7 v2 správou, nemapovanými značkami a opätovne odoslanými správami na syntetickom pacientovi je v návode [Ako importovať laboratórne výsledky do FHIR záznamu](https://developers.anpheros.com/sk/guides/import-lab-results-fhir).

## Skontrolujte výsledky pred ich odoslaním

Bezplatný [FHIR R4 validátor](https://developers.anpheros.com/tools/fhir-validator) kontroluje štruktúru Observation a požadované hodnotové sady. S profilom `eu-lab` tiež kontroluje, čo by mal laboratórny výsledok obsahovať: kategóriu `laboratory`, LOINC kód, subjekt, stav final-type, čas, hodnotu, UCUM jednotku a referenčný rozsah. Rovnaké kontroly prebiehajú na platforme prostredníctvom `POST /fhir/R4/Observation/$validate?profile=eu-lab`.

## Výber API pre laboratórne výsledky: kontrolný zoznam

- Ukladá výsledky ako FHIR R4 Observations s LOINC kódmi, alebo ako riadky vo vlastnej schéme?
- Dokáže prijať formáty, ktoré vaše laboratóriá skutočne posielajú (HL7 v2 vo väčšine nemocníc, CSV alebo PDF z menších laboratórií)?
- Čo sa stane so značkou, ktorú nedokáže namapovať: je odmietnutá, ignorovaná alebo ponechaná s kódom laboratória?
- Sú opätovné pokusy bezpečné, alebo duplicitný report vytvorí duplikáty?
- Sú opravené výsledky verzované, pričom skoršia hodnota je stále čitateľná?
- Je pôvod každej hodnoty zaznamenaný a viditeľný pre pacienta?
- Kto môže čítať výsledky a rozhoduje o tom súhlas pacienta?

## Čo Anpheros nerobí

Anpheros nie je laboratórny informačný systém a nie je pripojený k komerčným laboratórnym sieťam: správu posiela laboratórium, klinika alebo aplikácia pacienta. Nerieši laboratórne objednávky, nečíta PDF správy prostredníctvom tohto API (aplikácia Anpheros Daily extrahuje výsledky z fotografií a PDF na strane pacienta) a klinicky neinterpretuje výsledky. Jednotky sa ukladajú tak, ako ich posiela laboratórium; ich konverzia na kódy UCUM je na strane odosielateľa, ako je popísané v [Ako normalizovať lekárske údaje](https://developers.anpheros.com/sk/guides/normalize-medical-data).

## Často kladené otázky

### Čo je API pre laboratórne výsledky?
Rozhranie, ktoré umožňuje softvéru posielať alebo prijímať laboratórne výsledky ako štruktúrované údaje — kódovaný test, hodnotu s jednotkou, referenčný rozsah, stav a čas — namiesto dokumentu. Moderné API pre laboratórne výsledky používajú zdroje HL7 FHIR R4 Observation a DiagnosticReport; väčšina laboratórií stále emituje správy HL7 v2 ORU^R01.

### Ktorý kódovací systém identifikuje laboratórne testy?
LOINC. Každý LOINC kód pomenúva analyt, vzorku a často aj metódu, takže `2345-7` (glukóza v sére alebo plazme) a `2339-0` (glukóza v celej krvi) sú rôzne výsledky. Jednotky je najlepšie vyjadriť v UCUM.

### Aký je rozdiel medzi Observation a DiagnosticReport?
Observation je jeden výsledok, napríklad cholesterol 212 mg/dL. DiagnosticReport je celá správa — panel, ktorý bol objednaný, kto ju vydal a kedy — a uvádza svoje Observations v `result`.

### Môžem importovať HL7 v2 laboratórne správy na FHIR server?
Áno. Každý segment OBX sa mapuje na jedno Observation (OBX-3 na `code`, OBX-5 a OBX-6 na `valueQuantity`, OBX-7 na `referenceRange`, OBX-8 na `interpretation`). Konektor laboratória Anpheros to robí v jednom požiadavke a uchováva ID správy laboratória v Provenance.

### Ako sa vyhnúť duplicitným laboratórnym výsledkom, keď je správa odoslaná znova?
Každému výsledku priraďte stabilný identifikátor odvodený zo správy, testu, času a hodnoty a preskočte riadky, ktorých identifikátor už existuje. Konektor laboratória Anpheros to robí automaticky a hlási počet ako `skipped`.

## Súvisiace

- [Mapovanie HL7 v2 na FHIR](https://developers.anpheros.com/sk/guides/hl7-v2-to-fhir-mapping): každý segment a pole OBX
- [Ako importovať laboratórne výsledky do záznamu FHIR](https://developers.anpheros.com/sk/guides/import-lab-results-fhir): podrobný návod
- [Lab connector](https://developers.anpheros.com/sk/guides/lab-connector): referenčný dokument koncového bodu
- [Ako normalizovať lekárske údaje](https://developers.anpheros.com/sk/guides/normalize-medical-data): LOINC, UCUM, dátumy, rozsahy a duplicity
- [Vysvetlenie pôvodu lekárskych údajov](https://developers.anpheros.com/sk/guides/medical-data-provenance)
- [Kódové systémy FHIR](https://developers.anpheros.com/sk/guides/fhir-code-systems)
- [Ako integrovať klinické systémy s backendom FHIR](https://developers.anpheros.com/sk/guides/integrate-clinic-systems-fhir)
- [FHIR vs HL7 v2: praktické rozdiely](https://developers.anpheros.com/sk/guides/fhir-vs-hl7-v2)
- [HL7 v2 a FHIR pre klinické dashboardy](https://developers.anpheros.com/sk/guides/clinical-dashboard-hl7-fhir): od laboratórnej správy k dlaždici dashboardu