API接口

2026-10-31 · 公司新闻

DTU 设备管理平台 —— 开放 API 接口文档

适用对象：使用本平台管理设备的客户 / 第三方系统
接口地址：https://dtu2.minyee.com/api/openapi/...

---

一、鉴权说明（每个接口都必须带）

公共参数：GET / POST 都支持，参数放 URL 或表单都可以（两种方式对每个接口都有效）。

所有接口都不限制请求方法。测试时直接把地址粘到浏览器地址栏也能调，
正式对接建议用 POST 传参数（不受 URL 长度限制）。

参数名	必填	说明
`account`	是	你的平台登录账号（手机号；没手机号的账号用用户名）
`t`	是	当前时间戳（秒），例如 `1759999999`
`key`	是	签名，算法见下

签名算法

key = md5( md5(account) + md5(password) + t )

- md5(password) 指你登录密码明文的 md5（32 位小写）
- 中间的 + 是字符串连接，不是加法
- t 与服务器时间相差超过 5 分钟即失效，请每次请求重新生成
在线算key工具：http://simcard.minyee.com/dtuapikey/

PHP

php
$account  = '13800138000';
$password = '你的登录密码';
$t   = time();
$key = md5(md5($account) . md5($password) . $t);

Python

python
import hashlib, time

account, password = '13800138000', '你的登录密码'
t = int(time.time())
key = hashlib.md5((hashlib.md5(account.encode()).hexdigest()
                   + hashlib.md5(password.encode()).hexdigest()
                   + str(t)).encode()).hexdigest()

Node.js

javascript
const md5 = s => require('crypto').createHash('md5').update(s, 'utf8').digest('hex')

const account  = '13800138000'
const password = '你的登录密码'
const t   = Math.floor(Date.now() / 1000)
const key = md5(md5(account) + md5(password) + t)

---

二、返回格式

成功

json
{
  "code": 200,
  "msg": "ok",
  "data": { },
  "time": 1759999999
}

失败

json
{
  "code": 400,
  "msg": "错误说明",
  "data": null,
  "time": 1759999999
}

code	含义
`200`	成功
`400`	参数 / 业务错误（`msg` 里有具体原因）
`401`	鉴权失败（账号、key 不正确，或 `t` 已过期）

---

三、权限边界（重要）

1. 所有接口只作用于你账号下的分组和设备。传别人的 group_id 或 imei，一律返回「分组不存在 / 设备不存在」。

2. 本 API 不提供以下操作，只能登录平台操作：

- 新增设备

- 删除设备

（删除分组已开放，见 4.4；系统默认分组不允许删除）

3. 转移设备时，只能转移已经在你自己账号下的设备。别人的设备不会被转走，且整批会被拒绝并列出具体编号。

---

四、接口明细

4.1 查询分组列表

GET / POST  /api/openapi/groups

可选参数

参数	说明
`with_config=1`	列表里同时返回每个分组的 `config` 原文（默认不返回，减少数据量）

返回示例

json
{
  "code": 200,
  "msg": "ok",
  "data": {
    "total": 2,
    "rows": [
      {
        "id": 10,
        "group_name": "默认分组",
        "is_default": 1,
        "device_count": 5,
        "created_at": "2025-01-01 10:00:00"
      },
      {
        "id": 11,
        "group_name": "客户A",
        "is_default": 0,
        "device_count": 12,
        "created_at": "2025-02-03 11:20:00"
      }
    ]
  },
  "time": 1759999999
}

字段说明

字段	说明
`id`	分组 ID（后面查询参数、转移设备都要用）
`group_name`	分组名称
`is_default`	`1` = 系统默认分组，`0` = 普通分组
`device_count`	该分组下有多少台设备
`created_at`	创建时间

---

4.2 查询单个分组详情（含参数配置）

GET / POST  /api/openapi/groups?id=分组ID

返回示例

json
{
  "code": 200,
  "data": {
    "id": 11,
    "group_name": "客户A",
    "is_default": 0,
    "device_count": 12,
    "created_at": "2025-02-03 11:20:00",
    "config": "{\"conf\":[[\"tcp\",\"\",\"60\",\"1.2.3.4\",\"7777\",\"1\"]]}"
  }
}

config 是明文 JSON 字符串，未配置过时为 null。

