X

API 开发文档

XiaoyuSMS 平台 RESTful API 接口文档 v1.0
返回前台 调试工具
概述
认证
钱包
发码
接码
示例
调试
服务地址
http://{{ location.host }}
认证方式
Cookie Session
数据格式
JSON (UTF-8)

响应格式

大多数接口返回 JSON，注册验证码接口返回 SVG 图片；成功 HTTP 200，失败返回对应状态码和 error 字段

成功响应
{ "message": "操作成功" }
失败响应
{ "error": "错误原因描述" } // HTTP 400 参数错误 | 401 未登录 | 429 频率限制 | 500 服务器错误

调用流程

本系统使用 Cookie Session 鉴权，不是 API Key。所有需要登录的接口必须先调用登录接口获取 Set-Cookie，并在后续请求中携带 Cookie

1. 登录保存Cookie
→
2. 查余额/权限
→
3. 取号
→
4. 创建发码任务
→
5. 轮询最终状态/接码

公开接口（无需登录）

{{ api.method }} {{ api.path }} 公开
{{ api.desc }}
响应示例
{{ api.response }}

用户登录

登录成功后服务器返回 Set-Cookie，后续所有需登录接口必须携带该 Cookie；账号 ID 支持纯数字或字母数字字符串

{{ api.method }} {{ api.path }} {{ api.auth?'需登录':'公开' }}
{{ api.desc }}
参数类型必填说明
{{ p.name }}{{ p.type }}{{ p.required?'是':'否' }}{{ p.desc }}
请求体
{{ formatJson(api.body) }}
响应示例
{{ api.response }}

余额与充值

查询余额、卡密充值、用户资料等钱包相关接口

{{ api.method }} {{ api.path }} 需登录
{{ api.desc }}
参数类型必填说明
{{ p.name }}{{ p.type }}{{ p.required?'是':'否' }}{{ p.desc }}
请求体
{{ formatJson(api.body) }}
响应示例
{{ api.response }}

发码接口

发码是异步任务：先取号，再创建发码任务，最后轮询状态接口直到 success/failed

{{ api.method }} {{ api.path }} {{ api.auth?'需登录':'公开' }}
{{ api.desc }}
参数类型必填说明
{{ p.name }}{{ p.type }}{{ p.required?'是':'否' }}{{ p.desc }}
请求体
{{ formatJson(api.body) }}
响应示例
{{ api.response }}

接码接口

接收短信验证码，需要余额和接码权限

{{ api.method }} {{ api.path }} {{ api.auth?'需登录':'公开' }}
{{ api.desc }}
参数类型必填说明
{{ p.name }}{{ p.type }}{{ p.required?'是':'否' }}{{ p.desc }}
响应示例
{{ api.response }}

多语言调用示例

完整的登录 → 取号 → 发码 → 查状态流程，支持 curl / Java / 易语言 / 懒人精灵

curl
Java
易语言
懒人精灵
1

登录获取 Cookie

POST 请求登录接口，-c 保存 Cookie 到文件

# 登录并保存Cookie curl -X POST http://{{ location.host }}/api/users/login \ -H "Content-Type: application/json" \ -d '{"user_id":"your_user_id","password":"yourpwd"}' \ -c cookies.txt # 响应: {"message":"登录成功","user_id":"your_user_id","is_superuser":false,"user_type":"普通用户"}
2

查询余额

-b 读取之前保存的 Cookie 文件

curl http://{{ location.host }}/api/users/balance \ -b cookies.txt # 响应: {"balance":30.5}
3

取号

获取一个可用手机号，返回 phone 和 com

curl -X POST http://{{ location.host }}/api/get-phone \ -H "Content-Type: application/json" \ -d '{"type":"risk"}' \ -b cookies.txt # 响应: {"phone":"17600001111","com":"33","link_id":1,"verify_type":"risk"}
4

发码

创建发码任务并异步发送，需继续轮询状态；最终 success 后扣费 1 元

curl -X POST http://{{ location.host }}/api/verify \ -H "Content-Type: application/json" \ -d '{"type":"risk","phone":"17600001111"}' \ -b cookies.txt # 响应: {"token":"xxx","com":"33","phone":"17600001111","task_id":"uuid","command":"COM33##..."}
5

查状态

轮询任务状态，直到返回 success 或 failed

curl "http://{{ location.host }}/api/sms/status?token=返回的token&com=33&sendtype=risk&sendtext=" # 响应: {"status":"success","message":"发送成功"}
1

初始化 HTTP 客户端

使用 OkHttp + CookieJar 自动管理 Cookie

// 依赖：okhttp + okhttp-urlconnection import okhttp3.*; import okhttp3.JavaNetCookieJar; import java.net.CookieManager; import java.net.CookiePolicy; CookieManager cookieManager = new CookieManager(); cookieManager.setCookiePolicy(CookiePolicy.ACCEPT_ALL); OkHttpClient client = new OkHttpClient.Builder() .cookieJar(new JavaNetCookieJar(cookieManager)) .build(); MediaType JSON = MediaType.parse("application/json");
2

登录

CookieJar 会自动保存并在后续请求中发送 Cookie

RequestBody loginBody = RequestBody.create( "{\"user_id\":\"your_user_id\",\"password\":\"yourpwd\"}", JSON); Request loginReq = new Request.Builder() .url("http://{{ location.host }}/api/users/login") .post(loginBody).build(); Response loginRes = client.newCall(loginReq).execute(); System.out.println(loginRes.body().string()); // {"message":"登录成功","user_id":"your_user_id","is_superuser":false,"user_type":"普通用户"}
3

