查询设备实时状态

获取设备最近一次实时上报状态，包含绑定信息、在线状态、电量、音量、固件版本、网络状态与位置。查询范围仅限当前 API Key 授权的在线硬件渠道，不返回设备密钥等敏感信息。

请求信息

请求 URI

GET https://lg.jimitu.top/api/open/devices/status

请求头参数

请求头	必填	说明
`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,\"province\":\"XX省\",\"city\":\"XX市\",\"adcode\":\"XXXXXX\",\"road\":\"XX路\",\"poi\":\"XX园区\",\"location\":\"XX省 XX市 XX区 XX路 xxx号\",\"radius\":550}",  // 具体位置描述（省/市/道路/POI 等）在此字段内
    "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 字符）；具体位置信息（省/市/道路/POI 等）由固件在此字段内上报；未上报时为空字符串
元数据	status_source	string	`realtime`=命中网关实时心跳快照；`persisted`=使用数据库最近落库值
位置	position_source	string	位置数据来源：`realtime` 或 `persisted`
位置	position	object/null	设备坐标（`outdoor` 为经纬度 latitude/longitude；`indoor` 为 x/y/z + floor）；未上报时为 null

注意

position 与 extra_info 区分：position 为设备坐标（经纬度或室内坐标），用于地图定位；extra_info 为扩展字段，具体位置描述（省/市/道路/POI 等结构化字段）由固件在此字段内上报，需按 JSON 解析 extra_info 获取。position.type 取值：outdoor（经纬度）/ indoor（x/y/z + floor）。心跳未携带的可选字段会保留该设备最近有效值。

错误码

场景	error_code	状态码
缺少设备 ID	`DEVICE_ID_REQUIRED`	400
授权范围内没有该设备状态	`DEVICE_NOT_FOUND`	404
授权范围内有多个同 ID 设备	`DEVICE_ID_AMBIGUOUS`	409