اتصالات API
اربط واجهات API الخارجية الخاصة بك بـ enuchat حتى يتمكّن الذكاء الاصطناعي والقواعد من جلب بيانات حيّة من أنظمتك.
كيف تعمل
تتيح لك اتصالات API دمج enuchat مع أنظمة الخلفية الخاصة بك — محرّكات الحجز وCRMs وإدارة الطلبات والمخزون والمزيد. عندما يسأل زائر سؤالاً، يمكن لـ enuchat استدعاء API الخاص بك للحصول على بيانات حقيقية وإدراجها في الاستجابة.
التدفّق
- تكوين اتصال — عنوان URL الأساسي لـ API الخاص بك والمصادقة
- إضافة نقاط نهاية — استدعاءات API محدّدة مع قوالب المسار وربط الاستجابة
- إنشاء قاعدة — قاعدة ذكاء اصطناعي أو ثابتة مع إجراء CALL_API
- يسأل الزائر سؤالاً — تُطلق القاعدة وتستدعي API الخاص بك وتربط الاستجابة بمتغيّرات الجلسة
- يستجيب الذكاء الاصطناعي ببيانات حقيقية — متغيّرات الجلسة متاحة للذكاء الاصطناعي لتوليد إجابة دقيقة
مثال: توفّر غرفة فندق
الزائر: "هل الغرفة 205 متاحة الأسبوع القادم؟"
تُطابق قاعدة الذكاء الاصطناعي: "عندما يسأل الزائر عن توفّر الغرفة"
إجراء CALL_API: GET https://api.hotel.com/rooms/205/availability
الاستجابة المربوطة: room_available = true، price = "120 يورو/ليلة"
يستجيب الذكاء الاصطناعي: "الغرفة 205 متاحة الأسبوع القادم بسعر 120 يورو/ليلة. هل ترغب في حجزها؟"
إعداد اتصال
اذهب إلى الإعدادات → اتصالات API في لوحة التحكّم.
1. إنشاء اتصال
يمثّل الاتصال واجهة API خارجية واحدة. تحتاج إلى:
| الحقل | الوصف | مثال |
|---|---|---|
| الاسم | تسمية لهذا الاتصال | Hotel Booking API |
| عنوان URL الأساسي | عنوان URL الجذري لـ API | https://api.hotel.com/v1 |
| نوع المصادقة | كيفية المصادقة | Bearer Token، OAuth2، وما إلى ذلك |
2. أنواع المصادقة
لا شيء
لواجهات API العامة التي لا تتطلّب مصادقة.
مفتاح API
يُرسل مفتاحاً ثابتاً كرأس أو معامل استعلام.
| الحقل | الوصف |
|---|---|
| المفتاح | قيمة مفتاح API الخاص بك |
| اسم الرأس | الرأس المراد استخدامه (افتراضي: X-Api-Key) |
يُرسل المفتاح كـ: X-Api-Key: your_key_here
Bearer Token
يُرسل رمزاً ثابتاً في رأس Authorization.
يُرسل كـ: Authorization: Bearer your_token_here
Basic Auth
يُرسل اسم المستخدم وكلمة المرور مُرمَّزَين بـ base64.
يُرسل كـ: Authorization: Basic dXNlcjpwYXNz
OAuth 2.0 (Client Credentials)
يجلب رمز وصول تلقائياً ويُخزّنه مؤقتاً حتى انتهاء الصلاحية. الأفضل لواجهات API الحديثة مثل Salesforce أو Google أو خوادم OAuth المخصّصة.
| الحقل | الوصف |
|---|---|
| Token URL | نقطة نهاية رمز OAuth (مثلاً https://auth.example.com/oauth/token) |
| Client ID | معرّف عميل OAuth الخاص بك |
| Client Secret | سر عميل OAuth الخاص بك |
| Scope | النطاقات مفصولة بمسافات (مثلاً read write) |
يتولّى enuchat دورة حياة الرمز تلقائياً — يجلبه في الاستدعاء الأول، ويُخزّنه مؤقتاً حتى انتهاء الصلاحية، ويُحدّثه عند الحاجة.
الأمان: جميع بيانات الاعتماد مشفّرة أثناء الراحة باستخدام libsodium. لا يتم كشفها أبداً في استجابات API — تُعرض فقط قيم مُقنّعة في لوحة التحكّم.
تكوين نقاط النهاية
يمكن أن يحتوي كل اتصال على نقاط نهاية متعدّدة — استدعاءات API محدّدة تريد إجراءها.
| الحقل | الوصف | مثال |
|---|---|---|
| الاسم | تسمية لنقطة النهاية هذه | Check availability |
| الطريقة | طريقة HTTP | GET، POST، PUT، DELETE |
| المسار | مسار URL (مُلحق بعنوان URL الأساسي). استخدم {'{'}variable} للقيم الديناميكية | /rooms/{'{'}roomId}/availability |
| معاملات الاستعلام | معاملات URL كأزواج مفتاح-قيمة. تدعم القيم {'{'}variable} | date={'{'}checkIn} |
| قالب النص | نص JSON لـ POST/PUT. يدعم استيفاء {'{'}variable} | {'{'}"guest": "{'{'}name}"} |
| ربط الاستجابة | ربط حقول استجابة JSON بمتغيّرات الجلسة باستخدام الترميز النقطي | data.available → room_available |
| الوصف | سياق للذكاء الاصطناعي (ما هي البيانات التي تُرجعها نقطة النهاية هذه) | يُرجع توفّر الغرفة والأسعار |
استيفاء المتغيّر
استخدم {'{'}variableName} في المسارات ومعاملات الاستعلام وقوالب النص. تأتي المتغيّرات من:
- متغيّرات الجلسة — مُعيَّنة بقواعد سابقة (إجراء SET_VARIABLE)
- معاملات الإجراء — مُرمَّزة يدوياً في إجراء قاعدة CALL_API
ربط الاستجابة
اربط حقول استجابة JSON بمتغيّرات الجلسة باستخدام الترميز النقطي:
// API returns:
{'{'}
"data": {'{'}
"available": true,
"price": {'{'} "amount": 120, "currency": "EUR" }
}
}
// Mapping:
data.available → room_available // "true"
data.price.amount → room_price // "120"
data.price.currency → room_currency // "EUR"تُخزَّن المتغيّرات المربوطة كمتغيّرات جلسة على المحادثة وتكون متاحة للذكاء الاصطناعي لتوليد الاستجابات.
الاستخدام مع القواعد
تُطلق استدعاءات API بواسطة إجراء CALL_API في القواعد. يمكنك دمجها مع إجراءات أخرى.
وصفة: البحث عن حالة الطلب
الاتصال: Order Management API — https://api.shop.com/v2 — Bearer Token
نقطة النهاية: GET /orders/{'{'}orderId} → تربط data.status → order_status، data.eta → delivery_eta
القاعدة (نوع ذكاء اصطناعي): "عندما يسأل الزائر عن حالة طلبه أو التسليم"
الإجراءات:
- CALL_API → نقطة نهاية حالة الطلب
- REPLY_AI → يستخدم الذكاء الاصطناعي
order_statusوdelivery_etaللرد
النتيجة: الزائر: "أين طلبي رقم 4521؟" — الذكاء الاصطناعي: "طلبك رقم 4521 قيد الشحن حالياً ويجب أن يصل بحلول يوم الخميس."
وصفة: تسعير في الوقت الفعلي
الاتصال: Pricing API — https://pricing.example.com — API Key
نقطة النهاية: GET /products/{'{'}productId}/price → تربط price → current_price، currency → price_currency
القاعدة (ثابتة): MESSAGE_MATCHES_REGEX: /\b(price|cost|how much)\b/i
الإجراءات:
- CALL_API → نقطة نهاية التسعير
- REPLY_TEXT → "السعر الحالي هو {'{'}current_price} {'{'}price_currency}."
الاختبار
اختبر دائماً اتصالاتك ونقاط نهايتك قبل استخدامها في القواعد:
- اختبار الاتصال — يتحقّق من عمل المصادقة (لـ OAuth2: يجلب رمزاً)
- اختبار نقطة النهاية — يُجري استدعاء API حقيقياً مع متغيّرات عيّنة ويُظهر الاستجابة
- اختبار القاعدة (تشغيل جاف) — على صفحة القواعد، اختبر ما إذا كانت قاعدة ستُطابق وما الإجراءات التي ستُنفَّذ
نصيحة: ابدأ باختبار الاتصال، ثم كل نقطة نهاية، ثم القاعدة الكاملة. بهذه الطريقة يمكنك عزل المشكلات في كل مستوى.
الأمان
- التشفير أثناء الراحة — جميع بيانات الاعتماد مشفّرة باستخدام libsodium قبل التخزين
- لا يتم الكشف أبداً — لا تتضمّن استجابات API أبداً بيانات اعتماد مفكوكة التشفير، فقط قيم مُقنّعة
- حماية SSRF — يحظر enuchat الاستدعاءات إلى localhost وعناوين IP الخاصة وأسماء المضيفين الداخلية
- المهلة — استدعاءات API الخارجية لها مهلة 5 ثوانٍ لمنع التعليق
- التخزين المؤقت لرمز OAuth2 — تُخزَّن رموز الوصول مؤقتاً بأمان وتُحدَّث تلقائياً
- عزل المستأجر — الاتصالات مُقيّدة بمستأجرك، غير متاحة للآخرين