إرسال النماذج — مركز المساعدة

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

قبل أن تبدأ

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

العنوان

POST https://rutbacrm.com/intake/FORM_KEY

العنوان نفسه مع GET يعرض صفحة النموذج المستضافة. أضف ?lang=ar أو ?lang=en أو ?lang=tr أو ?lang=fr لتختار لغة الصفحة ورسائل أخطائها. ولا يمكن عرض الصفحة المستضافة داخل iframe في موقع آخر.

يقبل العنوان إرسال النموذج العادي (application/x-www-form-urlencoded أو multipart/form-data) ويقبل JSON. ولا يحتاج رمز CSRF ولا مفتاح API.

الحقول

الحقل	مطلوب	القواعد
`name`	نعم	حتى 160 حرفًا
`email`	أحدهما	عنوان صالح حتى 254 حرفًا
`phone`	أحدهما	من 6 إلى 15 رقمًا مع `+` اختيارية، بعد إزالة المسافات والشرطات والأقواس. وتُقبل الأرقام العربية، وتصبح `00` في البداية `+`
`message`	لا	حتى 2000 حرف، وتُحفظ ملاحظة على الجهة
`consent`	نعم	يجب قبوله: `1` أو `yes` أو `on` أو `true`
`page`	لا	الصفحة التي كان فيها الزائر، حتى 500 حرف
`utm_source` و`utm_medium` و`utm_campaign`	لا	حتى 100 حرف لكل منها
`crm_trap`	لا يُملأ أبدًا	مصيدة الرسائل المزعجة. أبقه في نموذجك مخفيًا عن الناس
`crm_vid`	لا	معرف الزائر من سكربت التتبع، ويربط الزيارات بالجهة الجديدة. يضيفه السكربت تلقائيًا

وإن حمل page وسوم حملة في عنوانه، مثل ?utm_campaign=ramadan-sale، ولم ترسل الوسوم منفصلة، فإنها تُقرأ منه.

الحقل المسمى website حقل عادي ولم يعد يوقف الاستفسار. والكود المنسوخ من كود لموقعك قبل تغيير اسم المصيدة فيه حقل website مخفي: ما زال يوصل الاستفسارات لكنه لم يعد يمنع السبام، فانسخ الكود من جديد.

أسماء الحقول من إضافات النماذج

يمكنك الإبقاء على أسماء الحقول التي تستخدمها إضافة النماذج لديك. هذه الأسماء مفهومة دون اعتبار لحالة الأحرف:

الحقل	يُقبل أيضًا
`name`	`full_name` و`fullname` و`your-name` و`your_name` و`first_name` و`الاسم` و`الاسم الكامل` و`اسمك` و`ad` و`ad soyad` و`nom` و`nom complet`
`email`	`e-mail` و`your-email` و`your_email` و`email_address` و`البريد` و`البريد الإلكتروني` و`الايميل` و`الإيميل` و`e-posta` و`courriel`
`phone`	`tel` و`mobile` و`your-phone` و`your-tel` و`your_phone` و`phone_number` و`whatsapp` و`الجوال` و`رقم الجوال` و`الهاتف` و`رقم الهاتف` و`واتساب` و`telefon` و`téléphone`
`message`	`your-message` و`your_message` و`comments` و`comment` و`details` و`الرسالة` و`رسالتك` و`التفاصيل` و`mesaj` و`votre message`
`consent`	أي حقل ممتلئ يبدأ اسمه بـ`consent` أو `acceptance` أو `agree` أو `privacy` أو `gdpr` أو `الموافقة` أو `أوافق` أو `onay` أو `accord`
`page`	`page_url` و`referer` و`referrer`، مكتوبة هكذا بالأحرف الصغيرة تمامًا

وتُقرأ أيضًا بيانات الإضافات المتداخلة: الحقول تحت fields أو form_fields بمعرفها أو عنوانها، مع raw_value أو value، وعنوان الصفحة تحت meta. ويُقرأ حتى 50 حقلًا متداخلًا.

إرسال استفسار من خادم

curl -X POST https://rutbacrm.com/intake/FORM_KEY \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "Layla Hassan", "email": "layla@example.com", "phone": "+966500000003", "message": "Do you ship to Jeddah?", "consent": "1", "page": "https://shop.example.com/contact?utm_source=google&utm_campaign=ramadan-sale"}'

