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

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

الفئة	شكل المسار	من يستدعيها	المصادقة
الإدارة	`/api/v2/accounts/{accountId}/forms/...`	خادمك	مفتاح API محدود النطاق
المستجيب	`/api/v2/forms/{publicCode}/...`	من يعبّئ النموذج	لا شيء؛ رمز النموذج العام وجلسته

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

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

قبل البدء

النماذج ميزة مرتبطة بالخطة. إذا لم تكن مفعّلة للحساب، تُجيب كل نقاط نهاية الإدارة بالرمز 402 مع {"code": "plan_disabled", "feature": "forms"} وليس 403. اطلب من فريق HueChat تفعيل Forms & Surveys على الخطة قبل التكامل.

أنشئ مفتاح API محدود النطاق من الحساب ← واجهة المطور بأقل الصلاحيات اللازمة. يبقى إنشاء المفتاح وتدويره وإلغاؤه داخل التطبيق الموثق:

النطاق	استخدامه
`forms:read`	عرض النماذج وقراءة التعريف والنسخ والملفات
`forms:write`	الإنشاء والتعديل والنشر والإغلاق والأرشفة والاستعادة وتدوير الرابط العام ورفع الملفات وإدارة الدعوات
`contacts:read`	مطلوب مع `forms:write` لإصدار دعوة لجهة اتصال
`reports:read`	مطلوب مع `forms:read` للتقارير والردود وتقارير الدعوات وتصدير CSV
`ai_agents:write`	مطلوب مع `forms:write` لتوليد نموذج عبر وكيل ذكاء اصطناعي

دورة الحياة

يكون النموذج دائمًا في إحدى أربع حالات، وتنقله الواجهة بينها:

مسودة draft

ينشئه POST /forms. ويعدّل PATCH /forms/{formId} التعريف كما تشاء. لا شيء متاح للعامة بعد.

منشور published

يجمّد POST /forms/{formId}/publish التعريف الحالي كنسخة ثابتة ويعيد الرابط العام. أي تعديل بعد ذلك ينشئ النسخة التالية، وتبقى الردود الجارية على النسخة التي عُرضت لها.

مغلق closed

يوقف POST /forms/{formId}/close استقبال ردود جديدة. يظل الرابط يعمل ويوضح أن النموذج مغلق.

مؤرشف archived

يزيله POST /forms/{formId}/archive من قائمة العمل، ويعيده POST /forms/{formId}/restore. وتبقى الردود محفوظة.

النشر والمشاركة

يعيد POST /forms/{formId}/publish الرمز العام public_code والرابط المبني عليه. ويمكن مشاركة النموذج المنشور بطريقتين:

رابط عام واحد للجميع: https://app.huechat.ai/to/{publicCode}.
دعوة تُصدر لكل مستلم عبر POST /forms/{formId}/invitations.

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

يستطيع أي شخص يملك رابط الدعوة فتحه، وإعادة توجيهه تنقل ذلك الانتساب معه. لا تعتبر الدعوة إثباتًا للهوية عند التعبئة المسبقة الحساسة أو تحديث الملف الشخصي. استخدم POST /forms/{formId}/invitations/{invitationId}/revoke لسحب دعوة، وPOST /forms/{formId}/rotate-link لإبطال كل الروابط القائمة دفعة واحدة.

جمع الرد

يمر عميل المستجيب بالاستدعاءات الثلاثة نفسها التي تستخدمها صفحتك:

# 1. تحميل النموذج المنشور. يعيد التعريف وجلسة موقّعة.
#    أضف ?invite=<token> عند فتح رابط دعوة.
curl https://app.huechat.ai/api/v2/forms/{publicCode}

# 2. تسجيل التقدم اختياريًا. القيم الممكنة لـ type هي
#    viewed و started و question_seen و question_answered و exited.
curl -X POST https://app.huechat.ai/api/v2/forms/{publicCode}/events \
  -H "Content-Type: application/json" \
  -d '{"session_id":"...","type":"question_seen","question_id":"q1"}'

# 3. الإرسال. يعيد الخادم تنفيذ قواعد النموذج قبل القبول.
curl -X POST https://app.huechat.ai/api/v2/forms/{publicCode}/responses \
  -H "Content-Type: application/json" \
  -d '{"session_id":"...","idempotency_key":"مفتاح-تولّده-أنت","answers":{"q1":"نعم"}}'

