# Connettore di laboratorio

> Invia un intero referto di laboratorio come CSV, HL7 v2 ORU^R01 o JSON e ottieni Osservazioni di laboratorio con codici LOINC e intervalli di riferimento.

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

Un laboratorio (o chiunque detenga un referto di laboratorio) invia l'intero referto in una singola richiesta e la
piattaforma trasforma ogni risultato in un laboratorio `Observation` del paziente:

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

## Formati

**CSV** con riga di intestazione; separatori `,` `;` o tabulazione, virgola decimale accettata, date ISO,
`DD.MM.YYYY` o `DD/MM/YYYY`. Colonne riconosciute (rumeno o inglese): marcatore
(`analiza`, `test`, `marker`, `name`) — o solo una colonna LOINC `code`, nel qual caso il nome LOINC diventa il marcatore —
valore (`rezultat`, `valoare`, `value`, `result`), unità (`um`, `unitate`, `unit`),
intervallo di riferimento (`interval`, `referinta`: `70-100`, `<5`, `>3.5`) o `ref_low`/`ref_high`,
data (`data`, `recoltare`), LOINC opzionale (`loinc`, `code`), nota.

```
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** (testo ER7, segmenti separati da CR o LF): `OBX-3` identificatore (`code^text^LN`
è LOINC; un codice locale (`^L`, `^99zzz`) o qualsiasi altro sistema di codifica viene mantenuto come codice proprio del laboratorio sotto
`urn:anpheros:lab-code`), `OBX-5` valore (`NM`, `SN`, o testo),
`OBX-6` unità, `OBX-7` intervallo di riferimento, `OBX-8` flag anomalo → `interpretation`, `OBX-11` stato,
`OBX-14` o `OBR-7` data; `OBR-3`/`MSH-10` diventano l'ID del report in Provenance.

**Il laboratorio.** Ogni risultato indica chi lo ha prodotto in `performer`, come richiesto da HL7 Europe Laboratory Report 2.1.0:
l'organizzazione per cui si agisce (`X-Anpheros-Acting-As`), altrimenti `MSH-4` (struttura mittente) per HL7, o
`laboratory` in JSON (livello superiore o per elemento). Un CSV non riporta il laboratorio; tali risultati vengono validati con un esecutore mancante,
che è la verità.

**Report testuali, documenti e date mancanti.** Un report testuale inviato una riga per OBX (`TX`/`FT`, stesso `OBX-3`)
diventa un risultato con le righe unite. Un intero documento in `OBX-5` (`ED`, o qualsiasi valore codificato `Base64`) non viene
memorizzato come risultato; la risposta avvisa e il documento appartiene a `/documents`. Senza `OBR-7`, i risultati vengono datati da
`OBR-14` (campione ricevuto), con un avviso.

**Orari e fusi orari.** Un orario v2 senza fuso orario è l'ora locale del mittente, non UTC. L'offset inviato con
`OBX-14`/`OBR-7` (`20260901081000+0300`) viene mantenuto (`2026-09-01T08:10:00+03:00`). Senza uno, viene utilizzato l'offset di `MSH-7`
e un avviso lo segnala; senza offset ovunque, il risultato conserva solo la sua data, anch'esso con un avviso. Gli orari CSV
(`01.09.2026 08:10`) non riportano il fuso orario, quindi vengono memorizzati solo come date. Fino al 17 ottobre 2026 tali orari erano
etichettati UTC; i risultati importati allora mantengono i loro identificatori e vengono ancora riconosciuti quando un report viene inviato nuovamente.

I risultati HL7 che sono ancora in sospeso (OBX-11 `I`), non ottenibili (`X`), eliminati (`D`) o errati (`W`), e i segmenti OBX
senza valore, non diventano Osservazioni; ognuno viene nominato in `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"}]}`.

## Cosa si ottiene in cambio

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

