استجابات تصدير الاستبيانات

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

1. رموز حالة HTTP

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

TIP

الفرق عن الإرسال: التصدير يُرجع 200 مع accepted_count / rejected_count ونتيجة لكل مستلم (status: accepted أو rejected). تعارض البريد/الهاتف أو التكرار يظهر كـ rejected لذلك المستلم فقط، وليس 409 للطلب كله. راجع أمثلة JSON أدناه لحقول data.

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

200 -الكل مقبول

HTTP 200

{
  "success": true,
  "message": "اكتمل التصدير.",
  "data": {
    "accepted_count": 2,
    "rejected_count": 0,
    "recipients": [
      {
        "email": "john1@example.com",
        "phone": "+966501234567",
        "first_name": "John",
        "last_name": "Doe",
        "survey_link": "https://cxm.akwad.sa/w/9mtmcor2?h=SdMZx57tsDc",
        "status": "accepted"
      },
      {
        "email": "jane2@example.com",
        "phone": "+966509876543",
        "first_name": null,
        "last_name": null,
        "survey_link": "https://cxm.akwad.sa/w/9mtmcor2?h=Xk2pQ9mN1wR",
        "status": "accepted"
      }
    ]
  }
}

200 -مختلط (مقبول + مرفوض -تكرار)

HTTP 200 -duplicate active invite

{
  "success": true,
  "message": "اكتمل التصدير.",
  "data": {
    "accepted_count": 0,
    "rejected_count": 2,
    "recipients": [
      {
        "email": "john1@example.com",
        "phone": "+966501234567",
        "first_name": "John",
        "last_name": "Doe",
        "survey_link": null,
        "status": "rejected",
        "error": "يوجد بالفعل دعوة نشطة لهذا المستلم."
      },
      {
        "email": "john1@example.com",
        "phone": "+966501234567",
        "first_name": "John",
        "last_name": "Doe",
        "survey_link": null,
        "status": "rejected",
        "error": "يوجد بالفعل دعوة نشطة لهذا المستلم."
      }
    ]
  }
}

200 -نفس البريد برقم هاتف مختلف (مرفوض)

HTTP 200 -email / phone conflict

{
  "success": true,
  "message": "اكتمل التصدير.",
  "data": {
    "accepted_count": 0,
    "rejected_count": 1,
    "recipients": [
      {
        "email": "john1@example.com",
        "phone": "+966509999999",
        "first_name": "John",
        "last_name": "Doe",
        "survey_link": null,
        "status": "rejected",
        "error": "هذا البريد الإلكتروني مرتبط بالفعل برقم هاتف مختلف على هذا المُجمّع."
      }
    ]
  }
}

200 -نفس الهاتف ببريد مختلف (مرفوض)

HTTP 200 -phone / email conflict

{
  "success": true,
  "message": "اكتمل التصدير.",
  "data": {
    "accepted_count": 0,
    "rejected_count": 1,
    "recipients": [
      {
        "email": "other@example.com",
        "phone": "+966501234567",
        "first_name": null,
        "last_name": null,
        "survey_link": null,
        "status": "rejected",
        "error": "رقم الهاتف هذا مرتبط بالفعل ببريد إلكتروني مختلف على هذا المُجمّع."
      }
    ]
  }
}

200 -مستلم غير صالح (مرفوض)

HTTP 200 -invalid recipient

{
  "success": true,
  "message": "اكتمل التصدير.",
  "data": {
    "accepted_count": 1,
    "rejected_count": 1,
    "recipients": [
      {
        "email": "bad@example.com",
        "phone": null,
        "first_name": null,
        "last_name": null,
        "survey_link": null,
        "status": "rejected",
        "error": "يجب أن يتضمن المستلم بريدًا إلكترونيًا ورقم هاتف صالحين."
      },
      {
        "email": "jane2@example.com",
        "phone": "+966509876543",
        "first_name": null,
        "last_name": null,
        "survey_link": "https://cxm.akwad.sa/w/9mtmcor2?h=Xk2pQ9mN1wR",
        "status": "accepted"
      }
    ]
  }
}

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

HTTP 409

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

422 -recipients مفقود

HTTP 422

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

INFO

قيم error الشائعة لكل مستلم مرفوض: يوجد بالفعل دعوة نشطة لهذا المستلم. · هذا البريد الإلكتروني مرتبط بالفعل برقم هاتف مختلف على هذا المُجمّع. · رقم الهاتف هذا مرتبط بالفعل ببريد إلكتروني مختلف على هذا المُجمّع. · يجب أن يتضمن المستلم بريدًا إلكترونيًا ورقم هاتف صالحين.

---

← حقول طلب التصدير · أمثلة JavaScript و PHP →