号码实时检测 API 怎么对接？HTTP/SMPP、批量提交与回调配置指南

<p>号码实时检测 API 的对接，核心就三步：<strong>拿鉴权凭证 → 按文档调接口 → 处理返回结果（同步或回调）</strong>。以智慧云信平台的接入为例，从申请到跑通首条查询，熟练的研发半天内能完成；从零了解全流程，读完这篇就够。</p> <p>本文覆盖 HTTP 同步查询、批量提交、回调通知三种对接方式，以及鉴权、限流、结果字段这些最容易踩坑的细节。</p>

<h2>小目录</h2>

<li>对接前需要准备什么</li>

<li>HTTP 同步查询：单条实时核验</li>

<li>批量提交 + 回调：大批量异步处理</li>

<li>返回结果字段说明</li>

<li>常见报错与排查</li>

<li>常见问题（FAQ）</li>

<h2>对接前需要准备什么</h2>

<p>先确认三件事，缺一不可：</p>

<li><strong>开通账号与测试额度</strong>：在智慧云信平台注册后，注册送 20 元测试额度，用测试额度跑通接口，不花真金白银。客服 TG：@zhihuiyunxin。</li>

<li><strong>拿到接口文档与凭证</strong>：平台会提供 app_id（或 api_key）、secret，以及接口地址、签名算法说明。凭证务必放服务端，不要写进前端代码。</li>

<li><strong>明确你的调用方式</strong>：单条实时（同步）、批量（异步+回调）、还是两者都要。先想清楚，再选接口。</li>

<h2>HTTP 同步查询：单条实时核验</h2>

