# Come integrare i sistemi clinici con un backend FHIR

> Tutorial: collega un EMR clinico ai record FHIR R4 dei pazienti — directory dei medici, corrispondenza per numero di record, una visita come una transazione con il medico come autore, referti di laboratorio, dati di altri fornitori e webhook.

Source: https://developers.anpheros.com/it/guides/integrate-clinic-systems-fhir

**Questo tutorial collega il software di una clinica (un EMR, un sistema di gestione dello studio o uno strumento di prenotazione) ai record HL7 FHIR R4 dei pazienti in Anpheros: la clinica e i suoi medici sono registrati nella directory, i pazienti vengono abbinati tramite il numero di record della clinica, una visita viene registrata come una transazione con il medico indicato come autore e la clinica viene informata sui dati aggiunti da altri fornitori.** Ogni richiesta viene `curl` contro la sandbox gratuita e le risposte sono quelle della piattaforma.

L'integrazione viene eseguita sul server della clinica, con una chiave API di progetto per i pazienti che la clinica registra e, per le persone che hanno già un record Anpheros, una concessione OAuth che approvano.

## Cosa corrisponde a cosa

| Nel sistema clinico | In FHIR R4 |
|---|---|
| la clinica, i suoi reparti | `Organization` |
| un medico o un infermiere | `Practitioner` |
| quella persona che lavora in quella clinica, con una specializzazione | `PractitionerRole` |
| la cartella clinica e il suo numero | `Patient` con un `identifier` nel sistema della clinica |
| una visita | `Encounter` |
| parametri vitali, risultati misurati durante la visita | `Observation` collegati al `Encounter` |
| una diagnosi | `Condition` (ICD-10), con `verificationStatus` provvisoria o confermata |
| una prescrizione, trattamento corrente | `MedicationStatement` (ATC) |
| una lettera, una lettera di dimissioni, una scansione | `DocumentReference` con il file |
| risultati di laboratorio | il [connettore di laboratorio](https://developers.anpheros.com/it/guides/lab-connector), in `Observation` |

## Passaggio 1: registrare la clinica e i suoi medici

Le risorse della directory non hanno pazienti. Altri progetti nello stesso ambiente possono leggerle, in modo che gli altri fornitori di un paziente vedano chi ha scritto cosa, ma solo il tuo progetto può modificarle.

```bash
export BASE=https://platform.anpheros.com/fhir/R4
export KEY=sk_test_…
H=(-H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json")

curl -X POST $BASE/Organization "${H[@]}" -d '{"resourceType": "Organization", "active": true, "name": "Clinica Cardio Nord",
  "identifier": [{"system": "https://clinic.example/org", "value": "CCN"}]}'

curl -X POST $BASE/Practitioner "${H[@]}" -d '{"resourceType": "Practitioner", "active": true,
  "name": [{"family": "Popescu", "given": ["Ana"], "prefix": ["Dr."]}]}'

curl -X POST $BASE/PractitionerRole "${H[@]}" -d '{"resourceType": "PractitionerRole", "active": true,
  "practitioner": {"reference": "Practitioner/'$PRACTITIONER'"},
  "organization": {"reference": "Organization/'$ORG'"},
  "code": [{"text": "Cardiologist"}]}'
```

Conserva gli ID restituiti accanto ai record del tuo personale. Quando qualcuno lascia, imposta il suo `PractitionerRole` su `"active": false`; le sue scritture passate mantengono il suo nome e non potrà più agire tramite il tuo sistema.

## Passaggio 2: corrispondenza pazienti

Per i pazienti che la clinica registra, crea il `Patient` con il numero di record della clinica come identificatore:

```bash
curl -X POST $BASE/Patient "${H[@]}" -d '{"resourceType": "Patient",
  "identifier": [{"system": "https://clinic.example/mrn", "value": "MRN-20981"}],
  "name": [{"family": "Dinu", "given": ["Andrei"]}], "gender": "male", "birthDate": "1968-11-05"}'
```

Da quel momento in poi, trova il paziente tramite quel numero, mai per nome e data di nascita:

```bash
curl "$BASE/Patient?identifier=https://clinic.example/mrn|MRN-20981" -H "Authorization: Bearer $KEY"
```

**Quando la persona ha già un record Anpheros**, dalla propria app o da un altro fornitore, la clinica non ne crea un secondo. Chiede alla persona l'accesso con OAuth, da un tablet alla reception o tramite un link inviato prima della visita, utilizzando un'applicazione **confidenziale** (il server della clinica conserva il segreto). La persona sceglie il proprio record e per quanto tempo la clinica può accedervi. I passaggi sono descritti in [Come implementare il consenso del paziente con SMART on FHIR](https://developers.anpheros.com/it/guides/smart-on-fhir-backend); il campo `patient` del token è l'id da memorizzare con il tuo file.

## Passaggio 3: scrivere una visita come una transazione

Una visita produce diverse risorse che appartengono insieme. Inviale in una `transaction` in modo che vengano archiviate tutte in una volta o nessuna, e indica chi sta lavorando: `X-Anpheros-Acting-As` nomina il ruolo del medico. Diventa l'autore in Provenance, viene scritto nel log di accesso e viene mostrato al paziente per nome.

```bash
curl -X POST $BASE "${H[@]}" \
  -H "X-Anpheros-Acting-As: PractitionerRole/$ROLE" \
  -H "X-Anpheros-Author-Type: practitioner" \
  -H "X-Anpheros-Source-System: ccn-emr" -d '{
  "resourceType": "Bundle", "type": "transaction",
  "entry": [
    {"fullUrl": "urn:uuid:aa000000-0000-4000-8000-000000000001",
     "resource": {"resourceType": "Encounter", "status": "finished",
       "class": {"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "AMB", "display": "ambulatory"},
       "subject": {"reference": "Patient/'$PID'"},
       "serviceProvider": {"reference": "Organization/'$ORG'"},
       "participant": [{"individual": {"reference": "PractitionerRole/'$ROLE'"}}],
       "period": {"start": "2026-10-09T10:00:00Z", "end": "2026-10-09T10:30:00Z"}},
     "request": {"method": "POST", "url": "Encounter"}},
    {"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": "8867-4", "display": "Heart rate"}]},
       "subject": {"reference": "Patient/'$PID'"},
       "encounter": {"reference": "urn:uuid:aa000000-0000-4000-8000-000000000001"},
       "effectiveDateTime": "2026-10-09T10:10:00Z",
       "valueQuantity": {"value": 92, "unit": "/min", "system": "http://unitsofmeasure.org", "code": "/min"}},
     "request": {"method": "POST", "url": "Observation"}},
    {"resource": {"resourceType": "Condition",
       "subject": {"reference": "Patient/'$PID'"},
       "encounter": {"reference": "urn:uuid:aa000000-0000-4000-8000-000000000001"},
       "clinicalStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-clinical", "code": "active"}]},
       "verificationStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-ver-status", "code": "provisional"}]},
       "code": {"coding": [{"system": "http://hl7.org/fhir/sid/icd-10", "code": "I48.0", "display": "Paroxysmal atrial fibrillation"}]}},
     "request": {"method": "POST", "url": "Condition"}}
  ]}'
```

Il `transaction-response` ha `201 Created` per l'Encounter, l'Observation e la Condition. L'Observation e la Condition ora puntano al vero `Encounter/0ca25459-…`. La Provenance di ciascuno nomina il ruolo del medico, la clinica e il sistema sorgente:

```json
"agent": [{"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"}}}]
```

La diagnosi è `provisional` finché non viene confermata. Aggiornala a `confirmed` in seguito, e la cronologia conserva entrambe. Cosa significa ogni campo è spiegato in [Provenienza dei dati medici spiegata](https://developers.anpheros.com/it/guides/medical-data-provenance).

## Passaggio 4: risultati di laboratorio e documenti

I risultati del laboratorio interno della clinica, o i referti che il paziente porta con sé, passano attraverso il connettore di laboratorio in una richiesta per referto:

```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 "X-Anpheros-Source-System: ccn-lab" --data-binary @oru.hl7
```

Lettere e lettere di dimissione sono documenti: creare un `DocumentReference` tramite `/v1/patients/{id}/documents` e caricare il PDF. Il file originale non viene mai modificato e i valori estratti da esso vi puntano. Vedere [Come importare i risultati di laboratorio in un record FHIR](https://developers.anpheros.com/it/guides/import-lab-results-fhir) e [API dati medici](https://developers.anpheros.com/it/guides/medical-data-api).

## Passaggio 5: leggi ciò che altri provider hanno scritto e rimani nella tua corsia

Con il consenso del paziente, la clinica legge l'intero record all'interno dei propri ambiti, incluse le informazioni aggiunte da altre cliniche, laboratori e dal paziente. Può modificare solo ciò che ha scritto autonomamente. Un aggiornamento o una cancellazione di una risorsa di un'altra organizzazione risponde `403`, e l'originale rimane invariato. Per correggere qualcosa scritto da un altro provider, scrivi la tua risorsa (ad esempio, un nuovo `Condition` con la tua valutazione) e lascia che il record mostri entrambe, ognuna con il proprio autore.

Prima di una visita, `GET $BASE/Patient/$PID/$summary` fornisce il Riepilogo Internazionale del Paziente (International Patient Summary) del record: problemi, farmaci, allergie e segni vitali recenti, da ogni fonte.

## Passo 6: Ricevere notifiche sui nuovi dati

Registra un webhook una sola volta per il progetto della clinica:

```bash
curl -X POST https://platform.anpheros.com/v1/webhooks -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
     -d '{"url": "https://ccn.example/anpheros/hook", "events": ["resource.created", "resource.updated", "consent.revoked"]}'
```

Quando un altro progetto scrive in un record a cui la tua clinica può accedere, l'evento lo comunica con `data.external: true` e la sorgente, in modo che il tuo EMR possa mostrare "nuovi risultati da un altro laboratorio" senza effettuare polling. Un evento `consent.revoked` significa che la persona ha ritirato l'accesso della clinica: interrompi la sincronizzazione di quel record. Firme, tentativi e payload sono trattati in [Webhooks](https://developers.anpheros.com/it/guides/webhooks).

## Cosa vede il paziente

Il paziente vede la visita, la frequenza cardiaca e la diagnosi provvisoria nel proprio record, ognuno contrassegnato come aggiunto dalla Dott.ssa Ana Popescu presso la Clinica Cardio Nord. Nelle proprie connessioni, l'applicazione della clinica elenca ogni accesso, per nome quando un professionista stava agendo. Questa trasparenza è ciò che rende i pazienti disposti a concedere l'accesso alla clinica successiva.

## Checklist per il rilascio

- [ ] Organizzazioni, Medici e Ruoli Medici registrati; i dipendenti in uscita impostati su inattivi
- [ ] Pazienti abbinati tramite l'identificatore della clinica, mai per nome
- [ ] Record esistenti raggiunti tramite consenso OAuth, non duplicati
- [ ] Ogni richiesta dal personale clinico trasporta `X-Anpheros-Acting-As`
- [ ] Visite scritte come transazioni; diagnosi con lo stato di verifica corretto
- [ ] Sistema di origine impostato su ogni scrittura; referti di laboratorio tramite il connettore
- [ ] Endpoint webhook che verifica le firme; `consent.revoked` gestito
- [ ] Progetto di produzione con un DPA firmato (chiavi `sk_live_…`); vedere [Prezzi](https://developers.anpheros.com/it/guides/pricing)

## Domande frequenti

### Anpheros dispone di un connettore pronto all'uso per il mio EMR?
No. Non esistono connettori pronti all'uso per specifici EMR o sistemi di laboratorio; l'integrazione viene creata contro le API FHIR R4 e REST, solitamente come un piccolo servizio accanto all'EMR. I messaggi di laboratorio HL7 v2 vengono accettati così come sono.

### Un medico può lavorare per due cliniche?
Sì. Un `Practitioner` può avere una `PractitionerRole` presso ciascuna organizzazione. Il ruolo indicato in `X-Anpheros-Acting-As` decide per quale clinica viene registrata ciascuna scrittura.

### Cosa succede quando il paziente revoca l'accesso alla clinica?
Le chiamate della clinica per quel record rispondono `401` e viene inviato un webhook `consent.revoked`. Ciò che la clinica ha scritto rimane nel record del paziente con la sua provenienza; la clinica semplicemente non può più leggerlo o modificarlo.

## Correlati

- [Integrazioni sanitarie](https://developers.anpheros.com/it/guides/healthcare-integrations): tutti i pattern di integrazione a colpo d'occhio
- [Provenienza dei dati medici spiegata](https://developers.anpheros.com/it/guides/medical-data-provenance)
- [Come implementare il consenso del paziente con SMART on FHIR](https://developers.anpheros.com/it/guides/smart-on-fhir-backend)
- [Come importare i risultati di laboratorio in un record FHIR](https://developers.anpheros.com/it/guides/import-lab-results-fhir)
- [Interoperabilità dei dati sanitari](https://developers.anpheros.com/it/guides/interoperability)