实时单号检测

POST/v1/realtime/check/phone

同步检测一个号码，一次请求可选 1 到 10 个实时产品——控制台走的就是这个接口、这套契约。产品一律用实时产品 ID 指定，不能用批量产品 slug。

请求参数

字段	类型	必填	说明
`identifier`	string	是	一个 E.164 手机号，例如 `+8613800138000`。
`country`	string	否	完整 E.164 号码可省略；本地号码必须提供匹配的 ISO 国家代码（见国家代码列表）。
`product_ids`	array<int>	是	实时产品 ID 数组，1 到 10 个。

产品怎么选

产品 ID 不用猜，去实时产品列表查——它由 GET /v1/products 提供，取其中 mode 为 realtime 的条目的 id 即可。批量产品用的是 slug，所以 slug 在实时接口上一定不生效；产品列表页把实时产品的 ID 显示为 # 前缀，就是为了区分这一点。

一次请求用同一个号码检测 1 到 10 个实时产品。返回里只有一个 request_id，results 中每个产品一条记录，每条独立计费，因此 status 可能是 partial_succeeded。超过 10 个 ID 会返回 invalid_realtime_request；控制台提交走的是同一个接口，上限一致。

响应示例

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "identifier": "+8613800138000",
  "status": "succeeded",
  "request_status": "completed",
  "replayed": false,
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "results": [
    {
      "product_id": 47,
      "product": "wavalid-realtime",
      "result": "valid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:00Z",
      "error_code": null
    },
    {
      "product_id": 50,
      "product": "tgValid-rt",
      "result": "invalid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:01Z",
      "error_code": null
    }
  ]
}

request_id 是 UUID。replayed 为 true 表示这次是 Idempotency-Key 重放、返回的是已存结果、没有调用上游——重放不动账。

响应字段

字段	类型	说明
`request_id`	string（UUID）	标识本次提交。联系 support 时请附上该值。
`identifier`	string	被检测的标识，原样回传。
`series`	string	`phone` 或 `email`。
`status`	string	`succeeded`、`partial_succeeded` 或 `failed`——由有多少条结果被计费推导得出。
`request_status`	string	请求的内部生命周期状态。
`total_reserved`	number	检测开始前预留的金额。
`total_charged`	number	本组合中所有产品的扣费合计。
`total_refunded`	number	对未能给出结论的子项退回的合计。
`charged_amount`	number	净扣费，恒等于 `total_charged`。
`refunded_amount`	number	净退款，恒等于 `total_refunded`。
`replayed`	boolean	为 `true` 时表示 `Idempotency-Key` 重放返回了已存结果。
`results`	array	每个请求的产品一条记录，顺序与请求顺序一致。

results 中每条记录各自带着自己的状态：

字段	类型	说明
`product_id`	integer	来自产品目录的实时产品 ID。
`product`	string	该 ID 对应的产品 slug。
`result`	string	`valid`、`invalid` 或 `unknown`——即该标识是否已注册。
`cached`	boolean	为 `true` 时表示结论来自缓存。缓存命中同样计费。
`billing_status`	string	`charged` 或 `refunded`。
`charged_amount`	number	该产品的扣费金额。
`refunded_amount`	number	该产品的退款金额。
`checked_at`	string（ISO 8601）	结论产生的时间，UTC。
`error_code`	string \| null	该子项未能给出结论的原因；成功时为 `null`。

cURL 示例

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","country":"CN","product_ids":[47,50]}'

计费与语义

计费：每个产品按本次请求锁定的单次价计费，缓存命中同价。仅 valid / invalid 收费；unknown、超时或通道繁忙退还对应子项。total_reserved = total_charged + total_refunded，charged_amount 是退款后的净扣费。
部分成功：组合检测部分成功仍返回 HTTP 200，status=partial_succeeded；全部失败为 failed。请逐项检查 billing_status 和 error_code，不要仅凭 HTTP 200 判断成功。
重放：Idempotency-Key 最长 191 字节，以用户为作用域。超时或 500 后使用原 Key 和原内容重试；处理中的重试返回 409/request_in_progress。日志与幂等结果默认保留 30 天。

HTTP 错误处理

HTTP	code	含义与处理
400	`invalid_realtime_request` / `idempotency_key_required`	检查号码、产品及请求键；未预扣。
401 / 403	`unauthorized` / `account_banned` / `realtime_disabled`	检查密钥、账号状态与实时功能权限；未预扣。
402	`insufficient_balance`	余额不足，整个组合不执行。
409	`request_in_progress` / `idempotency_conflict`	处理中请按 `Retry-After` 重试；内容冲突时不能复用该 Key。
429	`realtime_rate_limited`	按 `Retry-After` 等待；未预扣。
503	`realtime_route_unavailable` / `realtime_fact_cache_unavailable` / `realtime_rate_limiter_unavailable`	通道、缓存或限流设施不可用；未预扣，请稍后重试。
500	`internal_error`	结果暂时不能确认；保留原 Key 重试，不要换 Key 盲目重发。

子项 error_code 会指出上游、通道容量、请求时限、缓存或并发保护问题；上述失败子项均不收费。