Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card

API referti di laboratorio: HL7 v2, FHIR e LOINC

Come viaggiano i referti di laboratorio come dati HL7 v2 e FHIR R4, cosa deve contenere un referto e come ricevere referti di laboratorio in un fascicolo FHIR, con un esempio reale.

Un'API per i risultati di laboratorio fornisce i risultati di laboratorio come dati strutturati — codice del test, valore, unità, intervallo di riferimento, stato e ora — invece di un PDF, in modo che il software possa memorizzarli, confrontarli, tracciarli e condividerli. Oggi tali dati viaggiano in tre forme: messaggi HL7 v2 ORU^R01 (ancora la spina dorsale tra laboratori e ospedali), risorse HL7 FHIR R4 Observation e DiagnosticReport (il formato delle API moderne) ed esportazioni CSV, JSON o PDF specifiche del laboratorio. Questa pagina spiega come i pezzi si incastrano, cosa deve contenere una buona API per i risultati di laboratorio e come ricevere dati di laboratorio nel record FHIR di un paziente con Anpheros.

Chi scambia i risultati di laboratorio e in quale formato

Da → a	Formato usuale oggi	Note
Laboratorio → sistema ospedaliero o clinico	HL7 v2 ORU^R01 (negli Stati Uniti spesso secondo la guida HL7 v2.5.1 Laboratory Results Interface)	Gli ordini vanno nella direzione opposta come messaggi ORM/OML
Laboratorio → agenzia di sanità pubblica	HL7 v2 electronic lab reporting, sempre più FHIR	Solo condizioni segnalabili
Sistema clinico → app per pazienti	FHIR R4 tramite un'API di accesso per pazienti	Negli Stati Uniti, gli EHR certificati espongono i risultati di laboratorio come FHIR (US Core); nell'UE lo European Health Data Space elenca i risultati di laboratorio tra le sue categorie di dati prioritarie
Laboratorio → paziente	Report PDF, portale, a volte CSV	Il formato che la maggior parte dei pazienti riceve effettivamente
App → modello AI	Contesto strutturato costruito da Observations	Richiede codici e unità per essere affidabile

La direzione è importante: un sistema informativo di laboratorio (LIS) è la fonte autorevole per un risultato, e ogni sistema a valle ne conserva una copia. Ciò che rende attendibili le copie è che ognuna conserva il codice, l'unità, l'intervallo e l'origine del valore.

Cosa deve contenere un singolo risultato di laboratorio

Un risultato che dice solo "Glucosio 126" non può essere interpretato in modo sicuro. Un risultato completo contiene:

Un codice standard. LOINC identifica l'analita, il campione e il metodo: 2345-7 è glucosio in siero o plasma, 2339-0 è glucosio in sangue intero. Il codice proprio del laboratorio può viaggiare accanto ad esso.
Un valore con un'unità. Idealmente un'unità UCUM (mg/dL, mmol/L, 10*3/uL), in modo che i valori di due laboratori possano essere convertiti e confrontati.
Il range di riferimento utilizzato dal laboratorio e un flag di interpretazione (H, L, N...) quando il laboratorio ne fornisce uno.
Stato: preliminare, finale, corretto o modificato. Le correzioni accadono; un API deve permettere di vedere la nuova versione senza perdere quella vecchia.
Tempi: quando il campione è stato raccolto (effectiveDateTime) e quando il risultato è stato rilasciato (issued).
Origine: quale laboratorio lo ha prodotto e a quale referto o ordine appartiene.

In FHIR R4 ogni risultato è un Observation con category = laboratory, e il referto che li raggruppa è un DiagnosticReport che elenca le Osservazioni in result. Esempi validi di entrambi, con gli errori che i validatori segnalano più spesso, si trovano negli esempi JSON FHIR R4 — vedere anche l' esempio DiagnosticReport.

HL7 v2 e FHIR affiancati

Lo stesso risultato di un pannello lipidico, come la maggior parte dei laboratori lo invia oggi e come un'API dovrebbe memorizzarlo:

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

Campo HL7 v2	Significato	Elemento Observation FHIR R4
OBX-3 `2093-3^Cholesterol^LN`	Test, codificato in LOINC	`code.coding` (sistema `http://loinc.org`)
OBX-5 `212`, OBX-2 `NM`	Valore numerico	`valueQuantity.value`
OBX-6 `mg/dL`	Unità	`valueQuantity.unit`
OBX-7 `<200`	Intervallo di riferimento	`referenceRange.high`
OBX-8 `H`	Flag di anomalia	`interpretation`
OBX-11 `F`	Risultato finale	`status = final`
OBX-14	Ora dell'osservazione	`effectiveDateTime`

La conversione tra i due è principalmente una mappatura dei campi. Le parti difficili sono altrove: laboratori che inviano i propri codici invece di LOINC, numeri scritti come testo ("6,4", "<5"), intervalli in diverse notazioni e report che vengono inviati nuovamente dopo un timeout. Come normalizzare i dati medici tratta questi argomenti in dettaglio.

Ricezione dei risultati di laboratorio in un record FHIR con Anpheros

Anpheros memorizza il record di ogni paziente come HL7 FHIR R4 e dispone di un connettore di laboratorio: una richiesta accetta un intero report in formato HL7 v2, CSV o JSON e restituisce Observations di laboratorio con codici LOINC, intervalli di riferimento, interpretazione e provenienza.

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

Per un pannello lipidico a tre voci (colesterolo, HDL, trigliceridi), la risposta, da un'esecuzione locale della piattaforma, è:

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

Ogni risultato memorizzato è una Observation FHIR R4 standard, leggibile da qualsiasi client FHIR:

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

