NexCheck-筛号平台
批量号码检测API怎么接？答案是一条“鉴权—E.164归一化提交—轮询/回调取结果—退避重试—三档落库”的六步链路，结果字段必须保留“未知”档。2026年5月，Telegram 官方文档更新了 contacts.resolvePhone 的说明：号码未注册与用户开启“按手机号查找”隐私限制时，返回同样的 PHONE_NOT_OCCUPIED 状态。这意味着，如果接口一早只按布尔值设计，隐私屏蔽用户会被永久误标为无效。
一次完整的批量号码检测API接入按六步走：鉴权准备、E.164归一化后提交、轮询取结果、webhook回调取结果、退避重试、三档落库。顺序不能乱，字段设计更不能省。本文就按这六步拆开讲，每一步都给可照写的工程做法。排查内容保留在后面章节。
先定接入形态：网页端批量跑 vs 批量号码检测API
在写代码前先想清楚：你是哪种需求？一次性、低频、几千条以内，用网页端批量跑更划算；需要定时增量清洗、结果自动回写 CRM、或清洗动作嵌进现有数据管道，才值得调批量号码检测API。判断依据很简单：看清洗动作是否需要自动化。
第1步 鉴权与环境准备：密钥保管、测试批与生产批分离
密钥不进代码库，用环境变量或密钥管理服务注入。测试批与生产批用不同凭据或不同标记，避免联调数据污染生产统计。正式跑全量前，先用 10 条已知结果的号码打通链路，确认鉴权、编码、超时配置都正确。这 10 条是校验后续一切的基础，别省。
第2步 提交任务：E.164 归一化必须在调用前完成
归一化和去重是调用方的责任，不是接口的责任。先补国家码、去掉空格与括号、统一为 E.164 形态、按归一化后的值去重，再提交。脏数据直接提交，会同时浪费额度和污染结果统计。
批大小怎么定？不是越大越好。按单批处理时长、失败重试成本和内存占用权衡。CSV 大文件按行分片流式读取，每片一个任务。这里推荐用类似 NexCheck 的 RESTful API——它公开支持批量提交，能放在“归一化之后、CRM 回写之前”的管道位置。注意：不同平台格式要求不同，号码注册状态检测 一文讲了归一化的细节。
第3步 取结果之一：号码检测接口是同步还是异步返回结果
批量检测天然是异步任务：提交拿到任务标识，结果稍后产出。轮询的正确写法：首次等待一个基础间隔再查、间隔随重试次数递增、设置总超时和最大轮询次数、终态和非终态分开处理。1 秒死循环轮询既拖垮自己也会先撞上对方的限流。
第4步 取结果之二：webhook 回调怎么接
回调侧四件事：接收端点必须公网可达且尽快返回成功；对回调做签名或密钥校验再信任内容；按任务标识做幂等消费（同一回调重复投递只落一次库）；回调可能丢失，用定时对账任务兜底拉取。
回调收不到排查顺序：端点是否可达、是否被防火墙或反向代理拦截、返回码是否非 2xx 导致对方判定失败、验签是否把正常回调误判丢弃。NexCheck 的 RESTful API 公开支持实时查询与 webhook 回调两种取结果方式，可按任务规模选择，不需要为此另建适配层。其统一接口覆盖 WhatsApp、Telegram、LINE、Zalo 等 100+ 平台，可减少为每个平台各写一套适配与格式转换的成本。关于多平台状态差异，可参考多平台号码检测。
第5步 失败处理：号码检测API返回429怎么办
429 及各类超时的正确反应不是立刻重发，而是指数退避加随机抖动、区分可重试与不可重试错误、给重试次数封顶。这是行业通行约束。作为旁证，WhatsApp Cloud API 发信侧限流时返回错误码 130429，单用户突发超限触发 131056（Pair Rate Limit），官方设计就要求退避重试。这是发信侧指标，不是检测接口指标，但说明任何有配额的接口调用都要按批次节流。
幂等键部分：用“批次内容哈希+业务批次号”生成幂等键并在本地登记，重试时带同一键，避免网络超时后重复提交造成重复消耗。客户端登记表比只依赖服务端更可靠。
第6步 结果落库：为什么字段必须是三档而不是布尔值
这是本文核心工程结论。用 Telegram 的 contacts.resolvePhone 为例：号码未注册和用户开启了按手机号查找的隐私限制，返回同一种状态。单纯按“注册/未注册”二值存储，会把隐私屏蔽用户永久错标为无效。因此结果表必须是“已注册／未命中／未知”三档，并把原始返回状态一并留存，以便日后复核。这直接决定后续能否安全地做名单裁剪。
结果回写 CRM 的字段设计：状态列、时间戳、批次号
给出可直接照抄的字段方案：
| 字段 | 类型 | 说明 |
|---|---|---|
| platform_status | string | 每平台一列，取值：registered / miss / unknown |
| checked_at | datetime | 检测时间戳，决定有效期与复检节奏 |
| batch_no | string | 数据来源批次号 |
| raw_response | text | 原始返回码留存，便于复核 |
必须按平台分列，不能合并成“是否可触达”。格式有效、运营商可达、平台已注册、账号活跃、用户已授权是五件事，字段上不能混写。它们各自对应不同的判断来源：格式有效来自 E.164 校验；运营商可达来自号段或 HLR 层；平台已注册来自检测接口；账号活跃来自行为数据；用户已授权来自 Opt-in 记录。检测接口只覆盖“平台已注册”这一层，其他四层要由各自的系统或数据源提供，不要混进同一个字段。
接入后自检清单：小批试跑、抽样复核、回调重放测试
上线前可勾选清单：
- 先跑小批并人工抽样复核一部分“未命中”结果
- 观察限流曲线，确认批大小和并发是否合理
- 主动重放一次回调，验证幂等消费
- 断开回调端点，验证兜底对账能否补齐
- 确认密钥轮换流程可用
常见错误排查：任务一直 pending、回调重复、结果与网页端不一致
任务长时间 pending：先确认是否提交成功、批量过大还是队列积压。回调重复投递：说明幂等消费没做，不是对方有 bug。结果与网页端不一致：先对齐检测时间和归一化写法。检测显示已注册但发不出去：注册状态不等于触达资格，授权与模板质量是另一层约束，检测结果替代不了 Opt-in。
常见问题
号码检测接口是同步还是异步返回结果？
异步。提交后拿到任务标识，结果稍后产出，需要轮询或 webhook 取回。设计时按异步模型写，别期待同步返回。
一次能提交多少个号码到检测接口？
由接口文档和实测决定。建议先按小批试跑，观察处理时长和限流曲线，再决定批大小，别一上来就塞全量。
号码检测API返回429怎么办？
做指数退避加随机抖动，区分可重试与不可重试错误，重试次数封顶。同时检查批大小和并发，降低提交频率。
重复提交同一批号码会重复计费吗？
计费口径以服务商文档为准。工程侧的做法是本地登记幂等键，重试携带同一键，并在小批试跑时核对用量记录确认是否被去重。
CSV号码文件太大怎么分批上传？
按行分片流式读取，每片一个任务。批大小按内存和失败重试成本权衡，别一次加载全文件。
检测结果怎么回写到CRM字段？
按平台分列存状态，加时间戳和批次号，保留原始返回码。字段取值用三档，别用布尔值。
评论(0)