واجهة برمجة النماذج

إنشاء واسترجاع وتحديث وحذف ونشر وتكرار النماذج.

تتيح لك واجهة برمجة النماذج إدارة نماذج NueForm برمجياً. يمكنك عرض وإنشاء واسترجاع وتحديث وحذف ونشر وإلغاء نشر وتكرار النماذج.

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

Endpoints

GET/api/v1/formsPOST/api/v1/formsGET/api/v1/forms/:idPUT/api/v1/forms/:idDELETE/api/v1/forms/:idPOST/api/v1/forms/:id/publishDELETE/api/v1/forms/:id/publishPOST/api/v1/forms/:id/duplicate

عرض النماذج

GET/api/v1/forms

يُرجع قائمة مُقسّمة لصفحات من النماذج التي يملك المستخدم المُصادَق عليه حق الوصول إليها، بما في ذلك النماذج الشخصية والنماذج من الفرق التي ينتمي إليها المستخدم.

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

pageinteger

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

per_pageinteger

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

searchstring

تصفية النماذج حسب العنوان (مطابقة جزئية غير حساسة لحالة الأحرف)

team_idstring

إرجاع النماذج التابعة لهذا الفريق فقط

publishedboolean

التصفية حسب حالة النشر (true أو false)

الاستجابة

json

{
  "forms": [
    {
      "id": "665a1b2c3d4e5f6a7b8c9d0e",
      "title": "Customer Feedback Survey",
      "description": "Quarterly satisfaction survey for Q1 2026",
      "slug": "a1b2c3d4e5f6",
      "published": true,
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-02-20T14:22:00.000Z",
      "theme_color": "#6366f1",
      "background_color": "#0a0a0a",
      "response_count": 142,
      "team": {
        "id": "665b2c3d4e5f6a7b8c9d0e1f",
        "name": "Marketing"
      }
    }
  ],
  "total": 24,
  "page": 1,
  "per_page": 50
}

أمثلة على الكود

bash

curl -X GET "https://api.nueform.io/api/v1/forms?page=1&per_page=10&published=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

إنشاء نموذج

POST/api/v1/forms

يُنشئ نموذجاً جديداً. يمكنك اختيارياً تضمين مصفوفة من الأسئلة لإنشائها مع النموذج.

هيكل الطلب

titlestring

عنوان النموذج (لا يمكن أن يكون فارغاً)

descriptionstring

وصف النموذج

team_idstring

تعيين النموذج لفريق (يتطلب صلاحية create_forms)

publishedboolean

ما إذا كان النموذج منشوراً (افتراضي: false)

theme_colorstring

