企业官网建设流程全解析

短信发出去石沉大海，外呼打过去是“您拨打的号码是空号”，这类事做增长和客服的同行基本都遇到过。一个号码库躺了几十万条数据，看着挺厚实，真拉出来跑一轮触达，能接通的可能不到六成，剩下的全是空号、停机、长期不用的沉默号，还有一批被反复标记的风险号。钱按条扣了，通道信誉还被拉低，用户侧也落一身投诉。空号检测API就是拿来治这个的：号码状态实时查询把每条号码的当前状态问清楚，沉默号与风险号识别把“能打通但没价值”和“能打通但别打”的两类单独挑出来，批量号码清洗则把整套动作流程化、可复现。这篇就把我从接口选型、签名鉴权、批量提交、并发控制到结果落库缓存这一路的实操细节摊开讲，适合正在做触达系统、CRM清洗、注册风控的同行参考，新手也能照着走一遍。

1. 空号检测API到底在查什么：状态分类与底层逻辑

1.1 五类号码状态的业务边界，先分清再谈准确率

很多人一上来就问“准确率多少”，这个问题问得不完整。空号检测返回的从来不是一个布尔值，而是一组状态。不同服务商的状态码命名五花八门，但落到业务语义上，基本就这几类：实号、空号、停机、关机、沉默号、风险号。你得先把每类的业务含义钉死，后面做策略才有依据。

实号指的是当前在网、状态正常、具备接收短信或接听条件的号码。空号指的是号码未被分配，或者已经被注销回收、运营商侧查无此号。停机是号码还在，但处于欠费停机或主动停机状态，短信下发会失败，语音呼入通常提示停机。关机是号码正常但终端未开机，这个状态是动态的，几分钟后可能就变了，缓存价值极低。沉默号是在网、能通，但长期没有语音、短信、流量行为，典型的是副卡、备用号、老人机、设备卡。风险号则是在网可通，但被多源数据打过负面标记，比如高频被投诉、被标记骚扰、虚拟小号、二次放号不久、异常注册行为。

我见过不少团队把“空号”和“沉默号”混为一谈，结果把一大批能正常接收短信的副卡直接剔了，白白丢掉可触达人群。也见过把“停机”当“空号”处理的，实际上停机号码充值复活后是有效用户，直接拉黑属于误伤。状态边界不清，后面所有策略都是歪的。

注意：这张表是业务语义层面的归纳，不同服务商在状态码定义、置信度标注、返回字段上差异很大，接入前一定要拿到对方的字段字典逐条对齐，别拿A家的状态码去套B家的返回值。

1.2 检测原理：信令侧查询和行为模型打标是两套东西

空号检测的技术路径其实分两条腿，很多人没意识到这点，导致对结果的预期错位。

第一条腿是运营商侧的状态查询，本质是向号码归属的网元发起状态询问，拿回该号码当前是否分配、是否停机、是否可达。这条路径的结论相对硬，空号、停机这类判断的准确度比较高，时效性也好。但它有天然边界：只能告诉你“号码现在是什么状态”，告诉不了你“这个号码值不值得打扰”。

第二条腿是基于行为数据和标记库的建模打标，沉默号和风险号基本都出自这里。沉默号的判定靠的是长期行为特征的聚合，比如连续多少天没有语音主被叫、没有短信收发、没有流量记录。风险号靠的是多源标记的叠加，包括投诉记录、异常注册、虚拟号段识别、号段黑名单、短时间内的异常行为密度等等。

这两条腿的准确率特性完全不同。信令侧的空号判定在新入网号码上容易误判，因为号码刚放号、网元数据还没完全同步；携号转网的号码在归属运营商字段上也常出错。模型侧的沉默号判定受样本偏差影响很大，一个刚换手机的用户可能被误判成沉默，一个用双卡的用户副卡永远“沉默”但其实每次营销短信都收得到。

我的建议是：把状态查询结果和模型打标结果分开存储，字段上明确标注数据来源和置信度，后面做策略时对不同来源的结果给不同权重。别把两类结果混在一张表里，后面想追溯都没法追。

1.3 为什么必须做前置清洗：算一笔失败触达的隐性账

