نطاق الاستجابات الخام

نطاق الاستجابات الخام

يمنح نطاق RawResponsesRead وصولًا إلى بيانات وصفية لصفوف الاستجابات الفردية الحالية وارتباطات ملفاتها في المؤسسة. هذا هو أكثر نطاقات التكامل حساسية ولا ينبغي منحه إلا عندما يتطلب العقد بيانات على مستوى الصف.

النطاق المطلوب

RawResponsesRead

يجب أيضًا أن تفعّل خطة المؤسسة الفعالة الوصول إلى API الاستجابات الخام، وأن تحتفظ بالعميل ضمن التكاملات الخارجية، وأن تنجح فحوص المؤسسة النشطة والاشتراك.

متى تستخدم هذا النطاق؟

استخدم نطاق RawResponsesRead عندما يحتاج تكاملك إلى:

• بيانات كل إرسال الوصفية وحالته وعدد إجاباته، وهي معلومات لا توفرها التقارير التجميعية.
• قيم الإجابات الفعلية لاستجابة محددة.
• أوصاف ملفات الاستجابات الحالية وتنزيل الملفات المصرح بها.
• تصدير بيانات الإرسال والإجابات الحالية إلى مستودع بيانات أو بحيرة بيانات.
• سيناريوهات الامتثال أو التدقيق التي تتطلب سجلات الإرسال الفردية.

تعيد نقطة قائمة الاستجابات البيانات الوصفية فقط، بينما تعيد نقطة إجابات الاستجابة المخصصة قيم الإجابات الفعلية، بما فيها النص الحر عند وجوده. وتبقى بايتات الملفات في نقطة التنزيل المنفصلة. لا يعرض عقد التكامل الحالي حقل هوية للمستجيب.

لا تستخدم هذا النطاق بمجرد توافره. إذا كانت بيانات التقارير التجميعية من نطاق ReportsRead تفي بمتطلبات التكامل، فضّل ذلك النطاق.

نقاط النهاية المتاحة

قائمة استجابات المؤسسة

تعيد مصفوفة مباشرة مقسمة بالصفحات من بيانات الاستجابات الوصفية عبر المؤسسة. لا يتوفر مرشح استبيان أو تاريخ إرسال حاليًا.

GET /api/integrations/reports/raw-responses?page=1&pageSize=50

معاملات الاستعلام:

تُرفع page إلى 1 على الأقل، ولا تحتوي الاستجابة على غلاف عدد إجمالي. يكون الترتيب تنازليًا حسب createdAt ثم تنازليًا حسب id الفريد كفاصل حتمي عند تساوي الوقت.

هيكل عنصر الاستجابة:

[
  {
    "id": 123,
    "surveyId": 45,
    "surveyName": "رضا العملاء",
    "createdAt": "2026-06-11T12:00:00Z",
    "status": "Completed",
    "answerCount": 10,
    "files": []
  }
]

قراءة إجابات استجابة واحدة

GET /api/integrations/reports/raw-responses/{responseId}/answers

يجب أن يحمل المفتاح نطاق RawResponsesRead. تُقيد الاستجابة بالمؤسسة، وتتصرف الاستجابة غير الموجودة داخل مؤسسة المفتاح كحالة غير موجودة. تعيد النقطة قيم الإجابات المخزنة الفعلية ومراجع الملفات، بينما تبقى بايتات الملفات في نقطة التنزيل أدناه.

ملفات الاستجابة الحالية

يتضمن كل صف حقل files بأوصاف آمنة للارتباطات الحالية فقط: answerFileId وanswerId وquestionId وfileName وfileTypeCode وcontentType وsizeBytes وdownloadUrl. لا يتضمن العقد مسار التخزين أو FileMetadataId أو بيانات التشفير.

تنزيل ملف استجابة حالي

GET /api/integrations/files/{answerFileId}

يجب أن يحمل مفتاح API نفسه نطاق RawResponsesRead. يتحقق الخادم من ارتباط AnswerFile حالي وغير محذوف داخل مؤسسة المفتاح. تعيد نقطة النهاية الملف كمرفق إجباري بنوع application/octet-stream، وتضبط Cache-Control: no-store وX-Content-Type-Options: nosniff، وتعطّل معالجة النطاقات. لا تضبط حاليًا ETag أو توجيه التخزين private. تعيد الارتباطات العابرة للمؤسسات أو المحذوفة 404، بينما تشترط خدمة الملفات بصورة منفصلة أن تكون بيانات الملف الوصفية نشطة.

اعتبارات الخصوصية

• تتحمل المؤسسة مسؤولية التأكد من أن استخدامها لبيانات الاستجابات والملفات الوصفية يمتثل لأنظمة حماية البيانات المعمول بها (مثل GDPR أو ما يعادله محليًا).
• لا تعرض قائمة الاستجابات قيم الإجابات، لكن نقطة الإجابات المخصصة يمكن أن تعرض محتوى الاستجابة الفعلي بما فيه النص الحر. لا يعرض عقد التكامل الحالي حقل هوية للمستجيب. وقد تظل أسماء الملفات والبيانات الوصفية الأخرى حساسة أيضًا.
• لا تخزّن بيانات الاستجابة الخام في أنظمة لا تحتوي على ضوابط وصول مناسبة.

عزل المؤسسات

كل استعلام للاستجابات الخام مقيد تلقائيًا بالمؤسسة المرتبطة بمفتاح API. لا يمكن استرداد استجابات استبيانات مؤسسة أخرى باستخدام مفتاح التكامل.