192 lines
5.0 KiB
Markdown
192 lines
5.0 KiB
Markdown
# 设备信息同步查询接口
|
||
|
||
## 基本信息
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 接口路径 | `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 映射） | 全量字段 |
|
||
|
||
## 请求参数
|
||
|
||
### 请求体
|
||
|
||
```json
|
||
{
|
||
"appId": "your_app_id",
|
||
"sign": "签名字符串",
|
||
"timestamp": "时间戳",
|
||
"data": "加密后的业务数据"
|
||
}
|
||
```
|
||
|
||
### data 解密后结构
|
||
|
||
```json
|
||
{
|
||
"params": {
|
||
"cardNo": "设备标识"
|
||
}
|
||
}
|
||
```
|
||
|
||
### cardNo 说明
|
||
|
||
| 长度 | 类型 | 示例 |
|
||
|------|------|------|
|
||
| > 15 位 | ICCID | `89860624590014720038` |
|
||
| 15 位 | IMEI（设备号） | `868347081100410` |
|
||
| 11 位 | SN（序列号） | `90001473913` |
|
||
|
||
## 响应参数
|
||
|
||
### 响应结构
|
||
|
||
```json
|
||
{
|
||
"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`，表示该字段暂无数据。
|
||
|
||
## 响应示例
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"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 为空：**
|
||
```json
|
||
{
|
||
"code": 401,
|
||
"msg": "cardNo nil",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**设备不存在：**
|
||
```json
|
||
{
|
||
"code": 401,
|
||
"msg": "获取设备信息错误，无效设备号",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**服务调用失败：**
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "服务调用失败",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 数据来源说明
|
||
|
||
接口数据按以下优先级获取：
|
||
|
||
1. **Redis 缓存**（设备最近一次上报的实时数据，TTL 10 分钟）
|
||
2. **数据库**（缓存过期后 fallback，字段可能不完整）
|
||
|
||
设备在线时优先返回缓存中的实时上报数据；设备离线后缓存过期，返回数据库中最后一次同步的数据。部分字段（如 `wifi_password`、`battery_level` 等）在离线 fallback 场景下可能为 `null`。
|