Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card

Come integrare sistemi di clinica con un backend FHIR

Tutorial: collega un EMR di clinica ai fascicoli FHIR R4 dei pazienti — elenco medici, corrispondenza per numero di fascicolo, una visita come singola transazione con il medico come autore, referti di laboratorio, dati di altri fornitori e webhook.

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

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.

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:

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:

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; 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.

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:

"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.

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:

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 e API dati medici.

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:

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.

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

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: tutti i pattern di integrazione a colpo d'occhio
• Provenienza dei dati medici spiegata
• Come implementare il consenso del paziente con SMART on FHIR
• Come importare i risultati di laboratorio in un record FHIR
• Interoperabilità dei dati sanitari

Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card