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

智慧云信 > 号码实时检测 2026-08-16

号码实时检测 API 的对接，核心就三步：拿鉴权凭证 → 按文档调接口 → 处理返回结果（同步或回调）。以智慧云信平台的接入为例，从申请到跑通首条查询，熟练的研发半天内能完成；从零了解全流程，读完这篇就够。

本文覆盖 HTTP 同步查询、批量提交、回调通知三种对接方式，以及鉴权、限流、结果字段这些最容易踩坑的细节。

小目录

对接前需要准备什么

HTTP 同步查询：单条实时核验

批量提交 + 回调：大批量异步处理

返回结果字段说明

常见报错与排查

常见问题（FAQ）

对接前需要准备什么

先确认三件事，缺一不可：

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

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

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

HTTP 同步查询：单条实时核验

同步查询适合注册风控、下单校验这种"当场就要结果"的场景。流程是：你的服务端收到请求 → 调号码检测接口 → 拿到状态码 → 决定放行或拦截。

一次标准请求大致如下（示意，字段以平台文档为准）：

```http POST /api/v1/realtimecheck/check Host: api.3yit.com Content-Type: application/json Authorization: Bearer

{ "phone": "13800138000", "query_type": "full" // full=完整5状态；base=仅判空号/非空号 } ```

返回示例：

```json { "code": 0, "msg": "success", "data": { "phone": "13800138000", "status": 1, "status_desc": "活跃号", "carrier": "移动", "area": "广东·广州", "query_time": "2026-08-16 10:23:45" } } ```

对接注意点：

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

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

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

批量提交 + 回调：大批量异步处理

几万条、几十万条号码一次性处理，走批量接口。流程：上传号码清单 → 服务端排队处理 → 通过回调通知你结果。

批量提交示例（示意）：

```http POST /api/v1/realtimecheck/batch Content-Type: application/json Authorization: Bearer

{ "task_name": "20260816_清洗活动名单", "phones": ["13800138000", "13900139000", "13700137000"], "notify_url": "https://your-server.com/callback/realtimecheck" } ```

返回会给你一个 `task_id`，处理进度和结果都挂在它下面。

回调（notify_url）是批量模式的核心。处理完成后，平台会向你配置的地址推送结果。回调报文里通常包含 `task_id`、逐条 `phone` 与 `status`。你需要：

在回调接口里做验签，防止伪造推送。

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

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

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

返回结果字段说明

各平台字段名有差异，但核心状态语义一致。智慧云信平台的状态码约定如下：

状态码	含义	业务建议
1	活跃号	正常触达、放行
2	空号	剔除、拦截
3	停机号	转入唤醒名单
4	风险号	拦截、标记
5	沉默号	低频触达

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

常见报错与排查

对接期 90% 的问题集中在四类：

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