图腾API开放平台 V0.15

1. 平台概述

1.1 适用范围

图腾API开放平台提供完整的开放接口体系，支持MQTT和HTTP两种协议，实现设备的远程控制、状态同步和数据上报。同时提供开放API认证接口和业务查询接口，助力合作伙伴快速集成。

重要说明：协议选择规则

• 所有具备上机位的设备，在与图腾服务器进行数据交互时，一律采用HTTP协议进行通信
• 该规则具有最高优先级，覆盖其他协议选择规则
• 上机位设备需严格遵循第3章节HTTP协议规范

1.2 认证机制

设备认证参数

参数名	说明	获取方式
`device-key`	设备唯一标识符	图腾公司提供
`password`	设备认证密码	Base64(device-key)

MQTT协议认证

配置项	值
连接地址	`mqtts://mqtt.to-term.cn`
端口	8883
用户名	`{device-key}`
密码	`Base64({device-key})`
QoS级别	1（至少一次送达）
Retain标志	0（不保留消息）

HTTP协议认证（设备端）

设备数据上传接口需要在请求头中携带：
X-Device-Key: {device-key}

HTTP协议认证（业务端）

业务系统需先获取Token，后续请求在Header中携带：
Authorization: Bearer {accessToken}

1.3 环境配置

环境	MQTT地址	HTTP地址	用途
生产环境	`mqtts://mqtt.to-term.cn:8883`	`https://api.to-term.cn`	正式运营
测试环境	`mqtts://mqtt-test.to-term.cn:8883`	`https://api-test.to-term.cn`	开发测试

2. MQTT接口规范

2.1 Topic定义

用途	方向	Topic模板	QoS	Retain	说明
命令请求	云服务→设备	`server/{provider-name}/{device-key}/cmd/req`	1	0	云端下发命令
命令响应	设备→云服务	`client/{provider-name}/{device-key}/cmd/resp`	1	0	设备返回响应

参数说明：
• provider-name：设备厂商名称（由图腾分配）
• device-key：设备唯一标识

2.2 设备订阅/发布规则

设备端	云端
订阅：`server/{provider-name}/{device-key}/cmd/req`	订阅：`client/{provider-name}/{device-key}/cmd/resp`
发布：`client/{provider-name}/{device-key}/cmd/resp`	发布：`server/{provider-name}/{device-key}/cmd/req`

2.3 命令列表

命令	方向	说明
START	云→设备	启动设备
STOP	云→设备	停止设备
START_RESPONSE	设备→云	启动响应
STOP_RESPONSE	设备→云	停止响应
INIT_STOP	设备→云	主动停止通知
ON	设备→云	运行心跳(QoS0设备)

2.4 START命令

方向：服务器→设备

Topic：server/{provider-name}/{device-key}/cmd/req

请求参数

{
  "command": "START",
  "request_id": "0190abcd-1234-5678-90ab-cdef12345678",
  "data": {
    "user_id": 12345,
    "program_id": 1,
    "duration": 1800,
    "device_params": {
      "intensity": 50,
      "mode": "auto"
    }
  }
}

参数路径	类型	必填	说明
command	String	是	固定值：`"START"`
request_id	String	是	UUID v7格式，请求唯一标识
data	Object	否	启动参数
data.user_id	Integer	否	用户ID（32位）
data.program_id	Integer	否	方案ID（32位）
data.duration	Integer	否	运行时长（秒），超时需自动退出
data.device_params	Object	否	设备特定参数

响应参数（START_RESPONSE）

方向：设备→服务器

Topic：client/{provider-name}/{device-key}/cmd/resp

{
  "command": "START_RESPONSE",
  "success": true,
  "request_id": "0190abcd-1234-5678-90ab-cdef12345678",
  "message": "设备启动成功",
  "data": {
    "user_id": 12345,
    "program_id": 1,
    "device_params": {
      "intensity": 50,
      "mode": "auto"
    }
  }
}

2.5 STOP命令

方向：服务器→设备

Topic：server/{provider-name}/{device-key}/cmd/req

请求参数