لون القالب الرئيسي (hex، افتراضي: #6366f1)

background_colorstring

لون الخلفية (hex، افتراضي: #0a0a0a)

text_colorstring

لون نص السؤال (hex)

answer_text_colorstring

لون نص الإجابة (hex)

placeholder_colorstring

لون النص التوضيحي (hex)

button_colorstring

لون خلفية الزر (hex)

button_text_colorstring

لون نص الزر (hex)

title_colorstring

لون نص العنوان (hex)

description_colorstring

لون نص الوصف (hex)

option_text_colorstring

لون نص خيارات الاختيار (hex)

indicator_bg_colorstring

لون خلفية مؤشر الخطوة (hex)

indicator_text_colorstring

لون نص مؤشر الخطوة (hex)

font_familystring

عائلة خط السؤال

font_family_answerstring

عائلة خط الإجابة

font_family_buttonstring

عائلة خط الزر

font_family_descriptionstring

عائلة خط الوصف

font_family_optionstring

عائلة خط خيارات الاختيار

font_family_indicatorstring

عائلة خط مؤشر الخطوة

question_font_sizestring

حجم خط السؤال (مثل: "24px")

custom_cssstring

CSS مخصص يُحقن في عارض النموذج

show_progress_barboolean

عرض شريط التقدم (افتراضي: true)

branding_logo_urlstring

رابط شعار العلامة التجارية

branding_footer_textstring

نص التذييل المخصص

hide_brandingboolean

إخفاء علامة NueForm التجارية (افتراضي: false)

top_logo_urlstring

رابط الشعار المعروض في أعلى النموذج

top_logo_sizestring

حجم الشعار العلوي (مثل: "120px")

top_logo_alignmentstring

محاذاة الشعار العلوي ("left" أو "center" أو "right")

top_logo_cssstring

CSS مخصص للشعار العلوي

watermark_cssstring

CSS مخصص للعلامة المائية

welcome_titlestring

عنوان شاشة الترحيب

welcome_descriptionstring

وصف شاشة الترحيب

welcome_button_textstring

نص زر شاشة الترحيب (افتراضي: "Start")

thank_you_titlestring

عنوان شاشة الشكر (افتراضي: "Thank you!")

thank_you_descriptionstring

وصف شاشة الشكر

modestring

وضع النموذج: "standard" أو "knowledge_quiz" أو "lead_qualification" أو "match_quiz" (افتراضي: "standard")

quiz_settingsobject

إعدادات الاختبار (لأوضاع الاختبار)

variablesobject

متغيرات على مستوى النموذج للمنطق

start_logic_jumpsarray

قواعد القفز المنطقي المُطبَّقة عند بدء النموذج

webhook_urlstring

رابط لاستقبال POST عند الإرسال (يتطلب خطة Pro)

limit_one_responseboolean

تقييد استجابة واحدة لكل زائر (افتراضي: false)

incremental_submissionboolean

حفظ الإجابات تدريجياً أثناء تقدم المستجيب (افتراضي: false)

questionsarray

مصفوفة كائنات الأسئلة لإنشائها (انظر أدناه)

مثال على الطلب

json

{
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "show_progress_bar": true,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "questions": [
    {
      "type": "short_text",
      "title": "What is your name?",
      "required": true
    },
    {
      "type": "multiple_choice",
      "title": "How did you hear about us?",
      "required": true,
      "properties": {
        "choices": [
          { "label": "Search engine" },
          { "label": "Social media" },
          { "label": "Friend or colleague" },
          { "label": "Other" }
        ],
        "allow_multiple": false
      }
    },
    {
      "type": "rating",
      "title": "How would you rate your overall experience?",
      "required": true,
      "properties": {
        "steps": 5,
        "shape": "star"
      }
    }
  ]
}

الاستجابة

يُرجع كائن النموذج المُنشأ مع جميع الأسئلة:

json

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "slug": "a1b2c3d4e5f6",
  "published": false,
  "created_at": "2026-02-28T12:00:00.000Z",
  "updated_at": "2026-02-28T12:00:00.000Z",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "show_progress_bar": true,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your name?",
      "description": null,
      "required": true,
      "order": 0,
      "properties": {},
      "logic_jumps": [],
      "validations": {}
    },
    {
      "id": "66a1b2c3d4e5f6a7b8c9d002",
      "type": "multiple_choice",
      "title": "How did you hear about us?",
      "description": null,
      "required": true,
      "order": 1,
      "properties": {
        "choices": [
          { "label": "Search engine" },
          { "label": "Social media" },
          { "label": "Friend or colleague" },
          { "label": "Other" }
        ],
        "allow_multiple": false
      },
      "logic_jumps": [],
      "validations": {}
    },
    {
      "id": "66a1b2c3d4e5f6a7b8c9d003",
      "type": "rating",
      "title": "How would you rate your overall experience?",
      "description": null,
      "required": true,
      "order": 2,
      "properties": {
        "steps": 5,
        "shape": "star"
      },
      "logic_jumps": [],
      "validations": {}
    }
  ]
}

أمثلة على الكود

bash

curl -X POST "https://api.nueform.io/api/v1/forms" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customer Feedback Survey",
    "description": "Help us improve our product",
    "questions": [
      {
        "type": "short_text",
        "title": "What is your name?",
        "required": true
      }
    ]
  }'

الحصول على نموذج

GET/api/v1/forms/:id

يسترجع نموذجاً واحداً بواسطة المعرّف، بما في ذلك جميع الأسئلة مُرتَّبة حسب موقعها.

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

idstring

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

الاستجابة

json

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "slug": "a1b2c3d4e5f6",
  "published": true,
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-02-20T14:22:00.000Z",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "text_color": null,
  "answer_text_color": null,
  "placeholder_color": null,
  "button_color": null,
  "button_text_color": null,
  "font_family": null,
  "question_font_size": null,
  "custom_css": null,
  "show_progress_bar": true,
  "incremental_submission": false,
  "limit_one_response": false,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "branding_logo_url": null,
  "branding_footer_text": null,
  "hide_branding": false,
  "mode": "standard",
  "webhook_url": null,
  "has_unpublished_changes": false,
  "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
  "response_count": 142,
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your name?",
      "description": null,
      "required": true,
      "order": 0,
      "properties": {},
      "logic_jumps": [],
      "validations": {}
    }
  ]
}

أمثلة على الكود

bash

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

