إنتقل إلى المحتوى الرئيسي

واجهة برمجة تطبيقات Survey وMCP

يتصل imatic Survey ببقية حزمتك التقنية — دافعًا الاستجابات إلى أنظمتك الخاصة، وأتمتة عمل النماذج، والسماح لوكلاء الذكاء الاصطناعي بالعمل مع نماذجك. تغطّي هذه الصفحة سطح المطوّرين: مفاتيح API، وخطافات الويب، وREST API، وخادم MCP، وتسليم البريد الإلكتروني. هذه الميزات فعّالة اليوم.

منطقة التكاملات وإعدادات المطوّرين منطقة المطوّرين هي حيث تدير مفاتيح API وخطافات الويب والتكاملات.

مفاتيح API​

تصادق مفاتيح API تطبيقاتك وبرامجك النصية الخاصة مقابل REST API الخاصة بـ Survey. أنشئها وأدِرها ضمن /developers/api-keys، حيث يمكنك إصدار مفتاح، وإعطاؤه اسمًا، ورؤية إحصاءات استخدامه، وإبطاله إذا تعرّض للكشف يومًا ما.

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

تُستضاف واجهة API على https://surveyapi.imatic.ai، والمفاتيح مسبوقة بـ sk_. أرسل مفتاحك كرمز حامل (Bearer). نقاط النهاية هي طلبات POST بأفعال مخصّصة — على سبيل المثال، لسرد نماذجك:

curl -X POST https://surveyapi.imatic.ai/forms/list \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
أبقِ المفاتيح سرّية

تعامل مع مفتاح API كأنه كلمة مرور. لا تودِعه في إدارة المصدر، وأعد تدويره إذا اشتبهت في تسرّبه.

خطافات الويب​

تدفع خطافات الويب الأحداث إلى رابط تتحكم فيه، فتتفاعل أنظمتك لحظة حدوث شيء بدلًا من الاستقصاء عن التغييرات. هيّئها ضمن /developers/webhooks.

الأحداث المتاحة:

  • response.created — تُطلَق عند إرسال استجابة جديدة.
  • response.flagged (مُخطَّط له — لم يُطلَق بعد) — عند وضع علامة على استجابة (على سبيل المثال، عبر فحوص الاحتيال أو البريد العشوائي).
  • response.updated (مُخطَّط له — لم يُطلَق بعد) — عند تحديث استجابة أو الإشراف عليها.
  • form.published (مُخطَّط له — لم يُطلَق بعد) — عند نشر نموذج.
  • form.closed (مُخطَّط له — لم يُطلَق بعد) — عند إغلاق نموذج.

يُوقَّع كل تسليم بتوقيع HMAC-SHA256 (مُرسَل في الترويسة X-Signature، إلى جانب X-Timestamp وX-Event-Id وX-Event-Type) حتى تتمكن نقطة النهاية لديك من التحقق من أن الطلب جاء فعلًا من imatic Survey ولم يُعبَث به أثناء النقل. تُعاد عمليات التسليم الفاشلة بتراجع أسّي قبل وضع علامة عليها كفاشلة.

REST API​

تتيح لك REST API إدارة النماذج والاستجابات برمجيًا. تستخدم نقاط النهاية طلبات POST بأفعال مخصّصة بدلًا من بادئة مسار مُصدَّرة الإصدار — على سبيل المثال، POST /forms/list (سرد النماذج)، وPOST /forms/get-for-edit (قراءة مخطط نموذج)، وPOST /forms/generate (توليد نموذج بالذكاء الاصطناعي)، وPOST /forms/duplicate، وPOST /forms/delete. تُستضاف على https://surveyapi.imatic.ai وتُصادَق بـمفتاح API — رمز حامل مسبوق بـ sk_.

خادم MCP لوكلاء الذكاء الاصطناعي​

يكشف خادم MCP عن Survey لوكلاء الذكاء الاصطناعي عبر بروتوكول سياق النموذج، حتى يتمكن مساعد من العمل مع نماذجك واستجاباتك نيابةً عنك. يتحدث JSON-RPC 2.0 عبر POST /mcp ويُصادَق بـJWT الخاص بالبوابة (مُرسَلًا كرمز حامل)، الذي يحصر كل استدعاء في مؤسستك.

يأتي مزوّدًا بـ10 أدوات:

  • whoami — إرجاع سياق المؤسسة المُصادَق عليه.
  • list_forms — سرد نماذجك المنشورة.
  • get_form — قراءة مخطط نموذج وحقوله.
  • submit_response — إرسال استجابة لنموذج.
  • list_responses — سرد الاستجابات (مرقّمة الصفحات).
  • get_response — قراءة استجابة واحدة.
  • get_response_stats — قراءة إحصاءات الاستجابات المجمّعة.
  • create_poll — إنشاء ونشر استطلاع بسؤال واحد.
  • cast_vote — الإدلاء بصوت على استطلاع.
  • live_poll_results — قراءة الإحصاءات المباشرة للاستطلاع.
بيانا اعتماد مختلفان

يستخدم خادم MCP وخطافات الويب JWT الخاص بالبوابة (محصور بالمؤسسة). تستخدم REST API مفتاح API تنشئه ضمن /developers/api-keys. اختر بيانات الاعتماد الصحيحة للسطح الذي تستدعيه.

تسليم البريد الإلكتروني​

يُهيّأ تسليم البريد الإلكتروني (على سبيل المثال، إشعارات الاستجابات) ضمن /settings في علامة تبويب تسليم البريد الإلكتروني. يمكنك ربط أي من ستة مزوّدين:

  • Gmail
  • Resend
  • SendGrid
  • Postmark
  • Amazon SES
  • SMTP مخصص

الخطوات التالية​