الحقل idempotency_key مطلوب. إعادة الإرسال بالمفتاح نفسه تعيد النتيجة الأصلية بدل تسجيل رد ثانٍ، فتكون إعادة المحاولة عند انقطاع الشبكة آمنة. الإرسال ليس كتابة عمياء: يعيد الخادم تقييم التفرّع والتقييم في النموذج، فيُرفض أي عميل يتخطى سؤالًا مطلوبًا أو يرسل إجابة لا تسمح بها القواعد. مع الدعوة، مرّر رمزها في ?invite= عند التحميل وفي حقل invite داخل كل طلب. ثم يعيد POST /forms/{publicCode}/prefill الحقول التي وافق الحساب على تعبئتها لتلك الجهة، وهو يتطلب session_id وinvite وopt_in صريحًا.

حدود معدل المستجيب

كل عملية للمستجيب محدودة لكل نموذج ولكل عميل في الدقيقة. والحدود ضيّقة عن قصد لأن هذه النقاط بلا مصادقة:

العملية	في الدقيقة
فتح النموذج	120
تسجيل حدث	240
جلب ملف	240
إرسال رد	60
طلب أوقات الحجز	60
التعبئة المسبقة من دعوة	30
رفع ملف أو رد بالذكاء الاصطناعي	10
حجز موعد	5

يعيد التجاوز الرمز 429. راجع حدود المعدل للإرشادات العامة لإعادة المحاولة.

التقارير

نقطة النهاية	ما تعيده
`GET /forms/{formId}/reports`	ملخص الأداء وتوزيع الأجهزة ووصول الأسئلة ونقاط التسرب
`GET /forms/{formId}/responses`	الردود الفردية مع ترقيم الصفحات
`GET /forms/{formId}/invitations`	دورة حياة الدعوة: صادرة، مفتوحة، مُجاب عنها، مسحوبة
`GET /forms/{formId}/responses/export.csv`	الردود نفسها بصيغة CSV

وكلها تحتاج forms:read و reports:read.

تذكيرات المواعيد

يمكن ربط نموذج منشور بقاعدة تذكير موعد، فيحمل كل تذكير رابطًا خاصًا بذلك المستلم. نقاط نهاية التذكير موجودة في المواعيد، وتظهر حقول النموذج في POST وPUT /appointments/reminders. ولكل إرسال دعوته الخاصة، ويمكن إيقاف التذكير بعد رد المستلم.

الملفات والجدولة

الملفات. يرفع POST /forms/{formId}/assets ملفات الهوية أو وسائط الأسئلة. ويرفع المستجيبون عبر POST /forms/{publicCode}/assets، وتبقى ملفاتهم خاصة بالحساب.
الجدولة. يمكن أن يتضمن النموذج خطوة حجز: يعرض POST /forms/{publicCode}/schedule/slots الأوقات المتاحة، ويحجز POST /forms/{publicCode}/schedule/book أحدها ويعيد إيصالًا موقّعًا.

توليد نموذج بالذكاء الاصطناعي

يصوغ POST /forms/ai/generate نموذجًا من وصف نصي، ويعرض GET /forms/ai/generation-usage الرصيد الشهري. التوليد محدود لكل حساب شهريًا، وتخبرك نقطة الاستخدام بما تبقّى قبل استهلاك محاولة. ويصل النموذج المولَّد دائمًا كـ مسودة ليراجعه إنسان وينشره.

ابدأ هنا

العمل مع الواجهة

التكامل

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

قبل البدء

دورة الحياة

النشر والمشاركة

جمع الرد

حدود معدل المستجيب

التقارير

تذكيرات المواعيد

الملفات والجدولة

توليد نموذج بالذكاء الاصطناعي

​قبل البدء

​دورة الحياة

​النشر والمشاركة

​جمع الرد

​حدود معدل المستجيب

​التقارير

​تذكيرات المواعيد

​الملفات والجدولة

​توليد نموذج بالذكاء الاصطناعي

قبل البدء

دورة الحياة

النشر والمشاركة

جمع الرد

حدود معدل المستجيب

التقارير

تذكيرات المواعيد

الملفات والجدولة

توليد نموذج بالذكاء الاصطناعي