# Kezdő lépések

> Az API-kulcstól a beteg FHIR R4 rekordjának olvasásáig és írásáig a sandboxban: kulcsok, első hívások, írások provenienciával, dokumentumok, AI kontextus, IPS, hozzájárulás, webhookok és laboratóriumi jelentések.

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

Az Anpheros Platform egy egészségügyi adat-backend: minden beteghez egy FHIR R4 rekord, projekt elkülönítés,
minden íráshoz proveniencia, és egy egyszerű REST API ugyanazon adatok tetején. Ez az útmutató
elvezet a semmitől a beteg rekordjának olvasásáig és írásáig a sandboxban.

Alap URL (a sandbox és a production megosztja; a kulcs határozza meg az adat síkot):

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

Interaktív referenciák: `/docs` (OpenAPI) és `/fhir/R4/metadata` (CapabilityStatement).

## 1. Kulcs igénylése (1 perc)

A sandbox önkiszolgáló. Jelentkezzen be az irányítópultra (`https://platform.anpheros.com/dashboard/`)
a Google-lal, és nyomja meg a **Get a sandbox key** gombot: kap egy szervezetet, egy sandbox projektet saját
szintetikus betegekkel, és egy kulcsot – amely csak egyszer látható. Ugyanez az Admin API-n keresztül is elérhető, a Firebase felhasználói tokenjével:

```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": {…}}
```

Vagy lépésről lépésre:

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

