# API Sanitaria: cos'è e come funziona

> Cos'è un'API sanitaria, come funziona una chiamata, cosa cercare e un'API sanitaria FHIR R4 gratuita con consenso del paziente, provenienza e hosting UE — con esempi e FAQ.

Source: https://developers.anpheros.com/it/guides/healthcare-api

**Un'API sanitaria è un'interfaccia programmatica attraverso la quale il software legge e scrive dati sanitari — cartelle cliniche dei pazienti, osservazioni, diagnosi, farmaci, documenti — e attraverso la quale viene autorizzato l'accesso a tali dati.** L'API della Piattaforma Anpheros è un'API sanitaria su un record HL7 FHIR R4 controllato dal paziente: le applicazioni la utilizzano per archiviare e recuperare dati medici, per ottenere il consenso di un paziente e per essere notificati delle modifiche.

<!-- visual: hapi-hero -->

## Come funziona una chiamata API sanitaria

Indipendentemente dal fornitore, una chiamata API sanitaria supera gli stessi controlli: chi sta chiamando, quale paziente e quali dati può toccare, dove sono archiviati i dati, chi li ha scritti e chi ha bisogno di sapere che sono cambiati.

<!-- visual: hapi-request -->

## Tipi di API sanitarie

| Tipo | Cosa scambia | Uso tipico |
|---|---|---|
| API REST FHIR | Risorse FHIR su HTTP (`GET /Observation?patient=…`) | lo standard moderno per lo scambio di dati clinici |
| SMART on FHIR / OAuth | Autorizzazione per API FHIR | consentire ad app di terze parti di accedere a una cartella con il permesso dell'utente |
| Messaggistica HL7 v2 | Messaggi delimitati da pipe (`ORU^R01` per i risultati, `ADT` per le ammissioni) | sistemi di laboratorio e ospedalieri, spesso tramite interfacce piuttosto che HTTP |
| Scambio di documenti | Documenti clinici (PDF, CDA, bundle di documenti FHIR) | riassunti, lettere di dimissione, referenze |
| API REST proprietarie | JSON specifico del fornitore | l'app mobile o le integrazioni di un singolo prodotto |