{
  "command": "STOP",
  "request_id": "0190efgh-1234-5678-90ab-cdef12345678",
  "data": {
    "user_id": 12345,
    "program_id": 1
  }
}

响应参数（STOP_RESPONSE）

{
  "command": "STOP_RESPONSE",
  "success": true,
  "request_id": "0190efgh-1234-5678-90ab-cdef12345678",
  "message": "设备已停止",
  "data": {
    "user_id": 12345,
    "program_id": 1,
    "duration": 900,
    "device_params": {
      "intensity": 50,
      "mode": "auto"
    },
    "report_metrics": {
      "total_steps": 5400,
      "calories": 180
    }
  }
}

注意：停止时必须携带duration（实际运行时长）字段

2.6 INIT_STOP命令

方向：设备→服务器

Topic：client/{provider-name}/{device-key}/cmd/resp

设备在正常训练完成时主动发送此命令。

{
  "command": "INIT_STOP",
  "success": true,
  "request_id": "0190ijkl-1234-5678-90ab-cdef12345678",
  "message": "训练完成",
  "data": {
    "user_id": 12345,
    "program_id": 1,
    "duration": 1800,
    "device_params": {
      "intensity": 50
    },
    "report_metrics": {
      "total_steps": 10800,
      "calories": 360,
      "completion_rate": 1.0
    }
  }
}

参数说明：与STOP_RESPONSE结构一致

2.7 ON命令（心跳）

方向：设备→服务器

Topic：client/{provider-name}/{device-key}/cmd/resp

仅限QoS=0设备使用，在RUNNING状态下每5秒发送一次。

{
  "command": "ON",
  "success": true,
  "message": "运行中"
}

3. HTTP接口规范

3.1 开放API - 获取Token

接口说明

业务系统通过此接口获取访问令牌（Token），用于后续业务接口的鉴权认证。

接口定义

属性	值
URL	POST `/api/open/auth/token`
Content-Type	`application/json`
鉴权要求	无需Token

认证方式

支持以下三种认证方式（任选其一）：

方式1：appId + appSecret

{
  "appId": "elite_openapi_app",
  "appSecret": "Elite@2026!"
}

方式2：Base64编码凭证

{
  "base64Credentials": "ZWxpdGVfb3BlbmFwaV9hcHA6RWxpdGVAMjAyNiE="
}

方式3：HTTP Basic认证

Authorization: Basic base64(appId:appSecret)

响应参数

成功响应（200）

{
  "code": 200,
  "msg": "ok",
  "data": {
    "tokenType": "Bearer",
    "accessToken": "tok_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "expiresIn": 7200,
    "appId": "elite_openapi_app"
  }
}

失败响应（401）

{
  "code": 401,
  "msg": "appid或密钥错误，或应用已禁用",
  "data": null
}

使用说明

Token有效期为7200秒（2小时），过期后需重新获取
建议在客户端缓存Token，在过期前5分钟主动刷新
后续请求携带Token：在请求头中添加 Authorization: Bearer {accessToken}

3.2 开放API - 根据手机号查询客户信息

接口说明

根据手机号查询客户的基础信息，用于业务系统获取用户档案。

接口定义

属性	值
URL	GET `/api/customer/mobile/detail`
鉴权要求	必须携带Bearer Token

请求参数

参数名	类型	必填	说明
mobile	String	是	手机号，6~20位数字

请求示例：

GET /api/customer/mobile/detail?mobile=13800138000

请求头：

Authorization: Bearer {accessToken}

响应参数

成功响应（200）

{
  "code": 200,
  "msg": "ok",
  "data": {
    "name": "张三",
    "gender": 1,
    "birthYearMonth": "1990-08",
    "birthDate": "1990-08-15",
    "height": 175,
    "weight": 70
  }
}

失败响应（500）

{
  "code": 500,
  "msg": "客户不存在",
  "data": null
}

3.3 设备数据上传

接口说明

设备在停止后，如需上传原始数据，应调用此接口。

接口定义

属性	值
URL	POST `/upload-data`
Content-Type	`application/json` 或 `multipart/form-data`
认证	Header中携带 `X-Device-Key`

请求参数

场景1：仅上传指标数据（JSON）

