# Začínáme

> Od API klíče po čtení a zápis záznamu pacienta ve formátu FHIR R4 v sandboxu: klíče, první volání, zápisy s proveniencí, dokumenty, AI kontext, IPS, souhlas, webhooks a laboratorní zprávy.

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

Anpheros Platform je backend pro zdravotnická data: záznam FHIR R4 na pacienta, izolace projektů,
provenience u každého zápisu a jednoduché REST API nad stejnými daty. Tato příručka vás provede
od ničeho k čtení a zápisu záznamu pacienta v sandboxu.

Základní URL (sandbox a produkce sdílejí stejnou URL; klíč rozhoduje o datové rovině):

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

Interaktivní reference: `/docs` (OpenAPI) a `/fhir/R4/metadata` (CapabilityStatement).

## 1. Získání klíče (1 minuta)

Sandbox je samoobslužný. Přihlaste se na dashboard (`https://platform.anpheros.com/dashboard/`)
pomocí účtu Google a klikněte na **Get a sandbox key**: získáte organizaci, sandbox projekt s vlastními
syntetickými pacienty a klíč – zobrazený jednou. Stejně tak prostřednictvím Admin API s vaším Firebase user token:

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

Nebo krok za krokem:

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

Získáte `sk_test_…`. Sandbox klíče vidí pouze sandbox data. Produkční klíče (`sk_live_…`) jsou
vydávány ověřeným organizacím s podepsanou DPA – pište na platform@anpheros.com. Sandbox je zdarma;
produkce začíná na 99 € měsíčně a první měsíc je zdarma (viz [Ceník](https://developers.anpheros.com/cs/guides/pricing)).

## 2. První volání (1 minuta)

Váš sandbox projekt již obsahuje vlastní kopii 30 syntetických pacientů s šestiměsíční historií
do dne vytvoření projektu: dospělí, děti a starší lidé z celé EU, s
diagnózami (ICD-10), léky (ATC), alergiemi, laboratorními výsledky a vitálními funkcemi (LOINC). Tato kopie
patří vašemu projektu: cokoli změňte nebo smažte – žádný jiný projekt to neuvidí. **Resetovat testovací
pacienty** v dashboardu (nebo `POST /admin/projects/{id}/sandbox/reset`) je vrátí do původního stavu
s novými ID; pacienti, které jste si vytvořili sami, nejsou dotčeni. Každý syntetický pacient si zachovává
stabilní identifikátor napříč resety: `Patient?identifier=https://anpheros.com/fhir/sid/sandbox-persona|p02`
je vždy 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}
```

Limity sandboxu jsou štědré, ale konečné: 10 000 zápisů zdrojů denně na projekt, 50 vlastních pacientů
kromě syntetických, 250 MB dokumentů (viz [limity](https://developers.anpheros.com/cs/guides/limits)).

## 3. Čtení záznamu

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

ID jsou identická v `/v1` a `/fhir/R4`; každý objekt v1 nese svůj `fhir` odkaz.
`_summary=count` vrací pouze celkový počet; `_elements=code,effectiveDateTime` vrací zjednodušené zdroje označené `SUBSETTED`.

## 4. Zápis

Uveďte autora. `author_type` je `patient`, `practitioner`, `device`, `import` nebo `ai`;
pokud jej vynecháte, platforma zaznamená `import`, nikdy z předpokladu `patient`.
Zápisy s `author_type` `ai` se řídí [HL7 AI Transparency on FHIR](https://build.fhir.org/ig/HL7/aitransparency-ig/):
zdroj nese bezpečnostní označení `AIAST` (*Artificial Intelligence asserted*) a jeho Provenance má důvod
`AIAST`, roli agenta `Artificial-Intelligence` a profil `AI-Provenance`. Pro pojmenování modelu jej zaregistrujte jako
`Device` (typ `Artificial-Intelligence`, název, verze, výrobce) a odešlete `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"
}'
```

Odpovědí je uložené pozorování s `id`, `fhir` a `updated_at`. Opakování přesně
stejného požadavku se stejným `Idempotency-Key` vrátí stejnou odpověď a nic nevytvoří.

## 5. Dokumenty

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

Originál se po vytvoření nikdy nemění; `sha256` a `size` jsou zaznamenány a veškeré hodnoty, které
později extrahujete, odkazují zpět na dokument prostřednictvím `derived_from`.

## 6. Provenience

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

Jeden záznam na verzi: kdo (typ autora a projekt), kdy, z jakého zdrojového systému.

## Pravidla, která je dobré znát

- **Izolace**: projekt vidí pacienty, které vytvořil (plus sdílené pacienty sandboxu). Pacienti
  někoho jiného pro vás neexistují: `404`, nikdy `403`.
- **Párové ID**: ID pacienta, které vidíte, je vaše. Jiný projekt vidí stejnou osobu pod jiným ID.
  Naše ID ukládejte volně; nikdy se je nesnažte korelovat.
- **Původ**: každý zápis zanechává zdroj Provenance. Nic není tiše přepsáno; historie je
  k dispozici na `/fhir/R4/{Type}/{id}/_history`.
- **Chyby**: koncové body FHIR vracejí `OperationOutcome`; `/v1` a `/admin` vracejí
  `{"error": {"type", "message", "field"}}`. Každá odpověď obsahuje `Anpheros-Request-Id`; citujte ji,
  když nám píšete.
- **Limity**: ve výchozím nastavení 600 požadavků/minutu na klíč, 200 položek na stránku, 25 MB na dokument.

## 7. Kontext pro AI model

Místo načítání surových záznamů a rozhodování, co odpovídá výzvě, požádejte platformu o kontext:

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

Získáte sekce (souhrnná karta, diagnózy, léky, alergie, laboratorní výsledky, vitální funkce s týdenními trendy a značkami před/po léčbě, příznaky, časová osa, dokumenty), přičemž každá položka je označena `author_type` a `source`, seznamem toho, co bylo vynecháno, aby se vešlo do rozpočtu, varováními a `manifest_id`, které spojuje volání s auditním protokolem. Hodnoty generované AI se nikdy nemíchají s fakty: objevují se pouze pod `ai_notes`. Jsou akceptovány i explicitní požadavky:
`"needs": ["labs:4548-4", "vitals:trend:85354-9", "timeline:180d"]`.

## 8. Standardy

- `GET /fhir/R4/Patient/{id}/$summary` vrací dokument International Patient Summary ve formátu Bundle.
- `POST /fhir/R4/Observation/$validate?profile=eu-lab` hlásí, jak se laboratorní výsledek srovnává s profilem výsledku HL7 Europe Laboratory Report 2.1.0 (chyby, varování, informace): kategorie, kód (preferováno LOINC), subjekt, čas platnosti, provádějící osoba a hodnota, pokud výsledek není pouze registrován nebo zrušen.
- `GET /v1/terminology/loinc?q=hba1c` prohledává zabalenou podmnožinu LOINC a `GET /v1/search?q=metformin` katalog symptomů, stavů a léků; pozorování vytvořená bez zobrazovaného názvu automaticky získají název LOINC.

## 9. Souhlas pacienta (OAuth 2.1 + SMART on FHIR)

API klíče vidí pacienti, které váš projekt vytvořil. Chcete-li získat přístup k existujícímu záznamu osoby, požádejte ji:

1. Zaregistrujte aplikaci: `POST /admin/projects/{id}/applications` s vaším redirect URI
   (`public` pro mobilní/webové aplikace s PKCE, `confidential` pro servery; secret se zobrazí jednou).
2. Pošlete osobu na stránku se souhlasem:
   `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`
   Přihlásí se do Anpheros, uvidí, co žádáte, v běžném jazyce, vybere záznam (svůj vlastní,
   záznam závislé osoby nebo ten, který pro ně vaše aplikace vytvořila) a jak dlouho přístup trvá.
3. Vyměňte kód: `POST /oauth/token` (`authorization_code` + `code_verifier`). Obdržíte
   access token (30 min), refresh token (30 dní, rotuje se při použití) a patient id.
4. Zavolejte API s `Authorization: Bearer at_…`. Uvidíte pouze tohoto pacienta, pouze typy zdrojů
   a akce v rozsahu scopes; čtení mimo rozsah odpovídají `403`, vyhledávání jsou filtrována.

Osoba může kdykoli zrušit souhlas z Anpheros; další volání odpoví `401`. Každé udělení je
zrcadleno jako FHIR `Consent` resource a každý přístup pod ním je zaznamenán a viditelný pro
danou osobu. Discovery: `/.well-known/smart-configuration`.

## 10. Webhooky

Nechte platformu, aby vás kontaktovala, místo abyste ji dotazovali:

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

Ponechte `secret` z odpovědi a ověřte `Anpheros-Signature` při každém doručení
(`verifyWebhookSignature` v obou SDK). Události nesou ID a verze, nikoli klinická data.
Podrobnosti, opakované pokusy a příklady: [webhooks.md](https://developers.anpheros.com/cs/guides/webhooks).

## 11. Organizace a praktičtí lékaři

Kliniky, laboratoře a lidé, kteří v nich pracují, jsou zdroje první třídy: `Organization`,
`Practitioner`, `PractitionerRole`. Jedná se o **adresářové** zdroje: žádný pacient, čitelný
každým projektem ve stejném prostředí, měnitelný pouze projektem, který je vytvořil.

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

Pojmenujte praktického lékaře za zápisem pomocí `X-Anpheros-Author-Ref: Practitioner/<id>` (nebo
`PractitionerRole`, `Organization`, `Device`): serverem generované Provenance pak nese
`agent.who.reference` a `GET /fhir/R4/Provenance?agent=Practitioner/<id>` uvádí vše,
co daná osoba zaznamenala. Vyhledávání: `Organization?name=`, `?identifier=`, `?type=`, `Practitioner?name=`,
`?family=`, `?given=`, `PractitionerRole?practitioner=`, `?organization=`, `?role=`, `?specialty=`, `?active=`.

Kdo pracuje za vaší aplikací? Odešlete `X-Anpheros-Acting-As: PractitionerRole/<id>` (nebo
`Practitioner/<id>`) při jakémkoli požadavku `/v1` nebo `/fhir/R4` provedeném s klíčem projektu. Osoba musí
existovat v adresáři a být aktivní. Odkaz je zapsán do přístupového logu, stává se autorem
zápisů daného požadavku (pokud nenastavíte `X-Anpheros-Author-Ref`) a je pacientovi zobrazen
jménem v jeho připojeních ("Dr. Ana Popescu · Clinica Dente si přečetl/a vaše laboratorní výsledky").

## 12. Laboratorní zprávy v jednom volání

Odešlete celou laboratorní zprávu (CSV, HL7 v2 ORU^R01 nebo JSON) a získejte laboratorní pozorování (Observations) s LOINC a referenčními rozsahy; opětovné odeslání je bezpečné. Podrobnosti: [lab-connector.md](https://developers.anpheros.com/cs/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
```

## Zpětná vazba o shodě při zápisu

Každý `POST`/`PUT` klinického zdroje je kontrolován proti profilu IPS jeho sekce a pro
laboratorní pozorování proti pravidlům pro laboratorní zprávy HL7 Europe. Zápis není nikdy odmítnut z
důvodů profilu (strukturální chyby FHIR stále jsou); když něco chybí, odpověď nese

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

Opravte to, co pojmenovává, a zdroj bude zahrnut do `$summary` pacienta. Typy zdrojů přidané
22. září 2026: `Immunization`, `MedicationAdministration` (vyhledávání `statement=MedicationStatement/{id}`),
`RelatedPerson`, `QuestionnaireResponse`, `Basic`. Zápisy provedené jinými projekty do záznamu, který můžete
vidět, přicházejí jako události webhook s `data.external = true` — viz [`docs/webhooks.md`](https://developers.anpheros.com/cs/guides/webhooks).