# Erste Schritte

> Vom API-Schlüssel bis zum Lesen und Schreiben eines FHIR R4-Datensatzes eines Patienten in der Sandbox: Schlüssel, erste Aufrufe, Schreibvorgänge mit Provenienz, Dokumente, KI-Kontext, IPS, Zustimmung, Webhooks und Laborberichte.

Source: https://developers.anpheros.com/de/guides/getting-started

Die Anpheros Platform ist ein Health-Data-Backend: ein FHIR R4-Datensatz pro Patient, Projektisolation,
Provenienz bei jedem Schreibvorgang und eine einfache REST-API auf Basis derselben Daten. Diese Anleitung führt Sie
von Null zum Lesen und Schreiben eines Patientendatensatzes in der Sandbox.

Basis-URL (Sandbox und Produktion teilen sie; der Schlüssel entscheidet über die Datenebene):

```
https://platform.anpheros.com
```

Interaktive Referenz: `/docs` (OpenAPI) und `/fhir/R4/metadata` (CapabilityStatement).

## 1. Schlüssel erhalten (1 Minute)

Die Sandbox ist Self-Service. Melden Sie sich im Dashboard (`https://platform.anpheros.com/dashboard/`) mit Google an und klicken Sie auf **Sandbox-Schlüssel erhalten**: Sie erhalten eine Organisation, ein Sandbox-Projekt mit eigenen synthetischen Patienten und einen Schlüssel – dieser wird nur einmal angezeigt. Dasselbe gilt über die Admin API mit Ihrem Firebase-Benutzertoken:

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

Oder Schritt für Schritt:

```bash
# 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"]}'
```