{
  "request_id": "0190abcd-1234-5678-90ab-cdef12345678",
  "data": {
    "user_id": 12345,
    "program_id": 1,
    "device_params": {
      "intensity": 50
    },
    "report_metrics": {
      "total_steps": 10800,
      "calories": 360
    }
  }
}

场景2：上传原始数据（Excel文件）

使用 multipart/form-data 格式：

curl -X POST "https://api.to-term.cn/upload-data" \
  -H "X-Device-Key: your-device-key" \
  -F "request_id=0190abcd-1234-5678-90ab-cdef12345678" \
  -F "data={\"user_id\":12345,\"program_id\":1}" \
  -F "report_raw_data=@training_data.xlsx"

响应参数

{
  "success": true,
  "timestamp": 1713456789000,
  "message": "成功上传",
  "data": {
    "upload_id": "up_1234567890"
  }
}

4. 设备状态机

4.1 状态定义

状态	说明
IDLE	空闲/停止状态，设备待机
RUNNING	运行状态，设备正常工作
STOPPING	停止中，正在执行停止流程

4.2 状态转换图

┌─────────┐ │ IDLE │ └────┬────┘ │ START命令 ▼ ┌─────────┐ STOP命令/INIT_STOP ┌─────────┐ │ RUNNING │ ──────────────────────────► │ STOPPING│ └────┬────┘ └────┬────┘ │ │ │ 正常完成 │ │ (INIT_STOP) │ ▼ ▼ ┌─────────┐ ┌─────────┐ │ IDLE │ ◄───────────────────────── │ IDLE │ └─────────┘ STOP_RESPONSE/ └─────────┘ ON心跳(QoS0设备)

4.3 状态转换说明

当前状态	接收命令	响应动作	新状态	特殊说明
IDLE	START	发送START_RESPONSE	RUNNING	启动设备
IDLE	STOP	发送STOP_RESPONSE	IDLE	保持空闲
RUNNING	START(相同request_id)	发送START_RESPONSE	RUNNING	幂等，无变化
RUNNING	START(不同request_id)	发送START_RESPONSE	RUNNING	按新参数执行
RUNNING	STOP	发送STOP_RESPONSE	STOPPING	优雅停止
RUNNING	正常完成	发送INIT_STOP	STOPPING	自然结束
STOPPING	-	上传数据(如有)	IDLE	数据上传后切换

4.4 QoS0特殊处理

心跳机制：
• 在RUNNING状态下，每5秒发送一次ON命令
• ON命令仅可在运行时发送
• 发送STOP_RESPONSE或INIT_STOP后，禁止再发送ON

5. 错误码定义

5.1 设备相关错误码

错误码	含义	说明	处理建议
1001	DEVICE_NOT_FOUND	设备未注册	联系图腾注册设备
1002	INVALID_DEVICE_KEY	device-key无效	检查认证信息
1003	COMMAND_NOT_SUPPORTED	不支持的命令	检查协议版本
2001	INVALID_REQUEST_ID	request_id格式错误	使用UUID v7格式
2002	MISSING_REQUIRED_PARAM	缺少必填参数	补全参数
3001	DEVICE_BUSY	设备忙	等待当前任务完成
3002	DEVICE_OFFLINE	设备离线	检查网络连接
4001	INVALID_DURATION	运行时长无效	duration > 0
5001	DATA_UPLOAD_FAILED	数据上传失败	重试或联系技术支持
9001	UNKNOWN_ERROR	未知错误	记录日志并联系技术支持

5.2 开放API错误码

错误码	含义	说明
400	INVALID_PARAM	参数格式错误
401	UNAUTHORIZED	认证失败（Token无效或过期）
403	FORBIDDEN	无权限访问
500	SYSTEM_ERROR	系统内部错误
500	CUSTOMER_NOT_FOUND	客户不存在

6. 业务交互时序图

6.1 设备启动流程

云服务设备 │ │ │───START───────────────►│ │ (request_id=xxx) │ │ │ │◄──START_RESPONSE───────│ │ (request_id=xxx) │ │ │ │ [RUNNING状态] │ │ │ │◄──ON──────────────────│ (QoS0设备每5秒) │ │