不做清洗直接群发，成本不止是通道费。失败下发一样计费或者按提交计费，这块钱是纯扔的。更麻烦的是通道信誉：空号率高的号码包提交上去，通道侧的拦截比例会上升，实号的到达率跟着被拖累。再往外一层是用户侧体感，一个已经被注销的号码还在收营销短信，接盘的是二次放号的新用户，投诉就这么来的。

粗算一笔：一个50万条的存量号码包，不清洗直接发，按行业里常见的空号加停机占比15%到25%估算，就是7.5万到12.5万条无效提交。按单条三分钱算，一轮就是两千多到三千多块白扔，一年跑十轮就是两三万。这还没算通道质量下降带来的到达率损失。而清洗一次的成本，按同样的单价算，也就一万五左右，但清洗后的包可以复用多轮，边际成本是递减的。

所以清洗的定位不是“可选优化”，是触达链路上的必要前置环节。尤其是老客召回、沉睡用户唤醒这类场景，号码库往往躺了一两年没动过，状态变化极大，不清洗直接跑，效果基本没法看。

2. 接入前的方案设计：接口形态、鉴权与计费模式选型

2.1 同步单查和异步批量提交，别选错场景

空号检测API一般提供两种调用形态。同步接口是一条或少量号码提交，等响应返回结果，适合注册登录风控、下单前的实时校验、客服系统里手动查单号这类场景，要求响应快，通常几百毫秒内出结果。异步批量接口是一次提交几百到上千条，服务端受理后返回一个批次号，结果通过轮询或者回调通知拿回来，适合大规模号码清洗。

我踩过的第一个坑就是拿同步接口去跑批量。单条调用，串行循环，50万条跑到天荒地老，中途网络抖一下就断，还不敢重跑，怕重复计费。后来换成批量提交加异步回调，同样量级几十分钟跑完，中间还能断点续传。

选型上有个简单判断标准：如果一次要处理的号码超过一两千条，直接上批量接口；如果是业务链路上的实时判断，用同步接口，但记得加超时和降级。同步接口的超时我一般设800毫秒到1秒，超过就按“未知”处理走后续策略，不能让主业务链路被一个查询拖死。

2.2 鉴权与签名：几个看着小但会卡住半天的问题

主流接口的鉴权方式无非几种：AppKey加AppSecret换Token、请求头带签名、时间戳加随机串防重放。看起来简单，实际接入时最容易卡在这几处。

第一处是签名字符串的拼接顺序。不同服务商对参与签名的字段、排序方式、是否包含空值、是否URL编码的规定各不相同。我见过因为把空参数也拼进去导致签名一直对不上的，排查了两个小时。正确做法是先拿对方的签名示例，用固定参数在本地跑一遍，算出结果和文档示例比对，对上了再往下走。

第二处是时间戳的时区和单位。有的要求毫秒时间戳，有的要求秒级，有的还要求是UTC。时间戳偏差超过窗口期（常见五分钟）会直接返回签名过期，报错信息还往往很含糊。

第三处是请求体的编码和哈希。如果签名是对body做哈希，那body的序列化方式必须和实际发送的完全一致，多一个空格、少一个转义都会导致哈希不同。我的经验是：序列化一次，把结果字符串同时用于签名和发送，不要在发送时再序列化一遍。

import hmac, hashlib, time, uuid, json def build_headers(app_key, app_secret, body_dict): ts = str(int(time.time() * 1000)) nonce = uuid.uuid4().hex # 关键：序列化只做一次，签名和发送用同一个字符串 body_str = json.dumps(body_dict, ensure_ascii=False, separators=(',', ':')) sign_raw = f"{app_key}{ts}{nonce}{body_str}" sign = hmac.new(app_secret.encode('utf-8'), sign_raw.encode('utf-8'), hashlib.sha256).hexdigest() return { "Content-Type": "application/json; charset=utf-8", "X-App-Key": app_key, "X-Timestamp": ts, "X-Nonce": nonce, "X-Sign": sign }, body_str

注意：nonce要真正随机且服务端有去重窗口，否则重放保护形同虚设；另外密钥绝对不要写死在客户端代码里，走配置中心或者环境变量，日志里打印请求时要对签名和密钥做脱敏。

2.3 计费口径与成本测算，先把账算明白再选型

