电话与短信 API 快速入门
先用 SmartController 二层发现设备，再完成状态检查、拨号和短信发送。
1同一二层网络电脑与设备接入同一交换网络
2扫描 JYW记录设备列表中的 HTTP IP
3检查通信条件确认版本、SIM 和注册状态
4调用业务接口电话或短信；继续查询执行记录
1. 用 SmartController 发现设备 IP
安装并启动 SmartController 用户版。二层发现依赖 Npcap，不要求预先知道设备 IP，也不要求电脑与设备已经处于相同 IP 网段。
- 确保电脑和设备连接到同一二层网络；避免跨路由器、访客网络或开启客户端隔离的 Wi-Fi。
- 在“选择网卡”中选择连接设备网络的物理网卡。根据网卡名称和本机 IP 判断，不要选择 ZeroTier、VirtualBox、Hyper-V 等虚拟网卡。
- 点击“打开”，确认页面显示“二层设备发现可用（Npcap 已就绪）”。
- 点击“扫描设备”，在列表中找到类型为
JYW、设备类为HTTP的设备。 - 记录该设备的 IP；后续示例把它写入
$Base。
扫描不到设备：先确认 Npcap 已就绪、选中了物理网卡、电脑和设备在同一二层网络。临时关闭会拦截原始以太网帧的安全软件后再试；不建议用“手动添加”代替二层发现来判断设备是否在线。
2. 设置设备地址并做调用前检查
以下命令使用 Windows 自带的 curl.exe。将示例 IP 替换为扫描结果。
$Base = 'http://192.168.1.109' # 设备与 LTE 版本 curl.exe --noproxy "*" "$Base/api/status/version" # SIM、移动网络、信号和固话线路 curl.exe --noproxy "*" "$Base/api/module/sys/signal"
4G 电话和短信的最低条件
| 字段 | 期望值 | 说明 |
|---|---|---|
code | 0 | 还要同时确认 HTTP 状态为 2xx。 |
data.sim_card | 1 | 设备已识别 SIM 卡。 |
data.sys_sta | 4 或 5 | 模组已经启动并进入可用状态；5 表示信号较差。 |
data.rssi | 1..31 | 数值越大通常信号越强；99 表示未知。 |
只使用固话拨号：检查
data.tel_line=1，然后把拨号路径换成 /api/module/call/tel。3. 发起一次 4G 电话
POST /api/module/call/dial
| 参数 | 必填 | 作用 |
|---|---|---|
num | 是 | 被叫号码；客户端应限制为 3–13 位数字。 |
tts | 否 | 接通后播报的文字；普通中文可直接使用。 |
curl.exe --noproxy "*" -X POST ` -H "Content-Type: application/x-www-form-urlencoded" ` --data-urlencode "num=13800138000" ` --data-urlencode "tts=设备温度过高，请及时处理" ` "$Base/api/module/call/dial"
典型接受响应：
{
"code": 0,
"msg": "ok",
"data": {
"dialing": true,
"target": "13800138000",
"mode": "4g",
"has_tts": true,
"ts": 1786579200
}
}dialing=true 只表示设备开始拨号，不能证明已经振铃、接通或完成播报。最终结果应查询电话记录。查询最近 4G 电话记录：
curl.exe --noproxy "*" ` "$Base/api/module/record/list?type=1&offset=1&count=10"
4. 发送一条短信
POST /api/module/sms/send
| 参数 | 必填 | 作用 |
|---|---|---|
num | 是 | 短信接收号码；客户端应限制为 3–13 位数字。 |
content | 是 | 短信正文，不能为空。 |
encoding | 否 | 推荐使用 utf8；默认也是 UTF-8。 |
curl.exe --noproxy "*" -X POST ` -H "Content-Type: application/x-www-form-urlencoded" ` --data-urlencode "num=13800138000" ` --data-urlencode "content=设备温度过高，请及时处理" ` --data "encoding=utf8" ` "$Base/api/module/sms/send"
典型接受响应：
{
"code": 0,
"msg": "ok",
"data": {
"sent": true,
"target": "13800138000",
"len": 36,
"encoding": "utf8",
"ts": 1786579200
}
}sent=true 只表示发送动作已被接受，不是运营商送达报告。最终结果应查询已发送短信记录。查询最近已发送短信记录：
curl.exe --noproxy "*" ` "$Base/api/module/record/list?type=3&offset=1&count=10"
5. 客户端必须遵守的规则
请求规则
- 只使用 GET 和 POST。
- POST 使用
application/x-www-form-urlencoded，不要发送 JSON body。 - 电话、短信文本建议使用
--data-urlencode或等价表单编码。 - 文本暂时不要包含双引号、反斜杠或控制字符。
结果判断
- 同时判断 HTTP 2xx 和 JSON
code=0。 - LTE 业务错误可能仍返回 HTTP 200。
- 拨号/发送响应只代表动作开始。
- 不要对会改变设备状态的请求进行无条件自动重试。
安全要求：设备 API 当前不建立 token、Cookie 或 session，也没有全局访问控制。设备只能部署在可信专网中；跨网络使用时必须由上层网关实施认证、授权、审计和限流。
6. 重要告警：使用可恢复的电话/短信任务
上面的即时接口最容易上手，适合人工联调和不担心重复执行的场景。涉及告警、自动重试、断电恢复或去重时，应改用：
| 用途 | 接口 | 关键能力 |
|---|---|---|
| 告警电话任务 | POST /api/module/queue/add | src + rid + exp 防重复、过期控制和断电恢复 |
| 告警短信任务 | POST /api/module/smsq/add | src + rid + exp 防重复、过期控制和断电恢复 |
7. 常见问题
| 现象 | 优先检查 |
|---|---|
| 二层扫描不到设备 | Npcap、物理网卡、同一二层网络、交换机/Wi-Fi 客户端隔离。 |
Module timeout | LTE 模组状态、设备供电、是否有其他请求占用串口命令通道；不要立刻重复拨号。 |
reason=no_sim | SIM 是否安装、识别和可用。 |
reason=no_network | sys_sta、rssi、天线、套餐和运营商注册状态。 |
| 返回成功但对方没接到 | 成功仅表示已接受；继续查询 /module/record/list 的最终记录。 |