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

入门

从 API 密钥到在沙盒中读取和写入患者的 FHIR R4 记录：密钥、首次调用、带来源的写入、文档、AI 上下文、IPS、同意、Webhook 和实验室报告。

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）中重置测试患者会将他们恢复到原始状态，并赋予新的 ID；您自己创建的患者不受影响。每个合成患者在重置后会保留一个稳定的标识符：Patient?identifier=https://anpheros.com/fhir/sid/sandbox-persona|p02 始终是 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}

沙盒限制虽然慷慨但也是有限的：每个项目每天 10,000 次资源写入，除了合成患者外，您还可以拥有 50 名自己的患者，250 MB 的文档（请参阅限制）。

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"

Ids 在 /v1 和 /fhir/R4 中是相同的；每个 v1 对象都带有其 fhir 引用。 _summary=count 只返回总数；_elements=code,effectiveDateTime 返回标记为 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"
}'

响应是已存储的 observation，包含 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。
成对 ID: 你看到的患者 ID 是你自己的。另一个项目会看到同一个人，但使用不同的 ID。可以自由存储我们的 ID；切勿尝试关联它们。
来源: 每次写入都会生成一个 Provenance 资源。没有任何内容会被静默覆盖；历史记录可在 /fhir/R4/{Type}/{id}/_history 处找到。
错误: FHIR 端点返回 OperationOutcome；/v1 和 /admin 返回 {"error": {"type", "message", "field"}}。每个响应都包含 Anpheros-Request-Id；在联系我们时请引用它。
限制: 默认每分钟 600 个请求/密钥，每页 200 个项目，每个文档 25 MB。

7. AI 模型上下文

与其提取原始记录并决定哪些适合提示，不如向平台请求上下文：

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 生成的值绝不会与事实混淆：它们仅出现在 ai_notes 下。也接受明确的需求： "needs": ["labs:4548-4", "vitals:trend:85354-9", "timeline:180d"]。

8. 标准

GET /fhir/R4/Patient/{id}/$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 并提供您的重定向 URI （public 用于支持 PKCE 的移动/Web 应用，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 天，使用时轮换）以及患者 ID。
使用 Authorization: Bearer at_… 调用 API。您只能看到该患者、在范围（scopes）内指定的资源类型和操作；超出范围的读取请求将返回 403，搜索结果将被过滤。

用户可以随时从 Anpheros 中撤销访问权限；下一次调用将返回 401。每个授权都会被镜像为一个 FHIR Consent 资源，并且在此授权下的每次访问都会被记录并对用户可见。发现：/.well-known/smart-configuration。

10. Webhooks

让平台主动调用您，而不是轮询：

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 （在两个 SDK 中均为 verifyWebhookSignature）。事件携带 ID 和版本，不包含临床数据。详情、重试和示例：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=。

谁在您的应用程序背后工作？在带有项目密钥的任何 /v1 或 /fhir/R4 请求上发送 X-Anpheros-Acting-As: PractitionerRole/<id>（或 Practitioner/<id>）。该人员必须存在于目录中且处于活动状态。该引用将被写入访问日志，成为该请求写入的作者（除非您设置了 X-Anpheros-Author-Ref），并在其连接中以姓名显示给患者（“Ana Popescu 医生 · Clinica Dente 读取了您的实验室结果”）。

12. 一次调用获取所有实验室报告

发送完整的实验室报告（CSV、HL7 v2 ORU^R01 或 JSON），即可获取包含 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 profile 进行检查，对于实验室观察结果，还会根据 HL7 Europe 实验室报告规则进行检查。写入操作不会因为 profile 原因而被拒绝（结构性 FHIR 错误仍然会被拒绝）；当缺少某些内容时，响应会携带

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

修复其命名的内容，该资源将被包含在患者的 $summary 中。于 2026 年 9 月 22 日添加的资源类型：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