Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card

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

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

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:

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

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

# 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 — напишіть на [email protected]. Пісочниця безкоштовна; виробнича версія коштує від €99 на місяць, а перший місяць безкоштовний (див. Ціни).

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

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

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

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

Ліміти пісочниці щедрі, але обмежені: 10 000 записів ресурсів на день на проєкт, 50 власних пацієнтів на додаток до синтетичних, 250 МБ документів (див. ліміти).

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

# 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: ресурс несе мітку безпеки AIAST (Artificial Intelligence asserted) та його Provenance має причину AIAST, роль агента Artificial-Intelligence та профіль AI-Provenance. Щоб назвати модель, зареєструйте її як Device (тип Artificial-Intelligence, назва, версія, виробник) та надішліть X-Anpheros-Author-Ref: Device/<id>.

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. Документи

# 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. Походження

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. Контекст для моделі ШІ

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

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 бачать пацієнтів, створених вашим проєктом. Щоб отримати доступ до існуючого запису особи, запитайте її:

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

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

10. Вебхуки

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

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.

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

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

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.

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.

Try it free in the sandbox · first FHIR call in 5 minutesFree · 30 synthetic patients · no card