# Лабораторний конектор

> Надсилайте повний лабораторний звіт у форматі CSV, HL7 v2 ORU^R01 або JSON та отримуйте лабораторні спостереження (Observations) з кодами LOINC та референтними діапазонами.

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

Лабораторія (або будь-хто, хто має лабораторний звіт) надсилає повний звіт одним запитом, а платформа перетворює кожен результат на лабораторне `Observation` пацієнта:

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

## Формати

**CSV** з рядком заголовка; роздільники `,` `;` або табуляція, десяткова кома приймається, дати ISO,
`DD.MM.YYYY` або `DD/MM/YYYY`. Розпізнавані стовпці (румунською або англійською): маркер
(`analiza`, `test`, `marker`, `name`) — або лише стовпець LOINC `code`, у цьому випадку назва LOINC стає маркером —
значення (`rezultat`, `valoare`, `value`, `result`), одиниця виміру (`um`, `unitate`, `unit`),
діапазон посилань (`interval`, `referinta`: `70-100`, `<5`, `>3.5`) або `ref_low`/`ref_high`,
дата (`data`, `recoltare`), необов'язковий LOINC (`loinc`, `code`), примітка.

```
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, сегменти розділені CR або LF): `OBX-3` ідентифікатор (`code^text^LN`
є LOINC; локальний код (`^L`, `^99zzz`) або будь-яка інша система кодування зберігається як власний код лабораторії під
`urn:anpheros:lab-code`), `OBX-5` значення (`NM`, `SN` або текст),
`OBX-6` одиниця виміру, `OBX-7` діапазон посилань, `OBX-8` прапорець аномальності → `interpretation`, `OBX-11` статус,
`OBX-14` або `OBR-7` дата; `OBR-3`/`MSH-10` стають ідентифікатором звіту в Provenance.

**Лабораторія.** Кожен результат вказує, хто його створив, у `performer`, як того вимагає HL7 Europe Laboratory Report 2.1.0:
організація, яку ви представляєте (`X-Anpheros-Acting-As`), інакше `MSH-4` (відправляюча установа) для HL7, або
`laboratory` у JSON (верхній рівень або для кожного елемента). CSV не містить інформації про лабораторію; такі результати валідуються з відсутнім
виконавцем, що є правдою.

**Текстові звіти, документи та відсутні дати.** Текстовий звіт, надісланий одним рядком на OBX (`TX`/`FT`, той самий `OBX-3`)
стає одним результатом із об'єднаними рядками. Цілий документ у `OBX-5` (`ED` або будь-яке закодоване значення `Base64`) не
зберігається як результат; відповідь попереджає, і документ належить до `/documents`. Без `OBR-7` результати датуються за
`OBR-14` (отриманий зразок), з попередженням.

**Час та часові пояси.** Час v2 без часового поясу є локальним часом відправника, а не UTC. Зсув, надісланий з
`OBX-14`/`OBR-7` (`20260901081000+0300`), зберігається (`2026-09-01T08:10:00+03:00`). Без нього використовується зсув `MSH-7`,
і з'являється попередження; без зсуву будь-де результат зберігає лише свою дату, також з попередженням. Часи CSV
(`01.09.2026 08:10`) не містять часового поясу, тому вони зберігаються лише як дати. До 17 жовтня 2026 року такі часи були
позначені як UTC; результати, імпортовані тоді, зберігають свої ідентифікатори і все ще розпізнаються, коли звіт надсилається знову.

Результати HL7, які ще очікуються (OBX-11 `I`), недоступні (`X`), видалені (`D`) або неправильні (`W`), а також сегменти OBX
без значення, не стають Спостереженнями; кожен з них названий у `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"}]}`.

## Що ви отримуєте у відповідь

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

