استجابات إرسال الاستبيانات

مرجع رموز HTTP وأمثلة JSON لنقطة إرسال الاستبيانات عبر API (POST /api/v1/collectors/api/{collector_uuid}).

جميع الاستجابات تستخدم غلاف JSON موحّد:

• نجاح: { "success": true, "data": { … } } -قد يُضاف message اختياريًا
• خطأ: { "success": false, "message": "…", "errors": { … } } -errors اختياري

INFO

نصوص message و errors تعتمد على لغة الطلب (Accept-Language: ar أو en). الأمثلة أدناه بالعربية كما يرجعها الخادم للغة العربية.

1. رموز حالة HTTP

الرمز	متى يحدث	ملخص message
200	تم قبول المستلمين ووضع الإرسال في قائمة الانتظار	(لا رسالة إلزامية في النجاح)
401	رمز X-External-Access-Token مفقود أو غير صالح	رمز الوصول الخارجي غير صالح أو مفقود
403	الرمز صالح لكن المستخدم لا يملك صلاحية الاستبيان	ليس لديك صلاحية الوصول إلى مُجمّع API هذا
404	collector_uuid غير موجود	قناة التوزيع غير موجودة
422	فشل التحقق من جسم الطلب (medium، recipients، أرقام SMS السعودية، الحد الأقصى 5000)	البيانات المدخلة غير صالحة
409	قواعد العمل -يفشل الطلب بالكامل (لا يُ queued أحد): مُجمّع غير نشط، استبيان غير منشور، محتوى غير جاهز، مستلم مكرر، تعارض بريد/هاتف	يختلف حسب السبب (انظر الأمثلة)

TIP

على عكس تصدير الروابط، الإرسال لا يُرجع نتيجة لكل مستلم في نفس الطلب. إما يُقبل الطلب بالكامل (200) أو يُرفض بالكامل (409 / 422 / …).

2. أمثلة الاستجابة

200 -نجاح (تمت الجدولة)

HTTP 200

{
  "success": true,
  "data": {
    "queued": true,
    "medium": "sms",
    "recipient_count": 2,
    "scheduled_for": "2026-06-03T18:10:14+00:00",
    "jobs_dispatched": 2
  }
}

حقل data	الوصف
queued	true عند قبول الطلب
medium	sms أو email أو whatsapp كما في الطلب
recipient_count	عدد المستلمين المقبولين
scheduled_for	وقت الإرسال المجدول (ISO 8601) حسب إعدادات المُجمّع
jobs_dispatched	عدد مهام الإرسال المُجدّولة

409 -مستلم مكرر (دعوة نشطة)

HTTP 409

{
  "success": false,
  "message": "يوجد بالفعل دعوة نشطة لواحد أو أكثر من المستلمين على هذا المُجمّع.",
  "errors": {
    "recipients.0": [
      "يوجد بالفعل دعوة نشطة لواحد أو أكثر من المستلمين على هذا المُجمّع."
    ]
  }
}

409 -نفس البريد برقم هاتف مختلف

HTTP 409

{
  "success": false,
  "message": "هذا البريد الإلكتروني مرتبط بالفعل برقم هاتف مختلف على هذا المُجمّع.",
  "errors": {
    "recipients.0": [
      "هذا البريد الإلكتروني مرتبط بالفعل برقم هاتف مختلف على هذا المُجمّع."
    ]
  }
}

409 -نفس الهاتف ببريد مختلف

HTTP 409

{
  "success": false,
  "message": "رقم الهاتف هذا مرتبط بالفعل ببريد إلكتروني مختلف على هذا المُجمّع.",
  "errors": {
    "recipients.0": [
      "رقم الهاتف هذا مرتبط بالفعل ببريد إلكتروني مختلف على هذا المُجمّع."
    ]
  }
}

409 -مُجمّع غير نشط أو استبيان غير منشور

HTTP 409 -مُجمّع غير نشط

{
  "success": false,
  "message": "مُجمّع API هذا غير نشط."
}

HTTP 409 -استبيان غير منشور

{
  "success": false,
  "message": "لا يوجد إصدار منشور لهذا الاستبيان بعد."
}

422 -فشل التحقق

HTTP 422 -medium مفقود

{
  "success": false,
  "message": "البيانات المدخلة غير صالحة.",
  "errors": {
    "medium": [
      "The medium field is required."
    ]
  }
}

HTTP 422 -مستلم SMS بدون رقم

{
  "success": false,
  "message": "البيانات المدخلة غير صالحة.",
  "errors": {
    "recipients.0": [
      "أدخل رقم جوال سعوديًا صالحًا (+966 متبوعًا بـ 9 أرقام)."
    ]
  }
}

401 / 403 / 404

HTTP 401

{
  "success": false,
  "message": "رمز الوصول الخارجي غير صالح أو مفقود."
}

HTTP 403

{
  "success": false,
  "message": "ليس لديك صلاحية الوصول إلى مُجمّع API هذا."
}

HTTP 404

{
  "success": false,
  "message": "قناة التوزيع غير موجودة."
}

---

← مرجع حقول الطلب · أمثلة JavaScript و PHP →