AnpherosAnpheros PlatformDevelopers

Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card

Iniziare

Da una chiave API alla lettura e scrittura del record FHIR R4 di un paziente nella sandbox: chiavi, prime chiamate, scritture con provenienza, documenti, contesto AI, IPS, consenso, webhook e referti di laboratorio.

Anpheros Platform è un backend di dati sanitari: un record FHIR R4 per paziente, isolamento dei progetti, provenienza su ogni scrittura e una semplice API REST sopra gli stessi dati. Questa guida ti porta da zero alla lettura e scrittura del record di un paziente nella sandbox.

URL di base (sandbox e produzione lo condividono; la chiave decide il data plane):

https://platform.anpheros.com

Riferimento interattivo: /docs (OpenAPI) e /fhir/R4/metadata (CapabilityStatement).

1. Ottieni una chiave (1 minuto)

Il sandbox è self-service. Accedi alla dashboard (https://platform.anpheros.com/dashboard/) con Google e premi Ottieni una chiave sandbox: otterrai un'organizzazione, un progetto sandbox con i propri pazienti sintetici e una chiave, mostrata una sola volta. Lo stesso tramite l'Admin API, con il tuo token utente Firebase:

curl -X POST $BASE/admin/sandbox/quickstart -H "Authorization: Bearer $FIREBASE_ID_TOKEN"
# {"organization": {…}, "project": {"id": "proj_…", "environment": "sandbox", …}, "key": {"key": "sk_test_…", …}, "sandbox": {…}}

Oppure passo dopo passo:

# 1. an organization (you become its owner)
curl -X POST $BASE/admin/organizations -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
     -H 'content-type: application/json' -d '{"name":"CardioAI SRL","kind":"developer","country":"RO"}'
# 2. a sandbox project (it comes with its own synthetic patients)
curl -X POST $BASE/admin/organizations/org_…/projects -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
     -H 'content-type: application/json' -d '{"name":"CardioAI dev","environment":"sandbox"}'
# 3. a key — the plain key is returned exactly once
curl -X POST $BASE/admin/projects/proj_…/keys -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
     -H 'content-type: application/json' -d '{"name":"local dev","scopes":["read","write"]}'

Otterrai sk_test_…. Le chiavi sandbox vedono sempre e solo dati sandbox. Le chiavi di produzione (sk_live_…) vengono rilasciate a organizzazioni verificate con un DPA firmato: scrivi a [email protected]. Il sandbox è gratuito; la produzione inizia da €99 al mese e il primo mese è gratuito (vedi Prezzi).

2. Prima chiamata (1 minuto)

Il tuo progetto sandbox ha già una sua copia di 30 pazienti sintetici, con sei mesi di cronologia fino al giorno in cui è stato creato il progetto: adulti, bambini e anziani da tutta l'UE, con condizioni (ICD-10), farmaci (ATC), allergie, risultati di laboratorio e segni vitali (LOINC). La copia appartiene al tuo progetto: cambia o elimina qualsiasi cosa — nessun altro progetto la vedrà. Ripristina i pazienti di test nella dashboard (o POST /admin/projects/{id}/sandbox/reset) li riporterà come erano, con nuovi ID; i pazienti che hai creato tu stesso non vengono toccati. Ogni paziente sintetico mantiene un identificatore stabile tra i reset: Patient?identifier=https://anpheros.com/fhir/sid/sandbox-persona|p02 è sempre Elena Ionescu.

export KEY=sk_test_…
curl $BASE/v1/patients -H "Authorization: Bearer $KEY"

{"data":[{"id":"…","given":"Elena","family":"Ionescu","birth_date":"1985-09-03","gender":"female",…,"fhir":"Patient/…"}, …],"total":30,"next_cursor":null}

I limiti della sandbox sono generosi ma finiti: 10.000 scritture di risorse al giorno per progetto, 50 pazienti tuoi oltre a quelli sintetici, 250 MB di documenti (vedi limiti).

3. Leggere un record

# lab results, newest first
curl "$BASE/v1/patients/$PID/observations?category=laboratory&limit=10" -H "Authorization: Bearer $KEY"
# active medications
curl "$BASE/v1/patients/$PID/medications?status=active" -H "Authorization: Bearer $KEY"
# everything on one timeline
curl "$BASE/v1/patients/$PID/timeline?from=2026-06-01" -H "Authorization: Bearer $KEY"
# the same data, strict FHIR
curl "$BASE/fhir/R4/Observation?patient=$PID&code=http://loinc.org|4548-4&_sort=-date" -H "Authorization: Bearer $KEY"

Gli ID sono identici in /v1 e /fhir/R4; ogni oggetto v1 porta il suo riferimento fhir. _summary=count restituisce solo il totale; _elements=code,effectiveDateTime restituisce risorse slim contrassegnate SUBSETTED.

4. Scrivi

Indica chi è l'autore. author_type è patient, practitioner, device, import o ai; se lo ometti, la piattaforma registra import, mai patient per impostazione predefinita. Le scritture con author_type ai seguono HL7 AI Transparency on FHIR: la risorsa porta l'etichetta di sicurezza AIAST (Artificial Intelligence asserted) e la sua Provenance ha il motivo AIAST, il ruolo dell'agente Artificial-Intelligence e il profilo AI-Provenance. Per nominare il modello, registralo come Device (tipo Artificial-Intelligence, nome, versione, produttore) e invia X-Anpheros-Author-Ref: Device/<id>.

curl -X POST "$BASE/v1/patients/$PID/observations" -H "Authorization: Bearer $KEY" \
     -H 'content-type: application/json' -H "Idempotency-Key: $(uuidgen)" -d '{
  "code": "2339-0", "display": "Glucose", "category": "laboratory",
  "value": 112, "unit": "mg/dL", "effective_at": "2026-09-19T08:10:00Z",
  "author_type": "device"
}'