---

4.3 新建分组

GET / POST  /api/openapi/group/create

参数

参数	必填	说明
`name`	是	分组名称，最多 50 个字，同一账号下不能重名（值两端成对的引号会自动去掉）

成功返回

json
{
  "code": 200,
  "msg": "创建成功",
  "data": { "id": 12, "group_name": "客户B" }
}

常见错误

请输入分组名称
分组名称不能超过50个字
分组名称已存在
分组数量已达上限（200个）

---

4.4 删除分组

GET / POST  /api/openapi/group/delete

参数

参数	必填	说明
`id`	是	要删除的分组 ID

成功返回

json
{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "id": 11,
    "group_name": "客户A"
  }
}

规则说明

只能删自己账号下的分组，别人的 id 一律返回「分组不存在」
系统默认分组不允许删除（返回「默认分组不允许删除」），与平台页面一致
组里的设备不会被一起删除，删除分组后设备在页面上显示为「未分组」

常见错误

请传入分组ID(id)
分组不存在
默认分组不允许删除

---

4.5 查询分组参数配置

GET / POST  /api/openapi/group/config?id=分组ID

返回示例

json
{
  "code": 200,
  "data": {
    "id": 11,
    "group_name": "客户A",
    "config": "{\"conf\":[[\"tcp\",\"\",\"60\",\"1.2.3.4\",\"7777\",\"1\"]]}"
  }
}

返回明文 JSON，未配置时为 null。

---

4.6 修改分组参数配置

GET / POST  /api/openapi/group/config/update

参数版本号"param_ver"每次要每次要不同或加1，DTU才启用新参数

如果设备切换分组，但是俩个分组版本号一致，重启也不会生效。

参数

参数	必填	说明
`id`	是	分组 ID
`config`	是	参数内容，必须是 JSON 字符串

调用示例（config 需要 URL 编码后传）

config={"conf":[["tcp","","60","1.2.3.4","7777","1"]],"plate":1}

成功返回

json
{ "code": 200, "msg": "保存成功", "data": { "id": 11 } }

说明

服务端会先校验 JSON 格式，不合法直接返回错误，不会写入数据库
校验错误示例：

- config 不是合法的 JSON：Syntax error

- config 解析后不是对象或数组，请检查内容

- config 里的 conf 必须是数组

数组里的 null 值会被自动清理（与平台保存行为一致）

---

4.7 查询自己账号下的设备列表

GET / POST  /api/openapi/devices

可选参数

参数	默认	说明
`group_id`	—	只看某个分组下的设备
`page`	`1`	页码，从 1 开始
`page_size`	`100`	每页条数，最大 `500`

返回示例

json
{
  "code": 200,
  "data": {
    "total": 17,
    "page": 1,
    "page_size": 100,
    "rows": [
      {
        "imei": "864123456789012",
        "group_id": 11,
        "group_name": "客户A",
        "iccid": "89860012345678901234",
        "hadr": "0012",
        "csq": "23",
        "ver": "V3.2.1",
        "online_time": "2025-09-14 17:32:10"
      }
    ]
  }
}

说明

只返回你自己账号下的设备
未分组的设备 group_id 为 0、group_name 为「未分组」
设备量大时请用 page / page_size 分批拉取

---

4.8 把设备转移到分组

GET / POST  /api/openapi/device/transfer

参数

参数	必填	说明
`imeis`	是	设备 IMEI，多个用逗号分隔（也支持换行 / 中文逗号 / 空格）
`group_id`	二选一	目标分组 ID
`group_name`	二选一	目标分组名；分组不存在时会自动创建

成功返回

json
{
  "code": 200,
  "msg": "转移成功",
  "data": {
    "group_id": 12,
    "group_name": "客户B",
    "total": 2,
    "transferred": 2
  }
}

常见错误

请传入设备IMEI(imeis)
一次最多转移 2000 台设备
目标分组不存在
请传入目标分组 group_id 或 group_name
以下设备不存在或不属于当前账号：864123456789012、864123456789013

说明

只要有一台设备不是你账号下的，整批都不转移，并列出问题编号
重复的 IMEI 会自动去重
transferred 为实际转移成功的台数

转移成功截图：

---

4.9 修改分组名称

