واجهة برمجة الاستجابات

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

تتيح لك واجهة برمجة الاستجابات استرجاع وتصفية وحذف وتصدير الإرسالات التي تجمعها نماذجك. جميع الاستجابات مرتبطة بنموذج محدد.

تستخدم جميع هياكل الطلبات والاستجابات أسماء حقول بتنسيق snake_case.

Endpoints

GET/api/v1/forms/:id/responsesGET/api/v1/forms/:id/responses/:responseIdDELETE/api/v1/forms/:id/responses/:responseIdPOST/api/v1/forms/:id/responses/bulk-deleteGET/api/v1/forms/:id/responses/export

عرض الاستجابات

GET/api/v1/forms/:id/responses

يُرجع قائمة مُرقَّمة من الاستجابات لنموذج معين، مرتبة حسب تاريخ الإرسال (الأحدث أولاً).

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

idstringمطلوب

معرّف النموذج

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

pageinteger

رقم الصفحة (الافتراضي: 1)

per_pageinteger

عدد النتائج لكل صفحة (الافتراضي: 50)

sincestring

تاريخ بتنسيق ISO 8601. يُرجع فقط الاستجابات المُرسلة في هذا التاريخ أو بعده.

untilstring

تاريخ بتنسيق ISO 8601. يُرجع فقط الاستجابات المُرسلة في هذا التاريخ أو قبله.

completedboolean

التصفية حسب حالة الإكمال. true يُرجع فقط الاستجابات المكتملة، false يُرجع فقط الاستجابات الجزئية.

أنواع قيم الإجابات

short_textstring

مثال: "Jane Smith"

long_textstring

مثال: "I really enjoyed the product..."

multiple_choicestring

مثال: "Option A"

multiple_choice (multi)array of strings

مثال: ["Option A", "Option C"]

ratingnumber

مثال: 4

opinion_scalenumber

مثال: 8

numbernumber

مثال: 42

emailstring

مثال: "jane@example.com"

datestring (ISO 8601)

مثال: "2026-03-15"

yes_noboolean

مثال: true

file_uploadobject

مثال: { "url": "...", "name": "doc.pdf" }

dropdownstring

مثال: "United States"

الاستجابة

json

{
  "responses": [
    {
      "id": "667a1b2c3d4e5f6a7b8c9d01",
      "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "visitor_id": "v_8f2k3j4l5m6n",
      "submitted_at": "2026-02-27T15:42:00.000Z",
      "completed_at": "2026-02-27T15:45:30.000Z",
      "metadata": {
        "user_agent": "Mozilla/5.0",
        "referrer": "https://example.com"
      },
      "answers": [
        {
          "question_id": "66a1b2c3d4e5f6a7b8c9d001",
          "value": "Jane Smith"
        },
        {
          "question_id": "66a1b2c3d4e5f6a7b8c9d002",
          "value": "Social media"
        },
        {
          "question_id": "66a1b2c3d4e5f6a7b8c9d003",
          "value": 5
        }
      ],
      "quiz_results": null
    }
  ],
  "total": 142,
  "page": 1,
  "per_page": 50
}

أمثلة الشيفرة البرمجية

bash

curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/responses?page=1&per_page=25&completed=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

الحصول على استجابة

GET/api/v1/forms/:id/responses/:responseId

يسترجع استجابة واحدة بواسطة المعرّف.

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

idstringمطلوب

معرّف النموذج

responseIdstringمطلوب

معرّف الاستجابة

نتائج الاختبار

بالنسبة للنماذج التي تستخدم أوضاع الاختبار (knowledge_quiz، lead_qualification، match_quiz)، يحتوي حقل quiz_results على بيانات التقييم.

الاستجابة

json

{
  "id": "667a1b2c3d4e5f6a7b8c9d01",
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "visitor_id": "v_8f2k3j4l5m6n",
  "submitted_at": "2026-02-27T15:42:00.000Z",
  "completed_at": "2026-02-27T15:45:30.000Z",
  "metadata": {
    "user_agent": "Mozilla/5.0",
    "referrer": "https://example.com"
  },
  "answers": [
    {
      "question_id": "66a1b2c3d4e5f6a7b8c9d001",
      "value": "Jane Smith"
    },
    {
      "question_id": "66a1b2c3d4e5f6a7b8c9d002",
      "value": "Social media"
    },
    {
      "question_id": "66a1b2c3d4e5f6a7b8c9d003",
      "value": 5
    }
  ],
  "quiz_results": null
}

