# Laboratorní konektor

> Odešlete celou laboratorní zprávu ve formátu CSV, HL7 v2 ORU^R01 nebo JSON a získejte laboratorní Pozorování (Observations) s kódy LOINC a referenčními rozsahy.

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

Laboratoř (nebo kdokoli, kdo vlastní laboratorní zprávu) odešle celou zprávu v jednom požadavku a
platforma přemění každý výsledek na laboratorní `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; oddělovače `,` `;` nebo tabulátor, desetinná čárka přijata, data ISO,
`DD.MM.YYYY` nebo `DD/MM/YYYY`. Rozpoznané sloupce (rumunsky nebo anglicky): marker
(`analiza`, `test`, `marker`, `name`) — nebo pouze sloupec LOINC `code`, v takovém případě se název LOINC stane markerem —
hodnota (`rezultat`, `valoare`, `value`, `result`), jednotka (`um`, `unitate`, `unit`),
referenční rozsah (`interval`, `referinta`: `70-100`, `<5`, `>3.5`) nebo `ref_low`/`ref_high`,
datum (`data`, `recoltare`), volitelný 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** (text ER7, segmenty oddělené CR nebo LF): `OBX-3` identifikátor (`code^text^LN`
je LOINC; lokální kód (`^L`, `^99zzz`) nebo jakýkoli jiný kódovací systém je zachován jako vlastní kód laboratoře pod
`urn:anpheros:lab-code`), `OBX-5` hodnota (`NM`, `SN`, nebo text),
`OBX-6` jednotka, `OBX-7` referenční rozsah, `OBX-8` abnormální příznak → `interpretation`, `OBX-11` stav,
`OBX-14` nebo `OBR-7` datum; `OBR-3`/`MSH-10` se stanou ID zprávy v Provenance.

**Laboratoř.** Každý výsledek uvádí, kdo jej vyprodukoval v `performer`, jak vyžaduje HL7 Europe Laboratory Report 2.1.0:
organizace, za kterou jednáte (`X-Anpheros-Acting-As`), jinak `MSH-4` (odesílající zařízení) pro HL7, nebo
`laboratory` v JSON (nejvyšší úroveň nebo na položku). CSV nenese laboratoř; takové výsledky jsou platné s chybějícím
proveditelem, což je pravda.

**Textové zprávy, dokumenty a chybějící data.** Textová zpráva odeslaná jeden řádek na OBX (`TX`/`FT`, stejné `OBX-3`)
se stane jedním výsledkem s připojenými řádky. Celý dokument v `OBX-5` (`ED`, nebo jakákoli hodnota kódovaná `Base64`) není
uložen jako výsledek; odpověď varuje a dokument patří do `/documents`. Bez `OBR-7` jsou výsledky datovány podle
`OBR-14` (odebraný vzorek), s varováním.

**Časy a časová pásma.** Čas v2 bez časového pásma je lokální čas odesílatele, nikoli UTC. Posun odeslaný s
`OBX-14`/`OBR-7` (`20260901081000+0300`) je zachován (`2026-09-01T08:10:00+03:00`). Bez něj se použije posun `MSH-7`
a varování to hlásí; bez posunu kdekoli si výsledek ponechá pouze své datum, také s varováním. Časy CSV
(`01.09.2026 08:10`) neobsahují časové pásmo, takže jsou uloženy pouze jako data. Do 17. října 2026 byly takové časy
označeny jako UTC; výsledky importované v té době si zachovávají své identifikátory a jsou stále rozpoznány, když je zpráva odeslána znovu.

Výsledky HL7, které jsou stále čekající (OBX-11 `I`), nedostupné (`X`), smazané (`D`) nebo nesprávné (`W`), a segmenty OBX
bez hodnoty se nestanou Observation; každý je pojmenován 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"}]}`.

## Co dostanete zpět

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

