API对接怎么做？筛号场景下的 API集成、Webhook 完成回调与 CRM 数据回流教程

很多出海团队做筛号的起点都是同一条路：控制台生成号码 → 提交筛选任务 → 等任务跑完 → 下载 CSV → 手工整理 → 粘进 CRM 或发送系统。号码量在几千条时这套流程还能跑；一旦上到几十万条、每天提交多次，人工搬运就会变成整条链路里最慢、也最容易出错的一环。

这篇文章讲的就是怎么把这套动作变成可复用的 API对接：先分清 API集成 与 Webhook 的边界，再按「生成 → 去重 → 筛选 → 导出 → 回流」拆解落地步骤，最后给出数据治理与格式检查清单。

需要先说明：本文不涉及任何接口路径、鉴权细节与字段级实现，凡具体参数、返回字段与通知方式，一律以 使用文档 和控制台实际展示为准。

什么是筛号场景下的 API对接？三个概念一次分清

对接的本质不是「写代码」，而是让筛选结果自动流动，减少人工搬运。先把三个词放到正确的位置上。

API对接、API集成、Webhook 分别指什么

概念	一句话定义	在本业务中的典型位置	你需要准备什么
API对接	用程序代替人工操作控制台	提交批量筛号任务、查询任务状态、拉取结果	号码清单、字段映射、调用凭证（以官方文档为准）
API集成	把多个系统串成一条自动流转的链	号码生成 → 筛号 → CRM / BI / 发送系统	数据契约、主键定义、错误处理规则
Webhook	平台在事件发生时主动推送一条通知	任务完成提醒、结果就绪通知	接收地址、鉴权方式、幂等处理逻辑

关键区别在于方向：API 是「你去拉」，Webhook 是「平台推给你」。轮询接口能拿到结果，但要自己反复问；Webhook 只在事件发生那一刻通知一次，省资源，但要求接收端必须能处理重复通知和丢失重试。

控制台导出还够用吗？什么规模该考虑对接

不必一上来就开发。满足以下多数条件时，控制台导出仍然是最省事的方案：

• 每周筛号任务少于 3 次
• 单次号码量在几千条以内
• 结果只进一个人手上的表格，没有下游系统
• 对时效要求是「这周内」

出现下面任意一条，就该考虑对接了：

• 每天提交 3 次以上，或周号码量达到十万级别
• 筛选结果要同时进入 CRM、BI、发送系统等多个下游
• 结果回流必须在小时级完成
• 手工导出已经出现过漏行、错列、重复导入等问题

对接前必须先明确的四件事

这四件事没定下来，后面写得再快也会返工：

1. 号码格式标准：统一用 E.164（+[国家码][国内号码]），美国写为 +1XXXXXXXXXX。生成端、筛选端、CRM 端三处格式必须一致。
2. 去重策略：以哪个字段为主键，跨任务怎么去重，多久清理一次历史数据。
3. 结果落库位置：落在哪张表、字段叫什么、谁有权限改表结构。
4. 失败与重试的归属方：超时、任务部分完成、通知丢失，分别由谁负责补偿。

如何规划一条可复用的批量筛号数据链路？

标准流水线是：生成 → 去重 → 筛选 → 导出 → 回流。每一环都有明确产出物，断点通常出现在两个环节之间。

第一步：号码生成与 E164 格式统一

号码生成有三种方式，按你对目标地区的了解程度选：

• 全球号码生成：按国家 → 城市/地区 → 号段精确圈选，适合对目标号段有研究的团队。
• 自定义号段生成：上传自定义号段 CSV，按自有前缀批量生成。
• 国家号码随机生成：基于系统号段库按国家随机批量生成，适合快速铺量（数量下限以控制台为准，当前常见最低约 500 条）。

覆盖 240+ 国家/地区，生成免费，筛号按条扣费。美国国家码为 +1，属于 NANP（北美编号计划），+1 同时覆盖加拿大及部分加勒比地区——如果你只要美国号码，写规则时要注意区分「美国号码」和「所有 +1 号码」。洛杉矶常用地区码如 213/310/323/424/818，纽约州如 212/718/917/646/347/929，均以号段库实时数据为准。

格式统一是这一步的核心动作：导出和提交筛选任务都用 E.164，避免漏加号、漏国家码导致整批任务白跑。

第二步：数据治理与去重仓库

跨任务去重是省钱的第一手段。同一个号码被重复检测两次，就是两份成本。建议建立一张号码主表：

字段	说明
号码（E.164）	主键，全局唯一
来源	生成方式 / 号段 / 生成批次
生成时间	用于按批次回溯
是否已筛	避免重复提交
平台开通状态	分平台记录
活跃窗口	如三天、七天等，以控制台选项为准
uid	tgid / wsid / uid 等平台标识
最近筛选时间	判断数据新鲜度

来源、批次、筛选时间这三个字段最容易被忽略，但它们是后续排查问题、控制成本时唯一能依靠的依据。

第三步：筛选、导出与字段回写