- I marcatori vengono mappati a **LOINC** quando il report fornisce un codice LOINC o il nome corrisponde alla
  terminologia della piattaforma (nomi rumeni e inglesi e alias comuni). Altri mantengono il codice del laboratorio sotto `urn:anpheros:lab-code` con il testo esatto dal report, e sono elencati in `unmapped`
  in modo da poter migliorare la mappatura da parte vostra. Un codice proprio del laboratorio è univoco solo insieme al suo laboratorio:
  il sistema di origine è registrato nella Provenienza di ogni Osservazione (`X-Anpheros-Source-System`).
- I nomi vengono confrontati con i nomi e i sinonimi LOINC (ad esempio *Hemoglobin A1c*, *Glycated hemoglobin*,
  *HDL cholesterol*, *LDL-C*). Un nome che corrisponde a più concetti, o che porta un qualificatore che il concetto non ha (*urine*, *non-HDL*, *free*, *ratio*…), non viene indovinato: mantiene il codice del laboratorio ed è elencato in
  `unmapped`. Inviare codici LOINC ogni volta che il sistema li possiede.
- Urea e azoto ureico (BUN) sono misurazioni diverse: *Uree* / *Urea* si mappa a urea (LOINC `3091-6`, o
  `22664-7` in mmol/L), *BUN* / *Urea nitrogen* / *Azot ureic* a azoto ureico (`3094-0`, o `14937-7` in mmol/L).
  I valori non vengono mai convertiti.
- Colesterolo LDL: un nome senza metodo si mappa a `2089-1`; *calculated* / *calculat* / *Friedewald* al LDL calcolato (`13457-7`); *direct* al dosaggio diretto (`18262-6`). Il metodo è un qualificatore, come *direct* in *Bilirubina
  directa*, che non è bilirubina totale e mantiene il codice del laboratorio.
- Glucosio: un semplice "Glicemie" / "Glucose" su un report di laboratorio viene mappato a siero o plasma (LOINC `2345-7`);
  un nome che indica capillare, puntura del dito o sangue intero ("capilar", "sânge integral") a sangue intero (`2339-0`).
  Un codice LOINC nel report ha sempre la priorità.
- Ogni riga ottiene un identificatore stabile (`urn:anpheros:lab-import:v2`) costruito da ciò che dice il report — ID report,
  il nome e il codice sul report, data, valore e unità — mai dal codice LOINC scelto dalla piattaforma, quindi
  **l'invio ripetuto dello stesso report salta le righe già importate** (`skipped`), anche dopo che la mappatura migliora.
  Le righe che differiscono in uno qualsiasi di questi (un altro report, un altro momento di raccolta, un altro valore) vengono tenute separate.
  I risultati importati prima del 14 ottobre 2026 mantengono il loro identificatore originale e vengono riconosciuti per nome, data, valore,
  unità e ID report. Senza un ID report (CSV) tale corrispondenza viene segnalata in `warnings`; inviare un ID report
  (HL7 `OBR-3`/`MSH-10`, JSON `origin`) per tenere separati i report.
- Ogni Osservazione porta la Provenienza con `author_type = import`, il vostro sistema sorgente e l'ID report;
  i webhook si attivano `resource.created` per Osservazione; il paziente vede i risultati nella sua app e qualsiasi
  app a cui ha acconsentito può leggerli.
- Fino a 500 righe per richiesta.

Entrambi gli SDK: `labs.importCsv`, `labs.importHl7`, `labs.importItems`.

Un esempio pratico da un report CSV e HL7 v2 a Osservazioni FHIR, con marcatori non mappati e report inviati nuovamente: [Come importare i risultati di laboratorio in un record FHIR](https://developers.anpheros.com/it/guides/import-lab-results-fhir).

Come i dati di laboratorio si spostano tra laboratori, cliniche, app e AI, e cosa cercare in un API per i risultati di laboratorio: [API per i risultati di laboratorio](https://developers.anpheros.com/it/guides/lab-results-api).