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

Začíname

Od API kľúča po čítanie a zápis FHIR R4 záznamu pacienta 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.

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:

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:

# 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 [email protected]. Sandbox je bezplatný; produkcia začína od 99 € mesačne a prvý mesiac je bezplatný (pozri Cenník).

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.

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}

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).

3. Prečítanie záznamu

# 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: 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>.

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

# 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

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:

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:

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).
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í.
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.
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:

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.

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.

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.

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.

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