Tài liệu API

Xác thực

Tất cả endpoint yêu cầu khóa API trong header của request. The public product catalog does not require authentication.

http

X-API-Key: YOUR_KEY_HERE

Authorization: Bearer YOUR_KEY_HERE

Khóa của bạn dài 51 ký tự: tiền tố zn_ theo sau là 48 ký tự ngẫu nhiên. Các khóa đã cấp trước đây với tiền tố ck_ vẫn còn hiệu lực.

Khóa API có trong Bảng điều khiển tại "API Center". Khóa dạng văn bản chỉ hiển thị một lần khi tạo; hãy lưu ngay.

Định dạng phản hồi

Tất cả endpoint trả về JSON.

Ví dụ phản hồi realtime

json

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

Ví dụ phản hồi bulk

json

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

GET /v1/balance

Lấy số dư

Trả về số dư USD hiện tại của tài khoản đã xác thực.

Ví dụ phản hồi

json

{ "balance": "5.230000" }

GET /v1/products

Danh sách sản phẩm

Danh mục sản phẩm công khai; không cần API Key. Danh mục trả về các sản phẩm realtime và bulk đang hoạt động, series và số lượng tối thiểu. Hãy đọc trước khi gửi.

Ví dụ phản hồi

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

Chi tiết API Key

Trả về siêu dữ liệu API Key của tài khoản đã xác thực. Không bao giờ trả về khóa dạng văn bản thuần.

json

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

Khóa dạng văn bản thuần chỉ hiển thị một lần khi tạo hoặc xoay khóa; endpoint này chỉ trả về giá trị đã che.

Mã lỗi

Khi lỗi, hãy kiểm tra mã trạng thái HTTP và trường message.

Nội dung lỗi

json

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

Lỗi nghiệp vụ luôn trả về code đọc được bằng máy để xử lý theo chương trình. Tham số không hợp lệ (validation) và route không tồn tại trả về định dạng Laravel chuẩn: { "message": "...", "errors": { ... } }. Hãy kiểm tra dữ liệu trước khi gửi.

Lỗi

code	HTTP	Mô tả
unauthorized	401	Khóa API thiếu, không hợp lệ hoặc đã bị vô hiệu hóa.
account_banned	403	Tài khoản bị tạm ngưng. Vui lòng liên hệ hỗ trợ.
invalid_realtime_request	400	Yêu cầu realtime không hợp lệ (ví dụ: số điện thoại thiếu tiền tố quốc tế + khi bỏ trống country).
idempotency_key_required	400	Yêu cầu realtime bắt buộc có header Idempotency-Key.
invalid_idempotency_key	422	Idempotency-Key không hợp lệ: 1-128 ký tự gồm chữ, số và . _ : -
idempotency_conflict	409	Cùng một Idempotency-Key được dùng cho nội dung yêu cầu khác.
request_in_progress	409	Yêu cầu realtime giống hệt vẫn đang được xử lý. Thử lại sau ít phút (Retry-After: 1).
empty_input	422	Tệp tải lên không có dòng dữ liệu nào dùng được.
product_not_found	422	Slug sản phẩm gửi lên không tồn tại hoặc đã tắt.
product_mode_not_supported	422	Endpoint này không nhận chế độ sản phẩm này (sản phẩm realtime không dùng cho endpoint hàng loạt).
invalid_country	422	Sản phẩm không hỗ trợ quốc gia đã gửi.
too_few_numbers	422	Số lượng gửi dưới mức tối thiểu của sản phẩm.
too_many_numbers	422	Số lượng gửi vượt mức tối đa của nền tảng.
insufficient_balance	402	Số dư không đủ. Vui lòng nạp tiền rồi thử lại.
realtime_disabled	403	Tài khoản này chưa được bật kiểm tra realtime.
realtime_rate_limited	429	Vượt giới hạn tần suất realtime. Hãy tuân theo retry_after.
product_pricing_unavailable	503	Sản phẩm này chưa được cấu hình giá. Liên hệ hỗ trợ.
detection_capacity_unavailable	503	Hiện không còn dung lượng kiểm tra. Vui lòng thử lại sau.
realtime_route_unavailable	503	Không có tuyến realtime khả dụng. Vui lòng thử lại sau.
realtime_fact_cache_unavailable	503	Dịch vụ phụ trợ realtime tạm thời không khả dụng. Vui lòng thử lại sau.
realtime_rate_limiter_unavailable	503	Bộ giới hạn tần suất tạm thời không khả dụng. Vui lòng thử lại sau.
not_found	404	task_id không tồn tại hoặc thuộc tài khoản khác.
result_not_ready	422	Tác vụ chưa hoàn tất hoặc tệp kết quả chưa được tạo.
result_expired	404	Tệp kết quả đã hết hạn, bị thiếu hoặc không khả dụng.
validation_failed	422	Kiểm tra các trường bắt buộc, định dạng số và loại tệp.
internal_error	500	Lỗi máy chủ ngoài dự kiến. Có thể thử lại an toàn với cùng Idempotency-Key.

