同步实时 WhatsApp 注册检测如何接入业务流程

产品所说的“实时”是什么

这里的实时，是指注册判断在同一个 HTTP 请求中返回，而不是创建后台任务、等待 webhook 或稍后下载结果。

调用方提交一个规范手机号并等待响应。检测完成后，data.registered 表示该号码在本次请求时是否注册 WhatsApp，应用可以立即使用结果，无需轮询其他接口。

这个产品契约很明确：WA Lookup 只检测注册状态，不识别号码背后的人，不监控账号活跃度，也不提供消息服务。边界越清楚，调用方越不容易误用返回字段。

返回数据	含义	建议动作
status=success、registered=true	完成检测报告已注册	使用本次请求返回的布尔结果
status=success、registered=false	完成检测报告未注册	把 false 作为完成结果使用
status=undetermined、registered=null	服务没有返回注册判断	不虚构布尔值，本次不扣费

同步检测为什么有价值

当软件的下一步依赖当前注册状态时，同步结果可以直接参与判断。应用不需要创建任务、保存轮询令牌，也不用等待异步回调后才能分类号码。

例如内部表单可以按需检测一个号码，客服工具可以即时复核一条记录，后端 worker 也可以逐条处理列表。无论上层怎样组织任务，底层 API 始终是一号一请求、同步返回；批量处理方应自行控制队列和并发。

同步契约的核心价值是确定性：成功完成的响应包含一个布尔注册判断；文档定义的无法判定响应不包含布尔判断。输入错误、限流等 API 错误使用外层 code、msg 和 data=null，不会给 registered 增加更多取值。

一次请求的完整路径

1. 规范手机号 — 根据明确的国家区号与本地号码生成 E.164，不猜测缺失的国家信息。
2. 发起单号检测 — 携带规范号码和 service_type=ws 调用需要鉴权的检测接口。
3. 读取返回状态 — data.status 为 success 时使用 data.registered；为 undetermined 时保持为空。
4. 保存观测时间 — 注册状态是一次时点结果，因此必须记录检测时间。
5. 单独处理非结果 — 无效请求或临时失败需要纠正或重试，不能写成 false。

不丢失含义的数据模型

不要只保留一个含糊的 valid 字段，因为它无法区分格式错误与“号码有效但完成检测为未注册”。更可靠的最小记录包括：

字段	用途
source_phone	保留来源系统提供的原始值
e164_phone	保存实际提交检测的规范号码
status	原样保留结果数据返回的 success 或 undetermined
registered	仅在完成检测时保存 true 或 false
checked_at	记录这次时点观测发生的时间
service_type	记录产生结果的产品契约

HTTP 错误不是这条结果记录的更多取值。应用如果需要记录错误，应把 HTTP 状态与 API code 单独保存，不要写进注册观测。

一条实用的接入原则

只有返回结果的 status=success 时，才能根据 data.registered 分支处理。

这条原则可以避免最常见的错误：把超时、限流或格式错误当成 WhatsApp 返回的未注册。若业务在更晚时间需要新状态，请重新发起同步检测，并把它保存为一条新观测，而不是悄悄修改旧结果的时间。