# Come normalizzare i dati medici

> Tutorial: trasforma i dati medici da molte fonti in una forma comparabile — lookup LOINC, unità UCUM, date ISO, intervalli di riferimento, nessuna duplicazione al nuovo tentativo e validazione rispetto al profilo di laboratorio europeo.

Source: https://developers.anpheros.com/it/guides/normalize-medical-data

**Normalizzare i dati medici significa trasformare valori che arrivano in molte forme in una forma comparabile: lo stesso codice per lo stesso test, lo stesso sistema di unità, date in un unico formato, ogni valore con il suo intervallo di riferimento e la sua origine, e nessuna duplicazione.** Questo tutorial mostra come farlo prima che i dati raggiungano un record HL7 FHIR R4: ricerca di codici LOINC e ATC, utilizzo di unità UCUM, rifiuto di date ambigue, mantenimento degli intervalli, evitamento di duplicazioni al nuovo tentativo e verifica del risultato rispetto al profilo di laboratorio europeo. Ogni risposta mostrata proviene dall'API Anpheros.

## Perché è importante

Lo stesso risultato di HbA1c può raggiungerti come "HbA1c 6,4 %", "Emoglobina glicosilata: 6.4", "Emoglobina glicata 46 mmol/mol" o solo un codice di laboratorio che un singolo laboratorio comprende. Finché non saranno un unico codice con un'unica unità:

- un grafico dell'HbA1c del paziente nel tempo mostra tre linee non correlate;
- un avviso su "HbA1c superiore al 6,5 %" non rileva due dei valori;
- un modello AI vede quattro fatti invece di un trend;
- un altro sistema che riceve il record non è in grado di interpretarlo.

La normalizzazione appartiene al punto in cui i dati entrano nel record, una sola volta, non in ogni applicazione che li legge successivamente.

## Cosa ha un valore normalizzato

| Parte | Forma normalizzata | Esempio |
|---|---|---|
| Cosa è stato misurato | un codice da un sistema standard | LOINC `4548-4` (HbA1c), RxNorm `6809` (metformina), ICD-10 `E11` (diabete di tipo 2) |
| Il valore | un numero, o testo solo quando il risultato non è numerico | `6.4` |
| L'unità | UCUM | `%`, `mg/dL`, `mm[Hg]`, `kg` |
| Quando | una data-ora ISO 8601, con fuso orario quando l'ora è importante | `2026-10-01T07:30:00Z` |
| Intervallo normale | basso e alto, nella stessa unità | `4.0`–`5.6` |
| Sorgente | chi l'ha prodotto e da quale sistema | `import` da `labx` |
| Identità | qualcosa che rende riconoscibile una ripetizione | una chiave di idempotenza o un identificatore di sorgente |

