如何保存和刷新 WhatsApp 注册检测结果

注册状态是一次观测，不是永久标签

一次完成的 WhatsApp 注册检测，回答的是某个 E.164 号码在记录的检测时间是否被报告为已注册。

结果可以立即使用，但不应该作为 phone.is_valid 之类的永久属性保存。手机号和平台注册情况可能变化，后续一次技术失败也不会推翻之前完成的结果。可靠的数据模型必须同时记录判断与产生判断的上下文。

WA Lookup 同步返回注册信息，因此应用可以在收到结果的准确时点保存观测。同时，数据模型仍应区分完成检测与没有产生注册判断的请求。

最小可用结果记录

字段	示例	作用
source_phone	原始提交文本	支持纠错与审计，不改变来源数据
e164_phone	+14155552671	标识实际被检测的规范号码
service_type	ws	标识产生结果的产品契约
status	success	原样保留 API 返回的结果状态
registered	true 或 false	保存完成的注册结果
received_at	应用时间戳	记录同步响应到达时间
transaction_id	返回的检测标识	用于追踪完成请求

registered 应允许为空，因为文档定义的 undetermined 结果没有布尔判断。不要为 HTTP 错误创建额外结果状态；应用若需要错误历史，应单独记录 HTTP 状态与 API 错误码。

准确保存三种响应形态

公开契约包含两种结果形态和一种独立错误形态：

1. 成功且已注册 — code=0、data.status=success、data.registered=true。
2. 成功且未注册 — code=0、data.status=success、data.registered=false。
3. 无法判定结果 — code=0、data.status=undetermined、data.registered=null、data.charged_amount_micros=0。

输入无效、余额不足、限流、并发限制、维护和内部失败使用非零 API code 与 data=null。它们是请求错误，不是 WhatsApp 注册结果的取值。

新检测不能抹掉历史

应用需要更新状态时，应新增一条观测或对记录做版本化。不要保留旧结果却覆盖旧的 checked_at，也不要因为刷新失败就把最近一次完成结果改成 false。

一个简单的当前状态视图可以选择最新的完成观测，而底层表保存每次尝试。这样应用既能在有完成结果时提供当前答案，也能显示是否存在更新但未决的尝试。

场景	最新完成结果	独立请求日志
首次检测完成为 true	T1 收到的 true	T1 成功
后续 API 请求返回错误	T1 收到的 true	T2 HTTP/API 错误
后续检测完成为 false	T3 收到的 false	T3 成功

根据业务判断确定刷新时间

注册结果没有适用于所有场景的统一过期时间。合理的新鲜度窗口取决于周边流程可以容忍多大的时间差。用户即时操作可能需要重新同步检测，分析报表则可以接受更早的时间戳，只要结果年龄清晰可见。

刷新规则至少要明确：

• 流程接受的最大结果年龄；
• undetermined 响应是否需要稍后再次调用；
• 调用方选择在哪些 API 错误后再次提交；
• 如何遵守并发与速率限制；
• 操作界面怎样展示检测时间。

关键是不能把数据库中的旧值宣传为实时。WA Lookup 在被调用时提供同步当前观测；何时再次调用，由接入系统根据业务需要决定。

可靠的保存原则

把注册证据保存为带时间戳的观测，把运行尝试保存为各自独立的状态。

这样可以保持 registered=false 的准确含义，让重试更安全，也让每个界面明确说明状态是在什么时候检测的。这同样符合产品边界：WA Lookup 提供注册检测结果，客户系统负责保存期限、刷新策略与后续决策。