第三方 HIS 提供
接入申请资料
- 01厂商与联系人
厂商、产品版本、技术负责人及故障联系人
- 02医院标识
接入医院及该医院在 HIS 中的稳定外部编码
- 03固定出口 IP
实际调用 API 的服务器公网出口地址
- 04同步范围
房间、床位、人员、宠物、住院、诊断或医嘱
- 05外部 ID 规则
资源唯一编号、更新时间与状态变更语义
- 06调用规模
医院数量、预计日请求量与峰值请求量
开始之前
先明确双方各自需要准备什么
资料一次准备完整，可以避免联调期间反复确认医院身份、权限范围和数据归属。
EasyChong 交付
沙箱接入凭证包
- Client ID 与 Client Secret
按“厂商 × 医院 × 环境”独立签发
- 环境与服务地址
沙箱环境、Token 地址和 API Base URL
- 授权范围
Scopes、IP 白名单与每分钟请求限制
- 测试与验收说明
测试医院、调用顺序、错误处理和上线标准
无需传递 tenant_id
EasyChong 根据凭证自动确定医院租户。外部调用方不得提交内部租户编号。
标准接入路径
六步完成从申请到正式上线
每一步都有明确输入、动作和完成标准。生产凭证只在沙箱验收通过后签发。
-
01
双方
确认接入范围
确认医院授权、主数据来源、同步资源及业务动作语义。
产物：接入确认单 -
02
EasyChong
开通沙箱凭证
绑定测试医院、IP 白名单、Scopes 和限流策略。
产物：沙箱凭证包 -
03
第三方
获取访问令牌
使用 Client ID 和 Secret 获取短期 Access Token。
完成标准：Token 请求成功 -
04
第三方
完成首次调用
提交测试资源，并使用 operationId 查询异步结果。
完成标准：操作被正确受理 -
05
双方
全链路联调验收
跑通入院、诊断、医嘱、停嘱和出院，并核对异常场景。
产物：联调验收记录 -
06
EasyChong
签发生产凭证
生产与沙箱彻底隔离，先影子运行，再逐院开放。
产物：生产接入凭证
五分钟快速开始
拿到凭证后，先完成这三次调用
示例使用占位符，必须替换为已发放的沙箱信息。不要把 Client Secret 写进前端或提交到代码仓库。
AUTHENTICATE
获取 Access Token
curl -u "$CLIENT_ID:$CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
https://openapi.easychong.cn/oauth2/token令牌有效期 10 分钟。有效期内复用，过期或收到 401 后重新获取。
CREATE RESOURCE
提交第一个房间
curl -X PUT \
https://openapi.easychong.cn/openapi/v1/rooms/room-001 \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: room-001-v1" \
-d '{
"name": "一楼住院区",
"roomType": "DOG",
"status": "ACTIVE",
"sourceVersion": "1",
"sourceUpdatedAt": "2026-08-20T14:30:00+08:00"
}'所有写请求都必须携带唯一 Idempotency-Key 和真实的 sourceUpdatedAt。
TRACK RESULT
查询异步处理结果
curl \
-H "Authorization: Bearer $ACCESS_TOKEN" \
https://openapi.easychong.cn/openapi/v1/operations/$OPERATION_ID写请求返回 202 和 operationId，不代表核心系统已处理完成。请查询最终状态。
202Accepted
请求已安全进入处理队列
{
"operationId": "8322b4f8-…",
"status": "RECEIVED",
"traceId": "ec-…",
"statusUrl": "/openapi/v1/operations/8322b4f8-…",
"duplicate": false
}
编码前必读
五条规则决定联调是否稳定
这些不是可选建议，而是接口中心确保租户隔离、历史一致和故障可恢复的基础。
不要传 tenant_id
医院租户由 Client ID 的绑定关系决定，业务报文中不接受内部租户编号。
外部 ID 必须稳定
同一资源永久使用同一个 externalId，不要使用名称或当天流水号替代。
每次写入都要幂等
同一业务动作重试时复用 Idempotency-Key，内容变化必须使用新键。
旧数据不能覆盖新数据
sourceUpdatedAt 必须来自源系统；比已受理版本更旧的请求会被拒绝。
202 后继续查询结果
记录 operationId 和 traceId，根据状态处理重试、映射或人工介入。
推荐同步顺序
先基础资料，再进入临床流程
上游资源依赖未建立时，操作可能进入 NEEDS_MAPPING 或失败队列。
- 1房间 / 床位 / 人员
- 2主人 / 宠物
- 3住院
- 4诊断
- 5医嘱
- 6停嘱 / 出院
错误与重试
根据状态码采取动作，不要无条件重发
错误响应包含稳定的 errorCode、traceId 和 retryable 标识，排查时请优先保留这些信息。
| 状态码 | 含义 | 第三方处理方式 |
|---|---|---|
400 | 字段或请求格式错误 | 修正数据后使用新的 Idempotency-Key 重试 |
401 | 凭证或 Token 无效 | 检查环境与凭证；Token 过期则重新获取 |
403 | Scope 或 IP 不允许 | 停止重试，联系 EasyChong 核对授权 |
409 | 幂等冲突或版本过旧 | 核对业务版本，禁止直接覆盖 |
429 | 超过调用频率 | 遵循 Retry-After 并降低并发 |
5xx | 暂时性服务异常 | 指数退避；持续失败时携带 traceId 联系支持 |
上线前必须全部通过
- Token、Scope 和 IP 白名单验证通过
- 重复请求与 Idempotency-Key 冲突测试通过
- 旧版本、乱序请求和限流退避测试通过
- 人员映射与 NEEDS_MAPPING 流程验证通过
- 入院到出院的完整生命周期对账通过
- 双方故障联系人和暂停机制确认完成
开发者资源
需要更详细的字段和模型？
接入首页负责流程，技术文档负责精确定义。请始终以当前 V1 OpenAPI 描述为准。
联调支持
查看申请资料
出现问题时，请提供可定位的信息
联系 EasyChong 对接负责人时，请提供环境、请求时间、operationId、traceId 与 errorCode。不要发送 Client Secret 或真实临床正文。