# Mappatura da HL7 v2 a FHIR

> Mappatura da segmento a risorsa e da campo OBX a campo da HL7 v2 ORU^R01 a FHIR R4, le insidie che interrompono le integrazioni e un convertitore che si chiama tramite HTTPS.

Source: https://developers.anpheros.com/it/guides/hl7-v2-to-fhir-mapping

**Mappare HL7 v2 a FHIR significa trasformare ogni segmento di un messaggio v2 delimitato da pipe in risorse FHIR R4: PID in un Patient, OBR in un DiagnosticReport (o ServiceRequest), ogni OBX in un Observation, con codici, unità, intervalli e tempi trasferiti campo per campo.** HL7 pubblica una [guida all'implementazione V2-to-FHIR](https://hl7.org/fhir/uv/v2mappings/) ufficiale con mappe concettuali per i segmenti comuni. Questa pagina fornisce la mappatura pratica per i risultati di laboratorio (ORU^R01), le insidie che interrompono le integrazioni reali e un convertitore che è possibile chiamare tramite HTTPS: l'Anpheros lab connector.

<!-- visual:v2map-flow -->

## Segment to resource

| HL7 v2 segment | Cosa trasporta | FHIR R4 resource | Nel connettore di laboratorio Anpheros |
|---|---|---|---|
| MSH | Separatori, sistema mittente, tipo messaggio, ID messaggio | `MessageHeader` (o provenance) | Separatori letti da MSH; tipo controllato per ORU^R01; ID messaggio conservato per tracciabilità |
| PID | Identificatori paziente, nome, data di nascita, sesso | `Patient` | Non utilizzato: il paziente è quello nell'URL della richiesta, quindi un messaggio non può scrivere nel record sbagliato |
| PV1 | Visita | `Encounter` | Non utilizzato |
| ORC / OBR | Ordine e referto: filler/placer id, data | `ServiceRequest`, `DiagnosticReport` | OBR-3 (o OBR-2) è l'ID del referto, OBR-7 la data predefinita |
| OBX | Un risultato | `Observation` | Una Observation di laboratorio per OBX |
| NTE | Nota di testo libero | `Observation.note` | Non utilizzato |

## Campo OBX per campo

| Campo OBX | Elemento FHIR Observation | Note |
|---|---|---|
| Tipo di valore campo OBX-2 (NM, SN, ST, CWE) | choice of `value[x]` | NM e SN diventano `valueQuantity`; il testo rimane testo |
| Identificatore campo OBX-3 `code^text^system` | `code.coding` | `LN` in OBX-3.3 significa LOINC; altri sistemi sono il codice locale del laboratorio |
| Valore campo OBX-5, unità campo OBX-6 | `valueQuantity.value`, `.unit` / `.code` (UCUM) | `<5` e `6,4` devono essere analizzati deliberatamente |
| Intervallo di riferimento campo OBX-7 | `referenceRange.low` / `.high` | `3.5-5.1`, `<200`, `>40` |
| Flag anomalo campo OBX-8 | `interpretation` | H, L, HH, LL, A, N |
| Stato del risultato campo OBX-11 | `status` | F → finale, C → modificato, P → preliminare, I → registrato |
| Ora dell'osservazione campo OBX-14 | `effectiveDateTime` | gli orari v2 spesso mancano di fuso orario; FHIR ne richiede uno |

## Convertire un messaggio con una richiesta

```bash
curl -X POST "https://platform.anpheros.com/v1/patients/$PID/labs/import" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: x-application/hl7-v2+er7" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-binary @oru_r01.hl7
```

La risposta elenca quante Observations sono state create, quante sono state saltate perché già importate, quali marcatori non hanno potuto essere mappati e le nuove Observations con i loro codici. Ognuna ottiene un identificatore stabile derivato dal report, dal test, dall'ora e dal valore, in modo che un laboratorio che reinvia lo stesso messaggio non crei duplicati.

## Trappole che interrompono le integrazioni reali

1. **Fusi orari.** `20261002074500` non ha offset; decidi esplicitamente il fuso orario del mittente.
2. **Codici locali.** Conserva il codice proprio del laboratorio quando non esiste un LOINC; non eliminarlo mai.
3. **Rinvii.** Senza un identificatore stabile per risultato, i tentativi diventano duplicati.
4. **Correzioni.** OBX-11 `C` è una correzione; decidi se sostituisce o aggiunge, e contrassegna il vecchio risultato.
5. **Valori non numerici.** `positive`, `<5`, `6,4` necessitano di regole esplicite, non di un'ipotesi.

## Cosa non fa il connettore

Accetta risultati di laboratorio ORU^R01 tramite HTTPS. Non riceve messaggi ADT o di ordine, non utilizza MLLP su TCP (un engine di interfaccia frontale può inoltrare), non crea un DiagnosticReport e non associa pazienti da PID.

## Domande frequenti

### Come si mappa HL7 v2 a FHIR?
Segmento per segmento: PID a Patient, PV1 a Encounter, ORC/OBR a ServiceRequest e DiagnosticReport, OBX a Observation, NTE a notes. La guida all'implementazione V2-to-FHIR di HL7 definisce le mappature concettuali a livello di campo.

### Esiste un convertitore da HL7 v2 a FHIR?
Sì. Motori di interfaccia e librerie open-source convertono i messaggi; per i risultati di laboratorio, il connettore di laboratorio Anpheros converte un messaggio ORU^R01 in FHIR R4 Observations in una singola richiesta HTTPS e li memorizza nel record del paziente.

### Quali tipi di messaggi HL7 v2 accetta Anpheros?
ORU^R01 risultati di laboratorio. Un messaggio di altro tipo genera un avviso e vengono letti solo i suoi segmenti OBX; ADT, ordini e altri messaggi non sono supportati.

### Come vengono rappresentate le flag anomale di HL7 v2 in FHIR?
OBX-8 diventa `Observation.interpretation` utilizzando i codici HL7 ObservationInterpretation (H, L, HH, LL, A, N).

<!-- visual:cta-v2map -->

## Correlati

- [API per i risultati di laboratorio: HL7 v2, FHIR e LOINC](https://developers.anpheros.com/it/guides/lab-results-api)
- [FHIR vs HL7 v2: differenze pratiche](https://developers.anpheros.com/it/guides/fhir-vs-hl7-v2)
- [Come importare i risultati di laboratorio in un record FHIR](https://developers.anpheros.com/it/guides/import-lab-results-fhir)
- [HL7 v2 e FHIR per dashboard clinici](https://developers.anpheros.com/it/guides/clinical-dashboard-hl7-fhir)
- [Connettore di laboratorio](https://developers.anpheros.com/it/guides/lab-connector)