空号检测 - API文档

空号检测接口文档点击下载

空号检测接入指南点击访问

1、概要

1.1 文档说明

本文档提供互亿无线平台空号检测服务的接口对接指南，开发者可通过 HTTP 接口调用空号检测服务。

1.2 接口内容

空号检测提交、账户余额查询

1.3 提交方式

提交检测：POST + JSON
余额查询：GET

1.4 加密要求

所有请求必须使用 HMAC-SHA256 签名认证
【必读】签名机制文档：https://www.ihuyi.com/api/request.html

1.5 API ID / API KEY

登录用户中心，进入【空号检测】模块，在【产品总览】页面右侧，如下图所示：

空号检测接口

2、空号检测提交接口

2.1 接口描述

批量提交手机号进行空号检测，实时返回检测结果及计费状态，采用POST方式提交。

2.2 请求地址

https://api.ihuyi.com/empty-number/submit

2.3 请求头

参数名称	示例值	必填	说明
Content-Type	application/json	是	固定值
Date	Mon, 16 Jun 2025 08:24:34 GMT	是	GMT时间，误差±300秒
Authorization	Signature keyId="end7348191", algorithm="hmac-sha256", ...	是	签名头

2.4 请求参数（JSON）

参数名称	类型	必填	描述
mobiles	string	是	手机号数组（最多10个）

2.5 请求示例

{
  "mobiles": [
    "18221256432",
    "13611111112"
  ]
}

2.6 响应参数

参数	类型	描述
code	int	状态码（见下方说明）
msg	string	结果描述
data	array	检测结果数组
∟ mobile	string	手机号
∟ state	int	状态码 1：正常 2：空号 3：沉默号 4：风险号 -1：未知
∟ charge_state	int	计费状态 1：扣费 -1：不扣费

2.7 成功示例

{
  "code": 200,
  "data": [
    {
      "mobile": "18221256432",
      "state": 1,
      "charge_state": 1
    },
    {
      "mobile": "13611111112",
      "state": 2,
      "charge_state": -1
    }
  ],
  "msg": "请求成功"
}

2.8 失败示例

{
  "code": 4051,
  "msg": "剩余条数不足"
}

3、余额查询接口

3.1 接口描述

查询空号检测账户剩余额度，采用GET方式提交。

3.2 请求地址

https://api.ihuyi.com/empty-number/balance

3.3 请求头

参数名称	描述示例值	必填	说明
Date	如：Mon, 16 Jun 2025 08:24:34 GMT	是	GMT时间
Authorization	Signature keyId="end7348191", algorithm="hmac-sha256", ...	是	签名头

3.4 响应参数

参数名称	类型	描述
code	int	状态码（2成功）
message	string	结果描述
data	object	余额数据
∟ balance	int	剩余检测条数

3.5 响应示例

{
  "code": 2,
  "message": "请求成功",
  "data": {
    "balance": 97
  }
}

4、状态码说明

code	msg
0	未知错误
2	请求成功
400	非法IP访问
403	应用不存在
405	API ID或API KEY不正确
4050	余额查询失败
40505	没有签订合同
4051	剩余条数不足
1100	参数错误

完整python及php、Java、Go、Shell示例代码，可参考：https://gitee.com/shsurlink/api-demo/tree/master/hmac-auth

互亿无线 · 文档中心