实时单号检测

POST/v1/realtime/check/phone

同步检测一个号码。一次请求可以选择多个实时产品；每个产品必须使用实时产品 ID，不能使用批量产品 slug。

请求参数

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

响应示例

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

cURL 示例

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

计费与语义

计费：每个产品按本次请求锁定的单次价计费，缓存命中同价。仅 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 会指出上游、通道容量、请求时限、缓存或并发保护问题；上述失败子项均不收费。