# Conector de laborator

> Trimite un raport de laborator complet ca CSV, HL7 v2 ORU^R01 sau JSON și obține Observații de laborator cu coduri LOINC și intervale de referință.

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

Un laborator (sau oricine deține un raport de laborator) trimite întregul raport într-o singură cerere, iar
platforma transformă fiecare rezultat într-o `Observation` de laborator a pacientului:

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

## Formate

**CSV** cu un rând de antet; separatori `,` `;` sau tabulator, virgulă zecimală acceptată, date ISO,
`DD.MM.YYYY` sau `DD/MM/YYYY`. Coloane recunoscute (română sau engleză): marker
(`analiza`, `test`, `marker`, `name`) — sau doar o coloană LOINC `code`, caz în care numele LOINC devine markerul —
valoare (`rezultat`, `valoare`, `value`, `result`), unitate (`um`, `unitate`, `unit`),
interval de referință (`interval`, `referinta`: `70-100`, `<5`, `>3.5`) sau `ref_low`/`ref_high`,
dată (`data`, `recoltare`), LOINC opțional (`loinc`, `code`), notă.

```
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, segmente separate prin CR sau LF): `OBX-3` identificator (`code^text^LN`
este LOINC; un cod local (`^L`, `^99zzz`) sau orice alt sistem de codificare este păstrat ca propriul cod al laboratorului sub
`urn:anpheros:lab-code`), `OBX-5` valoare (`NM`, `SN`, sau text),
`OBX-6` unitate, `OBX-7` interval de referință, `OBX-8` flag anormal → `interpretation`, `OBX-11` status,
`OBX-14` sau `OBR-7` dată; `OBR-3`/`MSH-10` devin ID-ul raportului în Provenance.

**Laboratorul.** Fiecare rezultat numește cine l-a produs în `performer`, așa cum cere HL7 Europe Laboratory Report 2.1.0:
organizația pentru care acționați (`X-Anpheros-Acting-As`), altfel `MSH-4` (unitate de expediere) pentru HL7, sau
`laboratory` în JSON (nivel superior sau per element). Un CSV nu poartă laborator; astfel de rezultate se validează cu un
furnizor lipsă, ceea ce este adevărul.

**Rapoarte text, documente și date lipsă.** Un raport text trimis o linie per OBX (`TX`/`FT`, același `OBX-3`)
devine un rezultat cu liniile unite. Un document întreg în `OBX-5` (`ED`, sau orice valoare codificată `Base64`) nu este
stocat ca rezultat; răspunsul avertizează și documentul aparține `/documents`. Fără `OBR-7`, rezultatele sunt datate de
`OBR-14` (specimen primit), cu un avertisment.

**Ore și fusuri orare.** O oră v2 fără fus orar este ora locală a expeditorului, nu UTC. Offset-ul trimis cu
`OBX-14`/`OBR-7` (`20260901081000+0300`) este păstrat (`2026-09-01T08:10:00+03:00`). Fără unul, se folosește offset-ul de `MSH-7`
și un avertisment anunță acest lucru; fără offset nicăieri, rezultatul păstrează doar data sa, tot cu un avertisment. Orele CSV
(`01.09.2026 08:10`) nu poartă fus orar, deci sunt stocate doar ca date. Până la 17 octombrie 2026 astfel de ore au fost
etichetate UTC; rezultatele importate atunci își păstrează identificatorii și sunt recunoscute în continuare când un raport este trimis din nou.

Rezultatele HL7 care sunt încă în așteptare (OBX-11 `I`), indisponibile (`X`), șterse (`D`) sau greșite (`W`), și segmentele OBX
fără valoare, nu devin Observații; fiecare este numit în `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"}]}`.

## Ce primiți înapoi

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

- Markerii sunt mapați la **LOINC** atunci când raportul oferă un cod LOINC sau numele se potrivește cu terminologia platformei (nume românești și englezești și aliasuri comune). Alții păstrează codul laboratorului sub `urn:anpheros:lab-code` cu textul exact din raport și sunt listați în `unmapped` pentru a putea îmbunătăți maparea din partea dumneavoastră. Un cod propriu al laboratorului este unic doar împreună cu laboratorul său: sistemul sursă este înregistrat în Provenanța fiecărei Observații (`X-Anpheros-Source-System`).
- Numele sunt comparate cu numele și sinonimele LOINC (de exemplu, *Hemoglobin A1c*, *Hemoglobină glicozilată*, *Colesterol HDL*, *LDL-C*). Un nume care se potrivește cu mai multe concepte sau care poartă un calificativ pe care conceptul nu îl are (*urină*, *non-HDL*, *liber*, *raport*…), nu este ghicit: păstrează codul laboratorului și este listat în `unmapped`. Trimiteți coduri LOINC ori de câte ori sistemul dumneavoastră le are.
- Ureea și azotul ureic (BUN) sunt măsurători diferite: *Uree* / *Urea* se mapează la uree (LOINC `3091-6`, sau `22664-7` în mmol/L), *BUN* / *Azot ureic* / *Urea nitrogen* la azot ureic (`3094-0`, sau `14937-7` în mmol/L). Valorile nu sunt niciodată convertite.
- Colesterol LDL: un nume fără metodă se mapează la `2089-1`; *calculat* / *calculated* / *Friedewald* la LDL calculat (`13457-7`); *direct* la testul direct (`18262-6`). Metoda este un calificativ, precum *direct* în *Bilirubina directa*, care nu este bilirubină totală și păstrează codul laboratorului.
- Glucoză: un simplu "Glicemie" / "Glucose" pe un raport de laborator este mapat la ser sau plasmă (LOINC `2345-7`); un nume care indică capilar, înțepătură în deget sau sânge integral ("capilar", "sânge integral") la sânge integral (`2339-0`). Un cod LOINC din raport are întotdeauna prioritate.
- Fiecare rând primește un identificator stabil (`urn:anpheros:lab-import:v2`) construit din ceea ce spune raportul — ID-ul raportului, numele și codul din raport, data, valoarea și unitatea — niciodată din codul LOINC ales de platformă, astfel încât **re-trimiterea aceluiași raport omite rândurile deja importate** (`skipped`), chiar și după îmbunătățirea mapării. Rândurile care diferă în oricare dintre acestea (alt raport, altă dată de colectare, altă valoare) sunt păstrate separat. Rezultatele importate înainte de 14 octombrie 2026 își păstrează identificatorul original și sunt recunoscute după nume, dată, valoare, unitate și ID-ul raportului. Fără un ID de raport (CSV), o astfel de potrivire este raportată în `warnings`; trimiteți un ID de raport (HL7 `OBR-3`/`MSH-10`, JSON `origin`) pentru a păstra rapoartele separate.
- Fiecare Observație poartă Provenanța cu `author_type = import`, sistemul dumneavoastră sursă și ID-ul raportului; webhooks declanșează `resource.created` per Observație; pacientul vede rezultatele în aplicația sa și orice aplicație la care a consimțit le poate citi.
- Până la 500 de rânduri per cerere.

Ambele SDK-uri: `labs.importCsv`, `labs.importHl7`, `labs.importItems`.

Un exemplu practic dintr-un raport CSV și HL7 v2 către Observații FHIR, cu markeri nemapați și rapoarte retrimise: [Cum să importați rezultatele de laborator într-un dosar FHIR](https://developers.anpheros.com/ro/guides/import-lab-results-fhir).

Cum circulă datele de laborator între laboratoare, clinici, aplicații și AI, și la ce să fiți atenți într-un API de rezultate de laborator: [API pentru rezultate de laborator](https://developers.anpheros.com/ro/guides/lab-results-api).