Quale sistema di codici corrisponde a quale tipo di risorsa è elencato in [Sistemi di codici FHIR](https://developers.anpheros.com/it/guides/fhir-code-systems).

## Passo 1: Trova il codice

Cerca nella terminologia della piattaforma per nome inglese o rumeno, o per abbreviazione:

```bash
curl "https://platform.anpheros.com/v1/terminology/loinc?q=hba1c" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/terminology/loinc?q=hemoglobina%20glicozilata" -H "Authorization: Bearer $KEY"
```

Entrambi restituiscono lo stesso concetto:

```json
{"data": [{"system": "http://loinc.org", "code": "4548-4", "display": "Hemoglobin A1c/Hemoglobin.total in Blood",
           "display_ro": "Hemoglobină glicozilată (HbA1c)", "category": "laboratory", "unit": "%"}], "total": 1}
```

Per i farmaci, [Anpheros Search](https://developers.anpheros.com/it/guides/anpheros-search) trova la sostanza per nome o marchio e fornisce il suo codice ingrediente RxNorm e i numeri di prodotto EMA:

```bash
curl "https://platform.anpheros.com/v1/search?q=metformin&type=treatment" -H "Authorization: Bearer $KEY"
```

Il campo `unit` è l'unità che LOINC si aspetta per quel test. Usalo per verificare ciò che hai ricevuto. Costruisci la mappatura dai nomi propri di ciascuna sorgente ai codici una volta, per sorgente, e conservala nella tua integrazione. Non indovinare al momento della scrittura: quando un nome è ambiguo e nulla nella sorgente lo risolve, lascialo non mappato e chiedi alla sorgente. [Come importare i risultati di laboratorio in un record FHIR](https://developers.anpheros.com/it/guides/import-lab-results-fhir) mostra come i marcatori di laboratorio non mappati vengono conservati e segnalati.

## Passo 2: scrivere con codici, unità e intervalli

```bash
curl -X POST "https://platform.anpheros.com/v1/patients/$PID/observations" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: application/json" -H "Idempotency-Key: lab-77-hba1c" -d '{
  "code": "4548-4", "category": "laboratory",
  "value": 6.4, "unit": "%", "effective_at": "2026-10-01T07:30:00Z",
  "reference_range": {"low": 4.0, "high": 5.6},
  "author_type": "import"
}'
```

```json
{"id": "3296315c-…", "code": "4548-4", "system": "http://loinc.org", "display": "Hemoglobin A1c/Hemoglobin.total in Blood",
 "category": "laboratory", "effective_at": "2026-10-01T07:30:00Z", "value": 6.4, "unit": "%",
 "reference_range": {"low": 4.0, "high": 5.6}, "status": "final", "fhir": "Observation/3296315c-…"}
```

Quando invii solo il codice, la piattaforma compila il nome LOINC standard, sia sull'API REST che sull'API FHIR (`/fhir/R4`), in modo che ogni applicazione legga lo stesso `display`. Un `display` che invii tu stesso viene mantenuto così com'è.

Mantieni anche la formulazione originale. Per un referto di laboratorio, `code.text` sull'Osservazione FHIR contiene il nome del laboratorio ("Emoglobina glicata (HbA1c)") accanto alla codifica LOINC. Il paziente riconosce ancora il proprio referto cartaceo e nulla viene perso se la mappatura dovesse mai essere messa in discussione.

## Step 3: unità

Utilizzare i codici UCUM: `mg/dL`, `mmol/L`, `%`, `mm[Hg]`, `kg`, `cm`, `/min`, `Cel`. Due regole prevengono la maggior parte degli errori:

- **Non convertire silenziosamente.** Se un laboratorio riporta il glucosio in `mmol/L` e la tua app visualizza `mg/dL`, memorizza ciò che il laboratorio ha misurato e converti quando lo visualizzi. Il valore memorizzato rimane tracciabile al report.
- **Verificare l'unità rispetto al codice.** I codici LOINC sono specifici: HbA1c in `%` è `4548-4`, mentre HbA1c in `mmol/mol` è un codice LOINC diverso. Un valore la cui unità non corrisponde all'unità attesa dal codice è un errore di mappatura, non un problema di conversione.

Anpheros non converte le unità per te; memorizza l'unità che invii.

## Passaggio 4: date

Convertire le date in formato ISO 8601 prima di scriverle, utilizzando il formato noto della sorgente. `01.10.2026` è il 1° ottobre in Romania e in molti paesi europei, ma `10/01/2026` è il 1° ottobre solo negli Stati Uniti. L'API rifiuta tutto ciò che non è in formato ISO, piuttosto che tentare di indovinare:

```json
{"error": {"type": "invalid", "message": "Input should be a valid datetime or date, invalid character in year (at effective_at)", "field": "effective_at"}}
```

Il connettore di laboratorio fa eccezione: accetta `DD.MM.YYYY` e `DD/MM/YYYY` perché sa che sta leggendo un report europeo.

Per le misurazioni in cui l'ora del giorno è importante (pressione sanguigna, glucosio, dosi di farmaci), inviare l'ora con il suo fuso orario. Una lettura alle 23:30 a Bucarest è del giorno precedente in UTC, e il paziente si aspetta che venga registrata nel giorno in cui l'ha effettuata.

## Passo 5: nessun duplicato

I duplicati derivano da ritentativi, dall'invio dello stesso report due volte e dallo stesso valore che arriva attraverso due percorsi.

- **Ritentativi:** invia un `Idempotency-Key` che identifica il valore nella sorgente, ad esempio l'ID del report e il test. L'invio della stessa richiesta nuovamente con la stessa chiave restituisce la prima risposta e non memorizza nulla di nuovo. Gli SDK aggiungono uno a ogni creazione.
- **Lo stesso report due volte:** il connettore di laboratorio costruisce un identificatore stabile per riga dal report, codice, data e valore, e salta le righe già importate.
- **Due percorsi:** memorizza l'ID proprio del sistema sorgente con `X-Anpheros-Origin-Id` (o in `identifier` sulle risorse FHIR), e cerca questo ID prima di scrivere valori che potrebbero tornare attraverso un altro percorso.

## Passaggio 6: verifica rispetto a un profilo

Per i risultati di laboratorio, chiedi alla piattaforma come una risorsa si confronta con il profilo del report di laboratorio HL7 Europe prima di potersi fidare di essa:

```bash
curl -X POST "https://platform.anpheros.com/fhir/R4/Observation/\$validate?profile=eu-lab" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: application/fhir+json" -d '{
  "resourceType": "Observation", "status": "final",
  "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "laboratory"}]}],
  "code": {"text": "HbA1c"}, "subject": {"reference": "Patient/'$PID'"},
  "valueQuantity": {"value": 6.4, "unit": "%"}
}'
```

Questo risultato non normalizzato ottiene un elenco preciso:

```json
{"resourceType": "OperationOutcome", "issue": [
  {"severity": "error", "code": "invalid", "diagnostics": "Observation.code must carry a LOINC coding.", "expression": ["Observation.code"]},
  {"severity": "error", "code": "required", "diagnostics": "Observation.effective[x] is required.", "expression": ["Observation.effective"]},
  {"severity": "warning", "code": "business-rule", "diagnostics": "valueQuantity should carry a UCUM system and code.", "expression": ["Observation.valueQuantity"]},
  {"severity": "warning", "code": "informational", "diagnostics": "No referenceRange: interpretation will need the laboratory's ranges.", "expression": ["Observation.referenceRange"]},
  {"severity": "information", "code": "informational", "diagnostics": "No performer (laboratory) recorded.", "expression": ["Observation.performer"]},
  {"severity": "information", "code": "informational", "diagnostics": "No issued time (when the laboratory released the result).", "expression": ["Observation.issued"]}]}
```

Ogni problema corrisponde a uno dei passaggi precedenti. Esegui `$validate` nei tuoi test di integrazione, con campioni reali da ciascuna origine.

## Passaggio 7: mantenere la sorgente

La normalizzazione modifica il modo in cui un valore viene scritto, mai da dove proviene. Inviare `author_type` (`device`, `import`, `practitioner`, `patient`) e `X-Anpheros-Source-System` con ogni scrittura. Questo è ciò che consente a un medico, a un revisore o a un modello di intelligenza artificiale di distinguere un risultato di laboratorio da un valore digitato a casa. Vedere [Provenienza dei dati medici spiegata](https://developers.anpheros.com/it/guides/medical-data-provenance).

## Checklist

- [ ] Ogni sorgente ha una mappatura dai propri nomi a LOINC / ATC / ICD-10, mantenuta nella tua integrazione
- [ ] I nomi ambigui rimangono non mappati e vengono segnalati, mai indovinati
- [ ] Unità UCUM, corrispondenti al codice; nessuna conversione silenziosa
- [ ] Date ISO 8601, con fusi orari dove il tempo è importante
- [ ] Intervalli di riferimento mantenuti con i valori di laboratorio
- [ ] Formulazione originale mantenuta (`code.text`)
- [ ] Chiavi di idempotenza o ID sorgente su ogni scrittura
- [ ] `author_type` e sistema sorgente su ogni scrittura
- [ ] `$validate` nei test per i risultati di laboratorio

## Domande frequenti

### Cos'è la normalizzazione dei dati medici?
Conversione dei dati sanitari da diverse fonti in un'unica forma standard: codici condivisi (LOINC per test e misurazioni, ICD-10 per diagnosi, ATC per farmaci), unità UCUM, date ISO, intervalli di riferimento e una sorgente registrata, in modo che i valori di diversi sistemi possano essere confrontati, combinati e scambiati.

### Devo convertire tutti i valori in una sola unità?
Memorizza l'unità in cui la sorgente ha misurato, purché sia un'unità UCUM valida che corrisponda al codice, e converti durante la visualizzazione o l'analisi. Questo mantiene ogni valore memorizzato tracciabile al suo report originale.

### La normalizzazione può essere completamente automatica?
Per lo più. I codici nella sorgente, i nomi noti e le unità ben formate possono essere mappati automaticamente. Nomi ambigui e codici locali sconosciuti richiedono una decisione umana una volta per sorgente, dopodiché la mappatura è automatica.

## Correlati

- [Sistemi di codifica FHIR](https://developers.anpheros.com/it/guides/fhir-code-systems)
- [Come importare i risultati di laboratorio in un record FHIR](https://developers.anpheros.com/it/guides/import-lab-results-fhir)
- [Provenienza dei dati medici spiegata](https://developers.anpheros.com/it/guides/medical-data-provenance)
- [Interoperabilità dei dati sanitari](https://developers.anpheros.com/it/guides/interoperability)
- [API per dati medici](https://developers.anpheros.com/it/guides/medical-data-api)