概述
本文档面向接入和使用本平台 FHIR API 的开发者、集成实施人员及业务技术团队，介绍平台提供的标准化医疗健康数据存储与访问能力，并说明接口调用、资源操作、搜索检索、事务处理及错误响应等内容。
本平台提供基于标准 FHIR API 的数据服务能力，支持对医疗健康数据进行统一建模、标准化访问和结构化交换。调用方可通过标准 HTTP 方法对 FHIR 资源执行创建、读取、更新、删除、局部更新、条件搜索以及批量事务处理等操作，从而满足临床应用集成、科研数据治理、跨系统数据交换和业务服务化等场景需求。
平台接口采用资源化和 RESTful 风格设计，资源内容以标准 FHIR 结构进行组织，便于围绕 Patient、Observation、Encounter 等核心资源构建业务流程。同时，平台支持基于访问令牌的鉴权机制，确保接口调用过程中的身份认证与访问控制要求得到满足。
术语信息
下表汇总了调用本平台 FHIR API 时常见的主要概念与术语，便于在阅读后续章节前建立统一认识。
术语 | 说明 |
FHIR | Fast Healthcare Interoperability Resources，医疗健康领域的数据交换与互操作标准。本平台接口遵循该标准进行资源建模与交互。 |
baseUrl（服务基地址） | FHIR 服务的根访问地址，例如 https://HOSTNAME/INSTANCE_ID/fhir，其中 HOSTNAME 为 FHIR 服务访问域名，INSTANCE_ID 为 FHIR 服务实例 ID。腾讯云 SaaS 场景请在 腾讯健康数据服务控制台 > 实例概览中获取，独立部署场景以部署方提供的服务访问域名和实例 ID 为准。资源读写、搜索及 Bundle 提交均基于此地址构造请求 URL。 |
Content-Type | 请求体或响应体的 MIME 类型。写入类请求通常为 application/fhir+json；Patch 请求通常为 application/json-patch+json。 |
Resource（资源） | 平台存储和访问医疗健康数据的基本单元，以标准 FHIR JSON 结构表达，例如患者、检验结果、就诊记录等。 |
ResourceType（资源类型） | 资源的类别名称，用于区分不同业务实体，如 Patient、Observation、Encounter。请求 URL 中通常以资源类型作为路径段。 |
id（资源 ID） | 资源在平台内的唯一标识。读取、更新、删除等操作通常通过 [baseUrl]/[resourceType]/[id] 访问目标资源。 |
Reference（引用） | 资源之间的关联关系，通常以 ResourceType/id 形式指向另一条资源，例如 Patient/199963。 |
ETag / versionId（版本标识） | 标识资源当前版本的信息。创建或更新成功后，响应头中的 ETag 与资源 meta.versionId 可用于版本控制与并发更新判断。 |
_history | 资源历史版本访问路径后缀。通过 [baseUrl]/[resourceType]/[id]/_history/[versionId] 可读取指定历史版本。 |
Bundle | 一种特殊的 FHIR 资源，用于封装多条记录或多次交互。搜索接口返回结果 Bundle；事务/批处理接口通过提交 Bundle 批量执行操作。 |
Placeholder ID（占位符 ID） | 事务 Bundle 中为尚未落库资源分配的临时标识，通常采用 urn:uuid:{uuid} 形式，用于在同一请求内建立资源引用关系。 |
transaction / batch | Bundle 的两种处理模式。 - transaction：表示原子事务，全部条目要么一起成功，要么一起失败。 - batch：表示批处理，各条目独立执行。 |
Search Parameter（搜索参数） | 附加在资源类型 URL 后的查询参数，用于按条件筛选资源，例如 ?name=张三&gender=male。 |
OperationOutcome | 用于描述操作结果、校验信息或错误详情的 FHIR 资源，常见于删除失败或业务校验未通过等场景。 |
API Key | 调用方身份标识，用于向鉴权服务申请访问令牌。可在创建 FHIR 服务实例后于 API 密钥管理页面获取。 |
API Secret | 调用方身份密钥，与 API Key 配合使用，用于计算请求签名。请妥善保管，避免泄露。 |
Signature（签名） | 基于 API Secret 对 apiKey + timestamp 进行 HMAC-SHA256 计算得到的签名值，用于鉴权接口的身份校验。 |
AccessToken（访问令牌） | 调用鉴权接口成功后返回的 JWT 令牌，用于访问 FHIR 业务接口。 |
Bearer Token | 访问 FHIR 接口时在 HTTP 请求头中携带令牌的方式，格式为 Authorization: Bearer 。 |
内容说明
本文档主要包含以下内容：
API 概览：说明平台 API 的整体能力范围、主要接口分类、调用方式概述及典型适用场景。
调用方式：说明请求结构、公共参数、接口鉴权流程以及返回结果的通用规则。
FHIR 操作相关接口：说明资源基础操作、搜索操作以及 Bundle 请求接口等能力。
错误码：汇总常见错误码及其典型触发场景，便于调用方排查问题。
通过阅读本文档，调用方可以快速了解平台接口体系，并按照统一规范完成接口接入、资源访问、数据检索与批量处理。
整体调用流程
调用方在访问 FHIR 资源接口前，整体调用流程如下：
1. 创建 FHIR 服务实例并创建服务 API 密钥。调用方保存
API Key 和 API Secret。2. 使用
API Key、API Secret 和时间戳生成签名。3. 调用鉴权接口获取基于 JWT 的
AccessToken。4. 使用
AccessToken 访问 FHIR RESTful 接口。5. FHIR 服务向鉴权服务校验
AccessToken。6. 鉴权通过后返回业务结果，否则拒绝请求。