- Маркери зіставляються з **LOINC**, коли звіт надає код LOINC або назва відповідає термінології платформи (румунські та англійські назви та поширені псевдоніми). Інші зберігають код лабораторії під `urn:anpheros:lab-code` з точним текстом зі звіту, і перелічені в `unmapped`, щоб ви могли покращити зіставлення на своїй стороні. Власний код лабораторії є унікальним лише разом з її лабораторією: вихідна система записується в Provenance кожного спостереження (`X-Anpheros-Source-System`).
- Назви зіставляються з назвами та синонімами LOINC (наприклад, *Hemoglobin A1c*, *Glycated hemoglobin*, *HDL cholesterol*, *LDL-C*). Назва, яка відповідає кільком концепціям, або яка має кваліфікатор, якого концепція не має (*urine*, *non-HDL*, *free*, *ratio*…), не вгадується: вона зберігає код лабораторії та перелічена в `unmapped`. Надсилайте коди LOINC, коли ваша система їх має.
- Сечовина та азот сечовини (BUN) — це різні вимірювання: *Uree* / *Urea* зіставляється з сечовиною (LOINC `3091-6`, або `22664-7` в ммоль/л), *BUN* / *Urea nitrogen* / *Azot ureic* — з азотом сечовини (`3094-0`, або `14937-7` в ммоль/л). Значення ніколи не конвертуються.
- Холестерин ЛПНЩ: назва без методу зіставляється з `2089-1`; *calculated* / *calculat* / *Friedewald* — з розрахованим ЛПНЩ (`13457-7`); *direct* — з прямим аналізом (`18262-6`). Метод є кваліфікатором, як *direct* у *Bilirubina directa*, що не є загальним білірубіном і зберігає код лабораторії.
- Глюкоза: проста "Glicemie" / "Glucose" у лабораторному звіті зіставляється з сироваткою або плазмою (LOINC `2345-7`); назва, що вказує на капілярну кров, прокол пальця або цільну кров ("capilar", "sânge integral") — з цільною кров'ю (`2339-0`). Код LOINC у звіті завжди має пріоритет.
- Кожен рядок отримує стабільний ідентифікатор (`urn:anpheros:lab-import:v2`), побудований на основі даних зі звіту — ідентифікатор звіту, назва та код зі звіту, дата, значення та одиниця вимірювання — ніколи на основі коду LOINC, обраного платформою, тому **повторне надсилання того самого звіту пропускає вже імпортовані рядки** (`skipped`), навіть після покращення зіставлення. Рядки, що відрізняються будь-чим із цього (інший звіт, інший час забору, інше значення), зберігаються окремо. Результати, імпортовані до 14 жовтня 2026 року, зберігають свій початковий ідентифікатор і розпізнаються за назвою, датою, значенням, одиницею вимірювання та ідентифікатором звіту. Без ідентифікатора звіту (CSV) таке зіставлення повідомляється в `warnings`; надішліть ідентифікатор звіту (HL7 `OBR-3`/`MSH-10`, JSON `origin`), щоб розділяти окремі звіти.
- Кожне спостереження містить Provenance з `author_type = import`, вашою вихідною системою та ідентифікатором звіту; вебхуки спрацьовують `resource.created` на кожне спостереження; пацієнт бачить результати у своєму додатку, і будь-який додаток, на який він дав згоду, може їх читати.
- До 500 рядків на запит.

Обидва SDK: `labs.importCsv`, `labs.importHl7`, `labs.importItems`.

Практичний приклад імпорту результатів лабораторних досліджень у запис FHIR з CSV та звіту HL7 v2, з незіставленими маркерами та повторно надісланими звітами: [Як імпортувати результати лабораторних досліджень у запис FHIR](https://developers.anpheros.com/uk/guides/import-lab-results-fhir).

Як лабораторні дані переміщуються між лабораторіями, клініками, додатками та ШІ, і на що звернути увагу в API результатів лабораторних досліджень: [API результатів лабораторних досліджень](https://developers.anpheros.com/uk/guides/lab-results-api).