# Łącznik laboratorium

> Wyślij cały raport laboratoryjny w formacie CSV, HL7 v2 ORU^R01 lub JSON i uzyskaj obserwacje laboratoryjne z kodami LOINC i zakresami referencyjnymi.

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

Laboratorium (lub ktokolwiek posiadający raport laboratoryjny) wysyła cały raport w jednym żądaniu, a platforma przekształca każdy wynik w obserwację laboratoryjną `Observation` pacjenta:

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

## Formaty

**CSV** z wierszem nagłówka; separatory `,` `;` lub tabulator, akceptowana przecinek dziesiętna, daty ISO,
`DD.MM.YYYY` lub `DD/MM/YYYY`. Rozpoznawane kolumny (rumuńskie lub angielskie): marker
(`analiza`, `test`, `marker`, `name`) — lub tylko kolumna LOINC `code`, w tym przypadku nazwa LOINC staje się markerem —
wartość (`rezultat`, `valoare`, `value`, `result`), jednostka (`um`, `unitate`, `unit`),
zakres referencyjny (`interval`, `referinta`: `70-100`, `<5`, `>3.5`) lub `ref_low`/`ref_high`,
data (`data`, `recoltare`), opcjonalny LOINC (`loinc`, `code`), uwaga.

```
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** (tekst ER7, segmenty oddzielone CR lub LF): `OBX-3` identyfikator (`code^text^LN`
to LOINC; lokalny kod (`^L`, `^99zzz`) lub dowolny inny system kodowania jest zachowywany jako własny kod laboratorium pod
`urn:anpheros:lab-code`), `OBX-5` wartość (`NM`, `SN` lub tekst),
`OBX-6` jednostka, `OBX-7` zakres referencyjny, `OBX-8` flaga nieprawidłowości → `interpretation`, `OBX-11` status,
`OBX-14` lub `OBR-7` data; `OBR-3`/`MSH-10` stają się identyfikatorem raportu w Provenance.

**Laboratorium.** Każdy wynik określa, kto go wygenerował w `performer`, zgodnie z wymaganiami HL7 Europe Laboratory Report 2.1.0:
organizacja, w której działasz (`X-Anpheros-Acting-As`), w przeciwnym razie `MSH-4` (placówka wysyłająca) dla HL7, lub
`laboratory` w JSON (najwyższy poziom lub na element). CSV nie zawiera laboratorium; takie wyniki są walidowane z brakującym
wykonawcą, co jest prawdą.

**Raporty tekstowe, dokumenty i brakujące daty.** Raport tekstowy wysłany jedna linia na OBX (`TX`/`FT`, ten sam `OBX-3`)
staje się jednym wynikiem z połączonymi liniami. Cały dokument w `OBX-5` (`ED` lub dowolna wartość zakodowana `Base64`) nie jest
przechowywany jako wynik; odpowiedź ostrzega, a dokument należy do `/documents`. Bez `OBR-7` wyniki są datowane przez
`OBR-14` (odebrana próbka), z ostrzeżeniem.

**Czasy i strefy czasowe.** Czas v2 bez strefy czasowej jest czasem lokalnym nadawcy, a nie UTC. Przesunięcie wysłane z
`OBX-14`/`OBR-7` (`20260901081000+0300`) jest zachowywane (`2026-09-01T08:10:00+03:00`). Bez niego używane jest przesunięcie `MSH-7`,
a ostrzeżenie o tym informuje; bez przesunięcia w żadnym miejscu wynik zachowuje tylko swoją datę, również z ostrzeżeniem. Czasy CSV
(`01.09.2026 08:10`) nie zawierają strefy czasowej, więc są przechowywane tylko jako daty. Do 17 października 2026 r. takie czasy były
oznaczone jako UTC; zaimportowane wtedy wyniki zachowują swoje identyfikatory i są nadal rozpoznawane, gdy raport jest wysyłany ponownie.

Wyniki HL7, które są nadal w toku (OBX-11 `I`), niedostępne (`X`), usunięte (`D`) lub nieprawidłowe (`W`), oraz segmenty OBX
bez wartości, nie stają się Obserwacjami; każdy jest nazwany w `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 otrzymujesz w zamian

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

