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


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

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

![منطقة التكاملات وإعدادات المطوّرين](/img/screenshots/survey/integrations.png)
*منطقة المطوّرين هي حيث تدير مفاتيح API وخطافات الويب والتكاملات.*

## مفاتيح API

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

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

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

```bash
curl -X POST https://surveyapi.imatic.ai/forms/list \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

:::tip[أبقِ المفاتيح سرّية]

تعامل مع مفتاح 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](#مفاتيح-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`** — قراءة الإحصاءات المباشرة للاستطلاع.

:::info[بيانا اعتماد مختلفان]

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

:::

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

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

- **Gmail**
- **Resend**
- **SendGrid**
- **Postmark**
- **Amazon SES**
- **SMTP مخصص**

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

- [انشر نموذجًا وشاركه](./publishing-sharing)
- [اعرض الاستجابات](./responses)
- [افتح التحليلات](./analytics)
- [أنشئ نموذجًا بالذكاء الاصطناعي](./ai-generation)