NueForm

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

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

تتيح لك واجهة برمجة النماذج إدارة نماذج 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

عيّنه إلى true لنشر النموذج مباشرةً بعد إنشائه. يُجري النشر عمليات التحقق نفسها التي يُجريها نشر نموذج. إذا فشلت إحدى عمليات التحقق، يُنشأ النموذج رغم ذلك كمسودة: تكون الاستجابة 201 مع published: false وكائن publish_error (reason، message، question_ids، upgrade_required). لا تُنشئ النموذج مرة أخرى — أصلح المشكلة ثم استدعِ نشر نموذج. الافتراضي: 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)

auto_translateboolean

NueLingo — ترجمة النموذج المنشور عند الطلب إلى أي لغة مدعومة للمستجيبين (Pro+؛ يُحفظ كـ 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,
  "auto_translate": 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: تُحفظ تغييراتك كمسودة، ويستمر المستجيبون في رؤية النسخة المنشورة حتى تنشر مرة أخرى.

يغيّر published حالة النموذج بدلاً من حفظه كحقل:

  • في نموذج مسودة، يؤدي published: true إلى نشره بعد حفظ تغييراتك، مع عمليات التحقق نفسها التي يُجريها نشر نموذج. إذا فشلت إحدى عمليات التحقق، تُحفظ تغييراتك رغم ذلك وتُرجع الواجهة 409 Conflict مع form_id وsaved_as_draft: true.
  • في نموذج منشور بالفعل، لا يغيّر published: true شيئاً — استدعِ نشر نموذج لنشر تغييراتك.
  • يؤدي published: false إلى إلغاء نشر نموذج منشور، تماماً مثل إلغاء نشر نموذج.

في نماذج الفريق، لا يستطيع تغيير published إلا مسؤولو الفريق ومالكوه.

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

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

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

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

delete_signed_contractsboolean

يجب أن تكون true لحذف نموذج يحتوي على عقود موقّعة مكتملة. تُحذف هذه العقود نهائيًا مع النموذج، بما في ذلك ملفات PDF الموقّعة ومسارات التدقيق. بدونها لا يُحذف النموذج: تردّ الواجهة البرمجية بالرمز 409 مع reason: form_has_signed_contracts وsigned_contracts (عددها).

الاستجابة

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

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

قبل نشر أي شيء، يتحقق NueForm من أن:

  • نماذج الفريق لا ينشرها إلا مسؤولو الفريق ومالكوه، والنماذج الشخصية لا ينشرها إلا مالكها (ويتلقى أي شخص آخر 403 Forbidden، أو 404 Not Found إذا لم يكن عضوًا في فريق النموذج)؛
  • ميزات Pro (أسئلة الحجز، وعقود التوقيع الإلكتروني، وعُقد البيانات، وwebhooks النماذج، والمدفوعات إلى حسابك الخاص على Stripe) مشمولة في خطة مالك النموذج (خطة مالك الفريق في نماذج الفريق)؛
  • أسئلة الحجز وخطوات البريد الإلكتروني وأسئلة Fuse والمركّبات مُعدّة بالكامل.

إذا فشلت أي عملية تحقق، لا يُنشر النموذج وتُرجع الواجهة 409 Conflict مع رمز reason وquestion_ids المطلوب إصلاحها (راجع معالجة الأخطاء). تتضمن الاستجابات الناجحة published_version ومصفوفة warnings بالتنبيهات التي لا تمنع النشر.

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

idstring

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

الاستجابة

يُرجع النموذج المنشور مع published_version (رقم الإصدار الجديد) وwarnings (تنبيهات لا تمنع النشر، وغالباً ما تكون فارغة):

json
{
  "data": {
    "id": "665a1b2c3d4e5f6a7b8c9d0e",
    "title": "Customer Feedback Survey",
    "slug": "a1b2c3d4e5f6",
    "published": true,
    "has_unpublished_changes": false,
    "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
    "published_version": 3,
    "warnings": [
      {
        "code": "booking_attendee_ask",
        "question_id": "66a1b2c3d4e5f6a7b8c9d004",
        "question_title": "Book a demo",
        "message": "Booking question \"Book a demo\" has no attendee email mapping, so respondents will be asked for their email when they book."
      }
    ],
    "questions": [ ... ]
  }
}

حظر النشر (409)

لا يُنشر أي شيء. يوضّح reason عملية التحقق التي فشلت، وتسرد question_ids الأسئلة المطلوب إصلاحها؛ وتكون upgrade_required مساوية لـ true عندما تحتاج خطة مالك النموذج إلى ترقية:

json
{
  "error": {
    "code": "CONFLICT",
    "message": "E-signature contracts need a Pro plan to go live. Upgrade to publish this form, or remove the contract question.",
    "status": 409,
    "reason": "contract_requires_pro",
    "question_ids": ["66a1b2c3d4e5f6a7b8c9d001"],
    "upgrade_required": true
  }
}

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

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

يُلغي نشر نموذج، مما يجعله غير متاح عبر رابطه العام. يتم الاحتفاظ بلقطة الإصدار المنشور بحيث يمكنك إعادة النشر لاحقاً. لا يستطيع إلغاء نشر نماذج الفريق إلا مسؤولو الفريق ومالكوه، ولا يستطيع إلغاء نشر النماذج الشخصية إلا مالكها؛ ويتلقى أي شخص آخر 403 Forbidden، أو 404 Not Found إذا لم يكن عضوًا في فريق النموذج.

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

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

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

409Conflict

حظر النشر: فشلت إحدى عمليات التحقق من النشر (راجع نشر نموذج)

500Server Error

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

مثال على خطأ

json
{
  "error": "Title is required"
}
آخر تحديث: 8 أكتوبر 2026