GET/api/v2/messages/bulk/{jobId}

قراءة مهمة الإرسال الجماعي

يعيد الحالة والعدّادات وتقدم الفحص وسبب الإيقاف ورمز خطأ المهمة. استعلم حتى تصبح queued أو running أو rejected أو paused أو completed أو cancelled.

متى تستخدمه. متابعة مهمة أُنشئت عبر POST /api/v2/messages/bulk.

مثال الطلب

مثال صحيح: صحيح: التقدم

curl --location 'https://raselsms.com/api/v2/messages/bulk/64b0c0ff0000000000000001' \--header 'X-API-Key: YOUR_API_KEY'

مثال صحيح: صحيح: مرفوضة بلا إرسال

curl --location 'https://raselsms.com/api/v2/messages/bulk/64b0c0ff0000000000000001' \--header 'X-API-Key: YOUR_API_KEY'

مثال خاطئ: خطأ: مهمة غير موجودة

curl --location 'https://raselsms.com/api/v2/messages/bulk/000000000000000000000000' \--header 'X-API-Key: YOUR_API_KEY'

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

200 — صحيح: التقدم

{  "success": true,  "job": {    "id": "64b0c0ff0000000000000001",    "name": "Morning notices",    "status": "running",    "messagesPerSecond": 10,    "pauseReason": null,    "total": 2,    "validatedCount": 2,    "counts": {      "pending": 1,      "sent": 1,      "failed": 0,      "cancelled": 0    },    "errorCode": null,    "errorMessage": null,    "createdAt": "2026-09-24T12:00:00.000Z"  }}

200 — صحيح: مرفوضة بلا إرسال

{  "success": true,  "job": {    "id": "64b0c0ff0000000000000001",    "name": "Morning notices",    "status": "rejected",    "messagesPerSecond": 10,    "pauseReason": null,    "total": 2,    "validatedCount": 0,    "counts": {      "pending": 0,      "sent": 0,      "failed": 0,      "cancelled": 0    },    "errorCode": "VALIDATION_FAILED",    "errorMessage": "One or more messages failed validation",    "createdAt": "2026-09-24T12:00:00.000Z"  }}

404 — خطأ: مهمة غير موجودة

{  "success": false,  "code": "JOB_NOT_FOUND",  "error": "Job was not found"}

401 — مفتاح API مفقود أو غير صالح.

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "UNAUTHORIZED",  "error": "Missing or invalid API key"}

403 — الهاتف غير موثّق أو تنقص صلاحية messages:read. الرمز FORBIDDEN.

{  "success": false,  "code": "FORBIDDEN",  "error": "Phone not verified or missing permission"}

429 — تم تجاوز حد الطلبات. انتظر Retry-After إن وُجد.

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "RATE_LIMITED",  "error": "Rate limit exceeded",  "retryAfterSeconds": 30}

طلب HTTP

GET /api/v2/messages/bulk/{jobId}

ترويسات الطلب

الترويسة	النوع	الوصف
X-API-Key	string	مفتاح Rasel API. أرسله في كل طلب موثّق ما عدا الويب هوك الوارد. *

معاملات المسار

الحقل	النوع	الوصف
jobId	string	معرّف المهمة من رد الإنشاء. المهمة ظاهرة لصاحب المفتاح فقط. *

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

الحقل	النوع	الوصف
success	enum	صحيح عندما ينجح الإجراء، أو عندما ينجح مستلم واحد على الأقل في الدفعة. *
job	object	تفاصيل المهمة. الحقول التالية تخص هذه المهمة فقط ولا تظهر لحساب آخر. *
job.id	string	معرّف المورد. *
job.name	string	الاسم الظاهر أو معرّف القالب الإنجليزي الصغير، حسب المسار. *
job.status	enum	حالة التسليم أو السجل. في الإرسال: sent أو queued أو scheduled. في الموارد الأخرى هي فلتر الحالة أو قيمتها. *
job.messagesPerSecond	integer	سقف السرعة: عدد صحيح من 1 إلى 10. الصفر والكسور وما فوق 10 يرفض الطلب قبل إنشاء المهمة. السقف مشترك بين مهام الحساب حسب ترتيب إنشائها. *
job.pauseReason	enum	يظهر فقط والمهمة paused. insufficient_balance وprovider_rate_limit يوقفان النافذة الحالية. user يعني أن الحساب طلب الإيقاف. *
job.total	integer	إجمالي الصفوف المطابقة. *
job.validatedCount	integer	كم صفاً اكتمل فحصه بينما الحالة validating. *
job.counts	object	عدّادات الصفوف. تبقى منفصلة حتى لو اكتملت المهمة وفيها صفوف فاشلة. *
job.counts.pending	integer	صفوف لم تُرسل بعد. *
job.counts.sent	integer	صفوف قُبلت للتسليم. تظهر أيضاً في سجل الرسائل العادي. *
job.counts.failed	integer	صفوف فشلت. المهمة المكتملة قد تبقى فيها صفوف فاشلة. *
job.counts.cancelled	integer	صفوف أُلغيت قبل الإرسال. *
job.errorCode	string	رمز المهمة عندما تكون rejected: VALIDATION_FAILED (فشل فحص صف أو أكثر ولم يُرسل شيء)، أو INSUFFICIENT_BALANCE (الحساب لا يستطيع إرسال رسالة واحدة ولم يُرسل شيء)، أو INTAKE_INCOMPLETE (التخزين لم يكتمل ولم يُرسل شيء). *
job.errorMessage	string	شرح قصير آمن لعرضه لصاحب الحساب. طابق قراراتك على code لا على هذا النص. *
job.createdAt	string	وقت الإنشاء.

رموز الحالة

الحالة	الوصف
200	نجاح.
401	مفتاح API مفقود أو غير صالح.
403	الهاتف غير موثّق، أو الصلاحية ناقصة، أو الحساب لا يستطيع تنفيذ هذا الإجراء.
404	المورد غير موجود لمالك مفتاح API.
429	تم تجاوز حد المعدل، أو وصل عدد محاولات التحقق إلى الحد الأقصى.

حالات يجب أن تعرفها

accepting: التخزين لم يكتمل ولن يُرسَل شيء. إن توقف التخزين تصبح المهمة rejected بالرمز INTAKE_INCOMPLETE.
validating: يُفحص كل صف. validatedCount يوضح التقدم. لا إرسال في هذه الحالة.
rejected: لم يُرسَل شيء. errorCode هو VALIDATION_FAILED أو INSUFFICIENT_BALANCE أو INTAKE_INCOMPLETE.
queued: مقبولة وتنتظر دور الإرسال. running: الإرسال جارٍ.
paused: الإرسال متوقف. pauseReason هو insufficient_balance أو provider_rate_limit أو user.
completed: انتهت المهمة حتى لو فشل بعض الصفوف. العدّادات تبقى منفصلة.
cancelled: الصفوف التي لم تُرسَل أصبحت cancelled. النافذة الحالية قد تكمل بضع إرسالات بعد طلب الإيقاف أو الإلغاء.

جرّب الطلب

مفتاح الـ API

المتغيرات

jobId*

معرّف المهمة من رد الإنشاء. المهمة ظاهرة لصاحب المفتاح فقط.

الطلب

GET /api/v2/messages/bulk/

الاستجابة

نفّذ طلباً لعرض الاستجابة.