Giới hạn tần suất

Yêu cầu API bị giới hạn theo khóa API và theo nhóm endpoint:

Endpoint	Giới hạn
GET /v1/products · GET /v1/balance · GET /v1/api-key · GET /v1/tasks/{token} · GET /v1/tasks/{token}/result · GET /v1/tasks/{token}/download	60 yêu cầu / phút cho mỗi API key (120 / phút cho mỗi IP)
Điểm cuối: POST /v1/detect · POST /v1/detect/file · POST /v1/quotes/bulk	10 yêu cầu / phút cho mỗi API key (30 / phút cho mỗi IP)
Điểm cuối: POST /v1/realtime/quote/{series} · POST /v1/realtime/check/{series} · POST /v1/realtime/detect	Token bucket theo API key: burst 60, nạp lại 1/giây (≈60 / phút duy trì); theo tài khoản: burst 120, nạp lại 2/giây. Lớp IP cho phép 180 / phút. Mỗi phản hồi đều có header X-RateLimit-Remaining.

Khi vượt giới hạn, API trả về 429 kèm header Retry-After (phản hồi realtime còn có trường retry_after). Tạm dừng theo số giây được báo rồi tiếp tục với exponential backoff.

POST /v1/realtime/check/{series}

Kiểm tra một định danh theo thời gian thực

Kiểm tra đồng bộ một số điện thoại hoặc địa chỉ email. Một yêu cầu có thể chọn nhiều sản phẩm thời gian thực cùng chuỗi bằng ID; không dùng slug của sản phẩm hàng loạt.

Bắt buộc có Idempotency-Key. Gửi lại cùng nội dung và cùng khóa sẽ không bị tính phí hai lần; thay đổi nội dung sẽ trả về 409. cached=true cho biết kết quả được tái sử dụng.

Tham số

Trường	Kiểu	Bắt buộc	Mô tả
series	path	Có	Chuỗi: phone hoặc email; phải khớp với chuỗi của sản phẩm thời gian thực đã chọn.
identifier	string	Có	Một định danh: số điện thoại E.164 hoặc địa chỉ email hợp lệ.
country	string	Không	Chỉ áp dụng cho điện thoại: không bắt buộc với E.164 đầy đủ; số nội địa phải có mã quốc gia ISO phù hợp. Để trống với email.
product_ids	array<int>	Có	Mảng gồm 1 đến 10 ID sản phẩm thời gian thực.

Ví dụ phản hồi

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
    }
  ]
}

Ví dụ 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]}'

Mỗi sản phẩm dùng giá theo lượt đã khóa cho yêu cầu, kể cả khi dùng bộ nhớ đệm. valid và invalid bị tính phí; unknown, hết thời gian và mục đang bận được hoàn tiền.

Tổ hợp thành công một phần trả HTTP 200 với status=partial_succeeded; thất bại toàn bộ là status=failed. Hãy kiểm tra billing_status và error_code của từng mục.

Idempotency-Key tối đa 191 byte và áp dụng theo người dùng. Sau timeout hoặc lỗi 500, gửi lại nội dung gốc với khóa gốc. Kết quả được lưu 30 ngày theo mặc định.

