设备模块鉴权接口文档
概览
- 基础路径: /api
- 文档范围: 仅包含设备基础鉴权接口
- 鉴权方式: 请求头 X-Token
- Content-Type: application/json
文档拆分
- 本文档: 设备基础接口，包括列表、详情、绑定、解绑、更新
- P2P 代理接口: 见 device-auth-p2p.md
- 直播地址与录像地址接口: 见 device-auth-address.md
鉴权头
| 字段 |
类型 |
必填 |
说明 |
| X-Token |
string |
是 |
用户登录后获得的 JWT Token |
统一响应格式
{
"code": 200,
"msg": "操作成功",
"data": {}
}
返回字段说明
| 字段 |
类型 |
说明 |
| code |
integer |
业务状态码，200 表示成功，其他值表示失败 |
| msg |
string |
响应消息 |
| data |
object/array/null |
业务数据 |
通用鉴权失败响应
{
"code": 401,
"msg": "未登录或登录过期",
"data": null
}
{
"code": 401,
"msg": "登录已过期，请重新登录",
"data": null
}
设备对象字段说明
设备列表、设备详情、设备绑定成功时返回的 data 可能包含以下字段：
| 字段 |
类型 |
说明 |
| id |
string |
设备唯一标识 |
| userId |
integer |
当前绑定用户 ID |
| familyId |
string |
所属家庭 ID |
| name |
string |
设备名称 |
| batteryLevel |
integer |
电量百分比 |
| isCharging |
boolean |
是否正在充电 |
| foodLevel |
integer |
余粮百分比 |
| firmwareVersion |
string |
固件版本 |
| totalFeedCount |
integer |
总喂食次数 |
| todayFeedCount |
integer |
今日喂食次数 |
| todayFeedAmount |
integer |
今日喂食总量（跨天自动清零） |
| lastStartTime |
integer |
上次上线时间戳，秒 |
| lastCloseTime |
integer |
上次离线时间戳，秒 |
| online |
boolean |
是否在线 |
| isDisabled |
boolean |
是否禁用 |
| isNew |
integer |
设备状态标记，0 断线重连，1 程序重启，2 设备重启 |
| eip |
string |
外网 IP |
| cloudVer |
string |
云端版本 |
| addr |
string |
设备地址 |
| createdAt |
string |
创建时间 |
| updatedAt |
string |
更新时间 |
1. 获取设备列表
- 路径: /api/device/list
- 方法: POST
- 是否鉴权: 是
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| familyId |
string |
否 |
家庭 ID。不传时按当前用户查询设备列表，传入时按家庭查询 |
请求示例
{
"familyId": "family_001"
}
也可传空对象：
{}
成功响应示例
{
"code": 200,
"msg": "操作成功",
"data": [
{
"id": "dev_001",
"userId": 1,
"familyId": "family_001",
"name": "客厅喂食器",
"batteryLevel": 86,
"isCharging": false,
"foodLevel": 70,
"firmwareVersion": "1.0.2",
"totalFeedCount": 12,
"todayFeedCount": 3,
"lastStartTime": 1752297600,
"lastCloseTime": 1752280000,
"online": true,
"isDisabled": false,
"isNew": 0,
"eip": "1.2.3.4",
"cloudVer": "cloud-2026.05",
"addr": "192.168.1.10",
"createdAt": "2026-05-01T10:00:00Z",
"updatedAt": "2026-05-09T10:00:00Z"
}
]
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
成功时为 200 |
| msg |
string |
成功时为 操作成功 |
| data |
array |
设备列表 |
| data[].* |
object |
设备对象字段，见上方设备对象字段说明 |
失败响应示例
{
"code": 500,
"msg": "获取设备列表失败",
"data": null
}
2. 获取设备详情
- 路径: /api/device/detail
- 方法: POST
- 是否鉴权: 是
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| deviceId |
string |
是 |
设备唯一标识 |
请求示例
{
"deviceId": "dev_001"
}
成功响应示例
{
"code": 200,
"msg": "操作成功",
"data": {
"id": "dev_001",
"userId": 1,
"familyId": "family_001",
"name": "客厅喂食器",
"batteryLevel": 86,
"isCharging": false,
"foodLevel": 70,
"firmwareVersion": "1.0.2",
"totalFeedCount": 12,
"todayFeedCount": 3,
"lastStartTime": 1752297600,
"lastCloseTime": 1752280000,
"online": true,
"isDisabled": false,
"isNew": 0,
"eip": "1.2.3.4",
"cloudVer": "cloud-2026.05",
"addr": "192.168.1.10",
"createdAt": "2026-05-01T10:00:00Z",
"updatedAt": "2026-05-09T10:00:00Z"
}
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
成功时为 200 |
| msg |
string |
成功时为 操作成功 |
| data |
object |
设备详情 |
| data.* |
mixed |
设备对象字段，见上方设备对象字段说明 |
失败响应示例
{
"code": 400,
"msg": "参数错误",
"data": null
}
{
"code": 404,
"msg": "设备不存在",
"data": null
}
3. 绑定设备
- 路径: /api/device/bind
- 方法: POST
- 是否鉴权: 是
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| deviceId |
string |
是 |
设备唯一标识 |
| familyId |
string |
是 |
家庭 ID。设备绑定必须指定家庭 |
| name |
string |
否 |
自定义设备名称。最多 30 个字符，只允许中文、字母、数字、下划线和短横线 |
请求示例
{
"deviceId": "dev_001",
"familyId": "family_001",
"name": "客厅喂食器"
}
成功响应示例
{
"code": 200,
"msg": "设备绑定成功",
"data": {
"id": "dev_001",
"userId": 1,
"familyId": "family_001",
"name": "客厅喂食器"
}
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
成功时为 200 |
| msg |
string |
成功时为 设备绑定成功 |
| data.id |
string |
设备唯一标识 |
| data.userId |
integer |
当前绑定用户 ID |
| data.familyId |
string |
家庭 ID |
| data.name |
string |
设备名称 |
失败响应示例
{
"code": 400,
"msg": "familyId不能为空",
"data": null
}
{
"code": 400,
"msg": "设备不存在，无法绑定",
"data": null
}
{
"code": 400,
"msg": "该设备已被他人绑定",
"data": null
}
{
"code": 400,
"msg": "设备名称不能超过30个字符",
"data": null
}
{
"code": 400,
"msg": "设备名称只能包含中文、字母、数字、下划线和短横线",
"data": null
}
4. 解绑设备
- 路径: /api/device/unbind
- 方法: POST
- 是否鉴权: 是
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| deviceId |
string |
是 |
设备唯一标识 |
请求示例
{
"deviceId": "dev_001"
}
成功响应示例
{
"code": 200,
"msg": "设备已解绑",
"data": null
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
成功时为 200 |
| msg |
string |
成功时为 设备已解绑 |
| data |
null |
无返回数据 |
失败响应示例
{
"code": 400,
"msg": "设备不存在",
"data": null
}
{
"code": 400,
"msg": "无权限操作此设备",
"data": null
}
5. 更新设备名称
- 路径: /api/device/update
- 方法: POST
- 是否鉴权: 是
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| deviceId |
string |
是 |
设备唯一标识 |
| name |
string |
否 |
新设备名称。最多 30 个字符，只允许中文、字母、数字、下划线和短横线 |
请求示例
{
"deviceId": "dev_001",
"name": "餐厅喂食器"
}
成功响应示例
{
"code": 200,
"msg": "更新成功",
"data": null
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
成功时为 200 |
| msg |
string |
成功时为 更新成功 |
| data |
null |
无返回数据 |
失败响应示例
{
"code": 400,
"msg": "设备不存在",
"data": null
}
{
"code": 400,
"msg": "无权限操作此设备",
"data": null
}
{
"code": 400,
"msg": "设备名称不能超过30个字符",
"data": null
}
{
"code": 400,
"msg": "设备名称只能包含中文、字母、数字、下划线和短横线",
"data": null
}
附录
说明
- 本文档仅保留设备基础接口。
- P2P 代理接口仍使用 query 传递 deviceId、sessionId 等参数，见 device-auth-p2p.md。
- 直播地址与录像地址接口使用统一响应结构，见 device-auth-address.md。