- Znaczniki są mapowane na **LOINC**, gdy raport podaje kod LOINC lub nazwa pasuje do terminologii platformy (nazwy rumuńskie i angielskie oraz powszechne aliasy). Inne zachowują kod laboratorium pod `urn:anpheros:lab-code` z dokładnym tekstem z raportu i są wymienione w `unmapped`, aby można było ulepszyć mapowanie po swojej stronie. Własny kod laboratorium jest unikalny tylko w połączeniu z laboratorium: system źródłowy jest zapisywany w Provenance każdego Observation (`X-Anpheros-Source-System`).
- Nazwy są dopasowywane do nazw i synonimów LOINC (na przykład *Hemoglobin A1c*, *Glycated hemoglobin*, *HDL cholesterol*, *LDL-C*). Nazwa pasująca do kilku koncepcji lub zawierająca kwalifikator, którego koncepcja nie posiada (*urine*, *non-HDL*, *free*, *ratio*…), nie jest zgadywana: zachowuje kod laboratorium i jest wymieniona w `unmapped`. Wysyłaj kody LOINC, gdy tylko Twój system je posiada.
- Mocznika i azotu mocznika (BUN) to różne pomiary: *Uree* / *Urea* mapuje się na mocznik (LOINC `3091-6` lub `22664-7` w mmol/L), *BUN* / *Urea nitrogen* / *Azot ureic* na azot mocznika (`3094-0` lub `14937-7` w mmol/L). Wartości nigdy nie są konwertowane.
- Cholesterol LDL: nazwa bez metody mapuje się na `2089-1`; *calculated* / *calculat* / *Friedewald* na obliczony LDL (`13457-7`); *direct* na bezpośrednie badanie (`18262-6`). Metoda jest kwalifikatorem, takim jak *direct* w *Bilirubina directa*, który nie jest całkowitą bilirubiną i zachowuje kod laboratorium.
- Glukoza: samo "Glicemie" / "Glucose" w raporcie laboratoryjnym jest mapowane na surowicę lub osocze (LOINC `2345-7`); nazwa wskazująca na krew kapilarną, nakłucie palca lub krew pełną ("capilar", "sânge integral") na krew pełną (`2339-0`). Kod LOINC w raporcie zawsze ma pierwszeństwo.
- Każdy wiersz otrzymuje stabilny identyfikator (`urn:anpheros:lab-import:v2`) zbudowany na podstawie tego, co mówi raport — identyfikator raportu, nazwa i kod z raportu, data, wartość i jednostka — nigdy na podstawie kodu LOINC wybranego przez platformę, więc **ponowne wysłanie tego samego raportu pomija już zaimportowane wiersze** (`skipped`), nawet po ulepszeniu mapowania. Wiersze różniące się którymkolwiek z tych elementów (inny raport, inny czas pobrania, inna wartość) są przechowywane osobno. Wyniki zaimportowane przed 14 października 2026 r. zachowują swój pierwotny identyfikator i są rozpoznawane po nazwie, dacie, wartości, jednostce i identyfikatorze raportu. Bez identyfikatora raportu (CSV) takie dopasowanie jest zgłaszane w `warnings`; wyślij identyfikator raportu (HL7 `OBR-3`/`MSH-10`, JSON `origin`), aby rozróżnić poszczególne raporty.
- Każde Observation zawiera Provenance z `author_type = import`, Twoim systemem źródłowym i identyfikatorem raportu; webhooki uruchamiają się `resource.created` na Observation; pacjent widzi wyniki w swojej aplikacji, a każda aplikacja, na którą wyraził zgodę, może je odczytać.
- Do 500 wierszy na żądanie.

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

Praktyczny przykład importu wyników laboratoryjnych do rekordu FHIR z raportu CSV i HL7 v2, z niezmapowanymi znacznikami i ponownymi wysłaniami raportów: [Jak importować wyniki laboratoryjne do rekordu FHIR](https://developers.anpheros.com/pl/guides/import-lab-results-fhir).

Jak dane laboratoryjne przemieszczają się między laboratoriami, klinikami, aplikacjami i AI, oraz na co zwrócić uwagę w API wyników laboratoryjnych: [Laboratory results API](https://developers.anpheros.com/pl/guides/lab-results-api).