Anpheros combina i primi due come suo nucleo, accetta risultati di laboratorio HL7 v2 come input, memorizza documenti con i loro originali e produce bundle di documenti FHIR (l'International Patient Summary). Offre inoltre un'API REST più semplice sugli stessi dati per gli sviluppatori che non desiderano lavorare direttamente con FHIR.

## Cosa cercare in una API sanitaria

<!-- visual: hapi-checklist:replace -->

- **Un modello dati standard**, in modo che i dati possano spostarsi tra i sistemi senza mappature personalizzate.
- **Autorizzazione controllata dal paziente**, non solo credenziali controllate dall'applicazione.
- **Provenienza**: chi ha scritto ogni valore, per conto di chi, da quale sistema.
- **Cronologia**: versioni invece di sovrascritture silenziose.
- **Auditabilità** delle letture, non solo delle scritture.
- **Tentativi sicuri** (idempotenza) ed **errori prevedibili**, poiché i dati sanitari non devono essere duplicati o persi.
- **Isolamento** tra le applicazioni che condividono la stessa infrastruttura.
- **Residenza dei dati** che corrisponda a dove si trovano i pazienti.

Il resto di questa pagina mostra come ciascuno di questi elementi appare nell'API Anpheros.

## L'API Anpheros in sintesi

| Superficie | Percorso base | Scopo |
|---|---|---|
| FHIR R4 | `/fhir/R4` | 26 tipi di risorse; read, search, create, update, delete, history, transactions, `$everything`, `$summary`, `$validate` |
| REST v1 | `/v1` | patients, observations, conditions, medications, documents, timeline, provenance, AI context, lab import, terminology, webhooks |
| OAuth 2.1 | `/oauth` | pagina di consenso, token (PKCE), revoca, chiavi OpenID Connect |
| Lato paziente | `/me` | i propri record, chi ha accesso, log degli accessi, revoca |
| Discovery | `/fhir/R4/metadata`, `/fhir/R4/.well-known/smart-configuration`, `/openapi.json` | descrizioni leggibili dalla macchina dell'API |

URL di base: `https://platform.anpheros.com`. Sandbox e produzione condividono lo stesso URL; la chiave decide il data plane.

### Autenticazione

- **API keys** (`sk_test_…`, `sk_live_…`) per i tuoi server; vedono i pazienti creati dal tuo progetto.
- **OAuth access tokens** (`at_…`) per un'applicazione che agisce per conto di un paziente sotto consenso.

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

### Scrittura sicura

Le richieste `POST` accettano un `Idempotency-Key`: una richiesta ritentata con la stessa chiave restituisce la risposta originale e non crea nulla. Ogni scrittura riceve un `Provenance`; il tipo di autore viene inviato nel corpo (`author_type`) o in header come `X-Anpheros-Author-Type`, `X-Anpheros-Source-System`, `X-Anpheros-Origin-Id` e `X-Anpheros-On-Behalf-Of`.

```bash
curl -X POST https://platform.anpheros.com/v1/patients/$PID/observations \
     -H "Authorization: Bearer $KEY" -H 'content-type: application/json' -H "Idempotency-Key: $(uuidgen)" \
     -d '{"code": "29463-7", "display": "Body weight", "category": "vital-signs",
          "value": 71.4, "unit": "kg", "effective_at": "2026-09-28T07:30:00Z", "author_type": "patient"}'
```

### Errori e limiti

Gli endpoint FHIR rispondono con `OperationOutcome`; gli altri con `{"error": {"type", "message", "field"}}`. Ogni risposta contiene `Anpheros-Request-Id`. Il limite predefinito è di 600 richieste al minuto per chiave e per IP. [Errori](https://developers.anpheros.com/it/guides/errors) · [Limiti](https://developers.anpheros.com/it/guides/limits)

### Eventi

Webhook firmati per `resource.created`, `resource.updated`, `resource.deleted`, `consent.granted`, `consent.revoked`, `document.finalized` e `ping`. [Webhook](https://developers.anpheros.com/it/guides/webhooks)

## Scegliere tra FHIR e REST v1

Utilizza **FHIR** quando lavori già con FHIR, necessiti di tipi di risorse che `/v1` non copre (ad esempio `Immunization`, `Procedure` o `CarePlan`), o scambi dati con altri sistemi FHIR. Utilizza **REST v1** per il codice applicativo che desidera JSON piatto per i casi comuni. Entrambi leggono e scrivono le stesse risorse con gli stessi ID, quindi un progetto può mescolarli. [Medical data API](https://developers.anpheros.com/it/guides/medical-data-api) descrive le operazioni sui dati in dettaglio.

## Domande frequenti

### Cos'è un'API sanitaria?
Un'interfaccia programmatica attraverso la quale il software legge e scrive dati sanitari — cartelle cliniche dei pazienti, osservazioni, diagnosi, farmaci e documenti — e attraverso la quale l'accesso a tali dati è autorizzato. Le moderne API sanitarie utilizzano HL7 FHIR R4 per i dati e OAuth 2.0 o 2.1 con SMART on FHIR per l'autorizzazione.

### Qual è la differenza tra un'API sanitaria e un'API FHIR?
FHIR è uno standard che un'API sanitaria può seguire. Un'API FHIR scambia risorse FHIR tramite REST; un'API sanitaria può anche accettare messaggi HL7 v2, documenti o JSON proprietari. Anpheros offre un'API FHIR R4 e un'API REST più semplice sugli stessi dati.

### Esiste un'API sanitaria gratuita per gli sviluppatori?
Sì. Il sandbox Anpheros è gratuito e self-service: accedi con Google, ottieni una chiave API e lavora con 30 pazienti sintetici tramite FHIR R4 o REST. La produzione inizia da €99 al mese, con il primo mese gratuito.

### Come i pazienti danno il consenso a un'API sanitaria?
Tramite OAuth 2.1 con PKCE: l'applicazione invia la persona a una pagina di consenso con gli scope SMART on FHIR; la persona sceglie cosa condividere e per quanto tempo, può vedere un registro degli accessi e può revocare l'accesso in qualsiasi momento.

### Dove vengono archiviati i dati?
Nell'Unione Europea: il servizio e i suoi database sono in esecuzione su Google Cloud `europe-west4` (Paesi Bassi).

### Quale API sanitaria dovrei scegliere?
Confronta lo standard dei dati, chi autorizza l'accesso, la provenienza e l'audit, la residenza dei dati, come si comportano i tentativi e gli errori, e se puoi testare con dati realistici gratuitamente. [Piattaforma API sanitaria: cosa include e come scegliere](https://developers.anpheros.com/it/guides/healthcare-api-platform) trasforma questi elementi in domande da porre a qualsiasi fornitore.

<!-- visual:cta-hapi -->

## Correlati

- [API EHR e API per cartelle cliniche](https://developers.anpheros.com/it/guides/ehr-api)
- [Piattaforma API per la sanità: cosa include e come scegliere](https://developers.anpheros.com/it/guides/healthcare-api-platform)
- [Come creare un'API per la sanità con TypeScript](https://developers.anpheros.com/it/guides/healthcare-api-typescript): tutorial passo-passo con Express
- [Come archiviare cartelle cliniche utilizzando FHIR R4](https://developers.anpheros.com/it/guides/store-medical-records-fhir): tutorial passo-passo con curl
- [API per la sanità con consenso del paziente](https://developers.anpheros.com/it/guides/healthcare-api-patient-consent)
- [Backend SMART on FHIR](https://developers.anpheros.com/it/guides/smart-on-fhir-backend)
- [API per dati medici](https://developers.anpheros.com/it/guides/medical-data-api)
- [Piattaforma FHIR](https://developers.anpheros.com/it/guides/fhir)
- [Interoperabilità dei dati sanitari](https://developers.anpheros.com/it/guides/interoperability)
- [Integrazioni sanitarie](https://developers.anpheros.com/it/guides/healthcare-integrations)
- [Riferimento API (OpenAPI)](https://developers.anpheros.com/docs) · [Autenticazione e OAuth](https://developers.anpheros.com/it/guides/authentication)