Ön kap `sk_test_…`. A sandbox kulcsok csak sandbox adatokat látnak. A production kulcsok (`sk_live_…`)
hitelesített szervezeteknek kerülnek kiadásra aláírt DPA-val – írjon a platform@anpheros.com címre. A sandbox ingyenes;
a production havi 99 eurótól indul, és az első hónap ingyenes (lásd: [Árazás](https://developers.anpheros.com/hu/guides/pricing)).

## 2. Első hívás (1 perc)

Az Ön sandbox projektje már rendelkezik egy saját példánnyal 30 szintetikus betegből, hat hónapnyi előzménnyel
a projekt létrehozásának napjáig: felnőttek, gyermekek és idősek az EU egész területéről,
állapotokkal (ICD-10), gyógyszerekkel (ATC), allergiákkal, laboreredményekkel és életjelekkel (LOINC). A példány
a projektjéhez tartozik: bármit módosíthat vagy törölhet – más projekt nem látja. A **teszt betegek visszaállítása**
a dashboardon (vagy `POST /admin/projects/{id}/sandbox/reset`) visszaállítja őket az eredeti állapotukba, új azonosítókkal; az Ön által létrehozott betegek nem érintettek. Minden szintetikus beteg stabil azonosítót tart fenn a visszaállítások során: `Patient?identifier=https://anpheros.com/fhir/sid/sandbox-persona|p02`
mindig 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}
```

A sandbox korlátai nagylelkűek, de végesek: 10 000 erőforrás írás naponta projektenként, 50 saját beteg a szintetikusakon kívül, 250 MB dokumentum (lásd [korlátok](https://developers.anpheros.com/hu/guides/limits)).

## 3. Rekord olvasása

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

Az azonosítók azonosak a `/v1` és a `/fhir/R4` rendszerben; minden v1 objektum tartalmazza a `fhir` referenciáját.
A `_summary=count` csak a teljes számot adja vissza; a `_elements=code,effectiveDateTime` a `SUBSETTED` címkével ellátott karcsú erőforrásokat adja vissza.

## 4. Írás

Adja meg a szerzőt. A(z) `author_type` lehet `patient`, `practitioner`, `device`, `import` vagy `ai`;
ha ezt kihagyja, a platform a(z) `import` értéket rögzíti, soha nem a(z) `patient` értéket.
A(z) `author_type` `ai` segítségével történő írás a(z) [HL7 AI Transparency on FHIR](https://build.fhir.org/ig/HL7/aitransparency-ig/) követelményeit teljesíti:
az erőforrás viseli a(z) `AIAST` biztonsági címkét (*Artificial Intelligence asserted*), és a Provenance erőforrásának oka
a(z) `AIAST`, az ügynök szerepe a(z) `Artificial-Intelligence`, és a(z) `AI-Provenance` profil. A modell megnevezéséhez regisztrálja azt
a(z) `Device`-ként (típus `Artificial-Intelligence`, név, verzió, gyártó) és küldje el a(z) `X-Anpheros-Author-Ref: Device/<id>`-t.

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

A válasz a tárolt megfigyelés lesz a(z) `id`, `fhir` és `updated_at` értékekkel. Ugyanazon kérés ismételt elküldése
ugyanazon `Idempotency-Key` értékkel ugyanazt a választ eredményezi, és nem hoz létre semmit.

## 5. Dokumentumok

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

Az eredeti dokumentum soha nem módosul; a `sha256` és `size` rögzítésre kerülnek, és az Ön által később kinyert bármely érték a `derived_from`-en keresztül a dokumentumra mutat.

## 6. Származás

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

Egy bejegyzés verzióként: ki (szerző típusa és projektje), mikor, melyik forrásrendszerből.

## Tudnivaló szabályok

- **Elszigetelés**: Egy projekt látja az általa létrehozott betegeket (plusz a megosztott sandbox betegeket). Más projekt betegei nem léteznek számodra: `404`, soha `403`.
- **Párban lévő azonosítók**: Az általad látott betegazonosító a tiéd. Egy másik projekt ugyanazt a személyt más azonosítóval látja. Tárolj bátran az azonosítóinkat; soha ne próbáld meg őket korrelálni.
- **Származás (Provenance)**: Minden írási művelet egy Provenance erőforrást hagy maga után. Semmi sem íródik felül csendben; a történet a `/fhir/R4/{Type}/{id}/_history` címen érhető el.
- **Hibák**: A FHIR végpontok `OperationOutcome`-öt adnak vissza; a `/v1` és `/admin` `{"error": {"type", "message", "field"}}`-at adnak vissza. Minden válasz tartalmaz `Anpheros-Request-Id`-et; idézd ezt, amikor írsz nekünk.
- **Korlátok**: Alapértelmezetten 600 kérés/perc kulcsonként, 200 elem oldalanként, 25 MB dokumentumonként.

## 7. Kontextus egy AI modell számára

Nyers rekordok lekérése és annak eldöntése helyett, hogy mi illik egy prompt-hoz, kérje meg a platformot egy kontextusra:

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

Szekciókat kap (összefoglaló kártya, állapotok, gyógyszerek, allergiák, laboreredmények, vitális adatok heti trendekkel és kezelés előtti/utáni jelzőkkel, tünetek, idővonal, dokumentumok), minden elem `author_type` és `source` címkével van ellátva, egy lista arról, hogy mi maradt ki a költségvetéshez igazodva, figyelmeztetések, és egy `manifest_id`, amely összekapcsolja a hívást az audit log-gal. Az AI által generált értékek soha nem keverednek tényekkel: csak a `ai_notes` alatt jelennek meg. Explicit igények is elfogadottak:
`"needs": ["labs:4548-4", "vitals:trend:85354-9", "timeline:180d"]`.

## 8. Szabványok

- A `GET /fhir/R4/Patient/{id}/$summary` egy International Patient Summary dokumentum Bundle-t ad vissza.
- A `POST /fhir/R4/Observation/$validate?profile=eu-lab` beszámol arról, hogyan viszonyul egy laboreredmény az HL7 Europe Laboratory Report 2.1.0 eredményprofilhoz (hibák, figyelmeztetések, információk): kategória, kód (LOINC
  preferált), alany, hatályos idő, előadó és érték, kivéve, ha az eredményt csak regisztrálták vagy törölték.
- A `GET /v1/terminology/loinc?q=hba1c` a csomagolt LOINC alhalmazt keresi, a `GET /v1/search?q=metformin` pedig a tünetek, állapotok és gyógyszerek katalógusát; a kijelzőnév nélkül létrehozott megfigyelések automatikusan megkapják a LOINC nevet.

## 9. Beteg hozzájárulás (OAuth 2.1 + SMART on FHIR)

API kulcsok látják azokat a betegeket, amelyeket a projektje létrehozott. Egy személy meglévő rekordjának eléréséhez kérje meg őket:

1. Regisztráljon egy alkalmazást: `POST /admin/projects/{id}/applications` a visszahívási URI-jával
   (`public` mobil/webes alkalmazásokhoz PKCE-vel, `confidential` szerverekhez; a titkos kulcs egyszer jelenik meg).
2. Küldje el a személyt a hozzájárulási oldalra:
   `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`
   Bejelentkeznek az Anpherosba, világosan látják, mit kérnek, kiválasztják a rekordot (a sajátjukat,
   egy eltartott személyét, vagy azt, amelyet az alkalmazásuk hozott létre számukra), és meghatározzák a hozzáférés időtartamát.
3. Kicserélje a kódot: `POST /oauth/token` (`authorization_code` + `code_verifier`). Kap egy
   hozzáférési tokent (30 perc), egy frissítési tokent (30 nap, használatkor forgatott) és a beteg azonosítóját.
4. Hívja meg az API-t a `Authorization: Bearer at_…` használatával. Csak azt a beteget látja, csak azokat az erőforrás-
   típusokat és műveleteket, amelyek a hatókörökben szerepelnek; a hatókörön kívüli olvasások `403`-re válaszolnak, a keresések szűrt eredményeket adnak.

A személy bármikor visszavonhatja a hozzájárulást az Anpherosból; a következő hívás `401`-re válaszol. Minden engedély
tükröződik egy FHIR `Consent` erőforrásként, és minden hozzáférés alatta naplózásra kerül, és látható a
személy számára. Felfedezés: `/.well-known/smart-configuration`.

## 10. Webhookok

Hagyja, hogy a platform hívja Önt a lekérdezés helyett:

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

Tartsa meg a `secret` a válaszban, és ellenőrizze a `Anpheros-Signature` minden kézbesítéskor
(`verifyWebhookSignature` mindkét SDK-ban). Az események azonosítókat és verziókat tartalmaznak, nem klinikai adatokat.
Részletek, újrapróbálkozások és példák: [webhooks.md](https://developers.anpheros.com/hu/guides/webhooks).

## 11. Szervezetek és gyakorlók

Klinikák, laboratóriumok és az ott dolgozó emberek első osztályú erőforrások: `Organization`, `Practitioner`, `PractitionerRole`. Ezek **címtár** erőforrások: nincs beteg, minden projekt olvashatja ugyanabban a környezetben, és csak a létrehozó projekt módosíthatja őket.

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

Nevezze meg a gyakorlót egy írás mögött a `X-Anpheros-Author-Ref: Practitioner/<id>` (vagy egy `PractitionerRole`, `Organization`, `Device`) segítségével: a szerver által generált Provenance tartalmazza a `agent.who.reference`, és a `GET /fhir/R4/Provenance?agent=Practitioner/<id>` felsorolja mindazt, amit az adott személy rögzített. Keresés: `Organization?name=`, `?identifier=`, `?type=`, `Practitioner?name=`, `?family=`, `?given=`, `PractitionerRole?practitioner=`, `?organization=`, `?role=`, `?specialty=`, `?active=`.

Ki dolgozik az Ön alkalmazása mögött? Küldje el a `X-Anpheros-Acting-As: PractitionerRole/<id>` (vagy a `Practitioner/<id>`) parancsot bármely `/v1` vagy `/fhir/R4` kérésre, amelyet projektkulccsal hajt végre. A személynek léteznie kell a címtárban és aktívnak kell lennie. A hivatkozás bekerül a hozzáférési naplóba, az adott kérés írásainak szerzőjévé válik (hacsak nem állítja be a `X-Anpheros-Author-Ref` értéket), és a beteg számára név szerint megjelenik a kapcsolataiban ("Dr. Ana Popescu · Clinica Dente elolvasta a laboreredményeit").

## 12. Laboratóriumi jelentések egy hívásban

Küldjön egy teljes laboratóriumi jelentést (CSV, HL7 v2 ORU^R01 vagy JSON) és kapjon laboratóriumi megfigyeléseket (Observations) LOINC és referenciatartományokkal; az újra küldés biztonságos. Részletek: [lab-connector.md](https://developers.anpheros.com/hu/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
```

## Konformancia visszajelzés írásokhoz

Minden `POST`/`PUT` klinikai erőforrás ellenőrzésre kerül a szekció IPS profilja, és laboratóriumi megfigyelések esetén a HL7 Europe laborjelentési szabályai szerint. Az írás soha nem utasítódik el profilbeli okokból (strukturális FHIR hibák továbbra is azok); ha valami hiányzik, a válasz tartalmazza

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

Javítsa meg, amit megnevez, és az erőforrás bekerül a beteg `$summary`-ébe. 2026. szeptember 22-én hozzáadott erőforrás típusok: `Immunization`, `MedicationAdministration` (keresési `statement=MedicationStatement/{id}`), `RelatedPerson`, `QuestionnaireResponse`, `Basic`. Más projektek által egy rekordba írt adatok webhook eseményekként érkeznek `data.external = true` — lásd [`docs/webhooks.md`](https://developers.anpheros.com/hu/guides/webhooks).