计费模式上常见几种：按提交条数计费、按成功查询条数计费、按有效结果条数计费、包年套餐加超出部分阶梯价。字面上差别不大，量起来以后差得离谱。

按提交计费的问题是失败也扣钱，网络超时、参数错误这些本不该计费的也照扣。按成功查询计费相对合理，但要看“成功”的定义是接口返回200还是拿到了有效状态。有些服务商接口返回200但状态是“未知”，这种算不算成功，合同里必须写清楚。

成本测算我一般这么做：先算理论全量成本，再算清洗后的实际成本，两者对比看优化空间。

假设日清洗量100万条，单价0.03元每条。全量直查成本是3万元每天。做了三层优化之后：格式非法和明显错误号码本地剔除约3%，历史结果缓存命中约55%，号段黑名单和自身退订黑名单剔除约5%，实际需要调用接口的比例降到37%左右，也就是37万条，日成本降到1.11万元。一年按250个工作日算，差出来的钱是很可观的。缓存命中率是这里最关键的杠杆，后面第3.4节会专门讲TTL怎么设。

再说QPS的估算，很多人卡在这。假设批量接口单批最多500条，单次请求平均耗时300毫秒，那么单并发的理论吞吐是500除以0.3，约1666条每秒。目标日处理100万条，按8小时工作窗口算，需要约35条每秒，单并发绰绰有余。但如果服务商限制的是请求次数而不是号码条数，比如限20次每秒，那么理论峰值是20乘500等于1万条每秒，同样够用。真正的瓶颈往往不在算力，在对方的通道限流和网络抖动，所以并发数配3到5个就够，配太多只会撞限流。

3. 号码清洗全流程实操：从脏数据到可用画像

3.1 号码标准化：第一道闸门，能挡掉三成无效调用

别小看这一步。真实的号码库里脏数据五花八门：带空格的、带连字符的、带括号区号的、前面加86的、加0086的、加了各种长途拨号前缀的、Excel导出来变成科学计数法的、末尾多一位少一位的。这些如果不去本地处理，全部甩给接口，纯属浪费钱。

标准化的顺序很重要，我一般按这个流程走：先把非数字字符全部剔除，只保留数字；再处理前缀，去掉0086、86、加号86这类；然后处理各种拨号前缀；再校验长度是否为11位、首位是否为1、第二位是否在合理范围内；最后做明显错误号码的过滤，比如全同数字、连续递增递减、号段库里根本不存在的号段。

import re VALID_SECOND = set("3456789") def normalize_phone(raw: str): if raw is None: return None, "empty" s = re.sub(r"\D", "", str(raw)) # 处理国际前缀 for p in ("0086", "86"): if s.startswith(p) and len(s) == len(p) + 11: s = s[len(p):] break # 处理常见的长途拨号前缀，长度超出11位时循环剥离 while len(s) > 11: s = s[1:] if len(s) != 11: return None, "length_error" if not s.startswith("1") or s[1] not in VALID_SECOND: return None, "format_error" if len(set(s)) <= 2: return None, "obvious_fake" return s, "ok"

这段代码里有两个地方值得说。一个是超长号码的剥离策略，我采用从头部逐位剥离，因为绝大多数情况是前面多了前缀，尾部一般不会多。另一个是全同数字和只有两种数字的过滤，这类号码在测试数据里特别多，接口查出来大概率是空号，本地上规则挡掉更划算。

实测下来，一个未经处理的存量库，这一步能挡掉20%到30%的无效调用。省的都是真金白银。

注意：标准化之后一定要做去重。同一批数据里重复号码很常见，尤其是有多个来源渠道合并的库。去重放在调用接口之前，重复提交不仅多花钱，还会把接口的QPS额度占掉。

3.2 号段初筛：虚拟运营商、物联网卡、境外号要单独标

号段初筛的价值在于，有些号段根本不需要调用接口就能定性，有些号段则需要打上特殊标签走不同策略。

基础运营商号段、虚拟运营商号段、物联网专用号段，这三类的触达特性完全不同。虚拟运营商的号码在短信到达率上通常低于基础运营商，物联网卡则大多不具备正常的语音和短信能力，直接按普通手机号去发，失败率很高。境外号码更是如此，很多检测接口根本不支持境外号查询，提交上去只会返回未知。