La risposta è l'osservazione memorizzata con id, fhir e updated_at. Ripetere la stessa esatta richiesta con lo stesso Idempotency-Key restituisce la stessa risposta e non crea nulla.

5. Documenti

# 1. create the document → upload target
curl -X POST "$BASE/v1/patients/$PID/documents" -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"title":"Analize 2026-09-14","kind":"lab_report","content_type":"application/pdf","date":"2026-09-14"}'
# 2. upload the bytes to the returned url (direct to storage, or through the platform)
curl -X PUT "$BASE/v1/documents/$DOC/content" -H "Authorization: Bearer $KEY" -H 'content-type: application/pdf' --data-binary @analize.pdf

L'originale non viene mai modificato successivamente; sha256 e size vengono registrati, e qualsiasi valore che estrai successivamente punta al documento tramite derived_from.

6. Provenienza

curl "$BASE/v1/patients/$PID/provenance/Observation/$OBS" -H "Authorization: Bearer $KEY"

Una voce per versione: chi (tipo di autore e progetto), quando, da quale sistema sorgente.

Regole da conoscere

7. Contesto per un modello AI

Invece di estrarre record grezzi e decidere cosa si adatta a un prompt, chiedi alla piattaforma un contesto:

curl -X POST "$BASE/v1/context" -H "Authorization: Bearer $KEY" -H 'content-type: application/json' -d '{
  "patient": "'$PID'",
  "task": "medication review before a cardiology visit",
  "question": "How did blood pressure evolve over the last 3 months?",
  "budget_tokens": 1500,
  "format": "text"
}'

Ottieni sezioni (scheda riassuntiva, condizioni, farmaci, allergie, esami di laboratorio, parametri vitali con trend settimanali e marcatori pre/post trattamento, sintomi, timeline, documenti), ogni elemento etichettato con author_type e source, un elenco di ciò che è stato omesso per rientrare nel budget, avvisi e un manifest_id che collega la chiamata al log di audit. I valori prodotti dall'AI non vengono mai mescolati con i fatti: appaiono solo sotto ai_notes. Sono accettate anche esigenze esplicite: "needs": ["labs:4548-4", "vitals:trend:85354-9", "timeline:180d"].

8. Standard

9. Consenso del paziente (OAuth 2.1 + SMART on FHIR)