أرسل Accept: application/json لتصلك الردود بصيغة JSON. ومن دونها يجيب العنوان بصفحة الشكر المستضافة أو بالنموذج مع أخطائه، وهذا ما يحتاجه نموذج HTML عادي.

الخادم، أو إضافة النماذج على خادم موقعك، يرسل كل الاستفسارات من عنوان واحد. اكتب عنوان IP العام لهذا الخادم في خانة عنوان خادم موقعك (اختياري) في النموذج واضغط حفظ العنوان، حتى لا يوقفه حد العنوان الواحد في الساعة المذكور أدناه. ولا يُقبل إلا عنوان IPv4 أو IPv6 عام.

الردود

الحالة	جسم JSON	المعنى
`200`	`{"status": "received"}`	قُبل الاستفسار
`422`	`{"errors": {"consent": ["Please agree before sending."]}}`	حقل مفقود أو غير صالح، ولكل مفتاح رسائله
`404`		المفتاح خاطئ أو استُبدل، أو النموذج موقوف، أو الشركة موقوفة، أو الباقة لا تشمل نماذج المواقع
`429`		استفسارات كثيرة، راجع الحدود أدناه

الرد هو 200 نفسه سواء كان الشخص جديدًا أو معروفًا، فلا يستطيع الزائر أن يستخدم النموذج ليعرف هل بريد ما مسجل.

ما يحدث للاستفسار

يُطابَق الاستفسار مع الجهات النشطة بالبريد أو الهاتف، ولا يُكتب فوق البيانات الموجودة أبدًا:

الحالة	النتيجة	تظهر باسم
لا مطابقة	جهة جديدة (مصدرها الموقع، وحالتها عميل محتمل) وفرصة جديدة في مرحلة النموذج. ويطلق وصول عميل محتمل جديد	عميل محتمل جديد
مطابقة دون فرصة مفتوحة في مسار النموذج	فرصة جديدة للجهة الموجودة	جهة معروفة وفرصة جديدة
مطابقة مع فرصة مفتوحة في ذلك المسار	لا فرصة جديدة، والملاحظة فقط	استفسار متكرر

تُسمى الفرصة باسم النموذج والشخص، وتُسند إلى الشخص المختار في إسناد الفرص الجديدة إلى، وإلا فإلى مسؤول الجهة. وتصبح الرسالة ملاحظة. ويُحفظ مع الاستفسار وقت الموافقة والصفحة ووسوم الحملة. ولا يُحفظ عنوان IP للزائر.

الحدود

الحد	القيمة	عند تجاوزه
الإرسال من عنوان واحد	10 في الدقيقة	`429`
الاستفسارات من عنوان واحد إلى نموذج واحد	30 في الساعة، إلا من عنوان الخادم المحفوظ في النموذج	`429`
كل الاستفسارات إلى نموذج واحد	120 في الساعة	`429`
الاستفسارات عن البريد أو الهاتف نفسه إلى نموذج واحد	5 في الساعة	يُجاب بـ`200` ولا يُحفظ شيء
حقل `crm_trap` ممتلئ		يُجاب بـ`200` ولا يُحفظ شيء

معلومات مفيدة

لا توجد ترويسات CORS. فسكربت المتصفح في موقع آخر لا يستطيع قراءة الرد، وإرسال JSON من المتصفح يُمنع قبل أن يخرج. من صفحة الويب استخدم إرسال النموذج العادي، واستخدم JSON من الخوادم.
زر استبدال الرابط يعطي النموذج مفتاحًا جديدًا فورًا، ويرد العنوان القديم 404 منذ ذلك الحين، فحدّث موقعك فورًا.
الملفات المرفوعة لا تُحفظ، والحقول غير المذكورة أعلاه تُتجاهل.

حل المشكلات

المشكلة	ما تتحقق منه
`422` في `consent`	ليس في نموذجك حقل موافقة، أو اسمه لا يطابق. سمّه `consent` وأرسل `1` عند التأشير
`422` في `email` و`phone`	لم يُرسل بريد صالح ولا هاتف. قارن أسماء الحقول بجدول الأسماء البديلة
`404`	انسخ العنوان مجددًا من نماذج الموقع، فقد يكون الرابط استُبدل أو النموذج أُوقف
ينجح الإرسال ولا يظهر شيء	امتلأ حقل `crm_trap` المخفي، وكثيرًا ما يكون ذلك من الملء التلقائي في المتصفح، أو أرسل الشخص نفسه أكثر من 5 استفسارات في ساعة