我的做法是本地维护一份号段表，按月更新，字段包括号段前缀、运营商归属、号段类型、是否支持短信、是否支持语音。调用接口前先过一遍，号段类型是物联网或者境外的，直接打标不走接口，能省一大笔。

号段表从哪来？公开的号段分配信息是有的，运营商会定期公布，第三方也有整理好的数据。我的建议是自己维护一份，别完全依赖接口方返回的归属信息，因为接口返回的归属运营商在携号转网场景下经常是错的。本地号段表加接口返回归属做交叉校验，不一致的打上“待核实”标签，别直接信其中一个。

3.3 批量提交的并发控制与重试，这部分决定跑批能不能跑完

批量提交最容易出问题的地方不是接口本身，是工程实现。我总结下来四个要点：限流、重试、断点、对账。

限流用令牌桶实现，按合同约定的QPS配置。不要贪心配太高，撞了限流返回一堆429，反而更慢。重试策略要分错误类型：网络超时和5xx可以重试，4xx一般不要重试，参数错误重试多少次都是错的。重试间隔用指数退避，1秒、2秒、4秒这样，最多三次，超过就落到失败队列等人工处理。

断点续传靠批次号和偏移量。每批提交前先把批次元数据落库，状态标为“提交中”，拿到结果后更新为“已完成”。任务中断重启时，扫描状态为“提交中”且超过一定时间的批次，先调用批次查询接口确认服务端到底处理了没有，确认没处理再重新提交，确认处理了就拉结果。这一步不做，重复计费跑不掉。

对账是最容易被忽略的。提交了500条，返回了498条结果，少的那2条去哪了？如果不做数量校验，这2条就被静默吞掉了，后面所有统计都是错的。我的做法是每批返回后立刻做数量比对，缺失的号码单独进补查队列。

import time, threading from concurrent.futures import ThreadPoolExecutor class TokenBucket: def __init__(self, rate, capacity): self.rate, self.capacity = rate, capacity self.tokens, self.last = capacity, time.time() self.lock = threading.Lock() def acquire(self, n=1): while True: with self.lock: now = time.time() self.tokens = min(self.capacity, self.tokens + (now - self.last) * self.rate) self.last = now if self.tokens >= n: self.tokens -= n return time.sleep(0.01) def submit_batch(bucket, session, batch): bucket.acquire(1) for attempt in range(3): try: resp = session.post(API_URL, json=batch, timeout=5) if resp.status_code < 500: return resp.json() except Exception: pass time.sleep(2 ** attempt) return {"error": "retry_exhausted", "batch_id": batch["batch_id"]}

这套结构在50万条量级的实测里跑得比较顺，中途断过两次网，靠断点续传都接上了，没出现重复计费。

3.4 结果落库、分级标签与缓存有效期，降本的关键在这

结果落库的字段设计要有前瞻性，别只存一个状态码。我一般会存这些：原始号码、标准化号码、脱敏号码、归属省、归属市、归属运营商、号段类型、状态码、状态描述、数据来源、置信度、批次号、检测时间、下次可复用时间。

脱敏号码是给前端和报表用的，中间四位打星。原始号码加密存储，访问要单独授权。这不是形式主义，号码属于个人信息范畴，合规检查时这块是重点。

分级标签是把状态转换成可执行的业务语言。我一般分四级：A级正常触达，B级降频触达，C级暂停触达，D级永久排除。实号进A，沉默号进B，停机进C，空号和风险号进D。注意风险号进D不是一刀切，第4.3节会讲更细的分层。

缓存这块是降本的核心。不同状态的时效性差异极大，TTL必须分开设。

缓存key用标准化号码加状态类型，value带检测时间和置信度。查询时先看缓存，命中且未过期直接用，命中但接近过期可以异步刷新。这套机制在稳态运行后能把实际接口调用量压下去一半以上。

注意：缓存一定要留强制刷新入口。用户主动投诉、客服反馈和实际不符的时候，要能单条强制重查，不能因为缓存没过期就一直返回旧结果。

4. 沉默号与风险号的识别逻辑与落地判定

4.1 沉默号的判定窗口，别拿一个阈值套所有场景

