# 医疗保健 API：是什么以及如何工作

> 什么是医疗保健 API，一次调用如何工作，需要注意什么，以及一个免费的 FHIR R4 医疗保健 API，支持患者同意、出处和欧盟托管 — 附带示例和常见问题解答。

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

**医疗保健 API 是一种程序化接口，软件通过该接口读取和写入健康数据 — 患者记录、观察结果、诊断、药物、文档 — 以及授权对该数据的访问。** Anpheros Platform API 是一个基于患者控制的 HL7 FHIR R4 记录的医疗保健 API：应用程序使用它来存储和检索医疗数据，获取患者同意，并接收更改通知。

<!-- visual: hapi-hero -->

## 医疗 API 调用工作原理

无论供应商是谁，医疗 API 调用都会经过相同的检查点：谁在调用，哪个患者以及他们可能访问哪些数据，数据存储在哪里，谁编写了数据，以及谁需要知道数据已更改。

<!-- visual:hapi-request -->

## 医疗保健 API 的种类

| 种类 | 交换内容 | 典型用途 |
|---|---|---|
| FHIR REST API | 通过 HTTP 交换 FHIR 资源 (`GET /Observation?patient=…`) | 临床数据交换的现代标准 |
| SMART on FHIR / OAuth | FHIR API 的授权 | 允许第三方应用程序在用户许可下访问记录 |
| HL7 v2 消息 | 管道分隔的消息 (`ORU^R01` 用于结果，`ADT` 用于入院) | 实验室和医院系统，通常通过接口而非 HTTP |
| 文档交换 | 临床文档 (PDF, CDA, FHIR 文档包) | 摘要、出院信、转诊 |
| 专有 REST API | 供应商特定的 JSON | 单个产品的自有移动应用程序或集成 |

Anpheros 将前两种作为其核心，接受 HL7 v2 实验室结果作为输入，存储带有原始文件的文档，并生成 FHIR 文档包 (国际患者摘要)。它还为不想直接使用 FHIR 的开发人员提供了基于相同数据的更简单的 REST API。

## 选择医疗保健 API 时需要考虑的因素

<!-- visual:hapi-checklist:replace -->

- **标准数据模型**：这样数据就可以在系统之间移动，无需自定义映射。
- **患者可控的授权**：而不仅仅是应用程序可控的凭证。
- **溯源**：谁写入了每个值，代表谁，来自哪个系统。
- **历史记录**：版本控制而非静默覆盖。
- **可审计性**：不仅是写入操作，也包括读取操作。
- **安全重试**（幂等性）和**可预测的错误**：因为健康数据绝不能重复或丢失。
- **隔离**：共享相同基础设施的应用程序之间需要隔离。
- **数据驻留**：与患者所在位置匹配。

本页的其余部分将展示这些因素在 Anpheros API 中的具体体现。

## Anpheros API 概览

| 接口 | 基础路径 | 用途 |
|---|---|---|
| FHIR R4 | `/fhir/R4` | 26 种资源类型；读、搜索、创建、更新、删除、历史记录、事务、`$everything`、`$summary`、`$validate` |
| REST v1 | `/v1` | patients、observations、conditions、medications、documents、timeline、provenance、AI context、lab import、terminology、webhooks |
| OAuth 2.1 | `/oauth` | consent page、tokens (PKCE)、revocation、OpenID Connect keys |
| Patient side | `/me` | 个人记录、访问者、访问日志、撤销 |
| Discovery | `/fhir/R4/metadata`、`/fhir/R4/.well-known/smart-configuration`、`/openapi.json` | API 的机器可读描述 |

Base URL: `https://platform.anpheros.com`。沙盒和生产环境共享此 URL；密钥决定数据平面。

### 认证

- **API keys** (`sk_test_…`、`sk_live_…`) 用于您的服务器；它们可以看到您的项目创建的患者。
- **OAuth access tokens** (`at_…`) 用于代表患者在获得同意后进行操作的应用程序。

```bash
curl https://platform.anpheros.com/v1/patients -H "Authorization: Bearer $KEY"
```

### 安全写入

`POST` 请求接受一个 `Idempotency-Key`：具有相同密钥的重试请求将返回原始响应且不会创建任何内容。每次写入都会获得一个 `Provenance`；作者类型在请求体 (`author_type`) 或请求头（如 `X-Anpheros-Author-Type`、`X-Anpheros-Source-System`、`X-Anpheros-Origin-Id` 和 `X-Anpheros-On-Behalf-Of`）中发送。

