术语表

以下按接口的用法定义。某个词如果同时有日常含义，以接口的含义为准。

标识与产品

术语	含义
identifier	一次实时检测所针对的唯一对象：一个手机号或一个邮箱地址。批量提交携带的是它们的列表。
series	标识属于 phone 还是 email。产品、接口和请求都按系列划分，一次请求不能混用两个系列。
product	一个检测目标 —— 平台，加上针对它执行的检测类型。“WhatsApp 号码检测”与”WhatsApp 活跃度详情”是两个不同产品，尽管都关于 WhatsApp。
实时产品	通过同步接口使用的产品。用数字 ID 调用。
批量产品	通过异步接口使用的产品。用 slug 调用。
ID	标识实时产品的整数，在目录里显示为 #47。product_ids 接收的就是 ID。
slug	标识批量产品的字符串，例如 waValid。product 字段接收的就是 slug。
mode	realtime 或 async。一个产品只属于其中一种，模式决定了哪些接口接受它。

ID 与 slug 不可互换

实时 ID 永远不会在批量接口上解析成功，批量 slug 也永远不会在实时接口上解析成功。混用是最常见的接入错误，两侧也都不会静默解析 —— 但失败方式不同，因为两侧的校验方式本就不同：

• product_ids 按整数数组校验，所以传字符串 slug 会在任何产品查找开始之前就被拒为 400 invalid_realtime_request。
• 批量的 product 字段是按 slug 查找的，因此实时产品的 slug 确实能被找到 —— 然后被拒为 422 product_mode_not_supported，因为异步端点只接受异步产品。

结论

术语	含义
registered（已注册）	检测实际回答的问题：这个标识是否注册在该平台上。它不是在说号码或地址在语法上是否合法、是否可达、是否在用。
valid	确认已注册。计费。
invalid	确认未注册。计费 —— 否定答案也是答案。
unknown	上游无法判定。不计费；已退款。
cached	结论来自已存储的事实，而不是去问上游。命中缓存仍然计费。
combo（组合）	一次实时请求：一个标识，加上所选的 1 到 10 个产品。组合可能部分成功 —— 见 partial_succeeded。

资金

术语	含义
reserve（预占）	在检测执行前先把金额占住。每次提交都会对账户余额预占。
settle（结算）	在单项结果确定后，决定该单项的最终扣费。
refund（退款）	对没有产出可用结论的单项，退回预占金额。
billing_status	单项字段：charged 或 refunded。以此为准，不要从 HTTP 状态推断。
total_reserved	检测执行前预占的金额。恒等于 total_charged + total_refunded。
charged_amount	净扣费。refunded_amount 是净退款。

请求与任务

术语	含义
request_id	标识一次实时提交的 UUID。在支持请求中引用它。
task_id	标识一次批量提交的 token，提交时返回。它也同时是任务接口的 {token} 路径参数 —— 一个值，在文档里有两个名字。
Idempotency-Key	调用方提供的请求头，实时调用必需，让重试变得安全：同样的 key 配同样的请求体会返回已存结果，而不是再次扣费。
replayed（重放）	响应来自已存结果，而不是新执行的检测。实时响应的字段是 replayed，批量提交的字段是 idempotent_replay。重放从不动钱。
recovery_pending	批量任务已入队，但对账仍在进行。

任务计数器

术语	含义
submitted	你提交的行数。
prefiltered	检测前被丢弃的行 —— 例如格式错误。
deduped	被去掉的重复行。
total	实际参与检测的行数：submitted 减去 prefiltered 减去 deduped。
processed	上游通道已完成的行数。
unknown_unprocessed	始终未能判定的行。这些就是被退款的量。

限额与保留期

术语	含义
按 key 限额	挂在你 API key 上的预算。这是应该据以规划的数字。
按 IP 限额	所有共用同一出口地址的 key 共享的更粗上限。不是访问控制。
retention（保留期）	记录能存活多久。实时日志与重放结果：30 天。批量结果文件：7 天。

相关

• 响应格式 —— 信封本身，以及金额与时间戳的编码方式
• 错误码 —— 同一套词汇用在失败上