# Laboratórny konektor

> Pošlite celú laboratórnu správu ako CSV, HL7 v2 ORU^R01 alebo JSON a získajte laboratórne pozorovania (Observations) s LOINC kódmi a referenčnými rozsahmi.

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

Laboratórium (alebo ktokoľvek, kto vlastní laboratórnu správu) pošle celú správu v jednej požiadavke a platforma premení každý výsledok na laboratórne `Observation` pacienta:

```
POST /v1/patients/{patient_id}/labs/import
Authorization: Bearer <project key>
Content-Type: text/csv | x-application/hl7-v2+er7 | application/json
X-Anpheros-Source-System: labx        (optional; recorded in Provenance)
Idempotency-Key: <report id>          (optional; a retry returns the same answer)
```

## Formáty

**CSV** s hlavičkou; oddeľovače `,` `;` alebo tabulátor, desatinná čiarka akceptovaná, dátumy ISO,
`DD.MM.YYYY` alebo `DD/MM/YYYY`. Rozpoznané stĺpce (rumunsky alebo anglicky): marker
(`analiza`, `test`, `marker`, `name`) — alebo iba stĺpec LOINC `code`, v takom prípade sa názov LOINC stane markerom —
hodnota (`rezultat`, `valoare`, `value`, `result`), jednotka (`um`, `unitate`, `unit`),
referenčný rozsah (`interval`, `referinta`: `70-100`, `<5`, `>3.5`) alebo `ref_low`/`ref_high`,
dátum (`data`, `recoltare`), voliteľný LOINC (`loinc`, `code`), poznámka.

```
Analiza;Rezultat;UM;Interval de referinta;Data
Hemoglobina glicozilata (HbA1c);6,4;%;4,0-5,6;01.09.2026
TSH;2,1;mUI/L;0,4-4,0;01.09.2026
```

**HL7 v2 ORU^R01** (ER7 text, segmenty oddelené CR alebo LF): `OBX-3` identifikátor (`code^text^LN`
je LOINC; lokálny kód (`^L`, `^99zzz`) alebo akýkoľvek iný kódovací systém zostáva ako vlastný kód laboratória pod
`urn:anpheros:lab-code`), `OBX-5` hodnota (`NM`, `SN`, alebo text),
`OBX-6` jednotka, `OBX-7` referenčný rozsah, `OBX-8` abnormálna vlajka → `interpretation`, `OBX-11` stav,
`OBX-14` alebo `OBR-7` dátum; `OBR-3`/`MSH-10` sa stanú ID správy v Provenance.

**Laboratórium.** Každý výsledok uvádza, kto ho vyprodukoval v `performer`, ako to vyžaduje HL7 Europe Laboratory Report 2.1.0
: organizácia, za ktorú konáte (`X-Anpheros-Acting-As`), inak `MSH-4` (odosielajúce zariadenie) pre HL7, alebo
`laboratory` v JSON (najvyššia úroveň alebo na položku). CSV neobsahuje laboratórium; takéto výsledky sa validujú s chýbajúcim
vykonávateľom, čo je pravda.

**Textové správy, dokumenty a chýbajúce dátumy.** Textová správa odoslaná jeden riadok na OBX (`TX`/`FT`, rovnaké `OBX-3`)
sa stane jedným výsledkom so spojenými riadkami. Celý dokument v `OBX-5` (`ED`, alebo akákoľvek hodnota zakódovaná `Base64`) sa neukladá
ako výsledok; odpoveď varuje a dokument patrí do `/documents`. Bez `OBR-7` sú výsledky datované podľa
`OBR-14` (prijatie vzorky), s varovaním.

**Časy a časové zóny.** V2 čas bez časovej zóny je lokálny čas odosielateľa, nie UTC. Posun odoslaný s
`OBX-14`/`OBR-7` (`20260901081000+0300`) sa zachová (`2026-09-01T08:10:00+03:00`). Bez neho sa použije posun `MSH-7`
a o tom sa zobrazí varovanie; bez posunu kdekoľvek si výsledok ponechá iba svoj dátum, tiež s varovaním. CSV časy
(`01.09.2026 08:10`) neobsahujú časovú zónu, takže sa ukladajú iba ako dátumy. Do 17. októbra 2026 boli takéto časy
označené ako UTC; výsledky importované vtedy si zachovajú svoje identifikátory a sú stále rozpoznané, keď sa správa odošle znova.

Výsledky HL7, ktoré sú stále v procese (OBX-11 `I`), nedostupné (`X`), odstránené (`D`) alebo nesprávne (`W`), a segmenty OBX
bez hodnoty sa nestanú pozorovaniami; každý je pomenovaný v `warnings`.

