杉泰健康小屋集成

合作方将杉泰侧下发的用户 sign 提交至开放平台，由平台完成解析并返回标准化用户档案，供后续检测、上报等流程使用。

概述

接口路径前缀：/open/v1/integrations/shantai

方法	路径	说明
POST	`/open/v1/integrations/shantai/resolve-user`	解析用户 sign，返回用户档案

平台在解析成功后会将用户档案缓存至应用用户表（按应用 + 厂商 + 第三方用户 ID），便于后续链路复用，合作方无需关心落库细节。

接入前提

开放平台应用已由实施侧开通「杉泰健康小屋」集成（未开通将返回 422）。
合作方持有杉泰业务链路下发的 sign 字符串（由杉泰侧生成，勿在日志中明文长期留存）。
厂商侧对接凭证由晓葆平台配置与保管，合作方调用本接口时只需携带开放平台 App 签名，无需持有、也不应索取厂商侧密钥。

本页不提供加解密算法细节、密钥字段名或任何可用于伪造 sign 的材料。相关安全材料仅存在于平台服务端配置中。

鉴权说明

标准 S2S 签名。完整算法见鉴权说明。

Header	类型	必填	说明
`X-App-Id`	string	是	控制台「凭证管理」中的 App ID
`X-Timestamp`	integer	是	Unix 秒级时间戳，有效窗口 ±5 分钟
`X-Signature`	string	是	请求签名，见鉴权说明
`X-Request-ID`	string	否	链路追踪 ID，建议传入以便联调排查

解析用户档案

提交杉泰 sign。平台校验并解析后，向厂商侧查询用户信息，返回统一字段结构。失败时不会泄露厂商内部错误细节。

POST/open/v1/integrations/shantai/resolve-user

请求体（application/json）：

字段	类型	必填	说明
`sign`	string	是	杉泰下发的用户标识串；无效或过期将返回 422
`mock_user`	boolean	否	是否返回 Mock 用户档案。仅非生产环境生效；生产环境忽略并强制为 false

请求示例（占位符，非真实数据）：

POST /open/v1/integrations/shantai/resolve-user
X-App-Id: <your_app_id>
X-Timestamp: <unix_seconds>
X-Signature: <signature>
Content-Type: application/json

{
  "sign": "<shantai_sign_from_partner_flow>"
}

成功响应（200 OK，字段值为示意脱敏）：

{
  "success": true,
  "code": 0,
  "message": "用户信息获取成功",
  "data": {
    "third_user_id": "<third_user_id>",
    "name": "***",
    "gender": "MALE",
    "birthday": "YYYY-MM-DD",
    "height": null,
    "weight": null,
    "isHobby": null,
    "isMedicalHistory": null,
    "medicals": null,
    "osDiopter": null,
    "odVision": null,
    "isKneeWaistShoulderPain": null
  },
  "timestamp": "2026-07-20T15:30:00+08:00"
}

data 字段说明：

字段	类型	说明
`third_user_id`	string	第三方用户 ID（由 sign 解析得到）
`name`	string \| null	姓名
`gender`	string \| null	性别（厂商侧枚举，如 `MALE` / `FEMALE`）
`birthday`	string \| null	出生日期
`height`	number \| null	身高
`weight`	number \| null	体重
`isHobby`	any \| null	厂商侧扩展字段
`isMedicalHistory`	any \| null	厂商侧扩展字段
`medicals`	any \| null	厂商侧扩展字段
`osDiopter`	any \| null	厂商侧扩展字段
`odVision`	any \| null	厂商侧扩展字段
`isKneeWaistShoulderPain`	any \| null	厂商侧扩展字段

响应可能含健康相关字段。请按合作协议与合规要求处理、存储与展示，避免在前端日志、埋点中输出完整档案。

错误码

HTTP	说明	处理建议
422	`sign` 无效 / 过期 / 缺少必要字段，或当前应用未开通杉泰健康小屋集成	核对 sign 来源与时效；确认应用已开通集成
500	查询用户信息失败（厂商侧或网络异常）	稍后重试；持续失败联系实施排查（勿将厂商原始错误暴露给终端用户）
401	开放平台签名校验失败	检查 App 签名与时间戳
429	请求频率超限	降速并指数退避重试

模块概览