# 入门

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

Source: https://developers.anpheros.com/zh/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/zh/guides/pricing)）。

## 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。

```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 MB 的文档（请参阅 [限制](https://developers.anpheros.com/zh/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"
```

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

响应是已存储的 observation，包含 `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`。
- **成对 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 模型上下文

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

```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 生成的值绝不会与事实混淆：它们仅出现在 `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 密钥可以看到您的项目创建的患者。要访问个人的现有记录，请向他们提出请求：

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

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

## 10. Webhooks

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

```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`
（在两个 SDK 中均为 `verifyWebhookSignature`）。事件携带 ID 和版本，不包含临床数据。
详情、重试和示例：[webhooks.md](https://developers.anpheros.com/zh/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=`。

谁在您的应用程序背后工作？在带有项目密钥的任何 `/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](https://developers.anpheros.com/zh/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 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`](https://developers.anpheros.com/zh/guides/webhooks)。