GET / POST  /api/openapi/group/rename

参数

参数	必填	说明
`id`	是	分组 ID
`name`	是	新的分组名称，最多 50 个字

成功返回

json
{
  "code": 200,
  "msg": "修改成功",
  "data": { "id": 11, "group_name": "客户A-新", "old_name": "客户A" }
}

规则说明

只能改自己账号下的分组
默认分组不允许改名（返回「默认分组不允许修改名称」），与平台页面一致
同一账号下不能重名
名称与原来相同时返回 msg = 名称未变化

常见错误

请传入分组ID(id)
请输入新的分组名称(name)
分组名称不能超过50个字
分组不存在
默认分组不允许修改名称
分组名称已存在

---

4.10 查询设备参数

GET / POST  /api/openapi/device/info

参数

参数	必填	说明
`imei`	是	设备 IMEI
`with_config`	否	传 `1` 时同时返回该设备所属分组的参数配置

返回示例

json
{
  "code": 200,
  "msg": "ok",
  "data": {
    "imei": "864123456789012",
    "group_id": 11,
    "group_name": "客户A",
    "iccid": "89860012345678901234",
    "csq": "23",
    "hadr": "0012",
    "ver": "V3.2.1",
    "online_time": "2025-09-14 17:32:10",
    "created_at": "2025-01-01 10:00:00",
    "updated_at": "2025-09-14 17:32:10"
  }
}

未分组设备返回 group_id: 0、group_name: "未分组"；空字段返回空字符串而不是 null。

---

4.11 查询设备历史

GET / POST  /api/openapi/device/history

参数

参数	必填	说明
`imei`	是	设备 IMEI
`limit`	否	条数，默认 `50`，最大 `50`

返回示例

json
{
  "code": 200,
  "msg": "ok",
  "data": {
    "imei": "864123456789012",
    "total": 50,
    "rows": [
      {
        "id": 1234,
        "imei": "864123456789012",
        "iccid": "89860012345678901234",
        "csq": "23",
        "hadr": "0012",
        "ver": "V3.2.1",
        "created_at": "2025-09-14 17:32:10"
      }
    ]
  }
}

按 created_at 倒序，最新的在最前面。只能查自己账号下的设备。

---

4.12 设备上报参数

GET / POST  /api/openapi/device/report

作用与原有的 /api/config/:imei 相同（更新设备参数 + 返回分组配置），但需要 account/t/key 鉴权，且设备必须属于该账号。

参数

参数	必填	说明
`imei`	是	设备 IMEI
`iccid`	否	传了才更新
`csq`	否	传了才更新
`hadr`	否	传了才更新；传 `AAAAAAAAAAAA` 视为无效值，不更新
`ver`	否	传了才更新

成功返回

json
{
  "code": 200,
  "msg": "上报成功",
  "data": {
    "imei": "864123456789012",
    "group_id": 11,
    "group_name": "客户A",
    "iccid": "89860012345678901234",
    "csq": "23",
    "hadr": "0012",
    "ver": "V3.2.1",
    "online_time": "2025-10-21 12:00:00",
    "config": "{\"conf\":[[\"tcp\",\"\",\"60\",\"1.2.3.4\",\"7777\"]]}"
  }
}

说明

每次上报都会刷新 online_time，并写入一条历史记录（每台设备保留最近 500 条）
不传的字段保持原值，不会被清空（这一点比老接口 /api/config/:imei 更安全）
config 是设备所属分组的参数明文；设备没分组或分组没配参数时为 null
老接口 /api/config/:imei 继续可用，不受影响

---

附：老接口对照

老接口（无需鉴权）	新接口（需 account/t/key）	说明
`GET /api/config/:imei?iccid=&csq=&hadr=&ver=`	`GET/POST /api/openapi/device/report?imei=&iccid=&csq=&hadr=&ver=`	设备上报参数并取分组配置
—	`GET/POST /api/openapi/device/info?imei=`	查询单个设备参数
—	`GET/POST /api/openapi/device/history?imei=&limit=50`	查询设备历史
—	`GET/POST /api/openapi/group/rename?id=&name=`	修改分组名称

五、完整调用示例

PHP：查询所有分组 + 把设备转移到新分组

php
 $account, 't' => $t, 'key' => $key];

