# Začíname

> Od API kľúča po čítanie a zápis záznamu pacienta vo formáte FHIR R4 v sandboxe: kľúče, prvé volania, zápisy s pôvodom, dokumenty, AI kontext, IPS, súhlas, webové háčiky a laboratórne správy.

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

Anpheros Platform je backend pre zdravotnícke údaje: záznam FHIR R4 na pacienta, izolácia projektov,
pôvod pri každom zápise a jednoduché REST API nad rovnakými údajmi. Táto príručka vás prevedie
od ničoho k čítaniu a zápisu záznamu pacienta v sandboxe.

Základná URL (sandbox a produkcia ju zdieľajú; kľúč rozhoduje o dátovej rovine):

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

Interaktívna referencia: `/docs` (OpenAPI) a `/fhir/R4/metadata` (CapabilityStatement).

## 1. Získajte kľúč (1 minúta)

Sandbox je samoobslužný. Prihláste sa na dashboard (`https://platform.anpheros.com/dashboard/`) pomocou Google a stlačte **Získať sandbox kľúč**: získate organizáciu, sandbox projekt s vlastnými syntetickými pacientmi a kľúč – zobrazený raz. Rovnako cez Admin API, s vaším Firebase používateľským tokenom:

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

Alebo krok za krokom:

```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ískate `sk_test_…`. Sandbox kľúče vidia vždy iba sandbox dáta. Produkčné kľúče (`sk_live_…`) sú vydávané overeným organizáciám s podpísanou DPA – napíšte na platform@anpheros.com. Sandbox je bezplatný; produkcia začína od 99 € mesačne a prvý mesiac je bezplatný (pozri [Cenník](https://developers.anpheros.com/sk/guides/pricing)).

## 2. Prvý hovor (1 minúta)

Váš sandbox projekt už má vlastnú kópiu 30 syntetických pacientov so šesťmesačnou históriou
do dňa vytvorenia projektu: dospelí, deti a starší ľudia z celej EÚ, s
diagnózami (ICD-10), liekmi (ATC), alergiami, výsledkami laboratórnych testov a vitálnymi funkciami (LOINC). Kópia
patrí vášmu projektu: zmeňte alebo odstráňte čokoľvek – žiadny iný projekt to neuvidí. **Resetovať testovacích
pacientov** v dashboarde (alebo `POST /admin/projects/{id}/sandbox/reset`) ich vráti do pôvodného stavu
s novými ID; pacienti, ktorých ste vytvorili vy sami, nie sú ovplyvnení. Každý syntetický pacient si zachováva
stabilný identifikátor naprieč resetmi: `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 sú veľkorysé, ale konečné: 10 000 zápisov zdrojov denne na projekt, 50 vlastných pacientov
okrem syntetických, 250 MB dokumentov (pozri [limity](https://developers.anpheros.com/sk/guides/limits)).

## 3. Prečítanie 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 sú identické v `/v1` a `/fhir/R4`; každý objekt v1 nesie svoj `fhir` odkaz.
`_summary=count` vracia iba celkový počet; `_elements=code,effectiveDateTime` vracia štíhle zdroje označené `SUBSETTED`.

## 4. Zápis

Uveďte autora. `author_type` je `patient`, `practitioner`, `device`, `import` alebo `ai`;
ak ho vynecháte, platforma zaznamená `import`, nikdy nie `patient` z predpokladu.
Zápisy s `author_type` `ai` sa riadia [HL7 AI Transparency on FHIR](https://build.fhir.org/ig/HL7/aitransparency-ig/):
zdroj nesie bezpečnostný štítok `AIAST` (*Artificial Intelligence asserted*) a jeho Provenance má dôvod
`AIAST`, rolu agenta `Artificial-Intelligence` a profil `AI-Provenance`. Na pomenovanie modelu ho zaregistrujte ako
`Device` (typ `Artificial-Intelligence`, názov, verzia, výrobca) a odošlite `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"
}'
```

Odpoveďou je uložené pozorovanie s `id`, `fhir` a `updated_at`. Opakovanie presne
rovnakej požiadavky s rovnakým `Idempotency-Key` vráti rovnakú odpoveď a nič nevytvorí.

## 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 sa nikdy nemení; `sha256` a `size` sa zaznamenajú a akékoľvek hodnoty, ktoré neskôr extrahujete, odkazujú späť na dokument prostredníctvom `derived_from`.

## 6. Proveniencia

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

Jeden záznam na verziu: kto (typ autora a projekt), kedy, z ktorého zdrojového systému.

## Pravidlá, ktoré sa oplatí poznať

- **Izolácia**: projekt vidí pacientov, ktorých vytvoril (plus zdieľaných pacientov zo sandboxu). Pacienti iných používateľov pre vás neexistujú: `404`, nikdy `403`.
- **Párové ID**: ID pacienta, ktoré vidíte, je vaše. Iný projekt vidí tú istú osobu pod iným ID. Naše ID si ukladajte voľne; nikdy sa ich nesnažte korelovať.
- **Pôvod (Provenance)**: každý zápis zanecháva zdroj Provenance. Nič nie je potichu prepísané; história je dostupná na `/fhir/R4/{Type}/{id}/_history`.
- **Chyby**: FHIR endpointy vracajú `OperationOutcome`; `/v1` a `/admin` vracajú `{"error": {"type", "message", "field"}}`. Každá odpoveď obsahuje `Anpheros-Request-Id`; citujte ju, keď nás kontaktujete.
- **Limity**: štandardne 600 požiadaviek/minútu na kľúč, 200 položiek na stránku, 25 MB na dokument.

## 7. Kontext pre AI model

Namiesto načítania surových záznamov a rozhodovania o tom, čo zodpovedá výzve, požiadajte 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ískate sekcie (súhrnná karta, diagnózy, lieky, alergie, laboratórne výsledky, vitálne funkcie s týždennými trendmi a značkami pred/po liečbe, symptómy, časová os, dokumenty), pričom každá položka je označená `author_type` a `source`, zoznamom toho, čo bolo vynechané, aby sa zmestilo do rozpočtu, varovaniami a `manifest_id`, ktoré spája volanie s auditným denníkom. Hodnoty generované AI sa nikdy nemiešajú s faktami: objavujú sa iba pod `ai_notes`. Prijímajú sa aj explicitné požiadavky:
`"needs": ["labs:4548-4", "vitals:trend:85354-9", "timeline:180d"]`.

## 8. Štandardy

- `GET /fhir/R4/Patient/{id}/$summary` vráti dokument International Patient Summary vo formáte Bundle.
- `POST /fhir/R4/Observation/$validate?profile=eu-lab` hlási, ako sa výsledok laboratórneho testu porovnáva s profilom výsledkov HL7 Europe Laboratory Report 2.1.0 (chyby, varovania, informácie): kategória, kód (preferovaný LOINC), subjekt, čas platnosti, vykonávateľ a hodnota, pokiaľ výsledok nie je len zaregistrovaný alebo zrušený.
- `GET /v1/terminology/loinc?q=hba1c` vyhľadáva v zbalenej podmnožine LOINC a `GET /v1/search?q=metformin` v katalógu symptómov, stavov a liekov; pozorovania vytvorené bez zobrazovaného názvu automaticky získajú názov LOINC.

## 9. Súhlas pacienta (OAuth 2.1 + SMART on FHIR)

API kľúče vidia pacientov, ktorých váš projekt vytvoril. Na prístup k existujúcemu záznamu osoby sa jej opýtajte:

1. Zaregistrujte aplikáciu: `POST /admin/projects/{id}/applications` s vašou redirect URI
   (`public` pre mobilné/webové aplikácie s PKCE, `confidential` pre servery; secret sa zobrazí raz).
2. Pošlite osobu na stránku súhlasu:
   `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`
   Prihlási sa do Anpheros, uvidí, o čo žiadate, v zrozumiteľnom jazyku, vyberie si záznam (svoj vlastný,
   závislej osoby alebo ten, ktorý pre ňu vytvorila vaša aplikácia) a na akú dlhú dobu prístup platí.
3. Vymeňte kód: `POST /oauth/token` (`authorization_code` + `code_verifier`). Dostanete
   access token (30 min), refresh token (30 dní, rotovaný pri použití) a patient id.
4. Zavolajte API s `Authorization: Bearer at_…`. Vidíte iba tohto pacienta, iba typy zdrojov
   a akcie v scopes; čítania mimo scope odpovedajú `403`, vyhľadávania sú filtrované.

Osoba môže kedykoľvek odvolať súhlas z Anpheros; ďalšie volanie odpovie `401`. Každé udelenie je
zrkadlené ako FHIR `Consent` resource a každý prístup pod ním je zaznamenaný a viditeľný pre
danú osobu. Discovery: `/.well-known/smart-configuration`.

## 10. Webhooky

Nechajte platformu, aby vás kontaktovala namiesto neustáleho pýtania sa:

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

Ponechajte `secret` z odpovede a overte `Anpheros-Signature` pri každom doručení
(`verifyWebhookSignature` v oboch SDK). Udalosti obsahujú ID a verzie, nie klinické údaje.
Podrobnosti, opakované pokusy a príklady: [webhooks.md](https://developers.anpheros.com/sk/guides/webhooks).

## 11. Organizácie a praktickí lekári

Kliniky, laboratóriá a ľudia, ktorí tam pracujú, sú plnohodnotné zdroje: `Organization`,
`Practitioner`, `PractitionerRole`. Sú to **adresárové** zdroje: žiadny pacient, čitateľné
každým projektom v rovnakom prostredí, zmeniteľné iba projektom, ktorý ich vytvoril.

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

Pomenujte praktického lekára za zápis pomocou `X-Anpheros-Author-Ref: Practitioner/<id>` (alebo `PractitionerRole`,
`Organization`, `Device`): serverom generovaná Provenance potom nesie
`agent.who.reference` a `GET /fhir/R4/Provenance?agent=Practitioner/<id>` uvádza všetko, čo daná osoba zaznamenala. Vyhľadávanie: `Organization?name=`,
`?identifier=`, `?type=`, `Practitioner?name=`, `?family=`, `?given=`, `PractitionerRole?practitioner=`, `?organization=`, `?role=`, `?specialty=`, `?active=`.

Kto pracuje za vašou aplikáciou? Pošlite `X-Anpheros-Acting-As: PractitionerRole/<id>` (alebo `Practitioner/<id>`) pri akomkoľvek `/v1` alebo `/fhir/R4` požiadavke vykonanej s kľúčom projektu. Osoba musí existovať v adresári a byť aktívna. Referencia sa zapíše do prístupového denníka, stane sa autorom zápisov danej požiadavky (pokiaľ nenastavíte `X-Anpheros-Author-Ref`) a zobrazí sa pacientovi pod menom v jeho pripojeniach ("Dr. Ana Popescu · Clinica Dente si prečítal/a vaše laboratórne výsledky").

## 12. Laboratórne správy v jednom volaní

Odošlite celú laboratórnu správu (CSV, HL7 v2 ORU^R01 alebo JSON) a získajte laboratórne pozorovania (Observations) s LOINC a referenčnými rozsahmi; opätovné odoslanie je bezpečné. Podrobnosti: [lab-connector.md](https://developers.anpheros.com/sk/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
```

## Spätná väzba o zhode pri zápisoch

Každý `POST`/`PUT` klinického zdroja je skontrolovaný oproti profilu IPS jeho sekcie a pre
laboratórne pozorovania, pravidlám HL7 Europe pre laboratórne správy. Zápis nie je nikdy zamietnutý z
profilových dôvodov (štrukturálne chyby FHIR stále sú); keď niečo chýba, odpoveď obsahuje

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

Opravte to, čo pomenúva, a zdroj bude zahrnutý do `$summary` pacienta. Typy zdrojov pridané
22. septembra 2026: `Immunization`, `MedicationAdministration` (vyhľadávanie `statement=MedicationStatement/{id}`),
`RelatedPerson`, `QuestionnaireResponse`, `Basic`. Zápisy vykonané inými projektmi do záznamu môžete
vidieť prichádzať ako webhook udalosti s `data.external = true` — pozri [`docs/webhooks.md`](https://developers.anpheros.com/sk/guides/webhooks).