检测类型按业务目标选：开通/有效用于名单清洗，活跃度（可指定活跃窗口）用于判断触达优先级，性别检测的部分结果还含有年龄、头像等字段——这也是常说的「tg 30 岁数据」的正确理解方式：它来自性别检测结果里的年龄字段，可用于筛选或解读约 30 岁人群，而不是一个独立产品。

单次任务最多约 100 万条。任务跑完后导出 CSV / TXT，然后按下面的方式回写主表：

筛选结果字段	回写到主表	典型用途
开通状态	平台开通状态	过滤掉未注册号码
活跃标记	活跃窗口	分层触达，优先联系近期活跃人群
性别 / 年龄	人群标签	定向内容与话术
uid	平台标识	直接用于加粉或私信系统

Webhook 完成回调：把「等结果」变成「推结果」

轮询和 Webhook，怎么选

维度	轮询	Webhook
触发方式	你按固定间隔去问	平台在事件发生时推送
时效	取决于间隔，通常有延迟	通常接近实时
资源消耗	大量空查询	只在有事件时消耗
实现难度	低，适合脚本	需要公网可达的接收端
主要风险	错过完成时点、查询过密	重复推送、推送丢失需补偿

实践建议：以 Webhook 为主，保留一个低频轮询做兜底对账，防止通知丢失导致批次卡住。

回调触发后的三步处理

1. 校验批次：用批次 ID 匹配本地任务记录，确认这次回调对应哪次提交；校验不通过的直接丢弃，不要写库。
2. 拉取结果并落地：把原始结果写入一张只增不改的原始表，这一层不做清洗，保留现场。
3. 回写主表并触发下游：清洗后的数据回写号码主表，再触发 CRM 同步或发送队列。

第三步一定要做幂等：同一条通知可能被处理两次，回写逻辑要能在重复执行时得到相同结果。

CRM 字段映射建议

来源字段	CRM 字段	备注
号码（E.164）	手机号 / 联系人主键	用于匹配已有客户，避免重复建档
平台开通状态	渠道可用性	决定走哪个触达渠道
活跃窗口	活跃标签	影响跟进优先级
性别 / 年龄	画像字段	用于分组与话术
uid	外部平台 ID	与加粉、私信工具对齐

补充一点现状：KK-DATA 当前支持筛号任务完成后通过 Telegram 通知，便于第一时间知道结果就绪；其余接口与通知能力请以 使用文档 为准。

上线前的数据治理与格式检查清单

• 所有号码已统一为 E.164，含 + 与国家码
• 提交前已跑过去重仓库，跨任务无重复
• 单次任务量在平台上限内，必要时拆分批次
• 任务提交前已看到预估费用，余额充足（余额不足无法提交新任务）
• 导出格式（CSV / TXT）与下游导入模板一致
• 回调接收端做了幂等与失败重试
• 号码主表记录了来源、批次、最近筛选时间
• 结果落库位置与权限已确认

计费逻辑也影响链路设计：平台无订阅套餐，采用余额充值 + 按条扣费，充值方式为 USDT (TRC20)，最低约 50 USDT，任务完成后从余额扣除。各平台、各检测类型单价不同，详见控制台实时价格，也可参考计费说明。USDT 充值到账后余额自动更新。

常见问题

问：API对接一定要开发人员参与吗？ 答：不一定。如果只是把筛号结果导入自己的系统，用控制台导出 + 定时导入脚本也能跑。真正需要开发介入的是自动化提交任务、Webhook 接收与 CRM 自动回写这几类场景。

问：Webhook 和轮询可以同时用吗？ 答：可以，而且推荐这样做。Webhook 负责实时触发，低频轮询负责对账兜底，能避免通知丢失导致批次长时间卡在「处理中」。

问：批量筛号前必须统一成 E.164 格式吗？ 答：强烈建议。号码格式不统一最常见的后果是漏加国家码或加号，导致整批任务无效或结果错配。E.164 是国际标准写法，美国号码记作 +1XXXXXXXXXX。

问：生成出来的号码，能算「真实有效手机号码」吗？ 答：「真实有效」要拆成两层看。第一层是号段合法，符合 NANP / E.164 规则，这由生成器解决；第二层是业务有效，即经筛号确认在 WhatsApp、Telegram 等平台已开通或处于活跃状态，这只能靠平台状态检测得出。生成结果本身不代表可接码或可通话。

问：去重仓库会不会限制我复用历史号码？ 答：不会。去重仓库的作用是避免同一个号码被重复检测、重复扣费；历史号码依然可以按批次筛选，只是提交前系统会提示已检测过的部分，方便你决定是否跳过。

---

把链路跑通之后，你会发现真正的收益不在「省下几次点击」，而在于数据始终是一致的、可追溯的：每个号码从哪来、什么时候筛过、筛出什么结果，都能在主表里查到。

👉 登录控制台开始配置你的第一条筛号流水线：https://app.kkdata.cc/ 👉 双向联系客服（Telegram）：https://t.me/kkdata_robot 👉 接口能力、字段与参数细节，请查阅文档：https://docs.kkdata.cc/