取号 + 发码

自动携带 Cookie，无需手动处理

// 取号 Request phoneReq = new Request.Builder() .url("http://{{ location.host }}/api/get-phone") .post(RequestBody.create("{\"type\":\"risk\"}", JSON)) .build(); String phoneJson = client.newCall(phoneReq).execute().body().string(); // {"phone":"17600001111","com":"33","link_id":1,"verify_type":"risk"} // 发码 Request verifyReq = new Request.Builder() .url("http://{{ location.host }}/api/verify") .post(RequestBody.create( "{\"type\":\"risk\",\"phone\":\"17600001111\"}", JSON)) .build(); String result = client.newCall(verifyReq).execute().body().string();
1

声明变量

使用网页访问对象（精易模块或系统自带）

.局部变量 网页, 网页访问对象 .局部变量 返回文本, 文本型 .局部变量 Cookie, 文本型 .局部变量 手机号, 文本型
2

登录并保存 Cookie

注意 JSON 用 UTF-8 编码提交，不要用 GBK

' 登录 网页.打开 ("POST", "http://{{ location.host }}/api/users/login") 网页.设置请求头 ("Content-Type", "application/json") 网页.发送 (到字节集 ("{""user_id"":""your_user_id"",""password"":""yourpwd""}")) Cookie = 网页.取回应头 ("Set-Cookie") 返回文本 = 网页.取回应文本 () ' 返回: {"message":"登录成功"}
3

带 Cookie 调用业务接口

每次请求都要带上登录时获取的 Cookie

' 取号 网页.打开 ("POST", "http://{{ location.host }}/api/get-phone") 网页.设置请求头 ("Content-Type", "application/json") 网页.设置请求头 ("Cookie", Cookie) 网页.发送 (到字节集 ("{""type"":""risk""}")) 手机号 = 取JSON值 (网页.取回应文本 (), "phone") ' 发码 网页.打开 ("POST", "http://{{ location.host }}/api/verify") 网页.设置请求头 ("Content-Type", "application/json") 网页.设置请求头 ("Cookie", Cookie) 网页.发送 (到字节集 ("{""type"":""risk"",""phone"":""" + 手机号 + """"}"))
兼容说明：本平台所有 POST 接口同时支持 application/json 和 application/x-www-form-urlencoded 两种格式。懒人精灵推荐使用 表单格式（form），无需拼接 JSON 字符串。
1

登录获取 Cookie

使用 httpPost 提交表单参数，从响应头获取 Set-Cookie

-- ====== 方式一：表单格式（推荐）====== local baseUrl = "http://{{ location.host }}" -- 登录（表单格式，无需设置 Content-Type） local code, body, headers = httpPost( baseUrl .. "/api/users/login", "user_id=your_user_id&password=yourpwd" ) local cookie = headers["Set-Cookie"] or "" toast("登录结果: " .. body) -- ====== 方式二：JSON 格式（需支持自定义Header）====== -- local code, body, headers = httpPost( -- baseUrl .. "/api/users/login", -- '{"user_id":"your_user_id","password":"yourpwd"}', -- {"Content-Type: application/json"} -- )
2

取号

带 Cookie 请求取号接口，解析返回的 phone

-- 取号（表单格式 + Cookie） local code2, body2 = httpPost( baseUrl .. "/api/get-phone", "type=risk", {"Cookie: " .. cookie} ) local phone = body2:match([["phone":"(.-)"]]) local com = body2:match([["com":"(.-)"]]) toast("取号: " .. (phone or "失败"))
3

发码

表单提交发码请求

-- 发码（表单格式） local code3, body3 = httpPost( baseUrl .. "/api/verify", "type=risk&phone=" .. (phone or ""), {"Cookie: " .. cookie} ) local token = body3:match([["token":"(.-)"]]) toast("发码结果: " .. body3)
4

查状态（轮询）

GET 请求轮询，每2秒查一次，直到 success 或 failed

-- 轮询状态（每2秒查一次，最多30秒） for i = 1, 15 do mSleep(2000) local code4, body4 = httpGet( baseUrl .. "/api/sms/status?token=" .. (token or "") .. "&com=" .. (com or "") .. "&sendtype=risk&sendtext=" ) if body4:find([["success"]]) then toast("发送成功!") break elseif body4:find([["failed"]]) then toast("发送失败: " .. body4) break end end
5

接码（可选）

发码成功后查收验证码短信

-- 接码（GET 请求） local code5, body5 = httpGet( baseUrl .. "/api/sms/import?phone=" .. (phone or "") .. "&type=risk" ) local verifyCode = body5:match([["verify_code":"(.-)"]]) toast("收到验证码: " .. (verifyCode or "暂无"))
注意事项：① POST 请求同时支持 JSON（Content-Type: application/json）和表单（application/x-www-form-urlencoded）两种格式；② 登录后必须保存 Cookie 并在后续请求中携带；③ 发码成功后扣费 1 元，请确保余额充足；④ 查询状态建议间隔 2 秒轮询，避免过于频繁。

在线调试工具

点击其他标签页的接口可自动填充到调试器。登录接口调试成功后浏览器自动保存 Cookie。

发送请求 填入登录 填入取号 填入发码
响应结果
{{ debug.response || '等待请求...' }}