电话号码验证API：处理有效、未知与失败三类结果

问题与需要做的决定

注册处理程序调用电话检查并收到结果。有时是干净的有效答案；有时答案未知；有时是调用服务商失败；有时所问的问题根本不是该路由能回答的，例如验证码是否已送达。如果处理程序把一切非干净通过的结果都拒绝，一次临时故障就会变成一次流失的注册，一个不受支持的问题就会变成对号码错误的误判。你要做的决定很具体：哪个分支在你自己的策略下继续，哪个分支进入有上限的恢复或人工复核，哪个分支交给你已在运营的独立OTP服务商。该示例让你在申请沙箱集成之前，就能对照固定且经过检查的输出做出这一决定。

示例实际实现了什么

四分支示例是一个无依赖的 Python 3.10+ 脚本，位于可下载ZIP的 verification_delivery 目录中。它不需要凭据，也不发起任何网络调用。你以 phone 任务运行，并选择四个分支之一：normal、unknown、provider_failure 和 otp。唯一输入是分支；输出字段为 mode、branch、state、valid、line_type、next、otp_sent 和 live_line_type_available。每个输出都带有 mode 为 synthetic_fixture、otp_sent 为 false、live_line_type_available 为 false。无法识别的分支会抛出 UNSUPPORTED_FIXTURE。这是合成夹具，不是真实服务商适配器。它也不同于匿名的三场景HTTP试用：不要把其中一个的结果当作另一个的证据。随附的单元测试覆盖的是模拟状态转换，不能证明生产环境中的成功。

假设场景与预期输出

假设一个小型B2B团队把注册表单连接到该夹具，并逐一运行各分支。预期输出如下：normal 返回 state 为 simulated、valid 为 true、line_type 为 mobile、next 为 continue_customer_policy。mobile 这个值只存在于夹具中；真实的 Basic Lookup 路由不返回线路类型，这正是 live_line_type_available 保持为 false 的原因。unknown 返回 state 为 unknown、valid 为 null、line_type 为 null、next 为 review_or_existing_otp。provider_failure 返回 state 为 unknown、valid 为 null、line_type 为 null、next 为 bounded_retry_then_review。otp 返回 state 为 unsupported、valid 为 null、line_type 为 null、next 为 customer_otp_provider，且 otp_sent 仍为 false：不会发送任何消息。团队把每个分支的这八个字段记录为验收夹具，并逐字精确断言，包括各个 null 值，以防后续改动悄悄把“未知”变成“无效”。

建议在应用中采用的失败处理

以下是建议的设计，并非已实现的行为。只能把 valid 为 true 视为在你自己的注册策略下继续的许可，绝不能当作号码归属或身份的证明。把 unknown 映射到人工复核队列，或映射到你在其他地方已经运行的OTP步骤。把 provider_failure 映射为少量、固定次数且带退避的重试，之后转入复核；不要无限重试，也不要因为你的依赖服务失败就拒绝用户。把 unsupported 映射为交给你现有的OTP服务商，并等待该服务商自己的确认，而不是依据夹具结果。在存储和日志中把 valid 为 null 与 valid 为 false 严格区分。记录 branch 和 next 的值，让复核人员能看出注册为何暂停。还要记住真实路由有每分钟60次请求的技术速率限制；触发限流的响应应进入失败路径，而不是无效路径。

需要始终可见的限制

夹具输出是经过检查的合成结果，不是真实答案。号码有效性信号无法确定号码由谁持有、能否接收短信，或验证码是否已经到达。符合条件的企业可以自助开通免费的 Basic Lookup，作为应用的辅助功能，但真实路由是否适用于你的场景需要另行确认。关于这一主题的搜索热度并不代表客户需求，通过夹具测试也不能证明生产集成可以正常工作。夹具中的任何“许可”都只是本地合成记录，并不等同于真实的业务许可。

验收清单

在申请沙箱集成之前，请逐项确认：四个分支均可在本地运行，且与预期字段完全一致；未知的分支名会以 UNSUPPORTED_FIXTURE 失败；没有任何路径因 unknown 或 provider_failure 而拒绝用户；重试次数有上限并最终进入复核；otp 分支绝不会基于夹具结果显示“验证码已发送”之类的提示；测试中断言了 otp_sent 为 false；没有任何逻辑从真实路由读取 line_type；valid 为 null 与 valid 为 false 分开存储；团队笔记把这些明确记录为合成结果。如果每一项都成立，申请沙箱集成就是合理的下一步。

运行已检查的模拟示例

下载并解压 https://gridzen.ai/downloads/verification-delivery.zip，进入 verification_delivery，用 Python 3.10+ 运行。此本地示例不联网；独立身份实验请使用新的数据库。

python3 delivery.py phone --branch unknown
python3 delivery.py phone --branch provider_failure

来源与范围

https://gridzen.ai/guides/signup-phone-check/ https://gridzen.ai/guides/current-capabilities/ 依据已检查的来源快照与本地模拟；建议的业务规则属于设计建议，不代表已证明的生产行为。内容使用 AI 辅助写作，并经过独立审稿。