API 文档 — Zelnum

认证说明

所有需要认证的接口均需携带凭证。可使用 X-API-Key（推荐）或 Authorization: Bearer 请求头；公开产品目录无需认证。

http

X-API-Key: YOUR_KEY_HERE

Authorization: Bearer YOUR_KEY_HERE

密钥共 51 个字符：前缀 zn_ 加 48 位随机字符。此前签发的 ck_ 前缀密钥依然有效，无需更换。

API Key 可在控制台「API 中心」页面查看或重新生成。密钥仅在生成时完整显示一次，请立即保存。

响应格式

所有接口统一返回 JSON。

实时响应示例

json

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "status": "succeeded",
  "replayed": false,
  "results": []
}

批量响应示例

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued."
}

GET /v1/balance

查询余额

查询当前账号的可用 USD 余额。

响应示例

json

{ "balance": "5.230000" }

GET /v1/products

产品列表

公开产品目录，无需 API Key。返回当前启用的实时与批量产品、系列和最低数量；提交前请先读取此接口。

响应示例

json

{
  "data": [
    {
      "id": 101,
      "slug": "whatsapp-realtime",
      "name": "WhatsApp Number Checker",
      "name_translations": { "zh_CN": "WhatsApp 注册检测" },
      "mode": "realtime",
      "series": "phone",
      "min_phones": 1
    }
  ]
}

GET /v1/api-key

API Key 信息

查询当前账号的 API Key 元信息。出于安全原因不会返回完整密钥。

json

{
  "api_key_id": 42,
  "masked_key": "ck_••••••••••••••••••••••••••••••••••••••••••••••••",
  "last_used": "2026-09-05T10:00:00Z",
  "created_at": "2026-08-01T09:00:00Z"
}

完整密钥只会在创建或轮换时显示一次；此接口只能返回脱敏值。

错误码

请求失败时 HTTP 状态码与 message 字段说明如下。

错误响应体

json

{
  "code": "insufficient_balance",
  "message": "Insufficient balance for this submission."
}

业务错误始终返回机器可读的 code，便于程序化分支处理。参数校验失败与不存在的路由则返回 Laravel 标准结构：{ "message": "...", "errors": { ... } }。提交前请先做好入参校验。

错误信息

code	HTTP	说明
unauthorized	401	API Key 缺失、无效或已停用。
account_banned	403	账号已被封禁，请联系客服。
invalid_realtime_request	400	实时检测请求格式错误（例如 country 留空时号码缺少 + 国际区号前缀）。
idempotency_key_required	400	实时检测请求必须携带 Idempotency-Key 头。
invalid_idempotency_key	422	Idempotency-Key 格式非法：仅允许 1-128 位字母、数字及 . _ : - 字符。
idempotency_conflict	409	同一 Idempotency-Key 被用于内容不同的请求。
request_in_progress	409	完全相同的实时请求正在处理中，请稍后重试（Retry-After: 1）。
empty_input	422	上传的文件没有可用数据行。
product_not_found	422	提交的产品 slug 不存在或未启用。
product_mode_not_supported	422	该端点不接受此产品模式（实时产品不能提交到批量端点）。
invalid_country	422	该产品不支持所提交的国家。
too_few_numbers	422	提交数量低于该产品的最低起量。
too_many_numbers	422	提交数量超过平台上限。
insufficient_balance	402	余额不足以覆盖本次提交，请充值后重试。
realtime_disabled	403	该账号未开通实时检测。
realtime_rate_limited	429	实时检测触发限流，请遵循 retry_after。
product_pricing_unavailable	503	该产品尚未配置价格，请联系客服。
detection_capacity_unavailable	503	当前没有可用检测通道容量，请稍后重试。
realtime_route_unavailable	503	当前没有可用的实时检测路由，请稍后重试。
realtime_fact_cache_unavailable	503	实时检测依赖服务暂时不可用，请稍后重试。
realtime_rate_limiter_unavailable	503	限流器暂时不可用，请稍后重试。
not_found	404	task_id 不存在或不属于当前账号。
result_not_ready	422	任务尚未完成或结果文件尚未生成。
result_expired	404	结果文件已过期、缺失或不可用。
validation_failed	422	检查必填字段、号码格式和文件类型。
internal_error	500	服务器内部错误。携带相同 Idempotency-Key 重试是安全的。

限流规则

API 请求按 API Key 分别限流，按端点组计算：

端点	限额
GET /v1/products · GET /v1/balance · GET /v1/api-key · GET /v1/tasks/{token} · GET /v1/tasks/{token}/result · GET /v1/tasks/{token}/download	每个 API Key 60 次 / 分钟（每 IP 120 次 / 分钟）
接口：POST /v1/detect · POST /v1/detect/file · POST /v1/quotes/bulk	每个 API Key 10 次 / 分钟（每 IP 30 次 / 分钟）
接口：POST /v1/realtime/quote/{series} · POST /v1/realtime/check/{series} · POST /v1/realtime/detect	按 API Key 的令牌桶：容量 60，每秒回填 1 个（持续约 60 次 / 分钟）；按账号：容量 120，每秒回填 2 个。IP 层上限 180 次 / 分钟。每次响应都带 X-RateLimit-Remaining 头。

