# Backend e database dell'app medica

> Cosa devono gestire un backend di app medica e il suo database, quali parti Anpheros fornisce come database sanitario gestito, cosa rimane nel tuo backend, tre modi per connettersi e come rimanere sincronizzati con i webhook.

Source: https://developers.anpheros.com/it/guides/medical-app-backend

**Un backend di app medica è il lato server di un'applicazione sanitaria: memorizza i dati del paziente, impone chi può vederli, mantiene una cronologia delle modifiche e comunica con laboratori, cliniche e altri servizi.** Con Anpheros, la parte medica di tale backend — il database sanitario che detiene la cartella di ciascun paziente, con la sua cronologia, consenso, provenienza, audit, importazione di laboratorio ed eventi — è fornita dalla piattaforma tramite un'API, e il tuo backend conserva solo ciò che è specifico del tuo prodotto.

## Cosa deve gestire un backend medico

| Responsabilità | Perché è difficile in sanità | Con Anpheros |
|---|---|---|
| Un modello dati medico | dozzine di tipi di dati, ognuno con codici standard | HL7 FHIR R4, 26 tipi di risorse, LOINC / ICD-10 / ATC / UCUM |
| Versionamento | i dati medici vengono corretti, mai sovrascritti silenziosamente | ogni aggiornamento è una nuova versione; `If-Match` per aggiornamenti condizionali |
| Documenti | gli originali devono rimanere invariati e tracciabili | originali immutabili con SHA-256, archiviazione EU crittografata con una chiave gestita dal cliente |
| Controllo degli accessi | per paziente, per applicazione, per tipo di dati | isolamento del progetto, ID pairwise, ambiti OAuth con filtri per categoria |
| Consenso | il paziente decide e può cambiare idea | concessioni per 30–365 giorni, revocabili, rispecchiate come FHIR `Consent` |
| Audit | pazienti e regolatori chiedono chi ha visto cosa | ogni lettura e scrittura registrata e visibile al paziente |
| Provenienza | un valore da un laboratorio non è un valore digitato da un paziente | tipo di autore, organizzazione, professionista e sistema sorgente su ogni scrittura |
| Integrazioni | i laboratori inviano CSV, HL7 v2, JSON; le app necessitano di eventi | importazione di laboratorio, transazioni FHIR, webhook firmati |
| Tentativi sicuri | una duplicazione di farmaci o risultati è un errore clinico | `Idempotency-Key` su ogni creazione |
| Dati di test | i pazienti reali non devono mai essere in fase di sviluppo | un database sandbox con pazienti sintetici |

## Cosa rimane nel tuo backend

