API 接口文档
RESTful 接口，返回 JSON 格式。请自行测试哪个线路连通性较好并随时更换。
🌐 服务器地址
以下为可用线路，建议在代码中提供一个输入框让用户自行填写，以便服务器地址变更时不受影响。
| 请求协议 | 线路地址 | 备注 | 更新时间 |
|---|---|---|---|
| HTTPS | api.haozhuma.com | 线路一 | 2025-01-01 |
| HTTPS | api.haozhuyun.com | 线路二 | 2025-01-01 |
💡 提示：所有接口均使用 HTTPS 协议。API Base URL 格式：
https://api.haozhuma.com/sms/（替换为实际线路地址即可）
处理流程
1
获取 API 账号和密码
前往以下网页注册/登录获取 API 账号和 API 密码：
h5.haozhuma.com |
h5.haozhuyun.com
2
登录获取 Token
调用登录接口，使用账号+密码换取 Token 令牌。登录一次即可，不要每次取号都重新登录。
3
获取号码
调用获取号码接口，提交项目名称，获得一个可用手机号
4
获取验证码（每15秒轮询）
调用获取验证码接口，每 15 秒 查询一次来码情况。如果 3 分钟 还没收到，号码可能欠费，应拉黑该号码。
💡 如何正确选择项目名？
先用自己手机号在目标平台收一条短信看模板。例如收到 【4399】您的验证码是123456，项目名就是 4399。
如果试了很多号码都没收到验证码，非常大的概率是选错了项目名。
⚠ 再次使用已有号码流程：
必须先调用 指定号码接口，返回值提示成功后才代表号码占用成功，这时候才能读取验证码。否则会提示「你没有权限读取该号码」。
📂 接口目录
1. POST /login — 登录获取Token 2. GET /getPhone — 获取手机号（sid=项目ID） 3. GET /getPhone?phone= — 指定号码（同 getPhone + phone 参数） 4. GET /getMessage — 获取验证码（sid+phone 轮询） 5. GET /cancelRecv + /cancelAllRecv — 释放号码 6. POST /blacklist — 拉黑号码 7. 错误码说明 8. 完整代码示例1. 登录获取 Token
GET/POST
/sms/?api=login&user=用户名&pass=密码
用于获取令牌。登录一次即可，不要每一次获取号码都访问一次此接口。获得令牌后，后续就不要再次请求。令牌为固定值，除用户修改密码外不会变。
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| user | 是 | string | 用户名（API 账号） |
| pass | 是 | string | 密码（API 密码） |
返回成功示例：
{
"msg": "success",
"code": 0,
"token": "2f05a475cc82f05a4cc82f05a475cc8"
}
code=0 或 code=200 为成功，code=-1 为失败。令牌为固定值，开发者写软件时登录只请求一次获取到令牌后即可。
2. 获取手机号
GET/POST
/sms/?api=getPhone&token=令牌&sid=项目ID
根据项目 ID 获取可用手机号。
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| token | 是 | string | 令牌 |
| sid | 是 | int | 项目 ID |
| isp | 否 | int | 运营商：isp=1 中国移动，参考运营商参数代码表 |
| Province | 否 | string | 号码省份：Province=44 代表广东，参考省份代码表 |
| ascription | 否 | int | 号码类型：留空=不限制，ascription=1 只取虚拟，ascription=2 只取实卡 |
| paragraph | 否 | int | 只取号段，留空=不限制。多选用 | 连接，如 1380|1580|1880 |
| exclude | 否 | int | 排除号段，留空=不限制。多选用 | 连接 |
| uid | 否 | string | 只取该对接码，加入多个对接码时可用该参数只取这个对接码的手机号 |
| author | 否 | string | 开发者账号（置入该参数获取消费分成），开发者分成 50% |
返回成功示例：
{
"code": "0",
"msg": "成功",
"sid": "1000",
"shop_name": "淘宝网",
"country_name": "cn",
"country_code": "cn",
"country_qu": "+86",
"uid": null,
"phone": "手机号",
"sp": "移动",
"phone_gsd": "广东"
}
| 返回参数 | 说明 |
|---|---|
| code | 状态码，code=0 为成功，code=其他为失败 |
| msg | 描述 |
| sid | 项目 ID |
| country_name | 国家名称 |
| country_code | 国家代码 |
| country_qu | 国家区号 |
| uid | 手机号所属对接码 |
| phone | 号码 |
| sp | 号码运营商 |
| phone_gsd | 号码归属地 |
code=0 为成功，code=其他 为失败。
3. 指定手机号（再次接码）
GET/POST
/sms/?api=getPhone&token=令牌&sid=项目ID&phone=号码
⚠ 说明：此接口与「获取号码」是同一个
当某个号码需要再次接码时，调用该接口进行占用，成功后才能读取该号码的短信。
api=getPhone，区别是多了 phone 参数。当某个号码需要再次接码时，调用该接口进行占用，成功后才能读取该号码的短信。
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| token | 是 | string | 令牌 |
| sid | 是 | int | 项目 ID |
| phone | 是 | int | 要占用的号码 |
| author | 否 | string | 开发者账号（置入获取消费分成） |
返回成功示例：
{
"code": "0",
"msg": "成功",
"sid": "22563",
"country_name": "中国",
"country_code": "cn",
"country_qu": "+86",
"phone": "132548966",
"sp": "联通",
"phone_gsd": "上海 上海"
}
| 返回参数 | 说明 |
|---|---|
| code | 状态码，code=0 为成功，code=其他为失败 |
| msg | 描述 |
| sid | 项目 ID |
| country_name | 国家名称 |
| country_code | 国家代码 |
| country_qu | 国家区号 |
| phone | 号码 |
| sp | 号码运营商 |
| phone_gsd | 号码归属地 |
code=0 为成功，code=其他 为失败。占用成功后即可调用「获取验证码」接口读取该号码的短信。
4. 获取验证码
GET/POST
/sms/?api=getMessage&token=令牌&sid=项目ID&phone=号码
每 15 秒轮询一次，不要过于频繁。如果 3 分钟还没收到验证码，应拉黑该号码。
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| token | 是 | string | 令牌 |
| sid | 是 | int | 项目 ID |
| phone | 是 | int | 手机号码 |
返回成功示例（已收到验证码）：
{
"code": "0",
"msg": "成功",
"sms": "【游戏】您正在申请手机注册，验证码为：5184，1440分钟内有效！",
"yzm": "123456"
}
| 返回参数 | 说明 |
|---|---|
| code | 状态码，code=0 为成功（已收到短信），code=其他为未收到 |
| msg | 描述 |
| sms | 完整短信内容 |
| yzm | 系统识别的数字验证码 |
code=0 表示已收到验证码，code=其他 为尚未到达，继续等待下次轮询。
5. 释放手机号
5.1 释放指定号码
GET/POST
/sms/?api=cancelRecv&token=令牌&sid=项目ID&phone=号码
不来码或者号码是老号可以调用此接口进行释放。注意：释放后下次获取号码可能还会出来，如不想再分配到该号码请调用拉黑接口。
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| token | 是 | string | 令牌 |
| sid | 是 | int | 项目 ID |
| phone | 是 | int | 手机号码 |
{
"code": "0",
"data": "null",
"msg": "释放成功"
}
5.2 释放全部手机号
GET/POST
/sms/?api=cancelAllRecv&token=令牌
一次性释放当前账号下的所有号码。
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| token | 是 | string | 令牌 |
{
"code": "200",
"data": "null",
"msg": "success"
}
code=0 或 code=200 为成功，code=-1 为失败。
6. 拉黑号码
GET
/sms/?api=blacklist&token=xxx&task_id=88234
超过 3 分钟还没收到验证码时，应调用此接口拉黑该号码，防止再次遇到影响效率。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| token | string | 是 | Token |
| task_id | int | 是 | 任务 ID |
{"code":0,"msg":"已加入黑名单"}
7. 错误码说明
| 错误码 | 说明 |
|---|---|
| 0 | 请求成功 |
| 1001 | Token 无效或已过期，请重新登录 |
| 1002 | 余额不足 |
| 1003 | 项目不存在，请检查项目名是否正确 |
| 1004 | 暂无可用号码 |
| 1005 | 任务不存在或已过期 |
| 1006 | 短信尚未到达，请稍后重试 |
| 1007 | 你没有权限读取该号码（需先调用指定号码接口占用） |
| 1008 | 请求过于频繁，请每15秒轮询一次 |
| 9999 | 服务器内部错误 |
8. 完整代码示例
Python — 完整接码流程
import requests
import time
BASE = "https://api.haozhuma.com/sms/" # 也可用 api.haozhuyun.com
USER = "your_username"
PASS = "your_password"
# 第一步：登录获取 Token（只登一次！）
resp = requests.get(f"{BASE}?api=login&user={USER}&pass={PASS}")
data = resp.json()
if data["code"] != 0:
raise Exception(data["msg"])
token = data["token"]
print("登录成功，Token:", token)
# 第二步：获取号码（sid 为项目ID）
resp = requests.get(f"{BASE}?api=getPhone&token={token}&sid=1000")
data = resp.json()
if data["code"] != "0":
raise Exception(data["msg"])
phone = data["phone"]
sid = data["sid"]
shop = data["shop_name"]
print(f"获取号码: {phone}，项目: {shop}（SID:{sid}）运营商: {data.get('sp','')} 归属地: {data.get('phone_gsd','')}")
# 第三步：每15秒轮询获取验证码（api=getMessage，用 sid+phone）
for i in range(12): # 12次 × 15秒 = 3分钟
time.sleep(15)
resp = requests.get(f"{BASE}?api=getMessage&token={token}&sid={sid}&phone={phone}")
result = resp.json()
if result["code"] == "0":
sms = result["sms"]
yzm = result["yzm"] # 系统识别的数字验证码
print(f"短信内容: {sms}")
print(f"验证码: {yzm}")
break
else:
# 超时拉黑（释放+拉黑）
print("3分钟超时，拉黑号码")
requests.get(f"{BASE}?api=blacklist&token={token}&sid={sid}&phone={phone}")
# 再次使用同一号码（同一个 api=getPhone，加 phone 参数）
print("\n--- 再次使用同一号码 ---")
resp = requests.get(f"{BASE}?api=getPhone&token={token}&sid=1000&phone={phone}")
if resp.json()["code"] == "0":
print("号码占用成功，可以读取验证码了")
cURL 示例
# 登录（只登一次）
curl "https://api.haozhuma.com/sms/?api=login&user=your_user&pass=your_pass"
# 获取号码（sid 为项目ID）
curl "https://api.haozhuma.com/sms/?api=getPhone&token=tk_xxx&sid=1000"
# 获取验证码（api=getMessage，用 sid+phone；每15秒轮询一次）
curl "https://api.haozhuma.com/sms/?api=getMessage&token=tk_xxx&sid=1000&phone=132548966"
# 释放号码（不来码或老号；api=cancelRecv）
curl "https://api.haozhuma.com/sms/?api=cancelRecv&token=tk_xxx&sid=1000&phone=132548966"
# 释放全部号码（api=cancelAllRecv）
curl "https://api.haozhuma.com/sms/?api=cancelAllRecv&token=tk_xxx"
# 拉黑（3分钟超时后）
curl "https://api.haozhuma.com/sms/?api=blacklist&token=tk_xxx&sid=1000&phone=132548966"
Node.js 示例
const axios = require('axios');
const BASE = 'https://api.haozhuma.com/sms/'; // 也可用 api.haozhuyun.com
// 登录（只登一次！）
const { data } = await axios.get(`${BASE}?api=login&user=your_user&pass=your_pass`);
if (data.code !== 0) throw new Error(data.msg);
const token = data.token;
// 获取号码（sid 为项目ID）
const { data: phoneData } = await axios.get(`${BASE}?api=getPhone&token=${token}&sid=1000`);
const { phone, sid: shopSid, shop_name } = phoneData;
// 15秒轮询（api=getMessage，参数是 sid+phone）
for (let i = 0; i < 12; i++) {
await new Promise(r => setTimeout(r, 15000));
const { data } = await axios.get(`${BASE}?api=getMessage&token=${token}&sid=${shopSid}&phone=${phone}`);
if (data.code === "0" || data.code === 0) {
console.log('短信:', data.sms, '验证码:', data.yzm);
break;
}
}