超限后 API 返回 429，并带 Retry-After 头（实时检测响应还含 retry_after 字段）。请按提示秒数暂停请求，恢复后使用指数退避重试。

POST /v1/realtime/check/{series}

实时单标识检测

同步检测一个手机号或邮箱。一次请求可以选择同一系列的多个实时产品；每个产品必须使用实时产品 ID，不能使用批量产品 slug。

必须携带 Idempotency-Key。相同 Key 重试同一请求不会重复扣费；相同 Key 改变请求内容会返回 409。结果复用时 cached=true，失败或未知结果不会被当作有效事实缓存。

请求参数

字段	类型	必填	说明
series	path	是	系列：phone 或 email；必须与所选实时产品的 series 一致。
identifier	string	是	一个标识：E.164 手机号（例如 +8613800138000）或有效邮箱地址。
country	string	否	仅手机号使用：完整 E.164 号码可省略；本地号码必须提供匹配的 ISO 国家代码。邮箱请留空。
product_ids	array<int>	是	实时产品 ID 数组，1 到 10 个。

响应示例

json

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "identifier": "+8613800138000",
  "series": "phone",
  "status": "succeeded",
  "request_status": "completed",
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "charged_amount": 0.004000,
  "refunded_amount": 0.000000,
  "replayed": false,
  "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 示例

bash

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":[101,102]}'

bash

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/email" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"[email protected]","country":null,"product_ids":[201]}'

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

兼容入口 POST /v1/realtime/detect 仍暂时保留给旧客户端，但新集成应使用按系列区分的 /v1/realtime/check/phone 或 /v1/realtime/check/email。

产品列表 · 单次（实时）

实时产品使用产品 ID 和 series 选择，不能使用批量产品 slug。

产品名称	Series	调用标识	最低数量
Amazon 注册检测	`phone`	`#53`	1
Amazon 邮箱检测	`email`	`#54`	1
Apple ID 注册检测	`phone`	`#57`	1
Apple ID 邮箱检测	`email`	`#58`	1
BAND 注册检测	`phone`	`#60`	1
Facebook 注册检测	`phone`	`#51`	1
Facebook 邮箱检测	`email`	`#52`	1
Instagram 注册检测	`phone`	`#48`	1
Instagram 邮箱检测	`email`	`#49`	1
Microsoft 注册检测	`phone`	`#59`	1
Telegram 注册检测	`phone`	`#50`	1
Viber 注册检测	`phone`	`#55`	1
WhatsApp 注册检测	`phone`	`#47`	1
X（原 Twitter）注册检测	`phone`	`#61`	1

POST /v1/detect

提交检测（号码数组）

提交手机号或邮箱数组发起批量检测任务，异步处理。费用按提交总数预扣，无法检测部分完成后自动退回。

提交数量必须达到所选产品的最低数量，且不得超过平台上限（默认 2,000,000）。邮箱产品不需要 country；手机号产品必须提供 country。

HTTP 202 Accepted

请求参数

字段	类型	必填	说明
product	string	是	产品 slug，见产品列表。
country	string	手机号必填；邮箱省略	手机号产品必填的 ISO 3166-1 二位国家码；邮箱产品省略。
phones	array	是	号码或邮箱数组；最低数量由产品配置决定，平台上限默认 2,000,000。

响应示例

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "idempotent_replay": false,
  "message": "Task queued. Poll GET /api/v1/tasks/xKj9aP3qLm7v for progress.",
  "recovery_pending": false,
  "summary": {
    "total": 5000,
    "cost_deducted": 0.500000
  }
}

POST /v1/detect/file

提交检测（上传文件）

上传 TXT 或 CSV 文件批量检测，每行一个手机号或邮箱，最大 50 MB。

HTTP 202 Accepted

请求参数

Content-Type: multipart/form-data

字段	类型	必填	说明
product	string	是	产品 slug
country	string	手机号必填；邮箱省略	手机号必填的 ISO 国家码；邮箱省略。
file	file	是	TXT 或 CSV，每行一个手机号或邮箱，最大 50 MB。

响应示例

json

{
  "mode": "async",
  "task_id": "qH5rZ7Lp3Wm9",
  "idempotent_replay": false,
  "message": "File queued (10000 numbers). Poll GET /api/v1/tasks/qH5rZ7Lp3Wm9 for progress.",
  "recovery_pending": false,
  "summary": {
    "total": 10000,
    "cost_deducted": 1.000000
  }
}

GET /v1/tasks/{token}

查询任务进度

轮询任务执行状态，建议间隔 3-5 秒，直到 status 为 completed 或 failed。

响应示例

json