// 1) 查询分组
$url = $base . '/api/openapi/groups?' . http_build_query($common);
$res = json_decode(file_get_contents($url), true);
if ($res['code'] !== 200) {
    die('查询失败：' . $res['msg']);
}
foreach ($res['data']['rows'] as $g) {
    echo $g['id'] . '  ' . $g['group_name'] . '  设备数=' . $g['device_count'] . "\n";
}

// 2) 把设备转移到分组（不存在会自动创建）
$post = http_build_query($common + [
    'imeis'      => '864123456789012,864123456789013',
    'group_name' => '客户C',
]);
$ctx = stream_context_create(['http' => [
    'method'  => 'POST',
    'header'  => "Content-Type: application/x-www-form-urlencoded\r\n",
    'content' => $post,
    'timeout' => 10,
]]);
$res2 = json_decode(file_get_contents($base . '/api/openapi/device/transfer', false, $ctx), true);
print_r($res2);

`

### Python：修改分组参数

python

import hashlib, time, json, requests

account, password = '13800138000', '你的登录密码'

base = 'https://dtu2.minyee.com'

t = int(time.time())

key = hashlib.md5((hashlib.md5(account.encode()).hexdigest()

+ hashlib.md5(password.encode()).hexdigest()

+ str(t)).encode()).hexdigest()

common = {'account': account, 't': t, 'key': key}

cfg = {"conf": [["tcp", "", "60", "1.2.3.4", "7777", "1"]]}

r = requests.post(f'{base}/api/openapi/group/config/update', data={

**common,

'id': 11,

'config': json.dumps(cfg, ensure_ascii=False),

})

print(r.json())

`

---

## 六、常见问题

**Q：一直提示「key 已过期」？**

服务器校验的是它自己的当前时间。请确认你所在机器 / 服务器的时间准确，并且每次请求都用**当前**时间戳重新算 key，不要写死或缓存。

**Q：一直提示「账号不存在或 key 不正确」？**

按顺序检查：

1. `account` 是不是你的平台登录手机号
2. 密码是不是最新密码（平台改过密码需同步更新）
3. key 里两处 md5 是否都算了，且中间是字符串拼接
4. 有没有多空格（`account`、`key` 前后不能带空格）

**Q：可以指定别的账号 `group_id` 吗？**

不可以。所有接口只认你自己账号下的分组和设备，别人的 ID 一律返回「不存在」。

**Q：能不能用 API 新增设备或删除分组？**

不能。按授权范围，这两类操作只允许登录平台由人工操作。

**Q：频率限制？**

单账号每小时 3000 次、单 IP 每小时 2000 次。超出返回「请求过于频繁，请稍后再试」。正常业务调用不会触发。

**Q：设备参数（config）的格式是什么？**

就是平台「参数配置」里保存的那段 JSON。想确认格式，可以先调用 [4.5 查询分组参数配置](#45-查询分组参数配置)，把返回的 `config` 复制出来参照。

---

## 附：快速自测

在任意能运行 PHP 的环境（服务器、本机均可）执行，直接得到可用的请求参数：

bash

php -r '$a="你的手机号";$p="你的密码";$t=time();echo "account=".$a."&t=".$t."&key=".md5(md5($a).md5($p).$t)."\n";'

把输出拼到接口地址后面即可测试：

https://dtu2.minyee.com/api/openapi/groups?account=...&t=...&key=...

预期返回形如：

json

{ "code": 200, "msg": "ok", "data": { "total": 1, "rows": [ ... ] }, "time": 1759999999 }

```

← 返回列表

新闻详情

API接口

DTU 设备管理平台 —— 开放 API 接口文档

目录

一、鉴权说明（每个接口都必须带）

签名算法

二、返回格式

三、权限边界（重要）

四、接口明细

4.1 查询分组列表

4.2 查询单个分组详情（含参数配置）

4.3 新建分组

4.4 删除分组

4.5 查询分组参数配置

4.6 修改分组参数配置

4.7 查询自己账号下的设备列表

4.8 把设备转移到分组

转移成功截图：

4.9 修改分组名称

4.10 查询设备参数

4.11 查询设备历史

4.12 设备上报参数

附：老接口对照

五、完整调用示例

PHP：查询所有分组 + 把设备转移到新分组