# API pentru rezultate de laborator: HL7 v2, FHIR și LOINC

> Cum circulă rezultatele de laborator ca date HL7 v2 și FHIR, ce trebuie să conțină un rezultat și cum să primiți rapoarte de laborator într-un dosar FHIR, cu un exemplu real.

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

**O API pentru rezultate de laborator livrează rezultatele de laborator ca date structurate — codul testului, valoarea, unitatea, intervalul de referință, starea și timpul — în loc de un PDF, astfel încât software-ul să le poată stoca, compara, grafice și partaja.** Astăzi, aceste date circulă sub trei forme: mesaje HL7 v2 ORU^R01 (încă baza de comunicație între laboratoare și spitale), resurse HL7 FHIR R4 `Observation` și `DiagnosticReport` (formatul API-urilor moderne) și exporturi specifice laboratorului CSV, JSON sau PDF. Această pagină explică cum se potrivesc piesele, ce trebuie să conțină o API bună pentru rezultate de laborator și cum să primiți date de laborator într-un dosar FHIR al pacientului cu Anpheros.

## Cine schimbă rezultatele de laborator și în ce format

| De la → către | Format uzual astăzi | Note |
|---|---|---|
| Laborator → sistem spitalicesc sau clinic | HL7 v2 ORU^R01 (în SUA, adesea conform ghidului HL7 v2.5.1 Laboratory Results Interface) | Comenzile merg în direcția opusă ca mesaje ORM/OML |
| Laborator → agenție de sănătate publică | Raportare electronică de laborator HL7 v2, din ce în ce mai mult FHIR | Doar condiții raportabile |
| Sistem clinic → aplicație pacient | FHIR R4 printr-un API de acces pentru pacienți | În SUA, EHR-urile certificate expun rezultatele de laborator ca FHIR (US Core); în UE, European Health Data Space listează rezultatele de laborator printre categoriile sale prioritare de date |
| Laborator → pacient | Raport PDF, portal, uneori CSV | Formatul pe care majoritatea pacienților îl primesc de fapt |
| Aplicație → model AI | Context structurat construit din Observații | Necesită coduri și unități pentru a fi fiabil |

Direcția contează: un sistem informațional de laborator (LIS) este sursa de adevăr pentru un rezultat, iar fiecare sistem ulterior păstrează o copie. Ceea ce face copiile de încredere este faptul că fiecare dintre ele păstrează codul, unitatea, intervalul și originea valorii.

## Ce trebuie să conțină un rezultat de laborator

Un rezultat care spune doar „Glucoză 126” nu poate fi interpretat în siguranță. Un rezultat complet are:

- **Un cod standard.** LOINC identifică analitul, specimenul și metoda: `2345-7` este glucoză în ser sau plasmă, `2339-0` este glucoză în sânge integral. Codul propriu al laboratorului poate fi alături de acesta.
- **O valoare cu o unitate.** Ideal, o unitate UCUM (`mg/dL`, `mmol/L`, `10*3/uL`), astfel încât valorile de la două laboratoare să poată fi convertite și comparate.
- **Intervalul de referință** utilizat de laborator și un indicator de **interpretare** (H, L, N…) atunci când laboratorul oferă unul.
- **Stare:** preliminar, final, corectat sau modificat. Corecturile se întâmplă; un API trebuie să vă permită să vedeți noua versiune fără a o pierde pe cea veche.
- **Momente:** când a fost colectat specimenul (`effectiveDateTime`) și când a fost eliberat rezultatul (`issued`).
- **Origine:** ce laborator l-a produs și la ce raport sau comandă aparține.

