> ## Documentation Index
> Fetch the complete documentation index at: https://developers.huechat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> إنشاء نماذج أصلية ونشرها كروابط عامة أو بدعوة خاصة، وجمع الردود من موقعك أو تطبيقك، وقراءة تقارير الأداء والردود والدعوات عبر 29 عملية API للحساب وللمستجيب.

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

تظهر هنا فئتان مختلفتان من نقاط النهاية، والفرق بينهما مهم:

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

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

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

## قبل البدء

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

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

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

## دورة الحياة

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

<Steps>
  <Step title="مسودة draft">
    ينشئه `POST /forms`. ويعدّل `PATCH /forms/{formId}` التعريف كما تشاء. لا
    شيء متاح للعامة بعد.
  </Step>

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

  <Step title="مغلق closed">
    يوقف `POST /forms/{formId}/close` استقبال ردود جديدة. يظل الرابط يعمل
    ويوضح أن النموذج مغلق.
  </Step>

  <Step title="مؤرشف archived">
    يزيله `POST /forms/{formId}/archive` من قائمة العمل، ويعيده
    `POST /forms/{formId}/restore`. وتبقى الردود محفوظة.
  </Step>
</Steps>

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

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

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

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

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

## جمع الرد

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

```bash theme={null}
# 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`. راجع [حدود المعدل](/ar/rate-limits) للإرشادات العامة
لإعادة المحاولة.

## التقارير

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

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

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

يمكن ربط نموذج منشور بقاعدة تذكير موعد، فيحمل كل تذكير رابطًا خاصًا بذلك
المستلم. نقاط نهاية التذكير موجودة في [المواعيد](/ar/appointments)، وتظهر حقول
النموذج في `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` الرصيد الشهري. التوليد محدود لكل حساب شهريًا،
وتخبرك نقطة الاستخدام بما تبقّى قبل استهلاك محاولة. ويصل النموذج المولَّد دائمًا
كـ **مسودة** ليراجعه إنسان وينشره.