# Provenienza dei dati medici spiegata

> Cosa registra la provenienza ad ogni scrittura su un record FHIR R4 — tipo di autore, persona, organizzazione, sistema sorgente, versioni — come impostarla con gli header, come leggerla e come etichetta i dati forniti ai modelli AI.

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

**La provenienza è il registro di dove proviene un dato medico: chi lo ha scritto, per conto di quale organizzazione, da quale sistema, quando e cosa è cambiato in ogni versione.** In un record che raccoglie dati da pazienti, dispositivi, cliniche, laboratori e AI, la provenienza è ciò che rende un valore attendibile: una lettura della pressione sanguigna digitata a casa e una misurata in clinica appaiono identiche senza di essa. In Anpheros ogni scrittura su un record HL7 FHIR R4 produce automaticamente una risorsa FHIR `Provenance`. Questa pagina spiega cosa contiene, come compilarla correttamente e come leggerla.

## Perché la provenienza è importante

- **Fiducia clinica.** Un medico valuta un risultato di laboratorio in modo diverso da un valore inserito dal paziente o da un numero estratto da un'IA da una foto.
- **Sicurezza dell'IA.** Un modello a cui viene fornito un record deve sapere quali elementi sono fatti e quali sono note scritte da un altro modello. Senza etichette li tratta allo stesso modo.
- **Correzioni e contestazioni.** Quando un valore cambia, tutti devono sapere quale era prima, chi lo ha cambiato e perché.
- **Responsabilità.** Ai sensi del GDPR e dell'European Health Data Space, un'organizzazione deve essere in grado di dimostrare cosa ha fatto con i dati sanitari di una persona.
- **Condivisione.** Quando un paziente consente a una seconda clinica di leggere il proprio record, tale clinica deve sapere quali dati ha scritto la prima clinica.

## Cosa registra Anpheros ad ogni scrittura

| Domanda | Dove viene registrato | Come lo imposti |
|---|---|---|
| Che tipo di autore? | `agent.who.identifier` (tipo di autore) | `author_type` in `/v1`, o intestazione `X-Anpheros-Author-Type`: `patient`, `practitioner`, `device`, `import`, `ai` |
| Quale persona? | `agent.who.reference` | `X-Anpheros-Author-Ref: Practitioner/<id>`, o `X-Anpheros-Acting-As` |
| Per quale organizzazione? | `agent.onBehalfOf` | l'organizzazione del `PractitionerRole`, o `X-Anpheros-On-Behalf-Of: Organization/<id>` |
| Da quale sistema? | `entity` con ruolo `source` | `X-Anpheros-Source-System: <name>` |
| Quale record in quel sistema? | id origine | `X-Anpheros-Origin-Id: <id>` |
| Quando e cosa è successo? | `recorded`, `activity` (CREATE, UPDATE, DELETE) | automatico |
| Quale versione? | `target` punta a `<Resource>/<id>/_history/<version>` | automatico |

Se non specifichi chi è l'autore, la piattaforma registra `import`. Non assume mai `patient`, perché un valore attribuito erroneamente al paziente è peggio di uno etichettato onestamente come importato.

## Scrittura con provenienza completa

Un cardiologo in una clinica registra una frequenza cardiaca durante una visita, tramite il software della clinica:

```bash
curl -X POST https://platform.anpheros.com/fhir/R4/Observation -H "Authorization: Bearer $KEY" \
     -H "Content-Type: application/fhir+json" \
     -H "X-Anpheros-Author-Type: practitioner" \
     -H "X-Anpheros-Acting-As: PractitionerRole/$ROLE" \
     -H "X-Anpheros-Source-System: ccn-emr" \
     -d '{ "resourceType": "Observation", "status": "final", "code": {"coding": [{"system": "http://loinc.org", "code": "8867-4"}]}, … }'
```

La Provenance che la piattaforma scrive:

```json
{"resourceType": "Provenance",
 "target": [{"reference": "Observation/8660eb7c-…/_history/1"}],
 "recorded": "2026-10-12T20:41:47.469000Z",
 "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": {"reference": "PractitionerRole/e6d8c227-…",
                    "identifier": {"system": "https://anpheros.com/fhir/CodeSystem/author-type", "value": "practitioner"}},
            "onBehalfOf": {"reference": "Organization/c3a56a4b-…", "display": "Clinica Cardio Nord"}}],
 "entity": [{"role": "source", "what": {"identifier": {"system": "ccn-emr"}}}]}
```

Il ruolo del medico, la sua clinica, il tipo di autore e il sistema sorgente sono tutti presenti, in FHIR standard. Il `PractitionerRole` deve esistere nella directory del tuo progetto ed essere attivo. Una richiesta che nomina il practitioner di qualcun altro viene rifiutata:

```json
{"resourceType": "OperationOutcome", "issue": [{"severity": "error", "code": "invalid",
  "diagnostics": "Unknown or inactive Practitioner in X-Anpheros-Acting-As."}]}
```