**JSON**: `{"date": "2026-09-01", "origin": "report-77", "laboratory": "Synevo", "items": [{"marker": "TSH", "value": 2.1, "unit": "mUI/L", "ref_low": 0.4, "ref_high": 4.0, "date": "2026-09-01", "code": "3016-3"}]}`.

## Čo dostanete späť

```json
{"created": 3, "skipped": 0, "unmapped": ["Marker foarte rar"], "warnings": [],
 "observations": [{"id": "…", "marker": "TSH", "code": "3016-3", "system": "http://loinc.org", "value": 2.1, "unit": "mUI/L", "date": "2026-09-01"}]}
```

- Značky sú mapované na **LOINC**, keď správa poskytuje kód LOINC alebo názov zodpovedá terminológii platformy (rumunské a anglické názvy a bežné aliasy). Ostatné si ponechajú kód laboratória pod `urn:anpheros:lab-code` s presným textom zo správy a sú uvedené v `unmapped`, aby ste si mapovanie mohli vylepšiť na svojej strane. Vlastný kód laboratória je jedinečný iba spolu s jeho laboratóriom: zdrojový systém je zaznamenaný v Provenance každej Observation (`X-Anpheros-Source-System`).
- Názvy sú porovnávané s názvami a synonymami LOINC (napríklad *Hemoglobin A1c*, *Glycated hemoglobin*, *HDL cholesterol*, *LDL-C*). Názov, ktorý zodpovedá viacerým konceptom, alebo ktorý nesie kvalifikátor, ktorý koncept nemá (*urine*, *non-HDL*, *free*, *ratio*…), sa nehádá: ponechá si kód laboratória a je uvedený v `unmapped`. Posielajte kódy LOINC vždy, keď ich váš systém má.
- Močovina a dusík močoviny (BUN) sú rôzne merania: *Močovina* / *Urea* sa mapuje na močovinu (LOINC `3091-6`, alebo `22664-7` v mmol/l), *BUN* / *Dusík močoviny* / *Azot ureic* na dusík močoviny (`3094-0`, alebo `14937-7` v mmol/l). Hodnoty sa nikdy nekonvertujú.
- LDL cholesterol: názov bez metódy sa mapuje na `2089-1`; *vypočítaný* / *calculated* / *Friedewald* na vypočítaný LDL (`13457-7`); *priamy* na priamy odhad (`18262-6`). Metóda je kvalifikátor, ako napríklad *priamy* v *Bilirubina directa*, čo nie je celkový bilirubín a ponecháva si kód laboratória.
- Glukóza: holá "Glikemie" / "Glucose" na lekárskej správe sa mapuje na sérum alebo plazmu (LOINC `2345-7`); názov, ktorý uvádza kapilárny, odber z prsta alebo celú krv ("capilar", "sânge integral") na celú krv (`2339-0`). Kód LOINC v správe má vždy prednosť.
- Každý riadok dostane stabilný identifikátor (`urn:anpheros:lab-import:v2`) zostavený z toho, čo správa hovorí — ID správy, názov a kód v správe, dátum, hodnota a jednotka — nikdy z kódu LOINC, ktorý platforma vybrala, takže **opätovné odoslanie tej istej správy preskočí už importované riadky** (`skipped`), dokonca aj po zlepšení mapovania. Riadky, ktoré sa líšia v čomkoľvek z tohto (iná správa, iný čas odberu, iná hodnota), sú uchovávané oddelene. Výsledky importované pred 14. októbrom 2026 si zachovajú svoj pôvodný identifikátor a sú rozpoznané podľa názvu, dátumu, hodnoty, jednotky a ID správy. Bez ID správy (CSV) sa takéto zhodovanie hlási v `warnings`; pošlite ID správy (HL7 `OBR-3`/`MSH-10`, JSON `origin`), aby ste oddelili správy.
- Každá Observation nesie Provenance s `author_type = import`, váš zdrojový systém a ID správy; webové háčiky sa spustia `resource.created` na Observation; pacient vidí výsledky vo svojej aplikácii a akákoľvek aplikácia, na ktorú dal súhlas, si ich môže prečítať.
- Až 500 riadkov na požiadavku.

Oba SDK: `labs.importCsv`, `labs.importHl7`, `labs.importItems`.

Praktický príklad z CSV a správy HL7 v2 do FHIR Observations, s nemapovanými značkami a opätovne odoslanými správami: [Ako importovať laboratórne výsledky do záznamu FHIR](https://developers.anpheros.com/sk/guides/import-lab-results-fhir).

Ako sa laboratórne údaje pohybujú medzi laboratóriami, klinikami, aplikáciami a AI, a na čo sa zamerať v API pre laboratórne výsledky: [API pre laboratórne výsledky](https://developers.anpheros.com/sk/guides/lab-results-api).