Kiểm tra một số theo thời gian thực

POST/v1/realtime/check/phone

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

Tham số

Trường	Kiểu	Bắt buộc	Mô tả
`identifier`	string	Có	Một số điện thoại E.164, ví dụ +8613800138000.
`country`	string	Không	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. — Mã quốc gia
`product_ids`	array	Có	Mảng gồm 1 đến 10 ID sản phẩm thời gian thực.

Chọn sản phẩm cần kiểm tra

Không đoán ID sản phẩm: hãy lấy id của mục có mode là realtime từ GET /v1/products. Sản phẩm hàng loạt dùng slug, nên slug không bao giờ hoạt động ở endpoint này. Trang danh sách sản phẩm hiển thị ID thời gian thực với tiền tố # chính vì lý do này.

Danh sách sản phẩm

Một lần gọi kiểm tra một số với tối đa mười sản phẩm thời gian thực. Bạn nhận một request_id, mỗi sản phẩm một mục trong results, và mỗi mục được tính phí riêng nên status có thể trả về partial_succeeded. Gửi quá mười ID trong một lần gọi sẽ bị từ chối; bảng điều khiển áp dụng cùng giới hạn.

Ví dụ phản hồi

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

Trường phản hồi

Trường	Kiểu	Mô tả
`request_id`	string (UUID)	UUID định danh lần gửi này. Hãy cung cấp UUID này khi yêu cầu hỗ trợ.
`identifier`	string	Định danh đã được kiểm tra, được trả về nguyên vẹn.
`series`	string	`phone` hoặc `email`.
`status`	string	`succeeded`, `partial_succeeded` hoặc `failed` — suy ra từ số lượng kết quả đã bị tính phí.
`request_status`	string	Trạng thái vòng đời nội bộ của yêu cầu.
`total_reserved`	number	Số tiền tạm giữ trước khi các lượt kiểm tra chạy.
`total_charged`	number	Tổng số tiền đã tính phí trên mọi sản phẩm trong tổ hợp.
`total_refunded`	number	Tổng số tiền đã hoàn cho những mục không thể phân giải.
`charged_amount`	number	Số tiền tính phí thực tế. Luôn bằng `total_charged`.
`refunded_amount`	number	Số tiền hoàn thực tế. Luôn bằng `total_refunded`.
`replayed`	boolean	`true` khi một bản phát lại Idempotency-Key trả về kết quả đã lưu.
`results`	array	Mỗi sản phẩm được yêu cầu có một mục, theo đúng thứ tự yêu cầu.

`results[]`

Trường	Kiểu	Mô tả
`product_id`	integer	ID sản phẩm thời gian thực lấy từ danh mục.
`product`	string	Slug sản phẩm mà ID đó phân giải thành.
`result`	string	`valid`, `invalid` hoặc `unknown` — cho biết định danh đã được đăng ký hay chưa.
`cached`	boolean	`true` khi kết luận đến từ cache. Truy cập cache vẫn bị tính phí.
`billing_status`	string	`charged` hoặc `refunded`.
`charged_amount`	number	Số tiền đã trừ cho sản phẩm này.
`refunded_amount`	number	Số tiền đã hoàn cho sản phẩm này.
`checked_at`	string (ISO 8601)	Thời điểm kết luận được tạo, theo UTC.
`error_code`	string \| null	Lý do mục không thể phân giải, hoặc `null` khi thành công.

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

Thanh toán và ngữ nghĩa

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.

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í.

Lỗi

Endpoint	Ý nghĩa / xử lý
`400`	Sửa số, sản phẩm hoặc khóa yêu cầu; chưa tạm trừ tiền.
`401`	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`	Số dư không đủ; không mục nào được chạy.
`409`	Thử lại theo Retry-After; nội dung khác không được dùng lại khóa.
`429`	Chờ theo Retry-After; chưa tạm trừ tiền.
`500`	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.
`503`	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.