手机号码状态查询 API 接入指南：10 分钟完成对接
面向开发者的手机号码状态查询 API 接入教程，涵盖接口能力、AppCode 认证、curl/Python/Java 示例、返回状态说明与批量调用最佳实践。
呼叫中心、贷后管理、律所等场景都有一个共同需求：手上一批手机号，怎么知道哪些还能打通？ 手机号码状态查询 API 就是解决这个问题的标准方案——它实时查询号码在运营商侧的登记状态，返回「正常、空号、关机、欠费、不在网」等结果，让你在拨号之前就知道这个号码值不值得打。
本文是一份面向开发者的接入指南，按真实项目里的对接流程来写，10 分钟可以跑通第一个查询。
以阿里云市场的手机号在网状态 API / 实时空号检测为例，核心能力是直连三网运营商（移动、联通、电信）查询号码实时状态，准确率 ≥99.9%，支持携号转网识别。
一次查询返回的状态包括：
| 状态 | 含义 | 业务建议 |
|---|---|---|
| 正常 | 号码在用、可正常通话 | 优先外呼 |
| 空号 | 号码已注销/未分配 | 直接剔除 |
| 通话中 | 号码正忙 | 稍后重试 |
| 不在网 | 号码停机或未激活 | 标记沉睡 |
| 关机 | 终端关机 | 换个时段 |
| 无短信能力 | 收不到短信验证码 | 短信通道剔除 |
| 欠费 | 账户欠费停机 | 延缓联系 |
| 长时间关机 | 长期关停 | 高风险失联 |
在商品详情页下单（按次计费、即买即用），订单完成后到「云市场控制台 → 已购买的服务」里复制 AppCode。AppCode 相当于你的 API 密钥，请妥善保管，不要写进前端代码。
云市场 API 的认证方式是请求头携带 Authorization: APPCODE <你的AppCode>，请求地址、请求方法（GET 或 POST）与参数名以商品详情页提供的接口文档为准（网关域名为 api.market.aliyun.com，不同商品的路径不同，不要照搬其它商品的示例）。
提示：本文不贴具体代码示例，避免以偏概全——每个商品的接口文档都有差异，对接时以该商品详情页的 API 文档为准。
返回结构一般分为 code（状态码）与 data（业务数据）两部分，data 里包含手机号、检测状态、当前运营商、查询时间等字段，具体字段名以商品文档为准。核心是 status 字段——它告诉你这个号码当前是「正常、空号、关机」等 8 种状态中的哪一种。
接口按次计费，批量清洗时建议循环调用 + 结果落库，不要每次查询都现查现用：
- 逐条（或按接口支持的方式）提交号码，拿到返回的
status状态； - 把状态结果连同查询时间写入数据库，后续直接用缓存；
- 控制调用频率（QPS），避免触发限流；单条失败要记录日志，便于重试。
实现上就是一个「遍历号码 → 调接口 → 存结果」的循环，任何语言都能写，重点是频率控制和结果缓存。
- 先清洗后外呼：外呼前先批量查询，把「空号、欠费、长时间关机」过滤掉，接通率立竿见影（参考呼叫中心空号过滤实战）。
- 结果缓存：号码状态短期变化不大，查询结果建议缓存 7-30 天，节省调用成本。
- 关注携号转网：运营商变了不代表号码死了，把携号转网号码单独分组，营销话术可以差异化（详见携号转网识别）。
想直接体验？前往手机号在网状态 API / 实时空号检测下单即可获得 AppCode，按本文步骤 10 分钟完成首个查询。