La configurazione della directory è trattata in [Come integrare i sistemi clinici con un backend FHIR](https://developers.anpheros.com/it/guides/integrate-clinic-systems-fhir).

## Versioni: nulla viene sovrascritto silenziosamente

Ogni aggiornamento crea una nuova versione della risorsa e una nuova Provenance per essa. Dopo che la frequenza cardiaca sopra indicata viene corretta da 92 a 88:

```bash
curl https://platform.anpheros.com/fhir/R4/Observation/$OBS/_history -H "Authorization: Bearer $KEY"
```

restituisce la versione 2 (88) e la versione 1 (92). La vista REST riassume la Provenance di ogni versione:

```bash
curl https://platform.anpheros.com/v1/patients/$PID/provenance/Observation/$OBS -H "Authorization: Bearer $KEY"
```

```json
{"data": [
  {"version": 1, "activity": "CREATE", "recorded": "2026-10-12T20:41:47.469000Z", "author_type": "practitioner", "author": "PractitionerRole/e6d8c227-…", "source_system": "ccn-emr", "fhir": "Provenance/6ed91529-…"},
  {"version": 2, "activity": "UPDATE", "recorded": "2026-10-12T20:41:47.500000Z", "author_type": "practitioner", "fhir": "Provenance/3fbf270f-…"}],
 "total": 2}
```

Le eliminazioni sono "soft": una risorsa eliminata scompare dalle ricerche, ma la sua cronologia e la sua Provenance rimangono.

## Lettura della provenienza

```bash
# who wrote this resource (all versions)
GET /fhir/R4/Provenance?target=Observation/{id}
# everything a practitioner recorded
GET /fhir/R4/Provenance?agent=PractitionerRole/{id}
# the same, summarised, per resource
GET /v1/patients/{pid}/provenance/Observation/{id}
```

## Provenienza in contesti AI

La [API di contesto](https://developers.anpheros.com/it/guides/llm-healthcare-data) porta la provenienza in ogni elemento che fornisce a un modello, come `author_type` e `source`. In forma testuale:

```
- Type 2 diabetes mellitus (E11), active, onset 2024-10-15 [import/anpheros-sandbox]
- Metformin 1000 mg 1 tablet twice daily with meals, active [patient/anpheros-sandbox]
- Glucose [Mass/volume] in Blood: 2026-09-16: 140.0 mg/dL [device/anpheros-sandbox]
```

Le misurazioni scritte con `author_type: ai` non compaiono mai tra questi fatti. Sono elencate separatamente sotto `ai_notes` e contrassegnate come non verificate, in modo che un modello non possa scambiare l'ipotesi di un modello precedente per una misurazione. Indicare al modello cosa significano le etichette e chiedere di citarle; [Come creare un'app sanitaria AI con un backend FHIR](https://developers.anpheros.com/it/guides/build-ai-healthcare-app) mostra un prompt che lo fa.

## Cosa vede il paziente

La Provenance è anche ciò che vede il paziente. Il suo record mostra chi ha aggiunto ogni elemento e il suo elenco di connessioni mostra, per ogni applicazione, chi ha avuto accesso a cosa, per nome quando un professionista stava agendo ("Dr. Ana Popescu · Clinica Cardio Nord ha letto i tuoi risultati di laboratorio"). Vedi [Modello di consenso e accesso](https://developers.anpheros.com/it/guides/consent).

## Regole che rendono utile la provenienza

1. **Imposta sempre il tipo di autore.** Costa un campo ed è l'etichetta più importante nel record.
2. **Indica il nome della persona quando è stata scritta da una persona.** Usa `X-Anpheros-Acting-As` per il personale clinico.
3. **Indica il nome del sistema sorgente** e passa l'ID del sistema sorgente come ID di origine quando presente.
4. **Correggi aggiornando, mai eliminando e ricreando.** Un aggiornamento mantiene il collegamento tra il valore vecchio e quello nuovo.
5. **Etichetta l'output dell'IA come `ai`**, inclusi i valori estratti da un modello da un documento. I valori derivati da un documento possono anche puntare ad esso con `derived_from`.

## Domande frequenti

### Cos'è la provenienza dei dati in ambito sanitario?
L'origine e la storia documentata di un dato sanitario: chi l'ha creato o modificato, per conto di chi, da quale sistema e quando. In HL7 FHIR è rappresentato dalla risorsa `Provenance`, che punta alla versione esatta della risorsa che descrive.

### La provenienza è la stessa di un log di audit?
No. La provenienza descrive i dati: chi ha scritto ogni versione. Un log di audit descrive l'accesso: chi ha letto o scritto cosa, quando, con quale consenso. Anpheros conserva entrambi; il paziente vede il log di accesso per ogni applicazione collegata al proprio record.

### Posso scrivere le mie risorse di Provenienza?
Anpheros ne scrive una per ogni creazione, aggiornamento ed eliminazione, quindi normalmente non è necessario. Utilizzare gli header sopra per renderla precisa. Una Provenienza fornita dal client deve essere mirata a risorse di un singolo paziente.

## Correlati

- [Modello di consenso e accesso](https://developers.anpheros.com/it/guides/consent)
- [Come integrare sistemi clinici con un backend FHIR](https://developers.anpheros.com/it/guides/integrate-clinic-systems-fhir)
- [Come normalizzare i dati medici](https://developers.anpheros.com/it/guides/normalize-medical-data)
- [Interoperabilità dei dati sanitari](https://developers.anpheros.com/it/guides/interoperability)
- [Sicurezza, privacy e residenza dei dati](https://developers.anpheros.com/it/guides/security)