Connettore di laboratorio: come un referto di laboratorio in HL7 v2, CSV o JSON diventa Osservazioni FHIR in una sola richiesta

Un laboratorio ha un solo compito in un'integrazione: inserire il referto nella cartella del paziente senza doverlo riscrivere, senza perdere l'intervallo di riferimento e senza inventare un formato che nessuno legge. Il connettore di laboratorio Anpheros prende il referto così come il laboratorio lo produce già, in formato HL7 v2, CSV o JSON, e trasforma ogni risultato in un' Observation FHIR con un codice LOINC, un'unità di misura, un intervallo di riferimento, una data e il nome del laboratorio come esecutore. Questa guida è il contratto.

Versione tecnica per sviluppatori: Lab connector · Lab results API su developers.anpheros.com, con richieste, risposte e limiti. Questa pagina è la versione in linguaggio semplice.

Una richiesta

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        (opzionale; registrato in Provenance)
Idempotency-Key: <report id>          (opzionale; un nuovo tentativo restituisce la stessa risposta)

La risposta indica cosa è successo:

{"created": 3, "skipped": 0, "unmapped": ["Marker molto raro"], "warnings": [],
 "observations": [{"id": "…", "marker": "TSH", "code": "3016-3", "system": "http://loinc.org",
                   "value": 2.1, "unit": "mUI/L", "date": "2026-09-01"}]}

Formati

HL7 v2 ORU^R01, in formato testo ER7. OBX-3 è l'identificatore (code^text^LN è LOINC; un codice locale viene mantenuto come codice proprio del laboratorio), OBX-5 il valore, OBX-6 l'unità di misura, OBX-7 l'intervallo di riferimento, OBX-8 il flag di anomalia (diventa interpretation), OBX-11 lo stato, OBX-14 o OBR-7 la data. MSH-4 indica la struttura mittente, che diventa l'esecutore; OBR-3 e MSH-10 diventano l'ID del referto in Provenance. Risultati in sospeso, cancellati o errati (I, X, D, W) e segmenti OBX senza valore non diventano Osservazioni e vengono segnalati nei warnings.

CSV con una riga di intestazione; separatori , ; o tabulazione, virgola decimale accettata, date in formato ISO, DD.MM.YYYY o DD/MM/YYYY. Colonne riconosciute in rumeno o inglese: marker, value, unit, reference range (70-100, <5, >3.5) o ref_low/ref_high, date, codice LOINC opzionale, note. Un CSV non trasporta il nome del laboratorio, quindi l'esecutore è mancante a meno che non si invii X-Anpheros-Acting-As.

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

JSON quando si dispone già di dati strutturati: {"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, "code": "3016-3"}]}.

Regole di mappatura importanti

• LOINC quando fornito, altrimenti per nome. I nomi vengono confrontati con i nomi e i sinonimi LOINC in rumeno e inglese. 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 sotto urn:anpheros:lab-code e appare in unmapped, in modo da poter migliorare la mappatura da parte vostra. Inviare codici LOINC ogni volta che li si possiede.
• I valori non vengono mai convertiti. Urea e azoto ureico sono codici diversi; LDL diretto e LDL calcolato sono codici diversi; glucosio da siero e da sangue capillare sono codici diversi. Il connettore sceglie quello giusto dal nome e dal metodo, e lascia il numero invariato.
• Gli orari mantengono il loro fuso. Un orario v2 con un offset viene mantenuto; senza offset, viene utilizzato l'offset di MSH-7 con un avviso; senza alcun offset ovunque, viene memorizzata solo la data. Gli orari CSV non hanno fuso e vengono memorizzati come date.
• Idempotente. Inviare lo stesso referto due volte con lo stesso Idempotency-Key e si otterrà la stessa risposta e nessun duplicato.
• Provenance su ogni risultato: il sistema sorgente, l'ID del referto e l'esecutore, come richiesto dalla HL7 Europe Laboratory Report.

Cosa vede il paziente

I risultati appaiono nella cartella della persona e, se utilizzano Anpheros Daily, sul loro telefono non appena arrivano, con l'intervallo di riferimento e l'andamento rispetto ai referti precedenti. Niente da scansionare, niente da riscrivere. Se un risultato è anomalo, la persona vede il flag; l'app non lo interpreta.

Test

Il sandbox è gratuito e i pazienti sintetici hanno già una cronologia di laboratorio. Inviare un referto a uno di essi e rileggerlo:

curl -X POST "$BASE/v1/patients/$PID/labs/import" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: text/csv" --data-binary @report.csv
curl "$BASE/fhir/R4/Observation?patient=$PID&category=laboratory&_sort=-date" -H "Authorization: Bearer $KEY"

La specifica completa, incluse le note di conformità HL7 Europe, è disponibile su developers.anpheros.com/guides/lab-connector.

Domande frequenti

Dobbiamo cambiare ciò che produce il nostro LIS?

No. Inviare il messaggio ORU^R01 o l'esportazione CSV così come sono. Se potete aggiungere codici LOINC, fatelo; altrimenti il connettore mappa per nome e vi dice cosa non è riuscito a mappare.

Cosa succede ai risultati che non riuscite a mappare?

Vengono memorizzati con il codice proprio del laboratorio e il testo esatto del referto, in modo che nulla vada perso, e elencati in unmapped in modo da poter aggiungere un codice LOINC la prossima volta.

Gli intervalli di riferimento e i flag di anomalia vengono mantenuti?

Sì: l'intervallo va a referenceRange, il flag a interpretation, l'unità di misura viene memorizzata come UCUM, e il valore non viene mai convertito.

Un laboratorio può inviare risultati per un paziente che non ha creato?

Solo con il consenso della persona, o come organizzazione per cui il progetto agisce con X-Anpheros-Acting-As. Un progetto vede i pazienti che ha creato; tutto il resto richiede un'autorizzazione.

C'è un costo per l'integrazione?

Il sandbox è gratuito. La produzione inizia da €49 al mese per organizzazione, con il primo mese gratuito; vedere pricing.