# API pro laboratorní výsledky: HL7 v2, FHIR a LOINC

> Jak laboratorní výsledky cestují jako data HL7 v2 a FHIR, co musí jeden výsledek obsahovat a jak přijímat laboratorní zprávy do záznamu FHIR, s reálným příkladem.

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

**API pro laboratorní výsledky dodává laboratorní výsledky jako strukturovaná data — kód testu, hodnota, jednotka, referenční rozsah, stav a čas — namísto PDF, aby je software mohl ukládat, porovnávat, zobrazovat v grafech a sdílet.** Dnes tato data cestují ve třech formách: zprávy HL7 v2 ORU^R01 (stále páteř mezi laboratořemi a nemocnicemi), zdroje HL7 FHIR R4 `Observation` a `DiagnosticReport` (formát moderních API) a exporty CSV, JSON nebo PDF specifické pro laboratoř. Tato stránka vysvětluje, jak do sebe jednotlivé části zapadají, co musí dobré API pro laboratorní výsledky obsahovat a jak přijímat laboratorní data do záznamu pacienta ve formátu FHIR pomocí Anpheros.

## Kdo si vyměňuje laboratorní výsledky a v jakém formátu

| Od → do | Běžný formát dnes | Poznámky |
|---|---|---|
| Laboratoř → nemocniční nebo klinický systém | HL7 v2 ORU^R01 (v USA často dle průvodce HL7 v2.5.1 Laboratory Results Interface) | Požadavky jdou opačným směrem jako zprávy ORM/OML |
| Laboratoř → agentura veřejného zdraví | Elektronické hlášení laboratorních výsledků HL7 v2, stále častěji FHIR | Pouze hlášené stavy |
| Klinický systém → klientská aplikace | FHIR R4 prostřednictvím API pro přístup pacienta | V USA certifikované EHR zpřístupňují laboratorní výsledky jako FHIR (US Core); v EU European Health Data Space uvádí laboratorní výsledky mezi svými prioritními datovými kategoriemi |
| Laboratoř → pacient | PDF zpráva, portál, někdy CSV | Formát, který většina pacientů skutečně obdrží |
| Aplikace → AI model | Strukturovaný kontext vytvořený z Observations | Pro spolehlivost potřebuje kódy a jednotky |

Směr je důležitý: laboratorní informační systém (LIS) je zdro pravdy pro výsledek a každý navazující systém si uchovává jeho kopii. Důvěryhodnost kopií zajišťuje, že si každý z nich uchovává kód, jednotku, rozsah a původ hodnoty.

## Co potřebuje jeden laboratorní výsledek

Výsledek, který říká pouze „Glukóza 126“, nelze bezpečně interpretovat. Kompletní výsledek obsahuje:

- **Standardní kód.** LOINC identifikuje analyt, vzorek a metodu: `2345-7` je glukóza v séru nebo plazmě, `2339-0` je glukóza v celé krvi. Vedle něj může cestovat i vlastní kód laboratoře.
- **Hodnota s jednotkou.** Ideálně jednotka UCUM (`mg/dL`, `mmol/L`, `10*3/uL`), takže hodnoty ze dvou laboratoří lze převést a porovnat.
- **Referenční rozsah**, který laboratoř použila, a **interpretační** příznak (H, L, N…), pokud jej laboratoř poskytuje.
- **Stav:** předběžný, konečný, opravený nebo doplněný. Opravy se dějí; API musí umožnit vidět novou verzi bez ztráty té staré.
- **Časy:** kdy byl vzorek odebrán (`effectiveDateTime`) a kdy byl výsledek vydán (`issued`).
- **Původ:** která laboratoř jej vyprodukovala a ke které zprávě nebo objednávce patří.