تحديث نموذج

PUT/api/v1/forms/:id

يُحدّث حقول النموذج ويُزامن أسئلته. عند تضمين مصفوفة questions، سيقوم NueForm بما يلي:

تحديث الأسئلة الموجودة (المُطابَقة بواسطة id)
إنشاء أسئلة جديدة (بدون id أو id غير معروف)
حذف الأسئلة الموجودة في النموذج ولكن غير موجودة في المصفوفة

إذا كان النموذج منشوراً حالياً، يتم تعيين علامة has_unpublished_changes تلقائياً إلى true.

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

idstring

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

هيكل الطلب

يقبل جميع الحقول من إنشاء نموذج باستثناء team_id. قم بتضمين الحقول التي تريد تغييرها فقط.

مثال على الطلب

json

{
  "title": "Updated Survey Title",
  "description": "Revised description for Q2",
  "theme_color": "#10b981",
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your full name?",
      "required": true
    },
    {
      "type": "long_text",
      "title": "Any additional comments?",
      "required": false
    }
  ]
}

الاستجابة

يُرجع كائن النموذج المُحدَّث مع جميع الأسئلة (نفس مخطط الحصول على نموذج).

أمثلة على الكود

bash

curl -X PUT "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Survey Title",
    "theme_color": "#10b981"
  }'

حذف نموذج

DELETE/api/v1/forms/:id

يحذف نموذجاً نهائياً مع جميع البيانات المرتبطة به، بما في ذلك الأسئلة والاستجابات والإصدارات وإدخالات سجل التغييرات. يتم تنظيف الملفات المرفوعة المرتبطة بشكل غير متزامن.

هذا الإجراء لا يمكن التراجع عنه. سيتم حذف جميع الاستجابات المُجمَّعة لهذا النموذج نهائياً.

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

idstring

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

الاستجابة

json

{
  "success": true
}

أمثلة على الكود

bash

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

نشر نموذج

POST/api/v1/forms/:id/publish

ينشر نموذجاً عن طريق إنشاء لقطة مُرقَّمة للنموذج الحالي وأسئلته. كل عملية نشر تزيد رقم الإصدار. يصبح النموذج متاحاً للعامة عبر رابطه القابل للمشاركة.

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

idstring

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

الاستجابة

يُرجع كائن النموذج مع حقل published_version يشير إلى رقم الإصدار الجديد:

json

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "slug": "a1b2c3d4e5f6",
  "published": true,
  "has_unpublished_changes": false,
  "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
  "published_version": 3,
  "questions": [ ... ]
}

أمثلة على الكود

bash

curl -X POST "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/publish" \
  -H "Authorization: Bearer YOUR_API_KEY"

إلغاء نشر نموذج

DELETE/api/v1/forms/:id/publish

يُلغي نشر نموذج، مما يجعله غير متاح عبر رابطه العام. يتم الاحتفاظ بلقطة الإصدار المنشور بحيث يمكنك إعادة النشر لاحقاً.

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

idstring

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

الاستجابة

يُرجع كائن النموذج المُحدَّث مع تعيين published إلى false.

json

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "published": false,
  "questions": [ ... ]
}

أمثلة على الكود

bash

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

تكرار نموذج

POST/api/v1/forms/:id/duplicate

يُنشئ نسخة من نموذج موجود، بما في ذلك جميع الأسئلة. يتم إعادة تعيين مراجع القفز المنطقي تلقائياً إلى معرّفات الأسئلة الجديدة. يتم إنشاء النموذج المُكرَّر دائماً في حالة غير منشورة.

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

idstring

معرّف النموذج المراد تكراره

هيكل الطلب

titlestring

عنوان النموذج الجديد (افتراضي: "العنوان الأصلي (نسخة)")

team_idstring

تعيين النسخة المُكرَّرة لفريق مختلف

مثال على الطلب

json

{
  "title": "Customer Feedback Survey v2",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f"
}

الاستجابة

يُرجع كائن النموذج المُنشأ حديثاً (نفس مخطط الحصول على نموذج) مع تعيين published إلى false.

أمثلة على الكود

bash

curl -X POST "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/duplicate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Customer Feedback Survey v2" }'

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

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

رموز الأخطاء

400Bad Request

خطأ في التحقق أو حقل مطلوب مفقود

401Unauthorized

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

403Forbidden

صلاحيات غير كافية لنماذج الفريق

404Not Found

النموذج غير موجود

500Server Error

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

مثال على خطأ

json

{
  "error": "Title is required"
}

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