HTTP	code	Ý nghĩa / xử lý
400	invalid_realtime_request / idempotency_key_required	Sửa số, sản phẩm hoặc khóa yêu cầu; chưa tạm trừ tiền.
401 / 403	unauthorized / account_banned / realtime_disabled	Kiểm tra khóa, trạng thái tài khoản và quyền thời gian thực; chưa tạm trừ tiền.
402	insufficient_balance	Số dư không đủ; không mục nào được chạy.
409	request_in_progress / idempotency_conflict	Thử lại theo Retry-After; nội dung khác không được dùng lại khóa.
429	realtime_rate_limited	Chờ theo Retry-After; chưa tạm trừ tiền.
503	realtime_route_unavailable / realtime_fact_cache_unavailable / realtime_rate_limiter_unavailable	Tuyến, bộ nhớ đệm hoặc giới hạn tạm thời không khả dụng; hãy thử lại sau.
500	internal_error	Chưa xác định được kết quả. Hãy dùng khóa gốc để thử lại, không tạo khóa mới.

error_code cho biết lỗi nhà cung cấp, dung lượng kênh, thời hạn, bộ nhớ đệm hoặc bảo vệ đồng thời. Mục thất bại không bị tính phí.

Endpoint tương thích POST /v1/realtime/detect tạm thời được giữ lại cho client cũ. Tích hợp mới nên dùng /v1/realtime/check/phone hoặc /v1/realtime/check/email.

Danh sách sản phẩm · Đơn lẻ (thời gian thực)

Sản phẩm realtime được chọn theo ID sản phẩm và series; không dùng slug của sản phẩm bulk.

Tên sản phẩm	Series	Mã gọi	Tối thiểu
Kiểm tra số Amazon	`phone`	`#53`	1
Kiểm tra email Amazon	`email`	`#54`	1
Kiểm tra số Apple ID	`phone`	`#57`	1
Kiểm tra email Apple ID	`email`	`#58`	1
Kiểm tra số BAND	`phone`	`#60`	1
Kiểm tra số Facebook	`phone`	`#51`	1
Kiểm tra email Facebook	`email`	`#52`	1
Kiểm tra số Instagram	`phone`	`#48`	1
Kiểm tra email Instagram	`email`	`#49`	1
Kiểm tra số Microsoft	`phone`	`#59`	1
Kiểm tra số Telegram	`phone`	`#50`	1
Kiểm tra số Viber	`phone`	`#55`	1
Kiểm tra số WhatsApp	`phone`	`#47`	1
Kiểm tra số điện thoại trên X	`phone`	`#61`	1

POST /v1/detect

Gửi kiểm tra (Mảng)

Gửi mảng số điện thoại hoặc email để kiểm tra hàng loạt không đồng bộ. Chi phí được tạm giữ và hoàn lại phần chưa xử lý.

Số lượng tối thiểu do sản phẩm quy định, tối đa 2.000.000. Bỏ country với email; bắt buộc với số điện thoại.

HTTP 202 Accepted

Tham số

Trường	Kiểu	Bắt buộc	Mô tả
product	string	Có	Slug sản phẩm. Xem trong danh sách sản phẩm.
country	string	Bắt buộc với số điện thoại; bỏ qua với email	Mã quốc gia ISO 3166-1 gồm hai chữ cái. Bắt buộc với điện thoại, bỏ qua với email.
phones	array	Có	Mảng số điện thoại hoặc email; sản phẩm quy định số tối thiểu, tối đa 2.000.000.

Ví dụ phản hồi

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

Gửi kiểm tra (Tải tệp)

Tải TXT hoặc CSV để kiểm tra hàng loạt, mỗi dòng một số điện thoại hoặc email, tối đa 50 MB.

HTTP 202 Accepted

Tham số

Content-Type: multipart/form-data

Trường	Kiểu	Bắt buộc	Mô tả
product	string	Có	Slug sản phẩm
country	string	Bắt buộc với số điện thoại; bỏ qua với email	Mã quốc gia ISO cho điện thoại; bỏ qua với email.
file	file	Có	Tệp TXT hoặc CSV, mỗi dòng một số điện thoại hoặc email, tối đa 50 MB.

Ví dụ phản hồi

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}

Lấy trạng thái tác vụ

Kiểm tra định kỳ cho đến khi trạng thái hoàn tất hoặc thất bại. Khoảng cách khuyến nghị: 3–5 giây.

Ví dụ phản hồi

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"
}

Trạng thái tác vụ

