# 医疗数据 API

> 每种医疗数据在 Anpheros API 中的位置、如何编码、如何编写、过滤、追溯、更正和删除——附带可运行的示例。

Source: https://developers.anpheros.com/zh/guides/medical-data-api

**医疗数据 API 为软件提供了结构化的方式来访问患者记录的内容：创建患者、记录血压读数、列出当前用药、附加实验室报告、追溯谁编写了什么。** 本页描述了 Anpheros API 的数据操作——哪种医疗数据存放在哪里、如何编码、以及如何读回——并附带可在沙盒环境中运行的示例。

应用程序使用这些操作将 Anpheros 作为其产品的医疗数据库：患者记录存储在平台的 HL7 FHIR R4 存储中，应用程序通过 API 读取和写入这些记录，而不是维护自己的医疗数据表。

关于更广泛的图景（身份验证、授权、事件），请参阅 [医疗保健 API](https://developers.anpheros.com/zh/guides/healthcare-api)。

## 每种医疗数据去向

| 医疗数据 | REST v1 | FHIR 资源 | 编码 |
|---|---|---|---|
| 人员 | `POST /v1/patients` | `Patient` | name, birth date, gender, identifiers |
| 生命体征、实验室结果、症状、活动、调查 | `/v1/patients/{id}/observations` | `Observation` | LOINC (症状: ICD-10 chapter R); UCUM units |
| 诊断和问题 | `/v1/patients/{id}/conditions` | `Condition` | ICD-10 |
| 药物 | `/v1/patients/{id}/medications` | `MedicationStatement` | ATC, product name kept as text |
| 文档 (PDF, 图片) | `/v1/patients/{id}/documents` | `DocumentReference` | LOINC document kinds |
| 整份实验室报告 | `POST /v1/patients/{id}/labs/import` | `Observation` (laboratory) | LOINC where known, the lab's own code otherwise |
| 服用或跳过的剂量、疫苗接种、过敏、手术、报告、护理计划、目标、转诊、就诊、预约、护理团队、家族史、问卷 | `/fhir/R4/{type}` | `MedicationAdministration`, `Immunization`, `AllergyIntolerance`, `Procedure`, `DiagnosticReport`, `CarePlan`, `Goal`, `ServiceRequest`, `Encounter`, `Appointment`, `CareTeam`, `FamilyMemberHistory`, `QuestionnaireResponse` | per [FHIR code systems](https://developers.anpheros.com/zh/guides/fhir-code-systems) |

REST v1 对象和 FHIR 资源是相同的记录，具有相同的 id；每个 v1 对象都携带其 `fhir` 引用。

## 写入医疗数据

```bash
# a lab result with its reference range, linked to the report it came from
curl -X POST https://platform.anpheros.com/v1/patients/$PID/observations \
     -H "Authorization: Bearer $KEY" -H 'content-type: application/json' -H "Idempotency-Key: $(uuidgen)" -d '{
  "code": "4548-4", "display": "Hemoglobin A1c", "category": "laboratory",
  "value": 6.4, "unit": "%", "effective_at": "2026-09-01T08:00:00Z",
  "reference_range": {"low": 4.0, "high": 5.6},
  "derived_from": ["DocumentReference/'$DOC'"], "author_type": "import"
}'
```

- **Observation categories:** `vital-signs`, `laboratory`, `symptom`, `activity`, `survey`, `exam`, `imaging`, `social-history`。
- **Composite measurements** such as blood pressure use `components` (systolic `8480-6`, diastolic `8462-4` inside the panel `85354-9`)。
- **Author types:** `patient`, `practitioner`, `device`, `import`, `ai`。Without one, the platform records `import`。
- **Codes you do not know by heart:** `GET /v1/terminology/loinc?q=hba1c` searches the bundled LOINC subset and `GET /v1/search?q=metformin` the catalog of symptoms, conditions and medicines; an observation written without a display name gets the LOINC name automatically。

## 读取医疗数据

```bash
curl "https://platform.anpheros.com/v1/patients/$PID/observations?category=laboratory&code=4548-4&from=2026-01-01" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/conditions?clinical_status=active" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/medications?status=active" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/timeline?from=2026-06-01" -H "Authorization: Bearer $KEY"
```

| 端点 | 过滤器 |
|---|---|
| observations | `category`, `code`, `from`, `to` |
| conditions | `clinical_status` |
| medications | `status` |
| documents | `kind` |
| timeline | `from`, `to`, `types` |

列表支持分页，使用 `limit` 和 `cursor`。**timeline** 将观察值、病症、用药、文档、就诊、预约、疫苗接种和护理事件合并到一个按时间顺序排列的列表中——这是患者病史屏幕的自然输入。

对于 REST 过滤器未涵盖的任何内容，请使用 FHIR 搜索：`GET /fhir/R4/Observation?patient=$PID&code=http://loinc.org|4548-4&_sort=-date` ([FHIR 平台](https://developers.anpheros.com/zh/guides/fhir))。

## 追踪和更正数据

- **谁编写的：** `GET /v1/patients/{id}/provenance/{type}/{resourceId}` — 每个版本一个条目，包含作者类型、项目、组织和源系统。
- **每个版本：** `GET /fhir/R4/{type}/{id}/_history`；使用 `If-Match` 更新，以避免覆盖他人的更改。
- **所有权：** 经同意，您可以读取其他组织编写的内容，但只能更改或删除您项目编写的内容（否则为 `403`）。
- **删除：** `DELETE /v1/{observations|conditions|medications}/{id}`；删除一个 `Patient` 会删除整个记录。

## 文档

创建文档（您将获得一个上传目标），通过平台或直接上传字节到存储，然后进行最终化。最终化后，原始文档将不可变；其 SHA-256 和大小将被记录。每个文件最大 25 MiB。

## 相关

- [如何规范化医疗数据](https://developers.anpheros.com/zh/guides/normalize-medical-data)：代码、单位、日期、重复项、验证
- [医疗数据溯源详解](https://developers.anpheros.com/zh/guides/medical-data-provenance)：谁写了什么，以及如何记录
- [Healthcare API](https://developers.anpheros.com/zh/guides/healthcare-api)
- [患者病历](https://developers.anpheros.com/zh/guides/patient-medical-record)
- [构建医疗应用](https://developers.anpheros.com/zh/guides/build-a-healthcare-app)
- [API 参考 (OpenAPI)](https://developers.anpheros.com/docs) · [入门](https://developers.anpheros.com/zh/guides/getting-started)