{
  "task_id": "xKj9aP3qLm7v",
  "status": "completed",
  "progress": 100,
  "product": "YOUR_PRODUCT_SLUG",
  "country": "CN",
  "submitted": 5000,
  "prefiltered": 0,
  "deduped": 0,
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "unknown_processed": 0,
  "unknown_unprocessed": 0,
  "stage": "completed",
  "stage_seconds": 12,
  "last_progress_at": "2026-09-05T10:00:12+00:00",
  "failure_message": null,
  "cost_deducted": "0.500000",
  "cost_refunded": "0.000000",
  "result_available": true,
  "result_expires_at": "2026-05-02T10:00:00+00:00",
  "created_at": "2026-05-01T10:00:00+00:00"
}

任务状态

status	说明
pending	已提交，等待分配资源。
processing	检测进行中。
completed	已完成，可下载结果。
failed	执行失败。

GET /v1/tasks/{token}/result

获取下载地址

任务完成后获取结果文件下载链接，结果文件默认保留 7 天（由系统设置 result_retention_days 控制）。

响应示例

json

{
  "task_id": "xKj9aP3qLm7v",
  "download_url": "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/download",
  "expires_at": "2026-05-02T10:00:00+00:00",
  "summary": {
    "submitted": 5000,
    "prefiltered": 0,
    "deduped": 0,
    "total": 5000,
    "valid": 3800,
    "invalid": 1200,
    "unknown": 0,
    "unknown_processed": 0,
    "unknown_unprocessed": 0
  }
}

GET /v1/tasks/{token}/download

下载检测结果

使用 API Key 下载已完成且仍在保留期内的结果文件。

响应示例

Content-Type: application/zip (or text/csv for a single result).

此接口直接返回文件流，不返回 JSON。任务未完成、文件已过期或不属于当前账号时返回 404/422。

产品列表 · 批量（异步）

提交任务时 product 字段填写以下 slug 值。

产品名称	调用标识	最低数量
Amazon 注册检测	`amazonValid`	500
Amazon 邮箱检测	`amazonEmailValid`	1000
Apple ID 注册检测	`appleidValid`	2000
Apple ID 邮箱检测	`appleidEmailValid`	1000
BAND 注册检测	`bandValid`	500
Binance 注册检测	`binanceValid`	2000
Binance 邮箱检测	`binanceEmailValid`	2000
CoinW 注册检测	`coinwValid`	2000
CoinW 邮箱检测	`coinwEmailValid`	2000
Facebook 注册检测	`fbValid`	500
Facebook 邮箱检测	`fbEmailValid`	1000
HTX 注册检测	`htxValid`	1000
HTX 邮箱检测	`htxEmailValid`	2000
iMessage 注册检测	`imessageValid`	2000
Instagram 注册检测	`insValid`	500
Instagram 邮箱检测	`insEmailValid`	1000
KuCoin 注册检测	`kucoinValid`	1000
KuCoin 邮箱检测	`kucoinEmailValid`	2000
LINE 年龄与性别	`lineGender`	2000
LINE 注册检测	`lineValid`	2000
Linkedin 完整资料	`linkedinGender`	2000
Linkedin 注册检测	`linkedinValid`	2000
Microsoft 注册检测	`microsoftValid`	500
RCS 支持检测	`rcsValid`	1000
Signal 注册检测	`signalValid`	2000
Snapchat 注册检测	`snapchatValid`	500
Telegram 完整资料	`tgGender`	500
Telegram 注册检测	`tgValid`	1000
Telegram 活跃检测	`tgActive`	500
TikTok 用户名查询	`tiktokUsername`	2000
Viber 注册检测	`viberValid`	1000
Viber 活跃检测	`viberActive`	1000
WhatsApp 完整资料	`waGender`	1000
WhatsApp 注册检测	`waValid`	1000
WhatsApp 活跃信息	`waActive`	500
X（原 Twitter）注册检测	`twitterValid`	2000
X（原 Twitter）邮箱检测	`twitterEmailValid`	2000
Zalo 年龄与性别	`zaloGender`	500
Zalo 注册检测	`zaloValid`	2000
互联网活跃筛选	`live-activity-filter`	2000
号码状态检测	`phone-status-check`	2000
开关机检测	`phone-onoff-check`	1500
手机型号检测	`phone-model-detection`	500
运营商查询	`hlr-lookup`	2000

完整示例

以下为 cURL 完整调用示例，复制后替换 YOUR_KEY_HERE 和参数即可运行。

1. 查询余额

bash

curl -X GET "https://api.zelnum.com/api/v1/balance" \
  -H "X-API-Key: YOUR_KEY_HERE"

2. 提交号码检测

bash

curl -X POST "https://api.zelnum.com/api/v1/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "YOUR_PRODUCT_SLUG",
    "country": "CN",
    "phones": ["+8613800138000", "+8613900139000"]
  }'

3. 上传文件检测

bash

curl -X POST "https://api.zelnum.com/api/v1/detect/file" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -F "product=YOUR_PRODUCT_SLUG" \
  -F "country=CN" \
  -F "file=@/path/to/numbers.txt"

4. 查询任务进度

bash

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v" \
  -H "X-API-Key: YOUR_KEY_HERE"

5. 获取下载链接

bash

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/result" \
  -H "X-API-Key: YOUR_KEY_HERE"