# Costruisci un'app sanitaria

> Tutorial: utilizza Anpheros come backend di dati medici per un'app sanitaria — pazienti, misurazioni, condizioni, farmaci, documenti, esami di laboratorio, consensi, webhook e SDK.

Source: https://developers.anpheros.com/it/guides/build-a-healthcare-app

Questo tutorial mostra come un'applicazione sanitaria o medica può utilizzare Anpheros Platform come suo backend di dati medici: dove vengono archiviati i dati dei pazienti, come vengono letti e scritti, come vengono collegati altri sistemi e come il paziente mantiene il controllo. Ogni chiamata seguente fa parte dell'API pubblica ([riferimento](https://developers.anpheros.com/docs)).

## Cosa stai costruendo

Un'app tipica rivolta al paziente — un tracker di condizioni croniche, un'app per la salute familiare, un compagno di monitoraggio remoto — deve:

1.  mantenere un record per paziente: misurazioni, condizioni, farmaci, documenti;
2.  visualizzare quel record come elenchi e una timeline;
3.  accettare dati da altre fonti (dispositivi, laboratori, cliniche);
4.  condividere parti del record, con il consenso del paziente;
5.  reagire quando qualcosa cambia.

Con Anpheros la tua app mantiene i propri utenti, schermate e logica di business, delegando il record medico alla piattaforma:

```
Mobile / web app ──► your backend ──► Anpheros Platform API ──► FHIR R4 record of each patient
                         ▲                                              │
                         └──────────── signed webhooks ◄────────────────┘
```

Il tuo backend detiene la chiave API; l'app comunica con il tuo backend. (Le app che agiscono per un paziente che ha già un record Anpheros utilizzano OAuth invece — vedi passo 7.)

## 1. Ottenere una chiave sandbox

La sandbox è self-service: accedi con Google nella dashboard (`https://platform.anpheros.com/dashboard/`) e premi *Get a sandbox key*. Le chiavi sandbox iniziano con `sk_test_` e possono accedere solo al database sandbox, dove il tuo progetto ha già la propria copia di 30 pazienti sintetici.

```bash
export BASE=https://platform.anpheros.com
export KEY=sk_test_…
curl $BASE/v1/patients -H "Authorization: Bearer $KEY"
```

## 2. Creare un paziente

Ogni utente della tua app ottiene un record paziente di proprietà del tuo progetto.

```bash
curl -X POST $BASE/v1/patients -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{"given": "Elena", "family": "Ionescu", "birth_date": "1985-09-03", "gender": "female"}'
```

La risposta contiene il paziente `id` (il tuo identificatore per questa persona — altri progetti ne vedono uno diverso) e il suo riferimento `fhir`.

## 3. Scrivere misurazioni, condizioni e farmaci

Indica chi fornisce i dati con `author_type`: `patient`, `practitioner`, `device`, `import` o `ai`. Se lo ometti, la piattaforma registra `import`, mai `patient` per presunzione.

```bash
# a blood-pressure reading from a connected device (LOINC panel with two components)
curl -X POST $BASE/v1/patients/$PID/observations -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -H "Idempotency-Key: $(uuidgen)" -d '{
  "code": "85354-9", "display": "Blood pressure panel", "category": "vital-signs",
  "effective_at": "2026-09-28T08:00:00Z", "author_type": "device",
  "components": [
    {"code": "8480-6", "display": "Systolic", "value": 128, "unit": "mm[Hg]"},
    {"code": "8462-4", "display": "Diastolic", "value": 82, "unit": "mm[Hg]"}
  ]}'

# a diagnosis (ICD-10 by default)
curl -X POST $BASE/v1/patients/$PID/conditions -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"code": "I10", "display": "Essential hypertension", "onset": "2024-03-01", "author_type": "practitioner"}'

# a medication (ATC by default)
curl -X POST $BASE/v1/patients/$PID/medications -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"display": "Amlodipine 5 mg", "code": "C08CA01", "dosage": "1 tablet in the morning", "start": "2024-03-01", "author_type": "patient"}'
```

Categorie di osservazione: `vital-signs`, `laboratory`, `symptom`, `activity`, `survey`, `exam`, `imaging`, `social-history`. Ogni scrittura viene memorizzata come una risorsa FHIR e ottiene automaticamente una voce `Provenance`.

## 4. Archiviazione dei documenti

```bash
# create the document, then upload the bytes
curl -X POST $BASE/v1/patients/$PID/documents -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"title": "Blood tests 2026-09-14", "kind": "lab_report", "content_type": "application/pdf", "date": "2026-09-14"}'
curl -X PUT $BASE/v1/documents/$DOC/content -H "Authorization: Bearer $KEY" -H 'content-type: application/pdf' --data-binary @report.pdf
```

L'originale è immutabile dopo il caricamento; i valori estratti da esso possono puntare nuovamente ad esso con `derived_from`.

## 5. Leggere nuovamente il record

```bash
curl "$BASE/v1/patients/$PID/observations?category=vital-signs&limit=20" -H "Authorization: Bearer $KEY"
curl "$BASE/v1/patients/$PID/medications?status=active" -H "Authorization: Bearer $KEY"
curl "$BASE/v1/patients/$PID/timeline?from=2026-06-01" -H "Authorization: Bearer $KEY"   # everything, chronologically
```

Quando hai bisogno del modello FHIR completo, gli stessi dati sono disponibili su `/fhir/R4` con gli stessi ID ([API FHIR R4](https://developers.anpheros.com/it/guides/fhir)).

## 6. Collega laboratori e dispositivi

- **Referti di laboratorio:** `POST /v1/patients/{id}/labs/import` con CSV, HL7 v2 ORU^R01 o JSON trasformano un intero referto in Osservazioni di laboratorio con codici LOINC ([Connettore di laboratorio](https://developers.anpheros.com/it/guides/lab-connector)).
- **Dispositivi e dispositivi indossabili:** scrivono Osservazioni con `author_type: device` e il codice LOINC della misurazione (frequenza cardiaca, SpO₂, passi, durata del sonno e altri sono elencati in [Sistemi di codici FHIR](https://developers.anpheros.com/it/guides/fhir-code-systems)).

## 7. Raggiungere un record che il paziente possiede già (OAuth)

Se la persona possiede già un record in Anpheros (ad esempio tramite Anpheros Daily), la tua app può richiedere l'accesso invece di crearne uno nuovo: registra un'applicazione, invia la persona alla pagina di consenso con gli scope di cui hai bisogno, scambia il codice per i token e chiama l'API con l'access token. Il paziente sceglie la durata e può revocare l'accesso in qualsiasi momento. Dettagli: [Authentication and OAuth](https://developers.anpheros.com/it/guides/authentication).

## 8. Reagire alle modifiche con le webhook

```bash
curl -X POST $BASE/v1/webhooks -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"url": "https://your.app/anpheros/hook", "events": ["resource.created", "consent.revoked"]}'
```

Verificare l'header `Anpheros-Signature` di ogni consegna ([Webhook](https://developers.anpheros.com/it/guides/webhooks)).

## 9. Utilizzare un SDK

Lo stesso flusso in TypeScript:

```ts
import { Anpheros, apiKey } from '@anpheros/sdk';

const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });
const { data: patients } = await anpheros.patients.list();
const vitals = await anpheros.observations.list(patients[0].id, { category: 'vital-signs', limit: 20 });
```

Un client Dart / Flutter con la stessa struttura è disponibile come `anpheros_sdk` ([SDK](https://developers.anpheros.com/it/guides/sdks)).

## Prima di andare in produzione

- Le chiavi di produzione (`sk_live_`) vengono rilasciate a organizzazioni verificate con un accordo di elaborazione dati firmato.
- Leggere la pagina [Sicurezza, privacy e residenza dei dati](https://developers.anpheros.com/it/guides/security) e i [limiti](https://developers.anpheros.com/it/guides/limits).
- Gestire gli errori in base al loro tipo e citare l'header `Anpheros-Request-Id` quando si contatta il supporto ([Errori](https://developers.anpheros.com/it/guides/errors)).

## Correlati

- [Come creare un'API sanitaria con TypeScript](https://developers.anpheros.com/it/guides/healthcare-api-typescript): tutorial passo-passo con Express
- [Come creare un'app sanitaria con Flutter](https://developers.anpheros.com/it/guides/healthcare-app-flutter): tutorial passo-passo con il Dart SDK
- [Come creare un'app sanitaria AI con un backend FHIR](https://developers.anpheros.com/it/guides/build-ai-healthcare-app): tutorial passo-passo in TypeScript
- [Sviluppa con Anpheros](https://developers.anpheros.com/it/guides/build-with-anpheros)
- [Backend e database per app mediche](https://developers.anpheros.com/it/guides/medical-app-backend)
- [API per dati medici](https://developers.anpheros.com/it/guides/medical-data-api)
- [Sviluppo di software sanitario](https://developers.anpheros.com/it/guides/healthcare-software)
- [Come creare un'app per cartelle cliniche personali (PHR) con FHIR](https://developers.anpheros.com/it/guides/personal-health-record-app)