Sie erhalten `sk_test_…`. Sandbox-Schlüssel sehen ausschließlich Sandbox-Daten. Produktionsschlüssel (`sk_live_…`) werden an verifizierte Organisationen mit einer unterzeichneten DPA ausgestellt – schreiben Sie an platform@anpheros.com. Die Sandbox ist kostenlos; die Produktion beginnt bei 99 € pro Monat, wobei der erste Monat kostenlos ist (siehe [Preise](https://developers.anpheros.com/de/guides/pricing)).

## 2. Erster Aufruf (1 Minute)

Ihr Sandbox-Projekt hat bereits eine eigene Kopie von 30 synthetischen Patienten mit sechs Monaten Historie bis zum Tag der Projekterstellung: Erwachsene, Kinder und ältere Menschen aus der gesamten EU, mit Diagnosen (ICD-10), Medikamenten (ATC), Allergien, Laborergebnissen und Vitalparametern (LOINC). Die Kopie gehört zu Ihrem Projekt: Ändern oder löschen Sie alles – kein anderes Projekt sieht es. **Testpatienten zurücksetzen** im Dashboard (oder `POST /admin/projects/{id}/sandbox/reset`) bringt sie in ihren ursprünglichen Zustand zurück, mit neuen IDs; die von Ihnen selbst erstellten Patienten bleiben unberührt. Jeder synthetische Patient behält eine stabile Kennung über Zurücksetzungen hinweg: `Patient?identifier=https://anpheros.com/fhir/sid/sandbox-persona|p02` ist immer Elena Ionescu.

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

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

Sandbox-Limits sind großzügig, aber endlich: 10.000 Ressourcen-Schreibvorgänge pro Tag und Projekt, 50 eigene Patienten zusätzlich zu den synthetischen, 250 MB Dokumente (siehe [Limits](https://developers.anpheros.com/de/guides/limits)).

## 3. Datensatz lesen

```bash
# 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"
```

Ids sind in `/v1` und `/fhir/R4` identisch; jedes v1-Objekt trägt seinen `fhir`-Verweis.
`_summary=count` gibt nur die Gesamtzahl zurück; `_elements=code,effectiveDateTime` gibt schlanke Ressourcen zurück, die mit `SUBSETTED` getaggt sind.

## 4. Schreiben

Geben Sie den Autor an. `author_type` ist `patient`, `practitioner`, `device`, `import` oder `ai`;
wenn Sie ihn weglassen, speichert die Plattform `import`, niemals `patient` per Annahme.
Schreiben mit `author_type` `ai` folgen [HL7 AI Transparency on FHIR](https://build.fhir.org/ig/HL7/aitransparency-ig/):
die Ressource trägt das Sicherheitslabel `AIAST` (*Artificial Intelligence asserted*) und ihre Provenance hat den Grund
`AIAST`, die Agentenrolle `Artificial-Intelligence` und das Profil `AI-Provenance`. Um das Modell zu benennen, registrieren Sie es als
`Device` (Typ `Artificial-Intelligence`, Name, Version, Hersteller) und senden Sie `X-Anpheros-Author-Ref: Device/<id>`.

```bash
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"
}'
```

Die Antwort ist die gespeicherte Beobachtung mit `id`, `fhir` und `updated_at`. Die exakte
Wiederholung derselben Anfrage mit demselben `Idempotency-Key` gibt dieselbe Antwort zurück und erstellt nichts.

## 5. Dokumente

```bash
# 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
```

Das Original wird danach nie modifiziert; `sha256` und `size` werden aufgezeichnet, und alle Werte, die Sie
später extrahieren, verweisen über `derived_from` zurück auf das Dokument.

## 6. Provenance

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

Ein Eintrag pro Version: wer (Autorart und Projekt), wann, aus welchem Quellsystem.

## Wissenswerte Regeln

- **Isolation**: Ein Projekt sieht die Patienten, die es selbst erstellt hat (plus die gemeinsam genutzten Sandbox-Patienten). Patienten anderer Projekte existieren für Sie nicht: `404`, niemals `403`.
- **Pairwise IDs**: Die Patient-ID, die Sie sehen, ist Ihre eigene. Ein anderes Projekt sieht dieselbe Person unter einer anderen ID. Speichern Sie unsere IDs frei; versuchen Sie niemals, sie zu korrelieren.
- **Provenienz**: Jeder Schreibvorgang hinterlässt eine Provenance-Ressource. Nichts wird stillschweigend überschrieben; die Historie ist unter `/fhir/R4/{Type}/{id}/_history` verfügbar.
- **Fehler**: FHIR-Endpunkte geben `OperationOutcome` zurück; `/v1` und `/admin` geben `{"error": {"type", "message", "field"}}` zurück. Jede Antwort enthält `Anpheros-Request-Id`; zitieren Sie diese, wenn Sie uns schreiben.
- **Limits**: Standardmäßig 600 Anfragen/Minute pro Schlüssel, 200 Elemente pro Seite, 25 MB pro Dokument.

## 7. Kontext für ein KI-Modell

Anstatt Rohdaten abzurufen und zu entscheiden, was zu einer Eingabeaufforderung passt, fordern Sie die Plattform auf, einen Kontext bereitzustellen:

```bash
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"
}'
```

Sie erhalten Abschnitte (Zusammenfassungskarte, Diagnosen, Medikamente, Allergien, Laborwerte, Vitalparameter mit wöchentlichen Trends und Markern vor/nach der Behandlung, Symptome, Zeitachse, Dokumente), wobei jeder Eintrag mit `author_type` und `source` gekennzeichnet ist, eine Liste dessen, was zur Einhaltung des Budgets weggelassen wurde, Warnungen und ein `manifest_id`, das den Aufruf mit dem Audit-Log verknüpft. Von der KI erzeugte Werte werden niemals mit Fakten vermischt: Sie erscheinen nur unter `ai_notes`. Explizite Anforderungen werden ebenfalls akzeptiert:
`"needs": ["labs:4548-4", "vitals:trend:85354-9", "timeline:180d"]`.

## 8. Standards

- `GET /fhir/R4/Patient/{id}/$summary` gibt ein International Patient Summary Dokument Bundle zurück.
- `POST /fhir/R4/Observation/$validate?profile=eu-lab` berichtet, wie ein Laborergebnis mit dem HL7 Europe Laboratory Report 2.1.0 Ergebnisprofil verglichen wird (Fehler, Warnungen, Informationen): Kategorie, Code (LOINC bevorzugt), Subjekt, effektive Zeit, ein Ausführender und ein Wert, es sei denn, das Ergebnis ist nur registriert oder storniert.
- `GET /v1/terminology/loinc?q=hba1c` durchsucht die gebündelte LOINC-Teilmenge und `GET /v1/search?q=metformin` den Katalog von Symptomen, Zuständen und Medikamenten; Beobachtungen, die ohne Anzeigenamen erstellt werden, erhalten automatisch den LOINC-Namen.

## 9. Patienteneinwilligung (OAuth 2.1 + SMART on FHIR)

API-Schlüssel sehen die Patienten, die Ihr Projekt erstellt hat. Um auf den bestehenden Datensatz einer Person zuzugreifen, bitten Sie sie:

1. Registrieren Sie eine Anwendung: `POST /admin/projects/{id}/applications` mit Ihrer Redirect-URI
   (`public` für mobile/Web-Apps mit PKCE, `confidential` für Server; das Secret wird einmal angezeigt).
2. Leiten Sie die Person zur Einwilligungsseite weiter:
   `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`
   Sie melden sich bei Anpheros an, sehen in Klartext, was Sie anfordern, wählen den Datensatz (ihren eigenen,
   den eines Abhängigen oder den, den Ihre App für sie erstellt hat) und wie lange der Zugriff dauert.
3. Tauschen Sie den Code aus: `POST /oauth/token` (`authorization_code` + `code_verifier`). Sie erhalten einen
   Access Token (30 Min.), einen Refresh Token (30 Tage, wird bei Verwendung rotiert) und die Patienten-ID.
4. Rufen Sie die API mit `Authorization: Bearer at_…` auf. Sie sehen nur diesen Patienten, nur die Ressourcentypen
   und Aktionen in den Scopes; Leseanfragen außerhalb des Scopes antworten mit `403`, Suchen werden gefiltert.

Die Person kann die Einwilligung jederzeit in Anpheros widerrufen; der nächste Aufruf antwortet mit `401`. Jede Gewährung wird als FHIR `Consent` Ressource gespiegelt, und jeder Zugriff darunter wird protokolliert und ist für die Person sichtbar. Discovery: `/.well-known/smart-configuration`.

## 10. Webhooks

Lassen Sie sich von der Plattform aufrufen, anstatt zu pollen:

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

Behalten Sie `secret` aus der Antwort bei und verifizieren Sie `Anpheros-Signature` bei jeder Zustellung
(`verifyWebhookSignature` in beiden SDKs). Events enthalten IDs und Versionen, keine klinischen Daten.
Details, Wiederholungsversuche und Beispiele: [webhooks.md](https://developers.anpheros.com/de/guides/webhooks).

## 11. Organisationen und Praktiker

Kliniken, Labore und die dort arbeitenden Personen sind Ressourcen erster Klasse: `Organization`,
`Practitioner`, `PractitionerRole`. Es handelt sich um **Verzeichnis**-Ressourcen: kein Patient, lesbar für
jedes Projekt in derselben Umgebung, änderbar nur durch das Projekt, das sie erstellt hat.

```bash
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."]}]}'
```

Benennen Sie den Praktiker hinter einem Schreibvorgang mit `X-Anpheros-Author-Ref: Practitioner/<id>` (oder einem
`PractitionerRole`, `Organization`, `Device`): die vom Server generierte Provenance trägt dann
`agent.who.reference`, und `GET /fhir/R4/Provenance?agent=Practitioner/<id>` listet alles auf,
was diese Person erfasst hat. Suche: `Organization?name=`, `?identifier=`, `?type=`, `Practitioner?name=`,
`?family=`, `?given=`, `PractitionerRole?practitioner=`, `?organization=`, `?role=`, `?specialty=`, `?active=`.

Wer arbeitet hinter Ihrer App? Senden Sie `X-Anpheros-Acting-As: PractitionerRole/<id>` (oder
`Practitioner/<id>`) bei jeder `/v1`- oder `/fhir/R4`-Anfrage, die mit einem Projektschlüssel gestellt wird. Die Person muss
im Verzeichnis existieren und aktiv sein. Die Referenz wird in das Zugriffsprotokoll geschrieben, wird zum
Autor der Schreibvorgänge dieser Anfrage (es sei denn, Sie setzen `X-Anpheros-Author-Ref`) und wird dem
Patienten namentlich in seinen Verbindungen angezeigt ("Dr. Ana Popescu · Clinica Dente hat Ihre Laborergebnisse gelesen").

## 12. Laborberichte in einem Aufruf

Senden Sie einen vollständigen Laborbericht (CSV, HL7 v2 ORU^R01 oder JSON) und erhalten Sie Laborbeobachtungen mit LOINC und Referenzbereichen; erneutes Senden ist sicher. Details: [lab-connector.md](https://developers.anpheros.com/de/guides/lab-connector).

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

## Conformance-Feedback bei Schreibvorgängen

Jeder `POST`/`PUT` einer klinischen Ressource wird gegen das IPS-Profil seines Abschnitts und, für
Laborbeobachtungen, gegen die HL7 Europe Laboratory Report Rules geprüft. Der Schreibvorgang wird niemals aus Profilgründen abgelehnt (strukturelle FHIR-Fehler weiterhin); wenn etwas fehlt, enthält die Antwort

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

Beheben Sie, was es benennt, und die Ressource wird in die `$summary` des Patienten aufgenommen. Ressourcentypen, die am 22. September 2026 hinzugefügt wurden: `Immunization`, `MedicationAdministration` (Such-`statement=MedicationStatement/{id}`),
`RelatedPerson`, `QuestionnaireResponse`, `Basic`. Schreibvorgänge, die von anderen Projekten in einen Datensatz durchgeführt werden, den Sie sehen können, kommen als Webhook-Ereignisse mit `data.external = true` an — siehe [`docs/webhooks.md`](https://developers.anpheros.com/de/guides/webhooks).