# Початок роботи

> Від API ключа до читання та запису запису пацієнта FHIR R4 у пісочниці: ключі, перші виклики, записи з походженням, документи, контекст ШІ, IPS, згода, вебхуки та лабораторні звіти.

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

Anpheros Platform — це бекенд для медичних даних: запис FHIR R4 на пацієнта, ізоляція проєктів,
походження кожного запису та простий REST API поверх тих самих даних. Цей посібник проведе вас
від нуля до читання та запису запису пацієнта в пісочниці.

Базовий URL (пісочниця та продакшн використовують його; ключ визначає площину даних):

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

Інтерактивні посилання: `/docs` (OpenAPI) та `/fhir/R4/metadata` (CapabilityStatement).

## 1. Отримайте ключ (1 хвилина)

Пісочниця працює в режимі самообслуговування. Увійдіть на панель керування (`https://platform.anpheros.com/dashboard/`)
за допомогою Google та натисніть **Отримати ключ пісочниці**: ви отримаєте організацію, проєкт пісочниці з власними
синтетичними пацієнтами та ключ — який відображається один раз. Те саме через Admin API, використовуючи ваш токен користувача Firebase:

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

Або крок за кроком:

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

Ви отримаєте `sk_test_…`. Ключі пісочниці завжди бачать лише дані пісочниці. Виробничі ключі (`sk_live_…`)
видаються перевіреним організаціям з підписаною DPA — напишіть на platform@anpheros.com. Пісочниця безкоштовна;
виробнича версія коштує від €99 на місяць, а перший місяць безкоштовний (див. [Ціни](https://developers.anpheros.com/uk/guides/pricing)).

## 2. Перший виклик (1 хвилина)

Ваш проєкт пісочниці вже має власну копію 30 синтетичних пацієнтів із шестимісячною історією
до дня створення проєкту: дорослі, діти та люди похилого віку з усієї ЄС, із
діагнозами (ICD-10), ліками (ATC), алергіями, результатами лабораторних досліджень та життєвими показниками (LOINC). Копія
належить вашому проєкту: змінюйте або видаляйте будь-що — жоден інший проєкт цього не побачить. **Скинути тестових
пацієнтів** на панелі керування (або `POST /admin/projects/{id}/sandbox/reset`) повертає їх у початковий стан
з новими ідентифікаторами; пацієнти, яких ви створили самостійно, не зачіпаються. Кожен синтетичний пацієнт зберігає
стабільний ідентифікатор між скиданнями: `Patient?identifier=https://anpheros.com/fhir/sid/sandbox-persona|p02`
завжди є Оленою Іонеску.

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

Ліміти пісочниці щедрі, але обмежені: 10 000 записів ресурсів на день на проєкт, 50 власних пацієнтів
на додаток до синтетичних, 250 МБ документів (див. [ліміти](https://developers.anpheros.com/uk/guides/limits)).

## 3. Читання запису

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

Ідентифікатори є однаковими в `/v1` та `/fhir/R4`; кожен об'єкт v1 містить посилання на `fhir`.
`_summary=count` повертає лише загальну кількість; `_elements=code,effectiveDateTime` повертає "slim" ресурси з тегом `SUBSETTED`.

## 4. Запис

Вкажіть автора. `author_type` — це `patient`, `practitioner`, `device`, `import` або `ai`;
якщо ви його опустите, платформа запише `import`, ніколи не `patient` за замовчуванням.
Записи з `author_type` `ai` відповідають [HL7 AI Transparency on FHIR](https://build.fhir.org/ig/HL7/aitransparency-ig/):
ресурс несе мітку безпеки `AIAST` (*Artificial Intelligence asserted*) та його Provenance має причину
`AIAST`, роль агента `Artificial-Intelligence` та профіль `AI-Provenance`. Щоб назвати модель, зареєструйте її як
`Device` (тип `Artificial-Intelligence`, назва, версія, виробник) та надішліть `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"
}'
```

Відповіддю є збережене спостереження з `id`, `fhir` та `updated_at`. Повторний запит з тим самим
`Idempotency-Key` повертає ту саму відповідь і нічого не створює.

## 5. Документи

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

Оригінал ніколи не змінюється після цього; `sha256` та `size` записуються, а будь-які значення, які ви
пізніше витягнете, посилатимуться на документ через `derived_from`.

## 6. Походження

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

Один запис на версію: хто (тип автора та проєкт), коли, з якої вихідної системи.

## Правила, які варто знати

- **Ізоляція**: проєкт бачить пацієнтів, яких він створив (плюс спільних пацієнтів пісочниці). Пацієнти інших користувачів для вас не існують: `404`, ніколи `403`.
- **Парні ідентифікатори**: ідентифікатор пацієнта, який ви бачите, є вашим. Інший проєкт бачить ту саму особу під іншим ідентифікатором. Зберігайте наші ідентифікатори вільно; ніколи не намагайтеся їх співвіднести.
- **Походження**: кожен запис на запис залишає ресурс Provenance. Нічого не перезаписується мовчки; історія доступна за адресою `/fhir/R4/{Type}/{id}/_history`.
- **Помилки**: кінцеві точки FHIR повертають `OperationOutcome`; `/v1` та `/admin` повертають `{"error": {"type", "message", "field"}}`. Кожна відповідь містить `Anpheros-Request-Id`; цитуйте його, коли пишете нам.
- **Обмеження**: 600 запитів/хвилину на ключ за замовчуванням, 200 елементів на сторінку, 25 МБ на документ.

## 7. Контекст для моделі ШІ

Замість того, щоб витягувати необроблені записи та вирішувати, що відповідає запиту, попросіть платформу надати контекст:

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

Ви отримуєте розділи (картка зведення, стани, ліки, алергії, лабораторні дослідження, життєві показники з тижневими трендами та маркерами до/після лікування, симптоми, часова шкала, документи), кожен елемент позначений `author_type` та `source`, список того, що було опущено, щоб вписатися в бюджет, попередження та `manifest_id`, що пов'язує виклик з журналом аудиту. Значення, згенеровані ШІ, ніколи не змішуються з фактами: вони з'являються лише під `ai_notes`. Також приймаються явні потреби:
`"needs": ["labs:4548-4", "vitals:trend:85354-9", "timeline:180d"]`.

## 8. Стандарти

- `GET /fhir/R4/Patient/{id}/$summary` повертає документ International Patient Summary у форматі Bundle.
- `POST /fhir/R4/Observation/$validate?profile=eu-lab` повідомляє, як лабораторний результат співвідноситься з профілем результатів HL7 Europe Laboratory Report 2.1.0 (помилки, попередження, інформація): категорія, код (LOINC
  є кращим), суб'єкт, час дії, виконавець та значення, якщо результат лише зареєстровано або скасовано.
- `GET /v1/terminology/loinc?q=hba1c` шукає у пакеті підмножину LOINC, а `GET /v1/search?q=metformin` — каталог
  симптомів, станів та ліків; спостереження, створені без відображуваної назви, автоматично отримують назву LOINC.

## 9. Згода пацієнта (OAuth 2.1 + SMART on FHIR)

Ключі API бачать пацієнтів, створених вашим проєктом. Щоб отримати доступ до існуючого запису особи, запитайте її:

1. Зареєструйте застосунок: `POST /admin/projects/{id}/applications` з вашим redirect URI
   (`public` для мобільних/веб-застосунків з PKCE, `confidential` для серверів; секрет відображається один раз).
2. Надішліть особу на сторінку згоди:
   `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`
   Вони входять до Anpheros, бачать, що ви запитуєте, простою мовою, обирають запис (свій власний,
   залежної особи або той, який ваш застосунок створив для них) і визначають тривалість доступу.
3. Обміняйте код: `POST /oauth/token` (`authorization_code` + `code_verifier`). Ви отримуєте
   токен доступу (30 хв), токен оновлення (30 днів, обертається при використанні) та ідентифікатор пацієнта.
4. Викликайте API з `Authorization: Bearer at_…`. Ви бачите лише цього пацієнта, лише типи ресурсів
   та дії в межах scope; запити на читання поза scope відповідають `403`, пошуки фільтруються.

Особа може відкликати згоду в будь-який час з Anpheros; наступний виклик відповідає `401`. Кожна надана згода
відображається як ресурс FHIR `Consent`, і кожен доступ під нею реєструється та видимий для
особи. Discovery: `/.well-known/smart-configuration`.

## 10. Вебхуки

Нехай платформа викликає вас замість опитування:

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

Зберігайте `secret` з відповіді та перевіряйте `Anpheros-Signature` при кожній доставці
(`verifyWebhookSignature` в обох SDK). Події містять ідентифікатори та версії, а не клінічні дані.
Деталі, повторні спроби та приклади: [webhooks.md](https://developers.anpheros.com/uk/guides/webhooks).

## 11. Організації та практики

Клініки, лабораторії та люди, які там працюють, є ресурсами першого класу: `Organization`,
`Practitioner`, `PractitionerRole`. Це **каталогові** ресурси: жоден пацієнт, доступний для читання
кожним проєктом у тому самому середовищі, змінюваний лише проєктом, який їх створив.

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

Назвіть практикуючого лікаря, який стоїть за записом, за допомогою `X-Anpheros-Author-Ref: Practitioner/<id>` (або
`PractitionerRole`, `Organization`, `Device`): згенерований сервером Provenance тоді міститиме
`agent.who.reference`, а `GET /fhir/R4/Provenance?agent=Practitioner/<id>` перелічуватиме все,
що записала ця особа. Пошук: `Organization?name=`, `?identifier=`, `?type=`, `Practitioner?name=`,
`?family=`, `?given=`, `PractitionerRole?practitioner=`, `?organization=`, `?role=`, `?specialty=`, `?active=`.

Хто стоїть за вашим додатком? Надішліть `X-Anpheros-Acting-As: PractitionerRole/<id>` (або
`Practitioner/<id>`) для будь-якого запиту `/v1` або `/fhir/R4`, зробленого з ключем проєкту. Особа повинна
існувати в каталозі та бути активною. Посилання записується до журналу доступу, стає автором
записів цього запиту (якщо ви не встановили `X-Anpheros-Author-Ref`) і відображається пацієнту
під іменем у його підключеннях ("Д-р Ана Попеску · Clinica Dente прочитала ваші результати аналізів").

## 12. Лабораторні звіти в одному виклику

Надішліть повний лабораторний звіт (CSV, HL7 v2 ORU^R01 або JSON) і отримайте лабораторні спостереження (Observations) з кодами LOINC та референтними діапазонами; повторне надсилання є безпечним. Деталі: [lab-connector.md](https://developers.anpheros.com/uk/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
```

## Зворотний зв'язок щодо відповідності під час запису

Кожен `POST`/`PUT` клінічного ресурсу перевіряється відповідно до профілю IPS його розділу, а для
лабораторних спостережень – відповідно до правил HL7 Europe для лабораторних звітів. Запис ніколи не відхиляється з причин, пов'язаних з профілем (структурні помилки FHIR все ще можуть призвести до відхилення); коли чогось бракує, відповідь містить

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

Виправте те, що вказано, і ресурс буде включено до `$summary` пацієнта. Типи ресурсів, додані
22 вересня 2026 року: `Immunization`, `MedicationAdministration` (пошук `statement=MedicationStatement/{id}`),
`RelatedPerson`, `QuestionnaireResponse`, `Basic`. Записи, зроблені іншими проєктами до запису, який ви можете
бачити, надходять як події webhook з `data.external = true` — див. [`docs/webhooks.md`](https://developers.anpheros.com/uk/guides/webhooks).