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

GET/v1/tasks/{token}

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.

Token dùng để thăm dò và tải xuống. Đây là tham số đường dẫn {token} của các endpoint tác vụ.

Ví dụ phản hồi

{
  "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.

Trường phản hồi

Trường	Kiểu	Mô tả
task_id	string	Token dùng để thăm dò và tải xuống. Đây là tham số đường dẫn {token} của các endpoint tác vụ.
progress	integer	Phần trăm hoàn thành, 0 đến 100.
status	string	pending, processing, completed hoặc failed.
product	string	Slug sản phẩm đã dùng khi gửi tác vụ — xem danh sách sản phẩm hàng loạt.
country	string | null	Quốc gia mà tác vụ được gửi kèm, hoặc null với sản phẩm email.
submitted	integer	Số dòng nhận được trong lần gửi.
prefiltered	integer	Số dòng bị loại trước khi phát hiện — ví dụ các dòng sai định dạng.
deduped	integer	Số dòng trùng lặp đã bị loại bỏ.
total	integer	Số dòng thực sự được đưa vào hàng đợi phát hiện, sau khi lọc trước và loại trùng.
processed	integer	Số dòng mà kênh thượng nguồn đã xử lý xong.
valid	integer	Số dòng được xác nhận là đã đăng ký.
invalid	integer	Số dòng được xác nhận là chưa đăng ký.
unknown	integer	Số dòng mà nhà cung cấp không thể phân giải.
unknown_processed	integer	Các dòng không phân giải được đã được thử lại và quyết toán.
unknown_unprocessed	integer	Các dòng không phân giải được vẫn chưa xử lý. Những dòng này được hoàn tiền.
stage	string | null	Tên giai đoạn nội bộ khi tác vụ đang chạy. Chỉ dùng để chẩn đoán — không rẽ nhánh theo giá trị này.
stage_seconds	integer | null	Số giây đã dùng ở giai đoạn hiện tại.
last_progress_at	string (ISO 8601) | null	Thời điểm tiến độ tiến triển lần cuối. Mốc thời gian ngừng thay đổi nghĩa là tác vụ bị kẹt, chứ không chỉ chậm.
failure_message	string | null	Lý do tác vụ thất bại, hoặc null.
cost_deducted	string	Số tiền đã trừ cho tác vụ, ở dạng chuỗi.
cost_refunded	string	Số tiền đã hoàn cho những dòng chưa từng được kiểm tra, ở dạng chuỗi.
result_available	boolean	true khi có thể tải tệp kết quả.
result_expires_at	string (ISO 8601) | null	Thời điểm tệp kết quả không còn tải được.
created_at	string (ISO 8601)	Thời điểm tác vụ được tạo.

Đọc các số đếm

submitted là số bạn đã gửi; total là số thực sự được kiểm tra. Hai giá trị này khác nhau khi có dòng sai định dạng hoặc trùng lặp, và chênh lệch đúng bằng prefiltered + deduped.

cost_deducted được tính trên total, còn cost_refunded bao gồm các dòng không bao giờ có kết quả — nhóm unknown_unprocessed. Chỉ các kết luận valid và invalid mới bị tính phí.

Thăm dò

# Poll until the task leaves pending/processing. `last_progress_at` going
# stale is the real failure signal, not elapsed time.
for i in $(seq 1 120); do
  body=$(curl -s -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v" \
    -H "X-API-Key: YOUR_KEY_HERE")
  status=$(printf '%s' "$body" | jq -r '.status')
  printf '%s %s%%\n' "$status" "$(printf '%s' "$body" | jq -r '.progress')"
  case "$status" in
    completed) printf '%s' "$body" | jq .; break ;;
    failed)    printf '%s' "$body" | jq .; exit 1 ;;
  esac
  sleep 5
done

Tiếp theo

• Tải kết quả khi result_available là true