L'invio dello stesso messaggio più volte non crea nulla di nuovo ("created": 0, "skipped": 3): ogni riga ottiene un identificatore stabile dall'ID del report, dal codice, dalla data e dal valore. I marcatori che la piattaforma non riesce a mappare a LOINC mantengono il codice del laboratorio e ritornano in unmapped, in modo da poter correggere la mappatura alla fonte.

La lettura dei risultati è una ricerca FHIR standard:

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

Altri modi di ingresso e uscita degli stessi dati:

FHIR direttamente: POST /fhir/R4/Observation, o un Bundle di transazione con il DiagnosticReport e le sue Observations insieme.
Eventi: un webhook resource.created per Observation, in modo che una clinica o un'app possa reagire all'arrivo dei risultati.
Per persone e AI: il paziente vede i risultati nella propria app; le applicazioni a cui acconsente li leggono; POST /v1/context fornisce a un modello AI un riepilogo etichettato per sorgente che include i valori di laboratorio recenti.
Provenienza: ogni risultato importato registra author_type = import, il sistema sorgente e l'ID del report (provenienza dei dati medici).

La guida completa, con un report CSV, un messaggio HL7 v2, marcatori non mappati e report inviati nuovamente su un paziente sintetico, è il tutorial Come importare risultati di laboratorio in un record FHIR.

Controlla i risultati prima di inviarli

Il validatore FHIR R4 gratuito controlla la struttura di un'Observation e i value set richiesti, e con il profilo eu-lab controlla anche ciò che un risultato di laboratorio dovrebbe contenere: la categoria laboratory, un codice LOINC, un soggetto, uno stato final-type, un'ora, un valore, un'unità UCUM e un intervallo di riferimento. Gli stessi controlli vengono eseguiti sulla piattaforma tramite POST /fhir/R4/Observation/$validate?profile=eu-lab.

Scelta di un'API per i risultati di laboratorio: una checklist

Memorizza i risultati come FHIR R4 Observations con codici LOINC, o come righe nel proprio schema?
Può accettare i formati inviati dai vostri laboratori (HL7 v2 nella maggior parte degli ospedali, CSV o PDF da laboratori più piccoli)?
Cosa succede a un marcatore che non riesce a mappare: viene rifiutato, scartato o mantenuto con il codice del laboratorio?
I tentativi di nuovo invio sono sicuri, o un report inviato nuovamente crea duplicati?
I risultati corretti sono versionati, con il valore precedente ancora leggibile?
L'origine di ogni valore è registrata e visibile al paziente?
Chi può leggere i risultati e questa decisione è basata sul consenso del paziente?

Cosa Anpheros non fa

Anpheros non è un sistema informativo di laboratorio e non è collegato a reti di laboratori commerciali: il laboratorio, la clinica o l'app del paziente inviano il referto. Non instrada ordini di laboratorio, non legge referti PDF tramite questa API (l'app Anpheros Daily estrae i risultati da foto e PDF dal lato del paziente) e non interpreta clinicamente i risultati. Le unità vengono memorizzate così come il laboratorio le invia; la loro conversione in codici UCUM spetta al mittente, come descritto in Come normalizzare i dati medici.

Domande frequenti

Cos'è un'API per i risultati di laboratorio?

Un'interfaccia che consente al software di inviare o ricevere risultati di laboratorio come dati strutturati — un test codificato, un valore con un'unità, un intervallo di riferimento, uno stato e un'ora — piuttosto che come documento. Le moderne API per i risultati di laboratorio utilizzano le risorse Observation e DiagnosticReport di HL7 FHIR R4; la maggior parte dei laboratori emette ancora messaggi HL7 v2 ORU^R01.

Quale sistema di codifica identifica i test di laboratorio?

LOINC. Ogni codice LOINC denomina l'analita, il campione e spesso il metodo, quindi 2345-7 (glucosio nel siero o nel plasma) e 2339-0 (glucosio nel sangue intero) sono risultati diversi. Le unità sono meglio espresse in UCUM.

Qual è la differenza tra un Observation e un DiagnosticReport?

Un Observation è un singolo risultato, come il colesterolo 212 mg/dL. Un DiagnosticReport è il report nel suo complesso — il pannello che è stato ordinato, chi lo ha emesso e quando — e elenca i suoi Observation in result.

Posso importare messaggi HL7 v2 di laboratorio in un server FHIR?

Sì. Ogni segmento OBX viene mappato a un Observation (OBX-3 a code, OBX-5 e OBX-6 a valueQuantity, OBX-7 a referenceRange, OBX-8 a interpretation). Il connettore di laboratorio Anpheros esegue questa operazione in una singola richiesta e conserva l'ID del report del laboratorio in Provenance.

Come evito risultati di laboratorio duplicati quando un report viene reinviato?

Assegna a ogni risultato un identificatore stabile derivato dal report, dal test, dall'ora e dal valore, e salta le righe il cui identificatore esiste già. Il connettore di laboratorio Anpheros esegue questa operazione automaticamente e riporta il conteggio come skipped.

Correlati

HL7 v2 to FHIR mapping: ogni segmento e campo OBX
How to import laboratory results into a FHIR record: il tutorial passo-passo
Lab connector: il riferimento all'endpoint
How to normalize medical data: LOINC, UCUM, date, intervalli e duplicati
Medical data provenance explained
FHIR code systems
How to integrate clinic systems with a FHIR backend
FHIR vs HL7 v2: practical differences
HL7 v2 and FHIR for clinical dashboards: da un messaggio di laboratorio a una tile del dashboard

Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card