API per dati sanitari: cosa cercare, come leggere e scrivere una cartella clinica in un'ora

"API Sanitaria" comprende cose molto diverse: un feed HL7 v2 di un ospedale, un servizio nazionale di prescrizione elettronica, l'esportazione di un fornitore di dispositivi indossabili, un server FHIR. Se stai creando un'app sanitaria, uno strumento per cliniche o un assistente AI, ciò di cui hai bisogno è più specifico: un backend che contenga la cartella di un paziente in un formato standard, permetta al paziente di decidere chi la legge e ti fornisca un'API pulita. Questa guida dice cosa cercare e mostra, con chiamate reali, come appare la prima ora sulla Piattaforma Anpheros.

Versione tecnica per sviluppatori: API Sanitaria · API Dati Medici su developers.anpheros.com, con richieste, risposte e limiti. Questa pagina è la versione in linguaggio semplice.

Cosa deve fare un'API per i dati sanitari

Cinque cose separano un'API per i dati sanitari utilizzabile da un database con HTTP davanti.

• Un formato standard. HL7 FHIR R4 è il formato utilizzato da ospedali, sistemi nazionali e dallo spazio europeo dei dati sanitari. Una cartella memorizzata in FHIR può essere letta da altri sistemi senza un ponte personalizzato. Un JSON proprietario no.
• Il consenso del paziente come oggetto di prima classe. Chi può leggere cosa, per quanto tempo, revocabile, visibile al paziente. Non una casella di controllo nel tuo database.
• Provenienza. Ogni valore indica chi lo ha scritto: il paziente, un professionista sanitario, un dispositivo, un'importazione, un calcolo derivato. Un assistente AI che non può distinguere un risultato di laboratorio da un'ipotesi auto-riportata è pericoloso.
• Una sandbox con dati realistici. Non puoi testare con pazienti reali e non dovresti dover inventare tu stesso 30 pazienti sintetici con sei mesi di storia.
• Residenza dei dati nominabile. Per gli utenti europei, ciò significa server nell'UE, sotto GDPR, con un accordo di elaborazione dei dati.

Due modi per accedere: REST e FHIR, stessi dati

La Piattaforma Anpheros espone la stessa cartella due volte. Una semplice API REST (/v1) per il codice del prodotto e FHIR R4 rigoroso (/fhir/R4) per tutto ciò che deve comunicare con il resto del sistema sanitario. Gli ID sono identici in entrambi; ogni oggetto v1 porta il suo riferimento fhir.

export BASE=https://platform.anpheros.com
export KEY=sk_test_…

# pazienti che il tuo progetto può vedere
curl $BASE/v1/patients -H "Authorization: Bearer $KEY"

# risultati di laboratorio, dal più recente
curl "$BASE/v1/patients/$PID/observations?category=laboratory&limit=10" -H "Authorization: Bearer $KEY"

# farmaci attivi
curl "$BASE/v1/patients/$PID/medications?status=active" -H "Authorization: Bearer $KEY"

# tutto su una linea temporale
curl "$BASE/v1/patients/$PID/timeline?from=2026-06-01" -H "Authorization: Bearer $KEY"

# gli stessi dati, FHIR rigoroso
curl "$BASE/fhir/R4/Observation?patient=$PID&code=http://loinc.org|4548-4&_sort=-date" -H "Authorization: Bearer $KEY"

Dietro queste chiamate ci sono 26 tipi di risorse FHIR (Patient, Observation, Condition, MedicationStatement, AllergyIntolerance, Immunization, DocumentReference, Encounter, Consent, Provenance e altro), codificati con LOINC per le misurazioni, ICD-10 per le condizioni e ATC per i farmaci.

Ottenere una chiave richiede un minuto

La sandbox è self-service e gratuita. Accedi alla dashboard su platform.anpheros.com/dashboard, premi Ottieni una chiave sandbox e avrai un'organizzazione, un progetto sandbox e una chiave sk_test_…. Il progetto viene fornito con la propria copia di 30 pazienti sintetici: adulti, bambini e anziani da tutta l'UE, con condizioni, farmaci, allergie, risultati di laboratorio e segni vitali su sei mesi. Modifica o elimina qualsiasi cosa; un ripristino li riporterà indietro.

Le chiavi di produzione (sk_live_…) sono destinate a organizzazioni verificate con un accordo di elaborazione dei dati firmato. Sandbox e produzione sono database diversi: una chiave sandbox fisicamente non può raggiungere un paziente reale.

Cos'altro c'è nella confezione

• OAuth 2.1 con PKCE e avvio standalone SMART su FHIR, in modo che un'app possa chiedere a una persona l'accesso alla propria cartella.
• Consenso con ambiti (scopes), scadenza e revoca, e un registro degli accessi che il paziente può leggere.
• Webhook firmati (HMAC-SHA256, ritentati con backoff) per resource.created, consent.granted, consent.revoked, document.finalized.
• Un'API di contesto AI che crea un riassunto etichettato con provenienza di un paziente entro un budget di token.
• Importazione di referti di laboratorio da CSV, HL7 v2 ORU^R01 o JSON, mappato a LOINC.
• International Patient Summary ($summary) e SMART Health Links per la condivisione tramite QR.
• SDK per Dart e TypeScript, un riferimento OpenAPI su /docs e una CapabilityStatement su /fhir/R4/metadata.

La guida completa, con le risposte, è su developers.anpheros.com/guides/first-hour.

Domande frequenti

Esiste un'API sanitaria gratuita con cui posso iniziare oggi?

Sì. La sandbox Anpheros è gratuita e self-service: accedi, ottieni una chiave e avrai 30 pazienti sintetici da leggere e scrivere. I limiti sono 10.000 scritture di risorse al giorno, 100 pazienti tuoi e 250 MB di documenti per progetto.

REST o FHIR, quale dovrei usare?

Usa /v1 per il tuo codice prodotto: è più semplice e restituisce JSON semplice. Usa /fhir/R4 quando un altro sistema deve leggere i dati, quando hai bisogno di ricerche FHIR, _history, $everything o $summary, o quando una certificazione lo richiede. Entrambi vedono la stessa cartella.

Come viene gestito il consenso del paziente?

Una persona concede a un'applicazione l'accesso alla propria cartella tramite OAuth, scegliendo gli ambiti (scopes) e una durata (30, 90, 180 o 365 giorni). La concessione può essere revocata in qualsiasi momento e il paziente vede ogni lettura in un registro degli accessi. Dettagli nel modello di consenso.

Dove sono ospitati i dati?

Nell'Unione Europea (Cloud Run, europe-west4), con provenienza e cronologia delle versioni su ogni scrittura. L'uso in produzione richiede un accordo di elaborazione dei dati firmato.

Quanto costa la produzione?

La produzione inizia da 49 € al mese per 2.500 pazienti memorizzati, con il primo mese gratuito; piani più grandi costano 199 € e 799 € al mese. La sandbox rimane gratuita. Vedi prezzi.

Funziona con gli agenti AI?

Sì. Esiste un'API di contesto AI con etichette di provenienza e un budget di token, e un server MCP su platform.anpheros.com/mcp a cui qualsiasi assistente compatibile con MCP può connettersi. Vedi Integrazione EMR con assistenti medici AI.