健康站设备接入

健康站固定部署设备通过「扫码启动 → 异步匹配用户 → 检测 → 上报报告」 标准流程接入晓葆开放平台。本规范（V1）为正式对外契约，全品类复用同一主流程， 品类差异通过已发布的 device_key 与指标库表达。

概述

适用场景

• 设备固定部署于健康站，用户到场检测
• 设备需先获取受检者身份与基础体征后才能开始检测
• 检测结果需结构化上报并关联到晓葆用户档案
• 典型能力：肺功能、多参数监测等专业检测设备

接口总览

Base URL

鉴权规范

所有三个接口使用相同鉴权方案：AppKey + HMAC-SHA256 签名， 与开放平台 Partner API 一致。

接入凭证

请求头（规范强制）

签名算法（三步）

第一步：计算请求体哈希

body_hash = SHA256(request_body)
// 请求体为空时对空字符串取哈希

第二步：拼接签名字符串（换行符 \n 分隔）

sign_string = METHOD + "\n" + URI + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + body_hash

第三步：计算签名

X-Signature = HMAC-SHA256(sign_string, appSecret)
// 结果为十六进制小写字符串

统一响应格式

{
  "success": true,
  "code": 0,
  "message": "ok",
  "data": {},
  "timestamp": "2026-07-10 10:00:00"
}

接入流程

每次检测分三个阶段：

阶段 A：建立检测会话（取码）
  设备 → POST /open/v1/device/qrcode
  开放平台返回 Base64 二维码（有效期 30 分钟）
  设备展示二维码

阶段 B：用户匹配（轮询）
  用户用晓葆小程序扫码授权
  设备每隔 ~2s 轮询 POST /open/v1/device/start-check-user
  data=null → 继续轮询
  data=用户信息 → 进入检测

阶段 C：报告回传
  检测完成 → 设备 POST /open/v1/device/report
  开放平台校验会话 + 报告结构 → 入库 → 触发 AI 解读

接口一：获取启动二维码

请求体

请求示例

POST /open/v1/device/qrcode
Content-Type: application/json
X-App-Key: your_app_key
X-Timestamp: 1722000000
X-Nonce: a1b2c3d4e5f6...（32位）
X-Signature: 签名十六进制字符串

{
  "device_no": "DEVICE_SN_001",
  "qr_code_id": "778bbb7711c74fd793b5da929b7b5ad6"
}

成功响应

{
  "success": true,
  "code": 0,
  "message": "ok",
  "data": {
    "expire_time": 1722503891000,
    "qr_code": "data:image/png;base64,iVBORw0KGgo...",
    "qr_code_id": "778bbb7711c74fd793b5da929b7b5ad6"
  },
  "timestamp": "2026-07-10 10:00:00"
}

业务规则：

• 同一 qr_code_id 在有效期内可刷新二维码
• 过期、接口异常、code != 0 时需重新取码（生成新 qr_code_id）

接口二：获取检测用户信息

请求体

响应：用户尚未扫码

{
  "success": true,
  "code": 0,
  "message": "ok",
  "data": null,
  "timestamp": "2026-07-10 10:00:05"
}
// → 继续轮询

响应：已匹配到用户

{
  "success": true,
  "code": 0,
  "message": "ok",
  "data": {
    "user_unique_id": "aa440ce5298147c0b69ab19ba9b08b02",
    "name": "张三",
    "sex": "1",
    "birthday": "1990-01-21",
    "height": 171,
    "weight": 75.1,
    "age": 36
  },
  "timestamp": "2026-07-10 10:00:12"
}
// → 开始检测，使用 user_unique_id 上报报告

轮询约定（规范强制）

1. 建议轮询间隔：2 秒
2. 继续轮询条件：success == true && data == null
3. 以下情况应重新取码：接口异常、success != true、超过过期时间
4. 设备必须使用平台 sex 枚举，不得自行改写含义
5. 取码成功后必须开始轮询本接口，平台监控取码后未轮询异常

接口三：上传检测报告

通用必填字段

metrics 约定

metrics 为键值对象：key 必须等于该 device_key 在平台指标库中已发布的standard_indicator_code，value 为对应数值或字符串。 具体指标清单由供应商在开放平台配置，经运营审核发布后生效；本规范不绑定任一品类字段。

请求示例

{
  "user_unique_id": "aa440ce5298147c0b69ab19ba9b08b02",
  "device_no": "DEVICE_SN_001",
  "qr_code_id": "778bbb7711c74fd793b5da929b7b5ad6",
  "report_no": "7934ccc943174189be57da11f5627734",
  "device_key": "YOUR_DEVICE_KEY",
  "tested_at": "2025-11-04 10:23:00",
  "conclusion": "检测结论文本（可选）",
  "metrics": {
    "indicator_code_a": 120,
    "indicator_code_b": 80
  },
  "report_file": {
    "type": "PDF",
    "content_base64": "JVBERi0..."
  },
  "raw_payload": {
    "note": "可选：保留供应商原始明细用于质控追溯"
  }
}

成功响应

{
  "success": true,
  "code": 0,
  "message": "ok",
  "data": null,
  "timestamp": "2026-07-10 10:05:00"
}

业务规则

• user_unique_id、device_no、qr_code_id 必须属于同一有效会话
• 同一 report_no 重复上传返回成功，不重复计次（幂等）
• 已发布指标库中标记为必填的标准指标缺失会被拒绝（5106）
• device_key 未发布的设备不允许正式上报

错误码

指标配置

接入新设备型号前，供应商必须在开放平台完成设备指标配置并经运营审核发布，device_key 发布后才允许正式上报。

device_key 约束

• 全局唯一，由平台分配/审核后确定，确定后不可修改
• 上报报告中的 device_key 必须完全等于已发布值
• 测试环境联调时可使用 draft 状态，生产环境必须为 published

standard_indicator_code 映射

metrics 的 key 与平台指标库中的 standard_indicator_code 一一对应。 供应商在开放平台为每个字段配置标准编码、单位、展示规则与是否必填； 运营审核发布后，上报与报告渲染均按已发布定义校验与展示。 品类差异全部落在指标库配置，不进入本运行时 API 路径。

接入准入清单

供应商联调前需满足以下条件，平台侧会按此验收后才允许正式上线：

供应商必备

• 在开放平台完成设备模型注册与指标配置，状态达到 published
• 支持本规范三接口（或通过适配组件支持）
• 支持 AppKey + HMAC-SHA256 签名鉴权
• 支持二维码展示与轮询用户流程
• 按已发布 device_key 与 standard_indicator_code 上报核心数据
• 提供测试设备 SN、示例报告 JSON 与联调环境

监控门禁（联调验收）