6.2 设备停止流程

云服务设备 │ │ │───STOP────────────────►│ │ (request_id=yyy) │ │ │ │◄──STOP_RESPONSE───────│ │ (包含report_metrics) │ │ │ │◄──HTTP: upload-data───│ (如有原始数据) │ │

6.3 设备自然完成流程

云服务设备 │ │ │ │ │◄──INIT_STOP────────────│ │ (包含report_metrics) │ │ │ │◄──HTTP: upload-data───│ (如有原始数据) │ │

6.4 开放API业务流程

业务系统图腾API服务器数据库 │ │ │ │───获取Token─────────►│ │ │ (appId/appSecret) │ │ │ │───验证认证信息──────►│ │ │◄──返回应用信息───────│ │◄──返回accessToken───│ │ │ │ │ │───查询客户信息──────►│ │ │ (Bearer Token) │───验证Token────────►│ │ │───查询客户信息────►│ │ │◄──返回客户数据─────│ │◄──返回客户信息───────│ │

7. 最佳实践与注意事项

7.1 MQTT连接管理

持久连接：建议保持长连接，断线后自动重连
遗嘱消息：建议设置LWT（Last Will and Testament）通知离线
心跳保持：MQTT保活时间建议设为60秒

7.2 request_id处理

必须使用UUID v7格式，保证唯一性和可排序性
同一轮命令-响应必须使用相同的request_id
建议在本地缓存request_id，用于重复请求的幂等处理

7.3 Token管理（开放API）

Token有效期为7200秒（2小时）
建议在客户端缓存Token，在过期前5分钟主动刷新
每次刷新后，旧Token立即失效
建议使用Redis等中间件缓存Token，减少认证请求压力

7.4 异常场景处理

场景	处理方式
网络断开	自动重连，重连后恢复IDLE状态
收到未知命令	返回错误响应，保持当前状态
request_id不匹配	忽略该请求，记录日志
超时未收到响应	重试最多3次，超时时间30秒
Token过期	自动刷新Token，重试原请求

7.5 数据上传策略

小数据（<10KB）：直接在MQTT响应中的report_metrics字段携带
大数据（≥10KB）：使用HTTP接口上传原始Excel文件
失败重试：上传失败后本地缓存，间隔1分钟重试，最多3次

8. 附录

8.1 设备参数示例

{
  "device_params": {
    "intensity": 50,           // 强度级别
    "mode": "auto",            // 模式：auto/manual
    "speed": 5.5,              // 速度
    "incline": 3,              // 坡度
    "target_heart_rate": 140,  // 目标心率
    "custom_settings": {       // 自定义参数
      "feature_1": true,
      "feature_2": 100
    }
  }
}

8.2 报告指标示例

{
  "report_metrics": {
    "total_steps": 10800,           // 总步数
    "calories": 360,                // 消耗卡路里
    "distance": 5000,               // 距离（米）
    "avg_heart_rate": 125,          // 平均心率
    "max_heart_rate": 155,          // 最大心率
    "completion_rate": 1.0,         // 完成率
    "duration_actual": 1800,        // 实际时长（秒）
    "quality_score": 95,            // 质量评分
    "custom_metrics": {             // 自定义指标
      "efficiency": 0.85,
      "consistency": 0.92
    }
  }
}

8.3 接口分类索引

接口分类	接口名称	协议	章节
MQTT接口	START命令	MQTT	2.4节
MQTT接口	STOP命令	MQTT	2.5节
MQTT接口	INIT_STOP命令	MQTT	2.6节
MQTT接口	ON命令（心跳）	MQTT	2.7节
HTTP开放API	获取Token	HTTP	3.1节
HTTP开放API	根据手机号查询客户信息	HTTP	3.2节
HTTP设备接口	上传设备数据	HTTP	3.3节

版本说明：
本文档当前版本为 V0.15，后续版本更新将在顶部变更记录中注明。

向后兼容性声明：图腾承诺在主版本号不变的情况下，接口保持向后兼容。如需破坏性变更，将通过提前通知和版本迁移指南支持设备商升级。