API التقارير

واجهة برمجة التقارير

توفر واجهة برمجة التقارير وصولًا للقراءة فقط إلى بيانات تعريف الاستبيانات وملخصات الاستجابات وملخصات الاستخدام وصفوف الاستجابات الخام للمؤسسة. تتطلب نقاط النهاية أحد النطاقات الحالية: ReportsRead أو UsageRead أو RawResponsesRead.

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

ReportsRead لبيانات الاستبيانات وملخصات الاستجابات. UsageRead لملخص الاستخدام. RawResponsesRead لصفوف الاستجابات الخام وقيم إجابات الاستجابة الفردية وتنزيل ملفات الاستجابة المصرح بها.

تتطلب المصادقة أيضًا مؤسسة نشطة ووصول اشتراك مسموحًا وبقاء العميل ضمن الحد الفعلي التكاملات الخارجية وإمكانية الخطة المطابقة. يتطلب ReportsRead وUsageRead إمكانية الوصول إلى API التقارير، ويتطلب RawResponsesRead إمكانية الوصول إلى API الاستجابات الخام. يعيد فشل المصادقة أو بوابة الخطة HTTP 401، بينما يعيد المفتاح المصادق الذي يفتقد نطاق نقطة النهاية HTTP 403.

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

قائمة بيانات الاستبيانات

تعيد مصفوفة واحدة غير مقسمة بالصفحات من جميع استبيانات المؤسسة غير المحذوفة، مرتبة حسب الاسم.

GET /api/integrations/reports/surveys

حقول الاستجابة (لكل استبيان):

الحقل	النوع	الوصف
`id`	integer	المعرف الفريد للاستبيان
`code`	string أو null	رمز الاستبيان عند وجوده
`name`	string أو null	اسم الاستبيان عند وجوده
`description`	string أو null	الوصف عند وجوده
`isActive`	boolean	ما إذا كان الاستبيان نشطًا

قائمة ملخصات الاستجابات

تعيد مصفوفة غير مقسمة بالصفحات من أعداد الاستجابات مجمعة حسب الاستبيانات التي لديها استجابات غير محذوفة.

GET /api/integrations/reports/responses

حقول كل صف هي surveyId وsurveyName القابل للقيمة null وtotalResponses وcompletedResponses وlastResponseAt القابل للقيمة null.

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

[
  {
    "surveyId": 45,
    "surveyName": "رضا العملاء",
    "totalResponses": 342,
    "completedResponses": 310,
    "lastResponseAt": "2026-07-20T14:22:11Z"
  }
]

ملخص الاستخدام

يعيد GET /api/integrations/reports/usage كائنًا واحدًا يحتوي activeClients وtotalClients وactiveSurveys وresponsesThisMonth، ويتطلب UsageRead.

{
  "activeClients": 2,
  "totalClients": 3,
  "activeSurveys": 5,
  "responsesThisMonth": 342
}

الاستجابات الخام

يعيد GET /api/integrations/reports/raw-responses?page=1&pageSize=50 مصفوفة مباشرة من بيانات الاستجابة والملفات الوصفية. يتطلب RawResponsesRead، ولا يعرض هذا المسار نفسه قيم الإجابات. تُحصر pageSize عند 100، ويكون الترتيب تنازليًا حسب createdAt ثم id الفريد.

إجابات استجابة واحدة

يعيد GET /api/integrations/reports/raw-responses/{responseId}/answers قيم الإجابات الفعلية لاستجابة حالية واحدة داخل المؤسسة. يتطلب RawResponsesRead، ويعيد مراجع الملفات دون بايتاتها. لا تكشف الاستجابة عن وجود معرف تابع لمؤسسة أخرى.

حدود العقد

تعرض ملخصات التقارير أعدادًا، لا توزيعات لكل سؤال أو متوسطات أو تفصيل خيارات أو قيم إجابات. وتعرض قائمة الاستجابات الخام بيانات الاستجابة/الملف الوصفية وanswerCount، بينما تتوفر القيم الفعلية فقط عبر نقطة /{responseId}/answers المخصصة تحت نطاق RawResponsesRead.

عزل المؤسسات

جميع استجابات واجهة برمجة التقارير مقيدة تلقائيًا بالمؤسسة المرتبطة بمفتاح API. لن يعيد مفتاح صادر عن المؤسسة أ استبيانات أو استجابات تعود للمؤسسة ب.

ملاحظات

تعرض بيانات الاستبيانات كل الاستبيانات غير المحذوفة، النشطة وغير النشطة.
تعكس الملخصات الاستجابات غير المحذوفة المتاحة لحظة الطلب.
تتطلب صفوف الاستجابات الفردية نطاق RawResponsesRead الصريح.