设备信息同步查询接口

基本信息

属性	值
接口路径	`POST /v1/iot/openApi/device/sync-info`
请求方式	POST
Content-Type	application/json
认证方式	appId + sign 签名验证

接口说明

同步查询设备信息，直接返回设备完整数据。与异步接口 /device/info 的区别：

	异步 `/device/info`	同步 `/device/sync-info`
返回方式	立即返回 `requestId`，结果通过 `callbackUrl` 回调	直接返回设备信息
`callbackUrl`	必传	不需要
响应字段	部分字段（经 v1 映射）	全量字段

请求参数

请求体

{
  "appId": "your_app_id",
  "sign": "签名字符串",
  "timestamp": "时间戳",
  "data": "加密后的业务数据"
}

data 解密后结构

{
  "params": {
    "cardNo": "设备标识"
  }
}

cardNo 说明

长度	类型	示例
> 15 位	ICCID	`89860624590014720038`
15 位	IMEI（设备号）	`868347081100410`
11 位	SN（序列号）	`90001473913`

响应参数

响应结构

{
  "code": 200,
  "msg": "success",
  "data": { ... },
  "trace_id": "请求追踪ID"
}

data 字段说明

字段	类型	说明
`device_id`	string	设备ID（IMEI/SN）
`device_name`	string	设备名称
`imei`	string	IMEI号
`imsi`	string	IMSI用户标识码
`current_iccid`	string	当前使用的ICCID
`device_type`	string	设备类型：`1`=诺行，`2`=玺龙，`3`=迎势达
`software_version`	string	软件版本号
`mac_address`	string	MAC地址
`ip_address`	string	IP地址
`ssid`	string	WiFi热点名称
`wifi_password`	string	WiFi密码
`wifi_enabled`	bool	WiFi开关状态
`max_clients`	int	最大连接客户端数
`limit_speed`	int	限速速率（KB/s）
`sync_interval`	int	信息上报周期（秒）
`switch_mode`	string	切卡模式：`0`=自动，`1`=手动
`ul_stats`	string	本次开机上传流量（字节）
`dl_stats`	string	本次开机下载流量（字节）
`daily_usage`	string	日使用流量（字节）
`rsrp`	int	参考信号接收功率（dBm）
`rsrq`	int	参考信号接收质量（dB）
`sinr`	int	信噪比（dB）
`rssi`	string	接收信号强度
`lan_ip`	string	局域网网关IP地址
`wan_ip`	string	基站分配IPv4地址
`run_time`	string	设备本次开机运行时间（秒）
`connect_time`	string	设备本次联网时间（秒）
`battery_level`	int	电池电量百分比
`online_status`	int	在线状态：`1`=在线，`2`=离线
`status`	int	设备状态：`1`=正常，`0`=禁用
`last_update_time`	string	设备信息最后更新时间（ISO 8601）
`last_online_time`	string	设备最后在线时间（ISO 8601）
`created_at`	int	创建时间（Unix时间戳）
`updated_at`	int	更新时间（Unix时间戳）

所有字段均可能为 null，表示该字段暂无数据。

响应示例

成功响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "device_id": "90001473913",
    "device_name": "868347081100410",
    "imei": "868347081100410",
    "imsi": null,
    "current_iccid": "89860865192590302917",
    "device_type": "3",
    "software_version": "TZ103W_CN1_YSDPTZ12_TH_P42U28_U_17_PRO_20260121",
    "mac_address": "00904D8486DE",
    "ip_address": null,
    "ssid": "ZJ-8486DE",
    "wifi_password": null,
    "wifi_enabled": true,
    "max_clients": null,
    "limit_speed": 0,
    "sync_interval": 600,
    "switch_mode": "0",
    "ul_stats": null,
    "dl_stats": null,
    "daily_usage": "150980",
    "rsrp": null,
    "rsrq": null,
    "sinr": null,
    "rssi": "-72",
    "lan_ip": null,
    "wan_ip": null,
    "run_time": "2099",
    "connect_time": null,
    "battery_level": null,
    "online_status": 2,
    "status": 1,
    "last_update_time": "2026-03-23T16:53:18+08:00",
    "last_online_time": "2026-03-23T16:53:18+08:00",
    "created_at": null,
    "updated_at": null
  },
  "trace_id": "trace_xxx"
}

错误响应

cardNo 为空：

{
  "code": 401,
  "msg": "cardNo nil",
  "data": null
}

设备不存在：

{
  "code": 401,
  "msg": "获取设备信息错误，无效设备号",
  "data": null
}

服务调用失败：

{
  "code": 500,
  "msg": "服务调用失败",
  "data": null
}

数据来源说明

接口数据按以下优先级获取：

Redis 缓存（设备最近一次上报的实时数据，TTL 10 分钟）
数据库（缓存过期后 fallback，字段可能不完整）

设备在线时优先返回缓存中的实时上报数据；设备离线后缓存过期，返回数据库中最后一次同步的数据。部分字段（如 wifi_password、battery_level 等）在离线 fallback 场景下可能为 null。

5.0 KiB Raw Permalink Blame History Unescape Escape