Ve FHIR R4 je každý výsledek jeden `Observation` s `category = laboratory` a zpráva, která je seskupuje, je `DiagnosticReport`, která uvádí Observations v `result`. Platné příklady obou, s chybami, které validátory hlásí nejčastěji, jsou ve [FHIR R4 JSON příkladech](https://developers.anpheros.com/tools/fhir-examples/observation-lab-result) — viz také [příklad DiagnosticReport](https://developers.anpheros.com/tools/fhir-examples/diagnostic-report).

## HL7 v2 a FHIR vedle sebe

Stejný výsledek lipidového panelu, jak jej dnes většina laboratoří posílá a jak by jej API mělo ukládat:

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

| Pole HL7 v2 | Význam | Prvek 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` | Číselná hodnota | `valueQuantity.value` |
| OBX-6 `mg/dL` | Jednotka | `valueQuantity.unit` |
| OBX-7 `<200` | Referenční rozsah | `referenceRange.high` |
| OBX-8 `H` | Příznak abnormality | `interpretation` |
| OBX-11 `F` | Konečný výsledek | `status = final` |
| OBX-14 | Čas pozorování | `effectiveDateTime` |

Převod mezi těmito dvěma formáty je převážně mapování polí. Obtížné části jsou jinde: laboratoře, které posílají vlastní kódy místo LOINC, čísla zapsaná jako text (`"6,4"`, `"<5"`), rozsahy v několika notacích a zprávy, které jsou po uplynutí časového limitu poslány znovu. [Jak normalizovat lékařská data](https://developers.anpheros.com/cs/guides/normalize-medical-data) se těmito tématy podrobně zabývá.

## Příjem laboratorních výsledků do záznamu FHIR s Anpheros

Anpheros ukládá záznam každého pacienta jako HL7 FHIR R4 a má [konektor pro laboratoř](https://developers.anpheros.com/cs/guides/lab-connector): jeden požadavek přijme celou zprávu jako HL7 v2, CSV nebo JSON a vrátí laboratorní Observation s kódy LOINC, referenčními rozsahy, interpretací a původem dat.

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

Pro třířádkový lipidový panel (cholesterol, HDL, triglyceridy) je odpověď z lokálního běhu 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ýsledek je standardní FHIR R4 Observation, čitelný jakýmkoli FHIR klientem:

```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é odeslání stejné zprávy nevytvoří nic nového (`"created": 0, "skipped": 3`): každý řádek získá stabilní identifikátor z ID zprávy, kódu, data a hodnoty. Značky, které platforma nemůže namapovat na LOINC, si ponechají kód laboratoře a vrátí se v `unmapped`, takže můžete mapování opravit u zdroje.

Čtení výsledků zpět je standardní vyhledávání FHIR:

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

Další způsoby vstupu a výstupu stejných dat:

- **Přímo FHIR:** `POST /fhir/R4/Observation`, nebo transakční Bundle s `DiagnosticReport` a jeho Observation společně.
- **Události:** `resource.created` [webhook](https://developers.anpheros.com/cs/guides/webhooks) pro každou Observation, takže klinika nebo aplikace může reagovat, když výsledky dorazí.
- **Pro lidi a AI:** pacient vidí výsledky ve své aplikaci; aplikace, kterým udělí souhlas, si je přečtou; `POST /v1/context` poskytuje modelu AI souhrn označený zdrojem, který zahrnuje nedávné laboratorní hodnoty.
- **Původ dat:** každý importovaný výsledek zaznamenává `author_type = import`, zdrojový systém a ID zprávy ([původ lékařských dat](https://developers.anpheros.com/cs/guides/medical-data-provenance)).

Kompletní návod s CSV zprávou, HL7 v2 zprávou, nenamapovanými značkami a opakovaně odeslanými zprávami u syntetického pacienta je v tutoriálu [Jak importovat laboratorní výsledky do záznamu FHIR](https://developers.anpheros.com/cs/guides/import-lab-results-fhir).

## Zkontrolujte výsledky před odesláním

Bezplatný [FHIR R4 validátor](https://developers.anpheros.com/tools/fhir-validator) kontroluje strukturu Observation a požadované hodnotové sady. S profilem `eu-lab` také kontroluje, co by laboratorní výsledek měl obsahovat: kategorii `laboratory`, kód LOINC, subjekt, stav final-type, čas, hodnotu, jednotku UCUM a referenční rozsah. Stejné kontroly probíhají na platformě prostřednictvím `POST /fhir/R4/Observation/$validate?profile=eu-lab`.

## Výběr API pro laboratorní výsledky: kontrolní seznam

- Ukládá výsledky jako FHIR R4 Observations s kódy LOINC, nebo jako řádky ve vlastním schématu?
- Dokáže přijímat formáty, které vaše laboratoře skutečně posílají (HL7 v2 ve většině nemocnic, CSV nebo PDF z menších laboratoří)?
- Co se stane se značkou, kterou nelze namapovat: je odmítnuta, vynechána nebo ponechána s kódem laboratoře?
- Jsou opakované pokusy bezpečné, nebo opakovaně odeslaná zpráva vytvoří duplikáty?
- Jsou opravené výsledky verzovány, přičemž dřívější hodnota je stále čitelná?
- Je původ každé hodnoty zaznamenán a viditelný pro pacienta?
- Kdo může číst výsledky a je to rozhodnuto souhlasem pacienta?

## Co Anpheros nedělá

Anpheros není laboratorní informační systém a není připojen k komerčním laboratorním sítím: zprávu zasílá laboratoř, klinika nebo aplikace pacienta. Nerozesílá laboratorní objednávky, nečte PDF zprávy prostřednictvím tohoto API (aplikace Anpheros Daily extrahuje výsledky z fotografií a PDF na straně pacienta) a neinterpretuje výsledky klinicky. Jednotky jsou ukládány tak, jak je laboratoř pošle; jejich převod na kódy UCUM je na straně odesílatele, jak je popsáno v [Jak normalizovat lékařská data](https://developers.anpheros.com/cs/guides/normalize-medical-data).

## Často kladené dotazy

### Co je API pro laboratorní výsledky?
Rozhraní, které umožňuje softwaru odesílat nebo přijímat laboratorní výsledky ve strukturovaných datech — kódovaný test, hodnota s jednotkou, referenční rozsah, stav a čas — namísto dokumentu. Moderní API pro laboratorní výsledky používají zdroje HL7 FHIR R4 Observation a DiagnosticReport; většina laboratoří stále vydává zprávy HL7 v2 ORU^R01.

### Který kódovací systém identifikuje laboratorní testy?
LOINC. Každý kód LOINC pojmenovává analyt, vzorek a často metodu, takže `2345-7` (glukóza v séru nebo plazmě) a `2339-0` (glukóza v celé krvi) jsou různé výsledky. Jednotky jsou nejlépe vyjádřeny v UCUM.

### Jaký je rozdíl mezi Observation a DiagnosticReport?
Observation je jeden výsledek, například cholesterol 212 mg/dL. DiagnosticReport je zpráva jako celek — panel, který byl objednán, kdo jej vydal a kdy — a uvádí své Observation v `result`.

### Mohu importovat HL7 v2 laboratorní zprávy na FHIR server?
Ano. Každý segment OBX se mapuje na jedno Observation (OBX-3 na `code`, OBX-5 a OBX-6 na `valueQuantity`, OBX-7 na `referenceRange`, OBX-8 na `interpretation`). Anpheros lab connector to provádí jedním požadavkem a uchovává ID laboratorní zprávy v Provenance.

### Jak se vyhnout duplicitním laboratorním výsledkům, když je zpráva znovu odeslána?
Každému výsledku přiřaďte stabilní identifikátor odvozený ze zprávy, testu, času a hodnoty a přeskočte řádky, jejichž identifikátor již existuje. Anpheros lab connector to provádí automaticky a hlásí počet jako `skipped`.

## Související

- [Mapování HL7 v2 na FHIR](https://developers.anpheros.com/cs/guides/hl7-v2-to-fhir-mapping): každý segment a pole OBX
- [Jak importovat laboratorní výsledky do záznamu FHIR](https://developers.anpheros.com/cs/guides/import-lab-results-fhir): podrobný návod
- [Lab connector](https://developers.anpheros.com/cs/guides/lab-connector): reference koncového bodu
- [Jak normalizovat lékařská data](https://developers.anpheros.com/cs/guides/normalize-medical-data): LOINC, UCUM, data, rozsahy a duplicity
- [Vysvětlení původu lékařských dat](https://developers.anpheros.com/cs/guides/medical-data-provenance)
- [Kódovací systémy FHIR](https://developers.anpheros.com/cs/guides/fhir-code-systems)
- [Jak integrovat klinické systémy s backendem FHIR](https://developers.anpheros.com/cs/guides/integrate-clinic-systems-fhir)
- [FHIR vs HL7 v2: praktické rozdíly](https://developers.anpheros.com/cs/guides/fhir-vs-hl7-v2)
- [HL7 v2 a FHIR pro klinické dashboardy](https://developers.anpheros.com/cs/guides/clinical-dashboard-hl7-fhir): od laboratorní zprávy k dlaždici dashboardu