# API per dati longitudinali del paziente

> La storia di un paziente nel tempo da cliniche, laboratori, app e dispositivi: cosa serve per un record longitudinale e quattro modi per leggerlo — timeline, $everything, IPS e contesto AI.

Source: https://developers.anpheros.com/it/guides/longitudinal-patient-data-api

**Un'API per dati longitudinali del paziente restituisce la storia sanitaria di una persona nel tempo — diagnosi, farmaci, risultati di laboratorio, segni vitali, vaccinazioni e visite da ogni fonte — come un unico record ordinato invece di documenti separati per provider.** Anpheros mantiene quella storia come un singolo record HL7 FHIR R4 per paziente, scritto da cliniche, laboratori, app e dispositivi, conservando ogni versione e ogni autore. Gli sviluppatori la leggono in quattro modi: una timeline cronologica, il record FHIR completo con `Patient/$everything`, un International Patient Summary (IPS) o un contesto compatto per modelli AI.

<!-- visual:longitudinal-sources -->

## Cosa richiede il termine "longitudinale"

Un elenco di risultati non è ancora un record longitudinale. Affinché un'applicazione possa fidarsi di una cronologia che copre anni e provider, ogni voce deve contenere:

| Requisito | Perché è importante | Come Anpheros lo memorizza |
|---|---|---|
| Un significato codificato | I valori di diversi laboratori devono essere comparabili | LOINC per i risultati, ICD-10 per le condizioni, ATC per i farmaci |
| Una data clinica | Ordinamento per quando è accaduto, non per quando è stato caricato | Date `effective`, `onset`, `occurrence` su ogni risorsa |
| L'autore | La diagnosi di un medico e la nota di un paziente non sono uguali | Provenance su ogni scrittura: tipo di autore, persona, organizzazione, sistema sorgente |
| Ogni versione | Le correzioni non devono cancellare ciò che era noto in precedenza | Cronologia delle versioni su ogni risorsa (`_history`) |
| Consenso | Altre applicazioni vedono la cronologia solo se la persona acconsente | Concessioni OAuth con ambiti (scopes), scadenza e un registro degli accessi |

## Un record, molti autori

<!-- visual:longitudinal-timeline -->

## Quattro modi per leggere la cronologia

| Necessità | Endpoint | Cosa ottieni |
|---|---|---|
| Un feed cronologico per uno schermo | `GET /v1/patients/{id}/timeline` | Elementi di otto tipi (observation, condition, medication, document, encounter, appointment, immunization, episode) con data, titolo, riepilogo e riferimento FHIR; filtra con `from`, `to`, `types` |
| Il record completo come FHIR | `GET /fhir/R4/Patient/{id}/$everything` | Un Bundle di tipo searchset; sono supportati `_since`, `_type`, `_count` e `_offset` |
| Un riepilogo clinico condivisibile | `GET /fhir/R4/Patient/{id}/$summary` | Un documento International Patient Summary (IPS) |
| Input per un modello AI | `POST /v1/context` | Sezioni all'interno di un budget di token, ogni fatto etichettato con la sua origine |

La timeline con l'SDK TypeScript:

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

const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });   // a sandbox key, sk_test_…
const { data: patients } = await anpheros.patients.list();
const page = await anpheros.timeline.list(patients[0].id, {
  from: '2025-01-01',
  types: 'condition,medication,observation',
  limit: 50,
});
for (const item of page.data) console.log(item.date, item.type, item.title);
```

E lo stesso record come FHIR, limitato a ciò che è cambiato da una data:

```bash
curl -H "Authorization: Bearer $ANPHEROS_KEY" \
  "https://platform.anpheros.com/fhir/R4/Patient/$PATIENT/\$everything?_since=2026-01-01&_type=Observation,Condition"
```

## Mantenere la tua copia sincronizzata

Se la tua applicazione mantiene una propria visualizzazione della cronologia, sottoscrivi i webhook `resource.created`, `resource.updated` e `resource.deleted`. Questi vengono attivati anche quando un altro progetto scrive su un record a cui hai accesso, con `data.external: true` e lo scrittore in `data.source`, in modo che i dati di altre cliniche ti raggiungano senza polling.

## Limiti da conoscere

- Il record contiene ciò che è stato scritto al suo interno. Anpheros non recupera autonomamente la cronologia da ospedali o reti nazionali; cliniche, laboratori, app e la persona scrivono i dati.
- Vengono memorizzati 26 tipi di risorse FHIR R4. Le risorse di fatturazione come Claim e ExplanationOfBenefit non lo sono.
- Altre applicazioni leggono la cronologia di una persona solo con il consenso di tale persona; la chiave di un progetto vede i pazienti che ha creato.

## Domande frequenti

### Cos'è il dato longitudinale del paziente?
Le informazioni sanitarie di una persona raccolte nel tempo e attraverso i contesti di cura — diagnosi, farmaci, risultati, parametri vitali, vaccinazioni e visite — conservate in modo da poter essere lette come una storia continua.

### Quale API fornisce una vista cronologica della cartella di un paziente?
In Anpheros, `GET /v1/patients/{id}/timeline` restituisce voci da otto tipi di risorse in ordine di data, con paginazione e filtri per data e tipo. Per i dati FHIR completi utilizzare `Patient/$everything`.

### La cronologia è memorizzata in un formato standard?
Sì. Ogni voce è una risorsa HL7 FHIR R4 con codici standard (LOINC, ICD-10, ATC, CVX, UCUM), e il riassunto è un International Patient Summary.

### Come faccio a sapere chi ha scritto ogni voce?
Ogni scrittura crea una risorsa Provenance con il tipo di autore (paziente, professionista sanitario, dispositivo, importazione o IA), la persona, l'organizzazione e il sistema di origine.

### Posso testare con dati longitudinali realistici?
Sì. Ogni progetto sandbox inizia con 30 pazienti sintetici con circa sei mesi di condizioni, farmaci, risultati di laboratorio e parametri vitali.

<!-- visual:cta-longitudinal -->

## Correlati

- [App di cartella clinica personale (PHR) con FHIR](https://developers.anpheros.com/it/guides/personal-health-record-app): una timeline in un'app reale
- [Provenienza dei dati medici spiegata](https://developers.anpheros.com/it/guides/medical-data-provenance)
- [Piattaforma di consenso del paziente per app sanitarie](https://developers.anpheros.com/it/guides/patient-consent-platform)
- [Come archiviare cartelle cliniche utilizzando FHIR R4](https://developers.anpheros.com/it/guides/store-medical-records-fhir)
- [Agenti AI e dati medici](https://developers.anpheros.com/it/guides/ai-agents-medical-data): l'endpoint del contesto
- [Webhook](https://developers.anpheros.com/it/guides/webhooks)