# Connecteur de laboratoire

> Envoyez un rapport de laboratoire complet en CSV, HL7 v2 ORU^R01 ou JSON et obtenez des Observations de laboratoire avec des codes LOINC et des plages de référence.

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

Un laboratoire (ou toute personne détenant un rapport de laboratoire) envoie le rapport complet en une seule requête et la
plateforme transforme chaque résultat en un `Observation` de laboratoire du patient :

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

## Formats

**CSV** avec une ligne d'en-tête ; séparateurs `,` `;` ou tabulation, virgule décimale acceptée, dates ISO,
`DD.MM.YYYY` ou `DD/MM/YYYY`. Colonnes reconnues (roumaines ou anglaises) : marqueur
(`analiza`, `test`, `marker`, `name`) — ou seulement une colonne LOINC `code`, auquel cas le nom LOINC devient le marqueur —
valeur (`rezultat`, `valoare`, `value`, `result`), unité (`um`, `unitate`, `unit`),
plage de référence (`interval`, `referinta` : `70-100`, `<5`, `>3.5`) ou `ref_low`/`ref_high`,
date (`data`, `recoltare`), LOINC optionnel (`loinc`, `code`), note.

```
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** (texte ER7, segments séparés par CR ou LF) : identifiant `OBX-3` (`code^text^LN`
est LOINC ; un code local (`^L`, `^99zzz`) ou tout autre système de codage est conservé comme code propre du laboratoire sous
`urn:anpheros:lab-code`), `OBX-5` valeur (`NM`, `SN`, ou texte),
`OBX-6` unité, `OBX-7` plage de référence, `OBX-8` indicateur d'anomalie → `interpretation`, `OBX-11` statut,
date `OBX-14` ou `OBR-7` ; `OBR-3`/`MSH-10` deviennent l'identifiant du rapport dans Provenance.

**Le laboratoire.** Chaque résultat nomme qui l'a produit dans `performer`, comme l'exige HL7 Europe Laboratory Report 2.1.0 :
l'organisation pour laquelle vous agissez (`X-Anpheros-Acting-As`), sinon `MSH-4` (établissement expéditeur) pour HL7, ou
`laboratory` en JSON (niveau supérieur ou par élément). Un CSV ne porte pas de laboratoire ; de tels résultats sont validés avec un
exécutant manquant, ce qui est la vérité.

**Rapports textuels, documents et dates manquantes.** Un rapport textuel envoyé ligne par ligne par OBX (`TX`/`FT`, même `OBX-3`)
devient un résultat avec les lignes jointes. Un document entier en `OBX-5` (`ED`, ou toute valeur encodée `Base64`) n'est pas
stocké comme résultat ; la réponse avertit et le document appartient à `/documents`. Sans `OBR-7`, les résultats sont datés par
`OBR-14` (spécimen reçu), avec un avertissement.

**Heures et fuseaux horaires.** Une heure v2 sans fuseau horaire est l'heure locale de l'expéditeur, pas l'UTC. Le décalage envoyé avec
`OBX-14`/`OBR-7` (`20260901081000+0300`) est conservé (`2026-09-01T08:10:00+03:00`). Sans celui-ci, le décalage de `MSH-7` est
utilisé et un avertissement l'indique ; sans décalage nulle part, le résultat ne conserve que sa date, également avec un avertissement. Les heures CSV
(`01.09.2026 08:10`) ne portent pas de fuseau horaire, elles sont donc stockées comme dates uniquement. Jusqu'au 17 octobre 2026, ces heures étaient
étiquetées UTC ; les résultats importés alors conservent leurs identifiants et sont toujours reconnus lorsqu'un rapport est renvoyé.

Les résultats HL7 qui sont encore en attente (OBX-11 `I`), non obtenus (`X`), supprimés (`D`) ou erronés (`W`), et les segments OBX
sans valeur, ne deviennent pas des Observations ; chacun est nommé dans `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 primești î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"}]}
```

- Marcatorii sunt mapați la **LOINC** atunci când raportul oferă un cod LOINC sau numele corespunde terminologiei 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ă glicată*, *Colesterol HDL*, *LDL-C*). Un nume care corespunde mai multor 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ă: o simplă "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 raport, 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 recoltare, 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 raport. Fără un ID raport (CSV), o astfel de potrivire este raportată în `warnings`; trimiteți un ID 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/fr/guides/import-lab-results-fhir).

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