status	Mô tả
pending	Đã vào hàng đợi, đang chờ tài nguyên.
processing	Tác vụ kiểm tra đang chạy.
completed	Đã hoàn tất. Kết quả sẵn sàng để tải xuống.
failed	Thực thi thất bại.

GET /v1/tasks/{token}/result

Lấy URL tải xuống

Sau khi hoàn tất, lấy URL tải xuống cho tệp kết quả. Mặc định tệp được giữ 7 ngày (do cài đặt hệ thống result_retention_days kiểm soát).

Ví dụ phản hồi

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

Tải kết quả

Tải tệp kết quả của tác vụ đã hoàn tất khi tệp vẫn còn trong thời gian lưu trữ.

Ví dụ phản hồi

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

Endpoint này trả về tệp thay vì JSON. Trả về 404/422 khi tác vụ chưa sẵn sàng, đã hết hạn, không khả dụng hoặc thuộc tài khoản khác.

Danh sách sản phẩm · Hàng loạt (bất đồng bộ)

Dùng giá trị slug trong trường product khi gửi tác vụ.

Tên sản phẩm	Mã gọi	Tối thiểu
Kiểm tra số Amazon	`amazonValid`	500
Kiểm tra email Amazon	`amazonEmailValid`	1000
Kiểm tra số Apple ID	`appleidValid`	2000
Kiểm tra email Apple ID	`appleidEmailValid`	1000
Kiểm tra số BAND	`bandValid`	500
Kiểm tra số Binance	`binanceValid`	2000
Kiểm tra email Binance	`binanceEmailValid`	2000
Kiểm tra số CoinW	`coinwValid`	2000
Kiểm tra email CoinW	`coinwEmailValid`	2000
Kiểm tra số Facebook	`fbValid`	500
Kiểm tra email Facebook	`fbEmailValid`	1000
Kiểm tra số HTX	`htxValid`	1000
Kiểm tra email HTX	`htxEmailValid`	2000
Kiểm tra số iMessage	`imessageValid`	2000
Kiểm tra số Instagram	`insValid`	500
Kiểm tra email Instagram	`insEmailValid`	1000
Kiểm tra số KuCoin	`kucoinValid`	1000
Kiểm tra email KuCoin	`kucoinEmailValid`	2000
Tuổi và giới tính trên LINE	`lineGender`	2000
Kiểm tra số LINE	`lineValid`	2000
Hồ sơ Linkedin đầy đủ	`linkedinGender`	2000
Kiểm tra số Linkedin	`linkedinValid`	2000
Kiểm tra số Microsoft	`microsoftValid`	500
Kiểm tra hỗ trợ RCS	`rcsValid`	1000
Kiểm tra số Signal	`signalValid`	2000
Kiểm tra số Snapchat	`snapchatValid`	500
Hồ sơ Telegram đầy đủ	`tgGender`	500
Kiểm tra số Telegram	`tgValid`	1000
Kiểm tra hoạt động Telegram	`tgActive`	500
Tra cứu tên người dùng TikTok	`tiktokUsername`	2000
Kiểm tra số Viber	`viberValid`	1000
Kiểm tra hoạt động Viber	`viberActive`	1000
Hồ sơ WhatsApp đầy đủ	`waGender`	1000
Kiểm tra số WhatsApp	`waValid`	1000
Thông tin hoạt động WhatsApp	`waActive`	500
Kiểm tra số điện thoại trên X	`twitterValid`	2000
Kiểm tra email X	`twitterEmailValid`	2000
Tuổi và giới tính trên Zalo	`zaloGender`	500
Kiểm tra số Zalo	`zaloValid`	2000
Lọc hoạt động Internet	`live-activity-filter`	2000
Kiểm tra trạng thái số điện thoại	`phone-status-check`	2000
Điện thoại bật/tắt	`phone-onoff-check`	1500
Kiểm tra mẫu điện thoại	`phone-model-detection`	500
Tra cứu HLR	`hlr-lookup`	2000

Ví dụ đầy đủ

Sao chép và chạy các ví dụ cURL này — thay YOUR_KEY_HERE và các tham số.

1. Lấy số dư

bash

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

2. Gửi tác vụ kiểm tra

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. Tải tệp lên

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. Kiểm tra trạng thái tác vụ

bash

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

5. Lấy URL tải xuống

bash

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