Le chiavi API vedono i pazienti creati dal tuo progetto. Per raggiungere il record esistente di una persona, chiedi loro:

  1. Registra un'applicazione: POST /admin/projects/{id}/applications con il tuo redirect URI (public per app mobile/web con PKCE, confidential per server; il segreto viene mostrato una sola volta).
  2. Invia la persona alla pagina di consenso: GET /oauth/authorize?response_type=code&client_id=…&redirect_uri=…&state=…&code_challenge=…&code_challenge_method=S256&scope=patient/Observation.rs?category=laboratory patient/MedicationStatement.r offline_access&purpose=treatment&lang=ro Si autenticano su Anpheros, vedono ciò che richiedi in linguaggio chiaro, scelgono il record (il proprio, quello di un dipendente o quello che la tua app ha creato per loro) e per quanto tempo dura l'accesso.
  3. Scambia il codice: POST /oauth/token (authorization_code + code_verifier). Ricevi un access token (30 min), un refresh token (30 giorni, ruotato all'uso) e l'id del paziente.
  4. Chiama l'API con Authorization: Bearer at_…. Vedrai solo quel paziente, solo i tipi di risorsa e le azioni negli scope; le letture fuori scope rispondono 403, le ricerche vengono filtrate.

La persona può revocare in qualsiasi momento da Anpheros; la chiamata successiva risponde 401. Ogni concessione è riflessa come una risorsa FHIR Consent, e ogni accesso sottostante viene registrato e visibile alla persona. Discovery: /.well-known/smart-configuration.

10. Webhook

Lascia che la piattaforma ti chiami invece di effettuare il polling:

curl -X POST $BASE/v1/webhooks -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://your.app/anpheros/hook", "events": ["*"]}'

Mantieni il secret dalla risposta e verifica Anpheros-Signature ad ogni consegna (verifyWebhookSignature in entrambi gli SDK). Gli eventi trasportano ID e versioni, non dati clinici. Dettagli, tentativi ed esempi: webhooks.md.

11. Organizzazioni e professionisti

Cliniche, laboratori e le persone che vi lavorano sono risorse di prima classe: Organization, Practitioner, PractitionerRole. Sono risorse di directory: nessuna paziente, leggibile da ogni progetto nello stesso ambiente, modificabile solo dal progetto che le ha create.

curl -X POST $BASE/fhir/R4/Practitioner -H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json" \
  -d '{"resourceType":"Practitioner","active":true,"name":[{"family":"Popescu","given":["Ana"],"prefix":["Dr."]}]}'

Nomina il professionista dietro una scrittura con X-Anpheros-Author-Ref: Practitioner/<id> (o un PractitionerRole, Organization, Device): il Provenance generato dal server conterrà quindi agent.who.reference, e GET /fhir/R4/Provenance?agent=Practitioner/<id> elencherà tutto ciò che quella persona ha registrato. Ricerca: Organization?name=, ?identifier=, ?type=, Practitioner?name=, ?family=, ?given=, PractitionerRole?practitioner=, ?organization=, ?role=, ?specialty=, ?active=.

Chi sta lavorando dietro la tua app? Invia X-Anpheros-Acting-As: PractitionerRole/<id> (o Practitioner/<id>) su qualsiasi richiesta /v1 o /fhir/R4 effettuata con una chiave di progetto. La persona deve esistere nella directory ed essere attiva. Il riferimento viene scritto nel log di accesso, diventa l'autore delle scritture di quella richiesta (a meno che tu non imposti X-Anpheros-Author-Ref) e viene mostrato al paziente per nome nelle sue connessioni ("Dr. Ana Popescu · Clinica Dente ha letto i tuoi risultati di laboratorio").

12. Report di laboratorio in una singola chiamata

Invia un intero report di laboratorio (CSV, HL7 v2 ORU^R01 o JSON) e ottieni Osservazioni di laboratorio con LOINC e intervalli di riferimento; il reinvio è sicuro. Dettagli: lab-connector.md.

curl -X POST "$BASE/v1/patients/$PATIENT/labs/import" -H "Authorization: Bearer $KEY" -H "Content-Type: text/csv" --data-binary @report.csv

Feedback di conformità sulle scritture

Ogni POST/PUT di una risorsa clinica viene verificato rispetto al profilo IPS della sua sezione e, per le osservazioni di laboratorio, alle regole del report di laboratorio HL7 Europe. La scrittura non viene mai rifiutata per motivi di profilo (gli errori strutturali FHIR lo sono ancora); quando qualcosa manca, la risposta riporta

Anpheros-Conformance: warnings=2; IPS Condition: Condition without code | ...

Correggere ciò che indica e la risorsa sarà inclusa nel $summary del paziente. Tipi di risorsa aggiunti il 22 settembre 2026: Immunization, MedicationAdministration (ricerca statement=MedicationStatement/{id}), RelatedPerson, QuestionnaireResponse, Basic. Le scritture effettuate da altri progetti in un record che è possibile visualizzare arrivano come eventi webhook con data.external = true — vedere docs/webhooks.md.

Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card

Product updates by email

New features, guides and the end of the beta. One email a month at most.

Send me occasional Anpheros Platform updates by email (new features, API changes, guides). I'll confirm by email and can unsubscribe in one click from any email. Privacy