# Come archiviare cartelle cliniche utilizzando FHIR R4

> Tutorial: crea un Paziente, un'Osservazione della pressione sanguigna e una Condizione, usa una transazione, cerca, aggiorna con cronologia e leggi la provenienza — ogni richiesta con curl e la risposta reale, sul sandbox gratuito.

Source: https://developers.anpheros.com/it/guides/store-medical-records-fhir

**Questo tutorial archivia una piccola cartella clinica come risorse HL7 FHIR R4: un `Patient`, una `Observation` della pressione sanguigna e una diagnosi come `Condition`, quindi un paziente e una misurazione insieme in un'unica transazione. Li cerca, aggiorna la diagnosi senza perdere la versione precedente e legge chi ha scritto cosa.** Ogni richiesta è in `curl` semplice contro il sandbox gratuito Anpheros, e ogni risposta mostrata è ciò che l'API restituisce.

Se sei nuovo a FHIR, leggi prima [FHIR platform](https://developers.anpheros.com/it/guides/fhir) per i concetti. Questa pagina è la parte pratica.

## Le tre risorse con cui iniziano la maggior parte dei record

| Risorsa | Cosa contiene | Codificata con |
|---|---|---|
| `Patient` | chi riguarda il record: nome, data di nascita, genere, identificatori da altri sistemi | i tuoi sistemi di identificazione |
| `Observation` | qualsiasi cosa misurata o riportata: segni vitali, risultati di laboratorio, un peso, un punteggio di sintomi | unità LOINC, UCUM |
| `Condition` | una diagnosi o un problema di salute, con il suo stato nel tempo | ICD-10 (SNOMED CT dietro un flag di licenza) |

Farmaci (`MedicationStatement`), allergie (`AllergyIntolerance`), immunizzazioni e documenti seguono lo stesso schema; i [26 tipi di risorse supportati](https://developers.anpheros.com/it/guides/fhir) sono elencati nella dichiarazione di capacità a `/fhir/R4/metadata`.

## Prima di iniziare

Ottieni una chiave sandbox (`sk_test_…`) su [platform.anpheros.com/dashboard](https://platform.anpheros.com/dashboard/) con **Get a sandbox key**. Nulla di ciò che crei lì sono dati reali di pazienti e nulla è visibile ad altri progetti.

```bash
export BASE=https://platform.anpheros.com/fhir/R4
export KEY=sk_test_…
```

## Step 1: Creare un Paziente

```bash
curl -X POST "$BASE/Patient" -H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json" -d '{
  "resourceType": "Patient",
  "identifier": [{"system": "https://clinic.example/mrn", "value": "MRN-10442"}],
  "name": [{"family": "Marin", "given": ["Ioana"]}],
  "gender": "female",
  "birthDate": "1979-04-12"
}'
```

`201 Created`, con l'id e la versione assegnati dal server:

```json
{"resourceType": "Patient",
 "identifier": [{"system": "https://clinic.example/mrn", "value": "MRN-10442"}],
 "name": [{"family": "Marin", "given": ["Ioana"]}], "gender": "female", "birthDate": "1979-04-12",
 "id": "d09e3942-ed86-4458-b099-fa674ab21b84",
 "meta": {"versionId": "1", "lastUpdated": "2026-10-12T20:16:51.043Z"}}
```

Mantieni i tuoi ID in `identifier` con un `system` che controlli (qui un numero di cartella clinica), in modo da poter sempre ritrovare il paziente con `GET $BASE/Patient?identifier=https://clinic.example/mrn|MRN-10442`. Il `id` FHIR è quello della piattaforma ed è specifico per il tuo progetto: un altro progetto vedrà la stessa persona con un ID diverso.

```bash
export PID=d09e3942-ed86-4458-b099-fa674ab21b84
```

## Passaggio 2: memorizzare una misurazione come Osservazione

La pressione sanguigna è un'osservazione con due componenti, sistolica e diastolica, ognuna con il proprio codice LOINC. Indica chi l'ha misurata: qui un dispositivo domestico.

```bash
curl -X POST "$BASE/Observation" -H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json" \
     -H "X-Anpheros-Author-Type: device" -H "Idempotency-Key: bp-2026-10-10-0830" -d '{
  "resourceType": "Observation",
  "status": "final",
  "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "vital-signs"}]}],
  "code": {"coding": [{"system": "http://loinc.org", "code": "85354-9", "display": "Blood pressure panel"}]},
  "subject": {"reference": "Patient/'$PID'"},
  "effectiveDateTime": "2026-10-10T08:30:00Z",
  "component": [
    {"code": {"coding": [{"system": "http://loinc.org", "code": "8480-6"}]},
     "valueQuantity": {"value": 138, "unit": "mmHg", "system": "http://unitsofmeasure.org", "code": "mm[Hg]"}},
    {"code": {"coding": [{"system": "http://loinc.org", "code": "8462-4"}]},
     "valueQuantity": {"value": 88, "unit": "mmHg", "system": "http://unitsofmeasure.org", "code": "mm[Hg]"}}
  ]
}'
```

La risposta è la risorsa memorizzata con `id` e `meta.versionId: "1"`. Tre dettagli sono importanti per un record utilizzabile:

- **Codici, non etichette.** `85354-9` significa "pannello pressione sanguigna" in ogni sistema FHIR; un testo libero "BP" no. Cerca i codici con `GET /v1/terminology/loinc?q=blood pressure` ([Sistemi di codici FHIR](https://developers.anpheros.com/it/guides/fhir-code-systems)).
- **Unità UCUM** (`mm[Hg]`, `kg`, `mg/dL`) in `valueQuantity.code`, in modo che i valori possano essere confrontati e convertiti.
- **`Idempotency-Key`.** Un nuovo tentativo dopo un timeout restituisce la prima risposta invece di memorizzare la lettura due volte.

I risultati di laboratorio sono la stessa risorsa con `category` `laboratory` e solitamente un `referenceRange`. Per importare interi referti di laboratorio, vedi [Come importare risultati di laboratorio in un record FHIR](https://developers.anpheros.com/it/guides/import-lab-results-fhir).

## Passaggio 3: registrare una diagnosi come Condizione

```bash
curl -X POST "$BASE/Condition" -H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json" \
     -H "X-Anpheros-Author-Type: practitioner" -d '{
  "resourceType": "Condition",
  "subject": {"reference": "Patient/'$PID'"},
  "clinicalStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-clinical", "code": "active"}]},
  "verificationStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-ver-status", "code": "confirmed"}]},
  "code": {"coding": [{"system": "http://hl7.org/fhir/sid/icd-10", "code": "I10", "display": "Essential (primary) hypertension"}]},
  "onsetDateTime": "2026-03-02"
}'
```

`clinicalStatus` (attivo, risolto, in remissione) e `verificationStatus` (confermato, provvisorio) sono separati appositamente: una diagnosi sospetta non è la stessa di una confermata, e un problema risolto fa ancora parte della storia clinica.

## Passaggio 4: creare risorse correlate in una transazione

Quando un paziente e la sua prima misurazione arrivano insieme, ad esempio da un sistema di clinica, inviali come `transaction` Bundle. O tutto viene archiviato o nulla. I riferimenti tra le nuove risorse utilizzano ID temporanei `urn:uuid:` che il server sostituisce:

```bash
curl -X POST "$BASE" -H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json" -d '{
  "resourceType": "Bundle", "type": "transaction",
  "entry": [
    {"fullUrl": "urn:uuid:9f1c0d1e-0000-4000-8000-000000000001",
     "resource": {"resourceType": "Patient", "name": [{"family": "Stan", "given": ["Mihai"]}], "gender": "male", "birthDate": "1990-02-01"},
     "request": {"method": "POST", "url": "Patient"}},
    {"resource": {"resourceType": "Observation", "status": "final",
       "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "vital-signs"}]}],
       "code": {"coding": [{"system": "http://loinc.org", "code": "29463-7", "display": "Body weight"}]},
       "subject": {"reference": "urn:uuid:9f1c0d1e-0000-4000-8000-000000000001"},
       "effectiveDateTime": "2026-10-10",
       "valueQuantity": {"value": 82.4, "unit": "kg", "system": "http://unitsofmeasure.org", "code": "kg"}},
     "request": {"method": "POST", "url": "Observation"}}
  ]
}'
```

Il `transaction-response` ha una voce per risorsa, con `"status": "201 Created"`, il suo `location` e la risorsa archiviata. Il `subject` dell'Observation ora punta al vero `Patient/fad3665a-…`.

## Step 5: ricerca

```bash
curl "$BASE/Observation?patient=$PID&code=http://loinc.org|85354-9&date=ge2026-10-01&_sort=-date" \
     -H "Authorization: Bearer $KEY"
```

Si ottiene un `searchset` Bundle con `total` e le risorse corrispondenti, in ordine cronologico inverso. Altre ricerche che userai spesso: `Condition?patient=$PID&clinical-status=active`, `Observation?patient=$PID&category=laboratory` e `Patient/$PID/$everything` per l'intero record.

## Passo 6: aggiornare senza perdere la cronologia

L'ipertensione si risolve. Modifica lo stato e aggiungi la data di fine, e usa `If-Match` con la versione che hai letto per non sovrascrivere mai le modifiche di qualcun altro:

```bash
curl -X PUT "$BASE/Condition/$CID" -H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json" \
     -H 'If-Match: W/"1"' -d '{ …the same Condition…, "clinicalStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-clinical", "code": "resolved"}]}, "abatementDateTime": "2026-10-11" }'
```

`200 OK` con `ETag: W/"2"`. Se un'altra scrittura è arrivata prima, otterrai `412` e dovrai rileggere. La versione precedente è ancora lì:

```bash
curl "$BASE/Condition/$CID/_history" -H "Authorization: Bearer $KEY"
```

restituisce entrambe le versioni: `versionId` 2 (`resolved`) e 1 (`active`). `GET $BASE/Condition/$CID/_history/1` legge quella vecchia. Nulla in un record viene sovrascritto silenziosamente.

## Passaggio 7: vedere chi ha scritto cosa

Ogni scrittura crea una risorsa `Provenance`. Per la lettura della pressione sanguigna:

```bash
curl "$BASE/Provenance?target=Observation/$OBS" -H "Authorization: Bearer $KEY"
```

```json
{"resourceType": "Provenance",
 "target": [{"reference": "Observation/d83d9075-…/_history/1"}],
 "recorded": "2026-10-12T20:16:51.056000Z",
 "activity": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v3-DataOperation", "code": "CREATE"}]},
 "agent": [{"type": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type", "code": "author"}]},
            "who": {"identifier": {"system": "https://anpheros.com/fhir/CodeSystem/author-type", "value": "device"}, "display": "proj_…"},
            "onBehalfOf": {"identifier": {"system": "https://anpheros.com/fhir/sid/organization", "value": "org_…"}, "display": "…"}}]}
```

Il tipo di autore che hai inviato (`device`) viene registrato con il progetto e l'organizzazione. Invia `X-Anpheros-Author-Ref: Practitioner/<id>` per nominare il clinico dietro una scrittura.

## Passaggio 8: il record come riepilogo

```bash
curl "$BASE/Patient/$PID/\$summary" -H "Authorization: Bearer $KEY"
```

restituisce un International Patient Summary: un `document` Bundle che inizia con un `Composition` e contiene sezioni quali Problemi, Farmaci, Allergie e Segni vitali, costruite dalle risorse sopra. Questo è il formato da passare a un altro sistema o stampare per un medico ([FHIR platform](https://developers.anpheros.com/it/guides/fhir)).

## Preferisci JSON senza FHIR?

Gli stessi dati sono disponibili tramite una vista REST più semplice, `/v1`, con gli stessi ID: `POST /v1/patients/{id}/observations` prende `{"code": "85354-9", "category": "vital-signs", "effective_at": "…", "components": […]}` e memorizza la stessa FHIR Observation. Usa quello che si adatta meglio al tuo codice. Vedi [Medical data API](https://developers.anpheros.com/it/guides/medical-data-api) e gli [SDK](https://developers.anpheros.com/it/guides/sdks).

## Domande frequenti

### Qual è il modo migliore per archiviare le cartelle cliniche?
Come risorse codificate e versionate con un registro di chi le ha scritte. HL7 FHIR R4 fornisce la struttura (Patient, Observation, Condition e altri), sistemi di codifica standard come LOINC e ICD-10, e la cronologia; un backend FHIR aggiunge ricerca, consenso e provenienza.

### Ho bisogno di un server FHIR per usare FHIR?
È necessario un luogo che archivi e cerchi risorse FHIR e imponga chi può leggerle. È possibile eseguire autonomamente un server FHIR open-source o utilizzarne uno gestito come Anpheros; [Come Anpheros si confronta con altri server FHIR](https://developers.anpheros.com/it/guides/fhir-server-comparison) valuta le opzioni, e [FHIR vs. un database medico personalizzato](https://developers.anpheros.com/it/guides/fhir-vs-custom-database) copre la creazione del proprio schema.

### Come archivio la pressione sanguigna in FHIR?
Come un `Observation` con codice LOINC `85354-9` e due voci `component`: sistolica `8480-6` e diastolica `8462-4`, ciascuna con un `valueQuantity` in `mm[Hg]`.

### Posso modificare una risorsa archiviata?
Sì, con `PUT` e `If-Match`. Ogni modifica crea una nuova versione; le versioni precedenti rimangono leggibili tramite `_history`, e i record di Provenienza indicano chi ha apportato ciascuna modifica. Le eliminazioni sono "soft" e mantengono la cronologia.

## Correlati

- [Piattaforma FHIR](https://developers.anpheros.com/it/guides/fhir): concetti, tipi di risorse e operazioni
- [Sistemi di codici FHIR](https://developers.anpheros.com/it/guides/fhir-code-systems): LOINC, ICD-10, ATC, UCUM
- [Come importare risultati di laboratorio in un record FHIR](https://developers.anpheros.com/it/guides/import-lab-results-fhir)
- [API dati medici](https://developers.anpheros.com/it/guides/medical-data-api): la vista REST più semplice degli stessi dati
- [Database e sandbox FHIR gratuiti](https://developers.anpheros.com/it/guides/free-fhir-database)