查询设备实时状态
获取设备最近一次实时上报状态，包含绑定信息、在线状态、电量、音量、固件版本、网络状态与位置。查询范围仅限当前 API Key 授权的在线硬件渠道，不返回设备密钥等敏感信息。
请求信息
请求 URI
GET https://lg.jimitu.top/api/open/devices/status请求头参数
| Header | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer {API Key}，接口鉴权，所有请求均需携带 |
Content-Type | 否 | 仅 POST/PUT 携带 JSON 请求体时需要，值为 application/json |
请求查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| device_id | string | 是 | 设备 ID |
| channel_id | integer | 否 | 渠道 ID；授权范围内设备 ID 重复时用于消歧 |
| product_key | string | 否 | 产品型号 ID；授权范围内设备 ID 重复时用于消歧 |
请求示例
curl -X GET "https://lg.jimitu.top/api/open/devices/status?device_id=<device_id>&channel_id=100" \
-H "Authorization: Bearer <your_api_key>"响应信息
响应体示例
{
"success": true,
"data": {
"device_id": "DEV001",
"external_user_id": "user_12345",
"product_key": "ESP32",
"channel_id": 3,
"device_type": "AI玩偶",
"manufacturer": "乐鑫",
"is_online": true,
"last_heartbeat_at": "2026-08-13T15:20:30.125+08:00",
"status_source": "realtime",
"battery": 86,
"volume": 45,
"mac_address": "AA:BB:CC:DD:EE:FF",
"network_type": "WIFI",
"extra_info": "{\"temperature\":24.5,\"storage_free_mb\":128}",
"firmware_version": "1.3.2",
"position_source": "realtime",
"position": {
"type": "outdoor",
"latitude": 18.2528,
"longitude": 109.5119,
"x": null,
"y": null,
"z": null,
"floor": null,
"reported_at": "2026-08-13T15:20:12.031+08:00"
}
}
}响应参数
| 分组 | 字段 | 类型 | 说明 |
|---|---|---|---|
| 设备信息 | device_id | string | 硬件上报和网关鉴权使用的设备 ID |
| 设备信息 | external_user_id | string | 设备当前绑定的外部用户 ID；未绑定时为空字符串 |
| 设备信息 | product_key | string | 设备所属产品型号标识；与 device_id 共同确定设备唯一身份 |
| 设备信息 | channel_id | integer | 设备所属的硬件渠道 ID（ChannelPublish.id） |
| 设备信息 | device_type | string | 设备硬件类型（如 AI玩偶、AI眼镜） |
| 设备信息 | manufacturer | string | 设备录入时配置的厂商名称 |
| 设备信息 | mac_address | string | 最近一次心跳上报的 MAC 地址；未上报时为空字符串 |
| 设备状态 | is_online | boolean | 最近有效心跳在 150 秒内为 true，否则为 false |
| 设备状态 | last_heartbeat_at | string/null | 最近心跳时间（ISO 8601 含时区）；从未上报时为 null |
| 设备状态 | battery | integer/null | 最近有效心跳上报的电量百分比（0-100）；未上报时为 null |
| 设备状态 | volume | integer/null | 最近有效心跳上报的音量百分比（0-100）；未上报时为 null |
| 设备状态 | firmware_version | string | 最近心跳上报的固件版本号；未上报时为空字符串 |
| 设备状态 | network_type | string | 最近心跳上报的网络类型：4G / 5G / WIFI；未上报时为空字符串 |
| 设备状态 | extra_info | string | 最近有效心跳上报的 JSON 字符串（最大 16384 字符）；未上报时为空字符串 |
| 元数据 | status_source | string | realtime=命中网关实时心跳快照；persisted=使用数据库最近落库值 |
| 位置 | position_source | string | 位置数据来源：realtime 或 persisted |
| 位置 | position | object/null | 位置信息（type/latitude/longitude/x/y/z/floor/reported_at）；未上报时为 null |
注意
position.type 取值：outdoor（经纬度）/ indoor（x/y/z + floor）。心跳未携带的可选字段会保留该设备最近有效值。
错误码
错误码
| 场景 | error_code | HTTP |
|---|---|---|
| 缺少设备 ID | DEVICE_ID_REQUIRED | 400 |
| 授权范围内没有该设备状态 | DEVICE_NOT_FOUND | 404 |
| 授权范围内有多个同 ID 设备 | DEVICE_ID_AMBIGUOUS | 409 |