电话查询 API：基本属性能支持哪种注册决策？

问题与决策

你的注册表单收集电话号码，团队希望在创建账户前做一次查询。最诱人的设计是二元的：有效就通过，其他一律拒绝。这种设计会在两方面出错：只要查询无法给出答案，它就会拒绝用户；同时它悄悄地把一次属性检查升级为用户拥有该号码的证明。你真正需要做的决定更窄：基本属性可以影响注册流程中的哪一步，哪些结果应当转入人工审核、现有的 OTP 服务商或有上限的重试，而不是直接拒绝。查询描述的是号码，它不能说明这个人能否在该号码上收到消息，也完全不能说明此人是谁。

已检验示例的实际输出

可下载示例在本地运行，需要 Python 3.10 或更高版本，不需要凭据，也不进行任何网络调用。其 phone 任务只有一个输入 branch，可取四个值：normal、unknown、provider_failure 和 otp。每个输出都包含 mode 为 synthetic_fixture、分支名、otp_sent 为 false 以及 live_line_type_available 为 false。normal 分支返回 state simulated、valid true、line_type mobile、next continue_customer_policy。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。其他任何分支都会抛出 UNSUPPORTED_FIXTURE。注意，line_type mobile 只出现在合成的 normal 分支中：当前免费的 Basic Lookup 路由不请求线路类型、持有关系、可达性或 OTP 投递，live_line_type_available false 正是在表明这一点。这个四分支示例与匿名的三场景 HTTP 试用不同，两者不可混为一谈。

未知与服务商故障的区别

这两个分支都返回 state unknown 和空属性，所以只读取 state 的代码无法区分它们，差别在于 next。unknown 表示查询已经执行，但无法判定号码的特征；立即重复同一调用大概率无济于事，因此示例指向人工审核或你已在运营的 OTP 流程。provider_failure 表示调用本身没有完成；重试可能成功，因此示例建议有上限的重试，之后转入审核。两者都不能证明号码有问题，也都不应变成自动拒绝。在我们提议的应用设计中，应记录发生的是哪个分支，用固定次数和退避策略限制重试，并把用尽重试的请求送入与未知结果相同的审核队列。这个设计需要由你来实现；示例只负责给出下一步的名称，并不执行任何重试或审核。

一个假设场景

假设一个小型 B2B 工具允许新的工作区管理员用电话号码注册，该号码之后用于账户通知。其提议的策略是：有效结果允许注册按团队现有规则继续；查询结果不会授予任何卖家或付款权限。团队依次运行四个分支。normal 分支预期 valid true 和 next continue_customer_policy，代码继续注册，但仍把号码标记为未验证。unknown 分支预期 next review_or_existing_otp，把用户引导到现有 OTP 步骤。provider_failure 分支预期 next bounded_retry_then_review，团队代码自行重试两次，然后标记审核，同时允许用户完成表单。otp 分支预期 state unsupported 和 next customer_otp_provider，团队调用自己的 OTP 服务商；otp_sent false 确认示例没有发送任何内容。团队的断言逐字段精确比较，包括所有空值。

故障处理与限制

应把抛出的 UNSUPPORTED_FIXTURE 视为编程错误，而不是用户结果。绝不能让 valid null 被强制转换为 false。服务商故障的重试必须有上限，以免服务商性能下降时注册被无限期卡住。请记住边界：示例是合成的，其结果不是真实的业务许可；覆盖状态转换的工程测试也不能证明生产环境中的成功。符合条件的企业可以自助开通免费的 Basic Lookup，技术速率限制为每分钟 60 次请求，但你的场景下真实路由是否可用需要另行确认，而且该路由不返回线路类型。

验收清单

在从合成示例转向沙箱请求之前，请确认：四个分支都能运行，且与预期字段完全一致；unknown 与 provider_failure 进入不同的下一步，且都不会拒绝用户；重试有上限并以审核结束；otp_sent false 从不被理解为验证码已发送；遵守 live_line_type_available false，真实环境中没有任何逻辑依赖 line_type；任何查询结果都不会被存储为号码持有或身份信息；不受支持的分支会明确报错。如果每一项都成立，沙箱集成就适合这项任务；如果你的决策需要证明持有关系或身份，请改用 OTP 或身份验证。

运行已检查的模拟示例

下载并解压 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 辅助写作，并经过独立审稿。