<p>同步查询适合注册风控、下单校验这种"当场就要结果"的场景。流程是：你的服务端收到请求 → 调号码检测接口 → 拿到状态码 → 决定放行或拦截。</p> <p>一次标准请求大致如下（示意，字段以平台文档为准）：</p> <p>```http POST /api/v1/realtimecheck/check Host: api.3yit.com Content-Type: application/json Authorization: Bearer <your_token></p> <p>{ "phone": "13800138000", "query_type": "full" // full=完整5状态；base=仅判空号/非空号 }

<p>返回示例：</p>
<p>```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "phone": "13800138000",
    "status": 1,
    "status_desc": "活跃号",
    "carrier": "移动",
    "area": "广东·广州",
    "query_time": "2026-08-16 10:23:45"
  }
}
```</p>
<p>对接注意点：</p>

<li><strong>鉴权</strong>：签名或 token 有效期内复用，避免每次请求都重新换取，减少延迟。</li>

<li><strong>超时设置</strong>：同步接口建议客户端超时设 3-5 秒，预留网络抖动。返回超时时要按"放行"还是"拦截"处理，注册风控场景建议按拦截处理，宁可误伤不要放过风险号。</li>

<li><strong>缓存策略</strong>：短时间重复查询同一号码可以加一层缓存（比如 5 分钟内复用结果），省调用量。但记住实时检测的价值在"当下"，缓存时间别设太长。</li>


<h2>批量提交 + 回调：大批量异步处理</h2>

<p>几万条、几十万条号码一次性处理，走批量接口。流程：上传号码清单 → 服务端排队处理 → 通过回调通知你结果。</p>
<p>批量提交示例（示意）：</p>
<p>```http
POST /api/v1/realtimecheck/batch
Content-Type: application/json
Authorization: Bearer <your_token></p>
<p>{
  "task_name": "20260816_清洗活动名单",
  "phones": ["13800138000", "13900139000", "13700137000"],
  "notify_url": "https://your-server.com/callback/realtimecheck"
}
```</p>
<p>返回会给你一个 `task_id`，处理进度和结果都挂在它下面。</p>
<p><strong>回调（notify_url）是批量模式的核心</strong>。处理完成后，平台会向你配置的地址推送结果。回调报文里通常包含 `task_id`、逐条 `phone` 与 `status`。你需要：</p>

<li>在回调接口里做<strong>验签</strong>，防止伪造推送。</li>

<li>回调接口要<strong>幂等</strong>：同一批结果可能推送多次，用 `task_id + phone` 做去重。</li>

<li>回调超时或失败要有补偿：确认你的服务商支持失败重推。</li>

<p>来源：智慧云信通信技术团队根据平台接口设计与客户接入案例整理，具体字段以接口文档为准。</p>

<h2>返回结果字段说明</h2>

<p>各平台字段名有差异，但核心状态语义一致。智慧云信平台的状态码约定如下：</p>
<table><thead><tr><th>状态码</th><th>含义</th><th>业务建议</th></tr></thead><tbody>
<tr><td>1</td><td>活跃号</td><td>正常触达、放行</td></tr>
<tr><td>2</td><td>空号</td><td>剔除、拦截</td></tr>
<tr><td>3</td><td>停机号</td><td>转入唤醒名单</td></tr>
<tr><td>4</td><td>风险号</td><td>拦截、标记</td></tr>
<tr><td>5</td><td>沉默号</td><td>低频触达</td></tr>
</tbody></table>

<p>配套字段：`carrier`（运营商）、`area`（归属地）、`query_time`（查询时间）。有的场景还需要号码类型（个人号/物联网卡）判断，接入前确认你的服务商是否提供。</p>

<h2>常见报错与排查</h2>

<p>对接期 90% 的问题集中在四类：</p>
<table><thead><tr><th>报错/现象</th><th>大概率原因</th><th>处理</th></tr></thead><tbody>
<tr><td>401 鉴权失败</td><td>token 过期、secret 配错</td><td>检查凭证与签名算法，重新换取</td></tr>
<tr><td>400 号码格式错误</td><td>号码含空格、+86 前缀未处理</td><td>统一格式：11 位纯数字，或按文档要求带区号</td></tr>
<tr><td>限流（429）</td><td>触发 QPS 上限</td><td>加本地排队或降低并发，按文档限流值配置</td></tr>
<tr><td>回调没收到</td><td>notify_url 无法访问、未验签通过</td><td>检查回调地址公网可达性、是否要求 HTTPS</td></tr>
</tbody></table>

<p>排查效率最高的一招：先用平台在线调试工具（或 Postman）手工调通单条，确认返回结构，再写代码接入。别一上来就写批量逻辑。</p>
<p><strong>准备好接入了吗？</strong> 智慧云信平台注册送 20 元测试额度，直接用真数据跑通接口再决定是否采购。客服 TG：@zhihuiyunxin。</p>

<h2>常见问题（FAQ）</h2>

<p><strong>Q1：接口支持哪些语言？</strong>
接口是标准 HTTP，任何语言都能调。平台提供 Python、PHP、Java、Go 等示例代码，照着示例改参数即可。</p>
<p><strong>Q2：支持 SMPP 方式对接吗？</strong>
支持。需要走短信通道协议的场景（比如发送前在短信网关里联动校验），可以联系客服确认 SMPP 对接参数与限流要求。</p>
<p><strong>Q3：批量接口单次能提交多少条？</strong>
视通道配额而定，常见上限为单次 1 万-5 万条。更大体量可分片提交，配合回调逐批收结果。具体配额以平台账号等级为准。</p>
<p>---</p>
<p><strong>延伸阅读</strong></p>

<li><a href="realtimecheck-什么是号码实时检测.md">什么是号码实时检测</a></li>

<li><a href="realtimecheck-高并发批量.md">大批量号码提交的高并发方案</a></li>

<li><a href="realtimecheck-crm-vos集成.md">CRM/VOS/外呼系统集成</a></li>

<p>---</p>
<p>本文由智慧云信通信技术团队编写，内容结合运营商通道运营数据与客户接入案例整理。接口字段与配额以平台文档为准。</p>