```bash
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": "29463-7", "display": "Body weight", "category": "vital-signs",
          "value": 71.4, "unit": "kg", "effective_at": "2026-09-28T07:30:00Z", "author_type": "patient"}'
```

### 错误和限制

FHIR 端点返回 `OperationOutcome`；其他端点返回 `{"error": {"type", "message", "field"}}`。每个响应都包含 `Anpheros-Request-Id`。默认限制为每分钟每个密钥和每个 IP 600 个请求。[错误](https://developers.anpheros.com/zh/guides/errors) · [限制](https://developers.anpheros.com/zh/guides/limits)

### 事件

用于 `resource.created`、`resource.updated`、`resource.deleted`、`consent.granted`、`consent.revoked`、`document.finalized` 和 `ping` 的签名 Webhook。[Webhooks](https://developers.anpheros.com/zh/guides/webhooks)

## 在 FHIR 和 REST v1 之间进行选择

当您已经在使用 FHIR、需要 `/v1` 未涵盖的资源类型（例如 `Immunization`、`Procedure` 或 `CarePlan`），或者需要与其他 FHIR 系统交换数据时，请使用 **FHIR**。对于希望在常见情况下使用扁平化 JSON 的应用程序代码，请使用 **REST v1**。两者读写相同的资源，使用相同的 ID，因此一个项目可以混合使用它们。[Medical data API](https://developers.anpheros.com/zh/guides/medical-data-api) 详细描述了数据操作。

## 常见问题解答

### 什么是医疗保健 API？
一种程序化接口，软件通过该接口读取和写入健康数据 — 患者记录、观察结果、诊断、药物和文档 — 并通过该接口授权访问这些数据。现代医疗保健 API 使用 HL7 FHIR R4 进行数据交换，并使用 OAuth 2.0 或 2.1 与 SMART on FHIR 进行授权。

### 医疗保健 API 和 FHIR API 有什么区别？
FHIR 是医疗保健 API 可以遵循的标准之一。FHIR API 通过 REST 交换 FHIR 资源；医疗保健 API 也可能接受 HL7 v2 消息、文档或专有 JSON。Anpheros 提供 FHIR R4 API 和基于相同数据的更简单的 REST API。

### 有免费的开发者医疗保健 API 吗？
是的。Anpheros 沙盒是免费且自助服务的：使用 Google 登录，获取 API 密钥，并使用 FHIR R4 或 REST 处理 30 位合成患者。生产环境起价为每月 49 欧元，第一个月免费。

### 患者如何授予医疗保健 API 访问权限？
通过 OAuth 2.1 和 PKCE：应用程序将用户引导至一个带有 SMART on FHIR 范围的同意页面；用户选择要共享的内容和时长，可以看到访问日志，并可以随时撤销访问权限。

### 数据存储在哪里？
在欧盟：服务及其数据库运行在 Google Cloud `europe-west4`（荷兰）。

### 我应该选择哪个医疗保健 API？
比较数据标准、谁授权访问、来源和审计、数据驻留、重试和错误行为，以及是否可以免费使用真实数据进行测试。[医疗保健 API 平台：包含内容及选择方法](https://developers.anpheros.com/zh/guides/healthcare-api-platform) 将这些内容转化为可以询问任何供应商的问题。

<!-- visual:cta-hapi -->

## 相关资源

- [EHR API 和医疗记录 API](https://developers.anpheros.com/zh/guides/ehr-api)
- [医疗保健 API 平台：包含内容及选择指南](https://developers.anpheros.com/zh/guides/healthcare-api-platform)
- [如何使用 TypeScript 构建医疗保健 API](https://developers.anpheros.com/zh/guides/healthcare-api-typescript)：使用 Express 的分步教程
- [如何使用 FHIR R4 存储医疗记录](https://developers.anpheros.com/zh/guides/store-medical-records-fhir)：使用 curl 的分步教程
- [带有患者同意的医疗保健 API](https://developers.anpheros.com/zh/guides/healthcare-api-patient-consent)
- [SMART on FHIR 后端](https://developers.anpheros.com/zh/guides/smart-on-fhir-backend)
- [医疗数据 API](https://developers.anpheros.com/zh/guides/medical-data-api)
- [FHIR 平台](https://developers.anpheros.com/zh/guides/fhir)
- [医疗保健数据互操作性](https://developers.anpheros.com/zh/guides/interoperability)
- [医疗保健集成](https://developers.anpheros.com/zh/guides/healthcare-integrations)
- [API 参考 (OpenAPI)](https://developers.anpheros.com/docs) · [身份验证和 OAuth](https://developers.anpheros.com/zh/guides/authentication)