- i tuoi **utenti e account**, e la mappatura da ciascun utente al proprio ID paziente Anpheros (l'ID pairwise che il tuo progetto vede);
- **dati di prodotto** che non sono medici: impostazioni, abbonamenti, contenuti, pianificazioni dei promemoria;
- **regole di business** — quale del tuo staff può vedere quale paziente nel tuo prodotto;
- la **API key**, che non deve mai essere inclusa in un'app mobile o web.

## Tre modi per connettersi

**1. Il tuo backend detiene la chiave API (più comune).** La tua app chiama il tuo backend; il tuo backend chiama Anpheros con una chiave `sk_live_` e visualizza i pazienti creati dal tuo progetto.

```ts
import { Anpheros, apiKey } from '@anpheros/sdk';
const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });

// GET /api/me/vitals in your backend, after your own authentication
export async function myVitals(user: { anpherosPatientId: string }) {
  const page = await anpheros.observations.list(user.anpherosPatientId, { category: 'vital-signs', limit: 50 });
  return page.data;
}
```

**2. L'app agisce per conto del paziente con OAuth.** Per le persone che hanno già un record Anpheros, un'app mobile o web è un client OAuth *pubblico* con PKCE: la persona acconsente sulla pagina ospitata e l'app riceve un token di accesso di 30 minuti e un token di aggiornamento rotante per quel singolo record. Gli SDK implementano il flusso (`OAuthFlow`).

**3. Partner server-to-server.** Un client confidenziale (con un segreto, conservato su un server) può utilizzare il flusso authorization-code, o `client_credentials`, che si comporta come una chiave API per quel progetto.

## Mantenere il tuo backend sincronizzato

Iscriviti ai webhook invece di effettuare il polling. Le consegne sono firmate (`Anpheros-Signature`, HMAC-SHA256 su timestamp e corpo), "at-least-once" e potenzialmente fuori ordine; deduplica per ID evento e ignora versioni obsolete.

```ts
import { verifyWebhookSignature } from '@anpheros/sdk';

app.post('/anpheros/hook', express.raw({ type: 'application/json' }), async (req, res) => {
  const ok = await verifyWebhookSignature({ secret: process.env.ANPHEROS_WEBHOOK_SECRET!, header: req.header('anpheros-signature'), body: req.body });
  if (!ok) return res.status(400).end();
  const event = JSON.parse(req.body.toString());   // ids and versions only — read the resource if you need it
  res.status(204).end();
});
```

## Gestione degli errori e dei limiti

- Tratta `404` come "non visibile a te", mai come prova che un record non esiste.
- `403` significa che la credenziale esiste ma potrebbe non fare questo — uno scope mancante, o una risorsa scritta da un'altra organizzazione.
- `429` viene fornito con `Retry-After`; gli SDK attendono e ritentano automaticamente, come fanno per `5xx`.
- Conserva `Anpheros-Request-Id` delle chiamate fallite per il supporto.

[Errori](https://developers.anpheros.com/it/guides/errors) · [Limiti e limiti di frequenza](https://developers.anpheros.com/it/guides/limits)

## Domande frequenti

### Quale database dovrebbe utilizzare un'app medica?
Uno che mantenga i dati medici in una forma standardizzata e versionata e che controlli l'accesso per paziente. Anpheros è un database sanitario gestito basato su HL7 FHIR R4: il record di ogni paziente è versionato e ricercabile, ogni scrittura porta la provenienza e un'applicazione vede un paziente solo se ha creato il record o se il paziente ha dato il consenso. Il tuo database personale conserva il resto dei dati del tuo prodotto: account, fatturazione, contenuti. Per i compromessi derivanti dalla progettazione delle tue tabelle, consulta [FHIR vs. un database medico personalizzato](https://developers.anpheros.com/it/guides/fhir-vs-custom-database).

### Esiste un database gratuito per app mediche?
Sì. La sandbox di Anpheros è gratuita: accedi con Google, ottieni una chiave con un clic e il tuo progetto otterrà 30 pazienti sintetici e fino a 10.000 scritture al giorno. La produzione inizia da €99 al mese per 2.500 pazienti, con il primo mese gratuito; l'accesso alla produzione è riservato a organizzazioni verificate con un accordo di elaborazione dati firmato. Consulta [Prezzi](https://developers.anpheros.com/it/guides/pricing).

### Posso conservare dati reali di pazienti nella sandbox gratuita?
No. La sandbox è solo per dati sintetici: ogni progetto sandbox ottiene i propri pazienti sintetici e le chiavi della sandbox non possono raggiungere la produzione. I record reali dei pazienti appartengono a un progetto di produzione.

## Correlati

- [FHIR vs. un database medico personalizzato](https://developers.anpheros.com/it/guides/fhir-vs-custom-database): quando progettare le proprie tabelle e quando usare FHIR
- [Come costruire un'API sanitaria con TypeScript](https://developers.anpheros.com/it/guides/healthcare-api-typescript): tutorial passo-passo con Express
- [Come costruire un'app sanitaria con Flutter](https://developers.anpheros.com/it/guides/healthcare-app-flutter): tutorial passo-passo con l'SDK Dart
- [Sviluppo di software sanitario](https://developers.anpheros.com/it/guides/healthcare-software)
- [Costruire un'app sanitaria](https://developers.anpheros.com/it/guides/build-a-healthcare-app)
- [Architettura](https://developers.anpheros.com/it/guides/architecture)
- [API dati medici](https://developers.anpheros.com/it/guides/medical-data-api)
- [SDK](https://developers.anpheros.com/it/guides/sdks)