مثال نتائج الاختبار

json

{
  "quiz_results": {
    "score": 8,
    "correct_answers": 4,
    "total_scorable_questions": 5,
    "max_score": 10,
    "matched_ending_id": null,
    "form_mode": "knowledge_quiz"
  }
}

أمثلة الشيفرة البرمجية

bash

curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/responses/667a1b2c3d4e5f6a7b8c9d01" \
  -H "Authorization: Bearer YOUR_API_KEY"

حذف استجابة

DELETE/api/v1/forms/:id/responses/:responseId

يحذف استجابة واحدة بشكل نهائي.

هذا الإجراء لا يمكن التراجع عنه. لا يمكن استرداد بيانات الاستجابة بعد الحذف.

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

idstringمطلوب

معرّف النموذج

responseIdstringمطلوب

معرّف الاستجابة

الاستجابة

json

{
  "success": true
}

أمثلة الشيفرة البرمجية

bash

curl -X DELETE "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/responses/667a1b2c3d4e5f6a7b8c9d01" \
  -H "Authorization: Bearer YOUR_API_KEY"

حذف استجابات متعددة

POST/api/v1/forms/:id/responses/bulk-delete

يحذف عدة استجابات في طلب واحد. الحد الأقصى 100 استجابة لكل طلب. يجب أن تنتمي جميع معرّفات الاستجابات المحددة إلى النموذج المعني.

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

idstringمطلوب

معرّف النموذج

جسم الطلب

response_idsarray of stringsمطلوب

معرّفات الاستجابات المراد حذفها (الحد الأقصى 100)

مثال الطلب

json

{
  "response_ids": [
    "667a1b2c3d4e5f6a7b8c9d01",
    "667a1b2c3d4e5f6a7b8c9d02",
    "667a1b2c3d4e5f6a7b8c9d03"
  ]
}

الاستجابة

json

{
  "deleted": 3
}

أمثلة الشيفرة البرمجية

bash

curl -X POST "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/responses/bulk-delete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "response_ids": [
      "667a1b2c3d4e5f6a7b8c9d01",
      "667a1b2c3d4e5f6a7b8c9d02"
    ]
  }'

تصدير الاستجابات (CSV)

GET/api/v1/forms/:id/responses/export

يُصدّر جميع الاستجابات لنموذج معين كملف CSV. يتضمن ملف CSV أعمدة لـ responseId وsubmittedAt وcompletedAt وعمود واحد لكل سؤال (باستخدام عنوان السؤال كرأس العمود).

بالنسبة لأسئلة المجموعات (question_group، multi_question_page، contact_info، address)، يحصل كل حقل فرعي على عمود خاص به.

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

idstringمطلوب

معرّف النموذج

الاستجابة

يُرجع ملف CSV بنوع المحتوى Content-Type: text/csv.

text

responseId,submittedAt,completedAt,What is your name?,How did you hear about us?,How would you rate your overall experience?
667a1b2c3d4e5f6a7b8c9d01,2026-02-27T15:42:00.000Z,2026-02-27T15:45:30.000Z,Jane Smith,Social media,5
667a1b2c3d4e5f6a7b8c9d02,2026-02-26T10:15:00.000Z,2026-02-26T10:18:22.000Z,Bob Johnson,Search engine,4
667a1b2c3d4e5f6a7b8c9d03,2026-02-25T08:30:00.000Z,,Alex Chen,Friend or colleague,

أمثلة الشيفرة البرمجية

bash

curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/responses/export" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o responses.csv

استجابات الأخطاء

تُرجع جميع نقاط النهاية استجابات أخطاء قياسية:

رموز الحالة

400Bad Request

معاملات غير صالحة، الحذف المتعدد يتجاوز 100 عنصر

401Unauthorized

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

403Forbidden

صلاحيات الفريق غير كافية

404Not Found

النموذج أو الاستجابة غير موجود

500Internal Server Error

خطأ داخلي في الخادم

مثال خطأ

json

{
  "error": "Response not found"
}

آخر تحديث: 6 أبريل 2026