短信接收平台 API 文档

基础信息

项目	内容
API基础URL	`https://api.zhsms.xyz/api/Request/`
请求方式	POST
Content-Type	application/x-www-form-urlencoded
字符编码	UTF-8

签名方式

有出现验证失败的请使用 "校验签名" 接口，自行排除错误。

签名规则

登录管理后台获取用户编号和密钥
将参数拼接成数组形式，排除空值，按照ASCII码从小到大排序（字典序）
拼接成的字符串stringA再与密钥search_key拼接，进行md5运算得出签名

PHP示例代码

<?php
$search_key = '您的API密钥';
$post_data = [k1=>v1, k2=>v2, k3=>v3...];

$sign_str = [];

// 遍历参数数组并排除空值及sign参数本身
ksort($post_data); // 按参数名进行排序
foreach ($post_data as $k => $v){
    if($k == 'sign') continue;
    if(empty($v)) continue;
    
    $sign_str[] = $k.'='.$v;
}

$sign_str = implode($search_key, $sign_str) . $search_key;
$sign = md5($sign_str);
?>

特别注意

参数须ASCII码从小到大排序（字典序）
如果参数的值为空不参与签名
传递的sign参数不参与签名
参数名区分大小写

API 接口列表

1. 校验签名

接口说明：用于验证签名是否正确

POST

https://api.zhsms.xyz/api/Request/CheckSign

📝 请求参数：

参数名	示例值	必选	类型	说明
user_code	954368	必需	string	用户号
timestamp	1604219103	必需	number	请求时间戳(秒)
sign		必需	string	签名

✅ 成功返回示例：

{
  "code": 1,
  "msg": "SUCCESS",
  "time": "1707047116",
  "data": {
    "sign_str": "验证签名拼接的字符串",
    "sign": "签名"
  }
}

2. 取号回调

回调方式：POST

📝 回调参数：

参数名	说明
take_id	唯一ID
take_result	取号结果，1-取号成功 5-取号超时 7-余额不足
take_time	取号时间
platform_id	平台ID
phone_number	号码
timestamp	时间戳
sign	签名

回调说明

系统每10秒回调一次，回调次数10次后，将不再回调
验证成功后，必须返回纯字符串：success

3. 查询账户余额

接口说明：查询用户账户余额

POST

https://api.zhsms.xyz/api/Request/AccountBalance

📝 请求参数：

参数名	示例值	必选	类型	说明
user_code	378564	必需	string	用户号
timestamp	1604219103	必需	number	请求时间戳(秒)
sign		必需	string	签名

✅ 成功返回示例：

{
  "code": 1,
  "msg": "SUCCESS",
  "time": "1707047116",
  "data": {
    "balance": 0
  }
}

4. 取号请求(新)

接口说明：获取手机号码（同步方式）

POST

https://api.zhsms.xyz/api/Request/TakePhoneNumberEx

📝 请求参数：

参数名	示例值	必选	类型	说明
user_code	378564	必需	string	用户号
platform_id	231	必需	number	平台ID，请使用《获取平台信息》接口获取
take_count	1	必需	number	取号数量
notify_url		可选	string	回调地址，长度不能超过255
timestamp	1604219103	必需	number	请求时间戳(秒)
sign		必需	string	签名

✅ 成功返回示例：

{
  "code": 1,
  "msg": "SUCCESS",
  "time": "1710580013",
  "data": [
    {
      "take_id": "60241",
      "phone_number": "07046800611"
    }
  ]
}

5. 异步取号请求

接口说明：异步方式获取手机号，结果通过回调返回

POST

https://api.zhsms.xyz/api/Request/AsyncTakePhoneNumber

提示：此接口适合需要批量取号或不希望等待的场景，结果将通过notify_url回调返回。

6. 查询取号结果

接口说明：查询指定平台的取号结果

POST

https://api.zhsms.xyz/api/Request/GetTakeResult

备注

platform_ids为平台ID，多个ID用","分隔，如: 21,112,31，最多不能超过3个

7. 取消取号

接口说明：取消正在进行的取号任务

POST

https://api.zhsms.xyz/api/Request/CancelTake

8. 取消任务

接口说明：取消接收验证码任务

POST

https://api.zhsms.xyz/api/Request/CancelRecvCode

9. 设置为黑名单

接口说明：将号码加入黑名单

POST

https://api.zhsms.xyz/api/Request/Blocking

10. 查询状态

接口说明：查询取号任务的详细状态

POST

https://api.zhsms.xyz/api/Request/GetState

📊 状态码说明：

0 - 等待号码
1 - 等待短信(已成功)
3 - 已完成
4 - 超时
5 - 取号失败(超时)
6 - 取消任务
7 - 取号失败

11. 获取平台信息

接口说明：获取可用平台列表和价格信息

POST

https://api.zhsms.xyz/api/Request/GetPlatformInfo

返回数据包含平台ID、平台名称、单价、复购价等信息。

状态码说明

通用状态码

code值	说明
`1`	✅ 成功
`0`	❌ 失败

取号状态码 (state)

状态码	说明
`0`	⏳ 等待号码
`1`	📱 等待短信(已成功)
`3`	✅ 已完成
`4`	⏰ 超时
`5`	❌ 取号失败(超时)
`6`	🚫 取消任务
`7`	❌ 取号失败

取号结果码 (take_result)

结果码	说明
`1`	✅ 取号成功
`5`	⏰ 取号超时
`7`	💰 余额不足

注意事项

重要提醒

所有接口都需要签名验证
时间戳误差不能超过10分钟
参数必须按ASCII码排序
参数名区分大小写
空值参数不参与签名
sign参数不参与签名计算
回调接口必须返回 success 字符串
系统每10秒回调一次，最多回调10次

常见错误处理

签名验证失败：检查签名算法和参数排序
余额不足：充值账户余额
参数错误：检查必填参数是否完整
超时：增加超时时间或重试