جلب حالة المهمة

GET/v1/tasks/{token}

استعلم عن المهمة حتى تصبح مكتملة أو فاشلة. الفاصل الموصى به: 3–5 ثوان.

الرمز الذي تستعلم به وتنزّل عبره. وهو المعامل {token} في مسار نقاط نهاية المهمة.

مثال الاستجابة

{
  "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	فشل التنفيذ.

حقول الاستجابة

الحقل	النوع	الوصف
task_id	string	الرمز الذي تستعلم به وتنزّل عبره. وهو المعامل {token} في مسار نقاط نهاية المهمة.
progress	integer	نسبة الإنجاز، من 0 إلى 100.
status	string	pending أو processing أو completed أو failed.
product	string	المعرّف النصي للمنتج الذي أُرسلت به المهمة — راجع قائمة منتجات الدفعات.
country	string | null	الدولة التي أُرسلت بها المهمة، أو null لمنتجات البريد الإلكتروني.
submitted	integer	الصفوف المستلمة في الإرسال.
prefiltered	integer	الصفوف المستبعدة قبل الفحص — أسطر مشوّهة مثلًا.
deduped	integer	الصفوف المكررة المحذوفة.
total	integer	الصفوف الموضوعة فعليًا في قائمة انتظار الفحص، بعد الفلترة المسبقة وإزالة التكرار.
processed	integer	الصفوف التي أنهتها القناة المصدر.
valid	integer	الصفوف المؤكدة كمسجّلة.
invalid	integer	الصفوف المؤكدة كغير مسجّلة.
unknown	integer	الصفوف التي تعذّر على المزوّد حسمها.
unknown_processed	integer	الصفوف المجهولة التي أُعيدت محاولتها وسُوّيت.
unknown_unprocessed	integer	الصفوف المجهولة التي لا تزال دون حسم. ويُسترد مقابلها.
stage	string | null	اسم المرحلة الداخلية أثناء تشغيل المهمة. للتشخيص فقط — لا تبنِ عليه تفريعات.
stage_seconds	integer | null	الثواني المستغرقة في المرحلة الحالية.
last_progress_at	string (ISO 8601) | null	وقت آخر تقدّم. وتوقّف الطابع الزمني عن التحرك يعني أن المهمة عالقة لا بطيئة فحسب.
failure_message	string | null	سبب فشل المهمة، أو null.
cost_deducted	string	المبلغ المخصوم عن المهمة، على هيئة نص.
cost_refunded	string	المبلغ المسترد عن صفوف لم تُفحص قط، على هيئة نص.
result_available	boolean	true عندما يمكن تنزيل ملف النتائج.
result_expires_at	string (ISO 8601) | null	وقت توقف إمكانية تنزيل ملف النتائج.
created_at	string (ISO 8601)	وقت إنشاء المهمة.

قراءة العدّادات

submitted هو ما أرسلته؛ وtotal هو ما جرى فحصه فعليًا. ويختلفان كلما وُجدت صفوف مشوّهة أو مكررة، والفارق يساوي تمامًا prefiltered + deduped.

يُحتسب cost_deducted على total، ويغطي cost_refunded الصفوف التي لم تُحسم أبدًا — وهي فئة unknown_unprocessed. ولا يُحتسب إلا الحكمان valid وinvalid.

الاستعلام الدوري

# 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

التالي

• نزّل النتائج عندما يصبح result_available بقيمة true