- Položky jsou mapovány na **LOINC**, pokud zpráva poskytuje kód LOINC nebo název odpovídá terminologii platformy (rumunské a anglické názvy a běžné aliasy). Ostatní si ponechají kód laboratoře pod `urn:anpheros:lab-code` s přesným textem ze zprávy a jsou uvedeny v `unmapped`, abyste mohli mapování na vaší straně vylepšit. Vlastní kód laboratoře je jedinečný pouze spolu s její laboratoří: zdrojový systém je zaznamenán v Provenanci každého pozorování (`X-Anpheros-Source-System`).
- Názvy jsou porovnávány s názvy a synonymy LOINC (například *Hemoglobin A1c*, *Glycated hemoglobin*, *HDL cholesterol*, *LDL-C*). Název, který odpovídá několika konceptům, nebo který nese modifikátor, který koncept nemá (*urine*, *non-HDL*, *free*, *ratio*…), se nehádá: ponechá si kód laboratoře a je uveden v `unmapped`. Odesílejte kódy LOINC, kdykoli je váš systém má.
- Močovina a močovinový dusík (BUN) jsou různá měření: *Uree* / *Urea* se mapuje na močovinu (LOINC `3091-6`, nebo `22664-7` v mmol/L), *BUN* / *Urea nitrogen* / *Azot ureic* na močovinový dusík (`3094-0`, nebo `14937-7` v mmol/L). Hodnoty se nikdy nepřevádějí.
- LDL cholesterol: název bez metody se mapuje na `2089-1`; *calculated* / *calculat* / *Friedewald* na vypočtené LDL (`13457-7`); *direct* na přímý test (`18262-6`). Metoda je modifikátor, jako například *direct* v *Bilirubina directa*, což není celkový bilirubin a ponechává si kód laboratoře.
- Glukóza: holá "Glicemie" / "Glucose" v laboratorní zprávě se mapuje na sérum nebo plazmu (LOINC `2345-7`); název, který uvádí kapilární, vpich do prstu nebo celou krev ("capilar", "sânge integral") na celou krev (`2339-0`). Kód LOINC ve zprávě má vždy přednost.
- Každý řádek dostane stabilní identifikátor (`urn:anpheros:lab-import:v2`) sestavený z toho, co zpráva uvádí — ID zprávy, název a kód ve zprávě, datum, hodnota a jednotka — nikdy z kódu LOINC, který platforma zvolila, takže **opakované odesílání stejné zprávy přeskočí již importované řádky** (`skipped`), a to i po vylepšení mapování. Řádky, které se liší v kterémkoli z těchto údajů (jiná zpráva, jiný čas odběru, jiná hodnota), jsou uchovávány odděleně. Výsledky importované před 14. říjnem 2026 si ponechají svůj původní identifikátor a jsou rozpoznány podle názvu, data, hodnoty, jednotky a ID zprávy. Bez ID zprávy (CSV) je takové shoda hlášena v `warnings`; odešlete ID zprávy (HL7 `OBR-3`/`MSH-10`, JSON `origin`), abyste oddělili různé zprávy.
- Každé pozorování nese Provenanci s `author_type = import`, vaším zdrojovým systémem a ID zprávy; webhuky se spouštějí `resource.created` na pozorování; pacient vidí výsledky ve své aplikaci a jakákoli aplikace, ke které dal souhlas, si je může přečíst.
- Až 500 řádků na požadavek.

Obě SDK: `labs.importCsv`, `labs.importHl7`, `labs.importItems`.

Praktický příklad zprávy CSV a HL7 v2 do FHIR Observations, s nemapovanými položkami a opakovaně odeslanými zprávami: [Jak importovat laboratorní výsledky do záznamu FHIR](https://developers.anpheros.com/cs/guides/import-lab-results-fhir).

Jak se laboratorní data pohybují mezi laboratořemi, klinikami, aplikacemi a AI, a na co se zaměřit v API pro laboratorní výsledky: [API pro laboratorní výsledky](https://developers.anpheros.com/cs/guides/lab-results-api).