1. API 概述
慧医云 REST API 为合作伙伴和企业自有系统提供标准化的数据交互接口，支持产品管理、库存查询、订单同步、UDI 追溯等多种业务场景。
API 采用 RESTful 设计风格，使用 JSON 格式传输数据，支持 HTTPS 加密通信和 API Key/OAuth 2.0 两种认证方式。
当前版本：v2.1，基础域名：https://api.huiyiyun.host/v2
2. 认证方式
API Key 认证（推荐用于系统集成）：在慧医云控制台 → "系统设置" → "API 管理"中生成 API Key。每个请求在 Header 中携带：
GET /v2/products HTTP/1.1
Host: api.huiyiyun.host
Authorization: Bearer ylt_sk_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json1
获取 API Key
登录慧医云控制台，进入"系统设置→API管理"，点击"创建密钥"，选择合适的权限范围后生成密钥对。
2
配置白名单
设置 API Key 的允许访问 IP 地址白名单，增强安全性。支持多 IP 和 CIDR 格式。
3
发起测试调用
使用 curl 或 Postman 发送测试请求，确认认证通过和返回数据正确。
3. 核心接口
| 接口 | 方法 | 路径 | 说明 |
|---|---|---|---|
产品查询 | GET | /v2/products | 按条件查询产品列表 |
产品详情 | GET | /v2/products/{id} | 获取单个产品详细信息 |
库存查询 | GET | /v2/inventory | 按产品/仓库查询实时库存 |
订单同步 | POST | /v2/orders | 创建/同步销售订单 |
UDI追溯 | GET | /v2/udi/{udiCode} | 根据 UDI 码查询追溯链路 |
证照查询 | GET | /v2/certificates | 查询供应商/产品证照状态 |
Webhooks | POST | /v2/webhooks | 配置事件推送回调 |
4. 接口示例 — 库存查询
// 请求示例：查询产品库存
GET /v2/inventory?productCode=GS1-06924315000017&warehouse=WH001
// 响应示例
{
"code": 0,
"message": "success",
"data": {
"productCode": "GS1-06924315000017",
"productName": "一次性使用无菌注射器 5mL",
"warehouse": "WH001",
"totalQuantity": 1500,
"availableQuantity": 1200,
"reservedQuantity": 300,
"batches": [
{
"batchNo": "LOT20240501",
"expiryDate": "2026-05-01",
"quantity": 800
},
{
"batchNo": "LOT20240315",
"expiryDate": "2026-03-15",
"quantity": 400
}
]
}
}ℹ️
说明
所有接口调用频率限制为：普通用户 100 次/分钟，标准版 1000 次/分钟。超出限制返回 HTTP 429。
5. 错误码说明
| HTTP状态码 | 错误码 | 说明 |
|---|---|---|
| 200 | 0 | 请求成功 |
| 400 | 1001 | 请求参数错误 |
| 401 | 1002 | API Key 无效或已过期 |
| 403 | 1003 | 权限不足 |
| 404 | 1004 | 资源不存在 |
| 429 | 1005 | 请求频率超限 |
| 500 | 9999 | 服务器内部错误 |