În FHIR R4, fiecare rezultat este un `Observation` cu `category = laboratory`, iar raportul care le grupează este un `DiagnosticReport` care listează Observațiile în `result`. Exemple valide ale ambelor, cu greșelile pe care validatorii le raportează cel mai des, se găsesc în [Exemple JSON FHIR R4](https://developers.anpheros.com/tools/fhir-examples/observation-lab-result) — vezi și [exemplul DiagnosticReport](https://developers.anpheros.com/tools/fhir-examples/diagnostic-report).

## HL7 v2 și FHIR unul lângă altul

Același rezultat al panelului lipidic, așa cum îl trimit majoritatea laboratoarelor astăzi și cum ar trebui să îl stocheze un API:

```
OBX|1|NM|2093-3^Cholesterol^LN||212|mg/dL|<200|H|||F|||20261002074500
```

| Câmp HL7 v2 | Semnificație | Element FHIR R4 Observation |
|---|---|---|
| OBX-3 `2093-3^Cholesterol^LN` | Test, codificat în LOINC | `code.coding` (sistem `http://loinc.org`) |
| OBX-5 `212`, OBX-2 `NM` | Valoare numerică | `valueQuantity.value` |
| OBX-6 `mg/dL` | Unitate | `valueQuantity.unit` |
| OBX-7 `<200` | Interval de referință | `referenceRange.high` |
| OBX-8 `H` | Flag de anomalie | `interpretation` |
| OBX-11 `F` | Rezultat final | `status = final` |
| OBX-14 | Timpul observației | `effectiveDateTime` |

Conversia între cele două implică în mare parte maparea câmpurilor. Părțile dificile sunt în altă parte: laboratoare care trimit propriile coduri în loc de LOINC, numere scrise ca text (`"6,4"`, `"<5"`), intervale în mai multe notații și rapoarte care sunt trimise din nou după un timeout. [Cum să normalizați datele medicale](https://developers.anpheros.com/ro/guides/normalize-medical-data) acoperă aceste aspecte în detaliu.

## Primirea rezultatelor de laborator într-un fișier FHIR cu Anpheros

Anpheros stochează fișierul fiecărui pacient ca HL7 FHIR R4 și are un [conector de laborator](https://developers.anpheros.com/ro/guides/lab-connector): o singură cerere preia un raport complet ca HL7 v2, CSV sau JSON și returnează Observații de laborator cu coduri LOINC, intervale de referință, interpretare și proveniență.

```bash
curl -s -X POST "https://platform.anpheros.com/v1/patients/$PID/labs/import" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: x-application/hl7-v2+er7" \
  -H "X-Anpheros-Source-System: springfield-lis" \
  --data-binary @lipid-panel.hl7
```

Pentru un panou lipidic de trei linii (colesterol, HDL, trigliceride), răspunsul, dintr-o rulare locală a platformei, este:

```json
{
  "created": 3, "skipped": 0, "unmapped": [], "warnings": [],
  "observations": [
    {"id": "26ed9219-…", "marker": "Cholesterol", "code": "2093-3", "system": "http://loinc.org",
     "value": 212.0, "unit": "mg/dL", "date": "2026-10-02T07:45:00Z"},
    {"id": "2633d1d4-…", "marker": "HDL cholesterol", "code": "2085-9", "system": "http://loinc.org",
     "value": 48.0, "unit": "mg/dL", "date": "2026-10-02T07:45:00Z"},
    {"id": "a02520bb-…", "marker": "Triglyceride", "code": "2571-8", "system": "http://loinc.org",
     "value": 165.0, "unit": "mg/dL", "date": "2026-10-02T07:45:00Z"}
  ]
}
```

Fiecare rezultat stocat este o Observație FHIR R4 standard, citibilă de orice client FHIR:

```json
{
  "resourceType": "Observation",
  "status": "final",
  "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "laboratory"}]}],
  "code": {"coding": [{"system": "http://loinc.org", "code": "2093-3",
                        "display": "Cholesterol [Mass/volume] in Serum or Plasma"}], "text": "Cholesterol"},
  "subject": {"reference": "Patient/4c3062d9-…"},
  "effectiveDateTime": "2026-10-02T07:45:00Z",
  "valueQuantity": {"value": 212.0, "unit": "mg/dL"},
  "interpretation": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation", "code": "H"}]}],
  "referenceRange": [{"high": {"value": 200.0, "unit": "mg/dL"}}]
}
```

Trimiterea aceluiași mesaj din nou nu creează nimic nou (`"created": 0, "skipped": 3`): fiecare rând primește un identificator stabil din ID-ul raportului, codul, data și valoarea. Marcajele pe care platforma nu le poate mapa la LOINC păstrează codul laboratorului și revin în `unmapped`, astfel încât să puteți corecta maparea la sursă.

Citirea rezultatelor înapoi este o căutare FHIR standard:

```bash
curl -s "https://platform.anpheros.com/fhir/R4/Observation?patient=$PID&category=laboratory&code=http://loinc.org|2093-3" \
  -H "Authorization: Bearer $KEY"
```

Alte modalități de intrare și ieșire din aceleași date:

- **FHIR direct:** `POST /fhir/R4/Observation`, sau un pachet de tranzacție cu `DiagnosticReport` și Observațiile sale împreună.
- **Evenimente:** un [webhook](https://developers.anpheros.com/ro/guides/webhooks) `resource.created` pentru fiecare Observație, astfel încât o clinică sau o aplicație să poată reacționa atunci când sosesc rezultatele.
- **Pentru oameni și AI:** pacientul vede rezultatele în aplicația sa; aplicațiile cărora le acordă consimțământul le citesc; `POST /v1/context` oferă unui model AI un rezumat etichetat la sursă care include valorile recente de laborator.
- **Proveniență:** fiecare rezultat importat înregistrează `author_type = import`, sistemul sursă și ID-ul raportului ([proveniența datelor medicale](https://developers.anpheros.com/ro/guides/medical-data-provenance)).

Parcurgerea completă, cu un raport CSV, un mesaj HL7 v2, marcaje nemapate și rapoarte retrimise pe un pacient sintetic, este tutorialul [Cum să importați rezultatele de laborator într-un fișier FHIR](https://developers.anpheros.com/ro/guides/import-lab-results-fhir).

## Verificați rezultatele înainte de a le trimite

Validatul gratuit [FHIR R4 validator](https://developers.anpheros.com/tools/fhir-validator) verifică structura unei observații și seturile de valori necesare, iar cu profilul `eu-lab` verifică, de asemenea, ce ar trebui să conțină un rezultat de laborator: categoria `laboratory`, un cod LOINC, un subiect, un status final (final-type), un timp, o valoare, o unitate UCUM și un interval de referință. Aceleași verificări rulează pe platformă prin `POST /fhir/R4/Observation/$validate?profile=eu-lab`.

## Alegerea unui API pentru rezultate de laborator: o listă de verificare

- Stochează rezultatele ca Observații FHIR R4 cu coduri LOINC sau ca rânduri în propriul său schemă?
- Poate accepta formatele pe care laboratoarele dvs. le trimit efectiv (HL7 v2 în majoritatea spitalelor, CSV sau PDF de la laboratoare mai mici)?
- Ce se întâmplă cu un marker pe care nu îl poate mapa: este respins, eliminat sau păstrat cu codul laboratorului?
- Sunt reîncercările sigure, sau un raport retrimis creează duplicate?
- Sunt rezultatele corectate versionate, cu valoarea anterioară încă lizibilă?
- Este înregistrată originea fiecărei valori și vizibilă pacientului?
- Cine poate citi rezultatele și este acest lucru decis de consimțământul pacientului?

## Ce nu face Anpheros

Anpheros nu este un sistem informatic de laborator și nu este conectat la rețele comerciale de laboratoare: laboratorul, clinica sau aplicația pacientului trimite raportul. Nu direcționează comenzi de laborator, nu citește rapoarte PDF prin acest API (aplicația Anpheros Daily extrage rezultatele din fotografii și PDF-uri din partea pacientului) și nu interpretează rezultatele clinic. Unitățile sunt stocate așa cum le trimite laboratorul; conversia lor în coduri UCUM revine expeditorului, așa cum este descris în [Cum să normalizați datele medicale](https://developers.anpheros.com/ro/guides/normalize-medical-data).

## Întrebări frecvente

### Ce este un API pentru rezultate de laborator?
O interfață care permite software-ului să trimită sau să primească rezultate de laborator ca date structurate — un test codificat, o valoare cu o unitate, un interval de referință, un status și un timp — mai degrabă decât ca un document. API-urile moderne pentru rezultate de laborator utilizează resursele Observation și DiagnosticReport din HL7 FHIR R4; majoritatea laboratoarelor emit în continuare mesaje HL7 v2 ORU^R01.

### Ce sistem de codificare identifică testele de laborator?
LOINC. Fiecare cod LOINC numește analitul, specimenul și adesea metoda, astfel încât `2345-7` (glucoză în ser sau plasmă) și `2339-0` (glucoză în sânge integral) sunt rezultate diferite. Unitățile sunt cel mai bine exprimate în UCUM.

### Care este diferența dintre un Observation și un DiagnosticReport?
Un Observation este un singur rezultat, cum ar fi colesterolul 212 mg/dL. Un DiagnosticReport este raportul în ansamblul său — panelul care a fost comandat, cine l-a emis și când — și listează Observation-urile sale în `result`.

### Pot importa mesaje HL7 v2 de laborator într-un server FHIR?
Da. Fiecare segment OBX se mapează la un Observation (OBX-3 la `code`, OBX-5 și OBX-6 la `valueQuantity`, OBX-7 la `referenceRange`, OBX-8 la `interpretation`). Conectorul de laborator Anpheros face acest lucru într-o singură cerere și păstrează ID-ul raportului de laborator în Provenance.

### Cum evit rezultatele duplicate de laborator atunci când un raport este retrimis?
Acordați fiecărui rezultat un identificator stabil derivat din raport, test, timp și valoare, și omiteți rândurile al căror identificator există deja. Conectorul de laborator Anpheros face acest lucru automat și raportează numărul ca `skipped`.

## Conexe

- [Maparea HL7 v2 la FHIR](https://developers.anpheros.com/ro/guides/hl7-v2-to-fhir-mapping): fiecare segment și câmp OBX
- [Cum să importați rezultatele de laborator într-un fișier FHIR](https://developers.anpheros.com/ro/guides/import-lab-results-fhir): tutorialul pas cu pas
- [Conector de laborator](https://developers.anpheros.com/ro/guides/lab-connector): referința endpoint-ului
- [Cum să normalizați datele medicale](https://developers.anpheros.com/ro/guides/normalize-medical-data): LOINC, UCUM, date, intervale și duplicate
- [Proveniența datelor medicale explicată](https://developers.anpheros.com/ro/guides/medical-data-provenance)
- [Sisteme de coduri FHIR](https://developers.anpheros.com/ro/guides/fhir-code-systems)
- [Cum să integrați sistemele clinice cu un backend FHIR](https://developers.anpheros.com/ro/guides/integrate-clinic-systems-fhir)
- [FHIR vs HL7 v2: diferențe practice](https://developers.anpheros.com/ro/guides/fhir-vs-hl7-v2)
- [HL7 v2 și FHIR pentru tablouri de bord clinice](https://developers.anpheros.com/ro/guides/clinical-dashboard-hl7-fhir): de la un mesaj de laborator la o țiglă de tabloul de bord