沉默号的定义没有行业统一标准，各家服务商的窗口期从30天到90天不等，判定所依赖的行为维度也不一样。常见的有连续N天无语音主被叫、无短信收发、无流量使用，有的还会看是否有过充值、是否有过套餐变更。

这里的关键问题是样本偏差。同一个人主卡用得飞起，副卡常年不用，副卡就是沉默的，但副卡照样能收短信。一个用户换了新手机，旧号码刚停机保号，也会被判定为沉默。所以沉默号不等于无效号，它只是“低活跃”。

我实际用下来的经验是，沉默号要按场景分窗口。电商促销这类追求触达广度的场景，用较长窗口（比如60天以上无行为才算沉默）会更保守，避免把能触达的人筛掉；而成本敏感的高频通知类场景，用较短窗口更划算。同一个号码库，换个窗口判出来的沉默号比例可能差出十几个百分点，这个参数必须结合自己的业务数据调，不能照抄。

还有一个实操建议：沉默号的判定结果要带行为明细，比如“连续45天无语音、无短信、有流量”。只给一个“沉默号”的结论，后面想调策略就没依据了。我带过的项目里，把行为明细落库之后，通过分析发现相当一部分“沉默号”其实有流量记录，只是语音和短信为零，这类其实是智能设备和双卡副卡，策略上应该和那种三无号码区分开。

4.2 风险号的多源标记，叠加规则比单个标记更重要

风险号的识别逻辑是标记库的聚合，问题在于不同来源的标记权重差别巨大。用户主动投诉的权重最高，被多个用户投诉的权重更高；系统识别的高频外呼异常次之；号段级别的黑名单权重最低，因为号段黑名单是粗粒度的，一个号段里绝大多数是正常用户。

所以我一般不直接采用服务商返回的“风险号”单一结论，而是要求返回标记明细，自己在本地做加权。比如同一号码近30天内被投诉3次以上，直接进永久排除；被投诉1到2次的，进人工复核；命中虚拟号段但没有其他负面标记的，只做限流不做排除。

这里有个很容易踩的坑：二次放号。一个号码前主人是老赖或者被大量投诉，号码回收后重新分配给新用户，标记还挂在号码上，新用户就无辜中枪。这种情况靠单一标记库判断不了，需要结合入网时间和活跃度做判断，比如入网时间很短但负面标记很多的，大概率是二次放号，应该给新用户一个“观察期”，而不是直接永久拉黑。

4.3 分级处置策略：不是所有问题号码都只能拉黑

把所有非实号一律拉黑，是最省事也最浪费的做法。号码状态是动态的，今天的停机可能是明天的活跃用户，今天的沉默号可能是下个月的大促主力。

我的分层做法是这样的：空号和明确的无效号码进永久排除，这类基本不会复活，留着占空间；停机进暂停池，设置复活检测，比如每30天重查一次，查出来变成实号就重新入池；沉默号进低频池，触达频次压到正常用户的五分之一，但保留触达能力，一旦监测到有响应就升级；风险号按标记权重分层，高权重的永久排除，低权重的限流观察。

这套分层跑下来，实际可触达池子比我最初预估的大了将近两成，等于白捡回来一批用户。很多团队清洗完就一刀切，把可触达人群砍得太狠，这也是成本。

还有一个细节：分层标签要能随时间自动迁移，不能一次性打完就固化。我一般用定时任务每周跑一次状态复核，优先重查暂停池和观察池里的号码，正常池里的号码按缓存TTL自然过期。这样人力不用介入，池子也能自己流动起来。

5. 常见问题排查与避坑清单

5.1 状态误判的六类高频原因，逐条对号入座

误判是空号检测里最让人头疼的问题，因为结果看起来“有结论”，实际是错的，后面的策略全建立在错误结论上。我把遇到过的高频原因整理了一下。

新入网号码被判空号。号码刚放号，网元侧数据同步有延迟，查询结果可能是未分配。这类号码通常入网时间很短，处理上可以给一个宽限期，入网不足7天的号码即使查到是空号，也先放到观察池，过一周再查一次。

