# API dei dati medici

> Dove ogni tipo di dato medico rientra nell'API Anpheros, come viene codificato e come scriverlo, filtrarlo, tracciarlo, correggerlo ed eliminarlo — con esempi funzionanti.

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

**Un'API di dati medici fornisce al software un accesso strutturato ai contenuti delle cartelle cliniche: creare un paziente, registrare una misurazione della pressione sanguigna, elencare i farmaci attivi, allegare un referto di laboratorio, tracciare chi ha scritto cosa.** Questa pagina descrive le operazioni sui dati dell'API Anpheros — quale tipo di dato medico va dove, come viene codificato e come leggerlo — con esempi funzionanti contro la sandbox.

Le applicazioni utilizzano queste operazioni per trattare Anpheros come il database medico del loro prodotto: le cartelle cliniche vivono nello store HL7 FHIR R4 della piattaforma, e l'applicazione le legge e le scrive tramite l'API invece di mantenere le proprie tabelle di dati medici.

Per il quadro generale (autenticazione, consenso, eventi) vedere [API Sanitaria](https://developers.anpheros.com/it/guides/healthcare-api).

## Dove vanno i diversi tipi di dati medici

| Dati medici | REST v1 | Risorsa FHIR | Codifica |
|---|---|---|---|
| La persona | `POST /v1/patients` | `Patient` | name, birth date, gender, identifiers |
| Segni vitali, risultati di laboratorio, sintomi, attività, sondaggi | `/v1/patients/{id}/observations` | `Observation` | LOINC (sintomi: capitolo R dell'ICD-10); unità UCUM |
| Diagnosi e problemi | `/v1/patients/{id}/conditions` | `Condition` | ICD-10 |
| Farmaci | `/v1/patients/{id}/medications` | `MedicationStatement` | ATC, nome del prodotto mantenuto come testo |
| Documenti (PDF, immagini) | `/v1/patients/{id}/documents` | `DocumentReference` | Tipi di documenti LOINC |
| Un intero referto di laboratorio | `POST /v1/patients/{id}/labs/import` | `Observation` (laboratory) | LOINC ove noto, altrimenti il codice proprio del laboratorio |
| Dosi assunte o saltate, vaccinazioni, allergie, procedure, referti, piani di assistenza, obiettivi, invii, visite, appuntamenti, team di assistenza, storia familiare, questionari | `/fhir/R4/{type}` | `MedicationAdministration`, `Immunization`, `AllergyIntolerance`, `Procedure`, `DiagnosticReport`, `CarePlan`, `Goal`, `ServiceRequest`, `Encounter`, `Appointment`, `CareTeam`, `FamilyMemberHistory`, `QuestionnaireResponse` | per [sistemi di codifica FHIR](https://developers.anpheros.com/it/guides/fhir-code-systems) |

Gli oggetti REST v1 e le risorse FHIR sono gli stessi record con gli stessi ID; ogni oggetto v1 porta il suo riferimento `fhir`.

## Scrittura di dati medici

```bash
# a lab result with its reference range, linked to the report it came from
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": "4548-4", "display": "Hemoglobin A1c", "category": "laboratory",
  "value": 6.4, "unit": "%", "effective_at": "2026-09-01T08:00:00Z",
  "reference_range": {"low": 4.0, "high": 5.6},
  "derived_from": ["DocumentReference/'$DOC'"], "author_type": "import"
}'
```

- **Categorie di osservazione:** `vital-signs`, `laboratory`, `symptom`, `activity`, `survey`, `exam`, `imaging`, `social-history`.
- **Misurazioni composite** come la pressione sanguigna utilizzano `components` (sistolica `8480-6`, diastolica `8462-4` all'interno del pannello `85354-9`).
- **Tipi di autore:** `patient`, `practitioner`, `device`, `import`, `ai`. Senza uno, la piattaforma registra `import`.
- **Codici che non si conoscono a memoria:** `GET /v1/terminology/loinc?q=hba1c` cerca il sottoinsieme LOINC incluso e `GET /v1/search?q=metformin` il catalogo di sintomi, condizioni e farmaci; un'osservazione scritta senza un nome visualizzato ottiene automaticamente il nome LOINC.

## Lettura dei dati medici

```bash
curl "https://platform.anpheros.com/v1/patients/$PID/observations?category=laboratory&code=4548-4&from=2026-01-01" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/conditions?clinical_status=active" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/medications?status=active" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/timeline?from=2026-06-01" -H "Authorization: Bearer $KEY"
```

| Endpoint | Filtri |
|---|---|
| observations | `category`, `code`, `from`, `to` |
| conditions | `clinical_status` |
| medications | `status` |
| documents | `kind` |
| timeline | `from`, `to`, `types` |

Le liste sono paginate con `limit` e `cursor`. La **timeline** unisce osservazioni, condizioni, farmaci, documenti, visite, appuntamenti, vaccinazioni ed episodi di cura in un'unica lista cronologica — l'input naturale per una schermata di storia clinica del paziente.

Per tutto ciò che i filtri REST non coprono, utilizzare la ricerca FHIR: `GET /fhir/R4/Observation?patient=$PID&code=http://loinc.org|4548-4&_sort=-date` ([piattaforma FHIR](https://developers.anpheros.com/it/guides/fhir)).

## Tracciamento e correzione dei dati

- **Chi l'ha scritto:** `GET /v1/patients/{id}/provenance/{type}/{resourceId}` — una voce per versione, con tipo di autore, progetto, organizzazione e sistema di origine.
- **Ogni versione:** `GET /fhir/R4/{type}/{id}/_history`; aggiorna con `If-Match` per evitare di sovrascrivere le modifiche di qualcun altro.
- **Proprietà:** con il consenso è possibile leggere ciò che altre organizzazioni hanno scritto, ma modificare o eliminare solo ciò che il proprio progetto ha scritto (`403` altrimenti).
- **Eliminazione:** `DELETE /v1/{observations|conditions|medications}/{id}`; l'eliminazione di un `Patient` elimina l'intero record.

## Documenti

Crea il documento (ottieni un target di upload), carica i byte tramite la piattaforma o direttamente nello storage, quindi finalizza. Dopo la finalizzazione, l'originale è immutabile; il suo SHA-256 e la sua dimensione vengono registrati. Fino a 25 MiB per file.

## Correlati

- [Come normalizzare i dati medici](https://developers.anpheros.com/it/guides/normalize-medical-data): codici, unità, date, duplicati, convalida
- [Provenienza dei dati medici spiegata](https://developers.anpheros.com/it/guides/medical-data-provenance): chi ha scritto cosa e come registrarlo
- [API Sanitaria](https://developers.anpheros.com/it/guides/healthcare-api)
- [Cartella clinica del paziente](https://developers.anpheros.com/it/guides/patient-medical-record)
- [Creare un'app sanitaria](https://developers.anpheros.com/it/guides/build-a-healthcare-app)
- [Riferimento API (OpenAPI)](https://developers.anpheros.com/docs) · [Guida introduttiva](https://developers.anpheros.com/it/guides/getting-started)