# Ako importovať laboratórne výsledky do FHIR záznamu

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

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

**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](https://developers.anpheros.com/sk/guides/lab-connector) 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](https://platform.anpheros.com/dashboard/) (**Získať sandbox kľúč**). Príklady používajú `curl`; [SDK](https://developers.anpheros.com/sk/guides/sdks) majú rovnaké volania (`labs.importCsv`, `labs.importHl7`, `labs.importItems`).

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

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

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

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

```bash
curl "$BASE/v1/terminology/loinc?q=glucose" -H "Authorization: Bearer $KEY"
```

```json
{"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í:

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

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

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

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

```json
{
  "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](https://developers.anpheros.com/sk/guides/fhir) a [FHIR code systems](https://developers.anpheros.com/sk/guides/fhir-code-systems).

## Krok 6: Kontrola odosielateľa

```bash
curl "$BASE/v1/patients/$PID/provenance/Observation/62b1b0c0-…" -H "Authorization: Bearer $KEY"
```

```json
{"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](https://developers.anpheros.com/sk/guides/llm-healthcare-data), 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](https://developers.anpheros.com/sk/guides/consent)).
- Pre každé Observation sa spustí [webhook](https://developers.anpheros.com/sk/guides/webhooks) `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](https://developers.anpheros.com/sk/guides/limits).

## Č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](https://developers.anpheros.com/sk/guides/lab-results-api): HL7 v2 a FHIR vedľa seba a čo musí jeden výsledok obsahovať
- [Konektor pre laboratórne dáta](https://developers.anpheros.com/sk/guides/lab-connector): každý názov stĺpca, HL7 pole a pole odpovede
- [Interoperabilita zdravotníckych dát](https://developers.anpheros.com/sk/guides/interoperability): prečo kódy a pôvod robia vymenené dáta použiteľnými
- [Integrácie v zdravotníctve](https://developers.anpheros.com/sk/guides/healthcare-integrations): kliniky, laboratóriá, zariadenia a aplikácie tretích strán
- [API pre medicínske dáta](https://developers.anpheros.com/sk/guides/medical-data-api): písanie jednotlivých pozorovaní, diagnóz a liekov
- [Ako vytvoriť AI aplikáciu pre zdravotníctvo s FHIR backendom](https://developers.anpheros.com/sk/guides/build-ai-healthcare-app): použitie týchto výsledkov v AI odpovedi