携号转网导致归属运营商错误。号码转网后，本地号段表里的归属还是原运营商，和接口返回的对不上。这时候不要盲目信任何一方，打上待核实标签，触达时按实际接口返回的运营商走通道。

虚拟号段被误判风险。虚拟运营商的号码在到达率上确实偏低，但被统一打成风险号就过了。应该单独建一个虚拟号段的标签，策略是降级触达而不是排除。

测试号码和特殊号段。一些内部测试号、企业总机、短号，被当成普通手机号去查，结果自然奇怪。本地维护一份白名单，直接跳过。

接口降级导致返回未知。服务商侧偶发故障时可能返回全量未知，这时候如果程序把它当成空号处理，一批好号码就被误删了。必须区分“查询失败”和“查询结果为空号”，失败的要进补查队列，绝不能被当成结论使用。

缓存过期时间设太长。空号TTL设成半年，中间号码被重新放号，新用户就被当成空号漏掉了。这个前面讲过，TTL按状态分开设。

5.2 接口层报错速查表

报错信息往往很含糊，尤其签名类错误，文档说是签名错误，实际可能是时间戳、编码、字段顺序任意一个问题。这张表是我自己整理的排查顺序，按命中概率从高到低排。

这份表我基本贴在工位上，新同事接入时先过一遍，能省掉大量来回扯皮的时间。

注意：排查签名类问题时，最有效的办法是把发送出去的原始请求体完整打印出来（脱敏后），和签名时用的字符串逐字符比对。我遇到过一次是发送时序列化加了空格，签名时没加，肉眼根本看不出来，最后靠逐字符diff才发现。

5.3 合规红线与数据留存，别等出事才想起来

号码是个人信息，批量清洗意味着大规模处理个人信息，合规这块必须有动作，不能只停留在口头。

几个基本动作：清洗前确认号码来源的合法性和授权范围，营销触达要有明确的同意基础；存储时原始号码加密，展示时脱敏；访问要留操作日志，谁能查、查了哪些，都要可追溯；留存时间要有明确期限，超过期限的号码和检测结果要定期清理，不能无限期堆着。

还有一个容易忽略的点：退订名单。用户在任何一个渠道退订过，这个信息必须同步到全局的触达系统，不能每个业务线各管一套。退订名单要在清洗流程里作为最高优先级的过滤条件，排在号段初筛之前。我见过因为退订名单没打通，导致用户退订后仍然收到短信，最后投诉升级的情况，代价很大。

触达频次控制也是合规的一部分。同一个号码一天内被多个业务线各发一条，加起来就是骚扰。全局频控要放在清洗之后、发送之前，按号码维度统一计算。

6. 我踩过的坑和几条实操建议

做这类项目最深刻的体会是，接口本身不难接，难的是工程细节和策略设计。接口文档写得再全，真正跑起来一定会遇到没写在文档里的情况。

说几个我踩过的具体坑。第一个是没有做结果数量对账，一批500条提交上去返回498条，当时没注意，一个月后做数据统计发现总量对不上，回头查根本查不出来是哪批丢的，只能全量重跑一次，白花钱。第二个是缓存key设计得过于简单，只用了号码没带业务维度，结果一个业务线把号码标成了风险号，另一个业务线跟着被误伤，两个业务线的策略打架打了很久。第三个是没做强制刷新入口，用户投诉说自己是正常号码被误判，客服查了十分钟发现缓存里躺着一条两个月前的结果，没法当场重查，体验很差。

几条可以直接拿走的建议：清洗流程一定要做成可重入的，任何一步失败都能从断点继续，别做成一次性脚本；所有状态数据都要带检测时间和数据来源，没有时间戳的结果等于没有结果；接口调用量和成本要做日监控，环比突然涨了20%一定是哪里出了问题，早发现早处理；本地规则能挡掉的绝对不要甩给接口，规则越厚，成本越低。

后续这套东西还可以往下扩。比如把清洗结果和实际触达结果做回流比对，用真实到达率反过来校准接口的准确率，长期跑下来能摸出每个服务商在不同号段上的表现差异，选型时就有更硬的依据。再比如把沉默号的行为明细和后续转化数据关联起来，能反推出一个更适合自己业务的沉默判定阈值，而不是一直用服务商的默认值。这些工作都不难，难的是有没有意识去做。