الواجهات البرمجية (API)، الويب هوك ومفاتيح MCP في منصة سين
تُعد وحدة الواجهات البرمجية والتكامل الخارجي (External API & Webhooks) في منصة سين بوابتك لبناء منظومة متكاملة لخدمة العملاء وأتمتة المبيعات. تتيح لك الواجهات البرمجية المعتمدة ربط منصة سين بسلاسة مع أنظمة إدارة علاقات العملاء (CRM)، ومتاجر التجارة الإلكترونية (سلة، زد، Shopify)، وأنظمة تخطيط الموارد (ERP)، والتطبيقات المصرفية، وصولاً إلى وكلاء الذكاء الاصطناعي المستقلين عبر بروتوكول سياق النموذج (Model Context Protocol - MCP).
1. البنية المعمارية للواجهات البرمجية وعنوان الخدمة الأساسي
تعتمد منصة سين على معيار RESTful الصارم مع تبادل البيانات بصيغة JSON وترميز UTF-8 القياسي:
العنوان الأساسي للإنتاج (Production Base URL):
https://seen-api.neop.co/api/user/v1
بروتوكول المصادقة والأمان (Authentication)
تتم مصادقة كافة الطلبات البرمجية عبر ترويسة HTTP القياسية باستخدام رمز حامل المفتاح (Bearer Token):
Authorization: Bearer sec_live_9f8e7d6c5b4a3210...
Content-Type: application/json
Accept: application/json
2. التبويبات الأربعة الرئيسية في وحدة الواجهات البرمجية
توفر منصة سين في شاشة الواجهة البرمجية الخارجية (External API) أربعة تبويبات متخصصة تلبي كافة احتياجات المطورين:
هيكلية وحدة الواجهات البرمجية:
┌──────────────┬────────────────┬──────────────────────┬─────────────┐
│ توثيق الـ API│ مفاتيح API │ سجلات الطلبات │ مفاتيح MCP │
│ (API Docs) │ (API Keys) │ (API Logs) │ (AI MCP) │
└──────────────┴────────────────┴──────────────────────┴─────────────┘
أ) توثيق الـ API التفاعلي (API Docs)
- مستندات برمجية حية تستعرض كافة المسارات (Endpoints)، ومواصفات الطلبات (Schemas)، ونماذج لحمولات الإرسال والاستجابة بكافة اللغات.
- يتيح لك تجربة استدعاء المسارات مباشرة من المتصفح والتحقق من صحة الاستجابة في ثوانٍ.
ب) مفاتيح الـ API وإدارة الحصص (API Keys)
- توليد مفاتيح برمجية جديدة مع تخصيص اسم وصفي لكل مفتاح (مثال:
Salla Store Webhook KeyأوMobile App Integration). - تحديد الصلاحيات الدقيقة (Permission Scoping): منح المفتاح صلاحيات محددة فقط (مثل إرسال الرسائل فقط، أو قراءة جهات الاتصال فقط).
- إدارة الحصص وسقف الطلبات: تحديد سقف الطلبات في الدقيقة (
rate_limit_per_minute)، وتحديد الحصة الشهرية واليومية لاستهلاك الرسائل. - القائمة البيضاء لعناوين IP (IP Allowlist): ميزة أمان مصرفية تتيح حصر قبول الطلبات فقط من عناوين IP الخاصة بخوادمك، ورفض أي طلب قادم من عنوان آخر حتى لو كان يحمل المفتاح الصحيح.
ج) سجلات وتيليمتري الطلبات اللحظية (API Logs)
- سجل رقمي فوري يوثق كل استدعاء برمجي يصل إلى مساحة عملك.
- يعرض مسار الطلب، وقت الاستجابة بالمللي ثانية (Latency ms)، كود الحالة البرمجية (200, 400, 429, 500)، وعنوان IP المصدر.
- عند النقر على أي سجل، تفتح لك نافذة فحص تفصيلية (
ApiLogDetailView) تستعرض حمولة الطلب الكاملة (Payload) ورد الخادم بدقة لتسهيل تشخيص الأخطاء ومعالجتها فورياً.
د) مفاتيح بروتوكول سياق النموذج للذكاء الاصطناعي (MCP Keys)
- قسم مبتكر صُمم خصيصاً لربط نماذج الذكاء الاصطناعي ووكلاء LLM (مثل Claude Desktop، وCursor، وأدوات OpenAI Agents) بمنصة سين كأدوات تنفيذية مستقلة.
- يتيح للوكلاء الذكيين قراءة التذاكر، إرسال الرسائل، الاستعلام عن جهات الاتصال، وتعيين المحادثات ذاتياً ضمن بيئة آمنة ومراقبة.
3. خطوات إنشاء مفتاح API وتأمينه
- انتقل إلى الواجهة البرمجية (External API) وافتح تبويب مفاتيح API (API Keys).
- انقر على زر "إنشاء مفتاح جديد" (Generate API Key).
- أدخل اسماً تعريفياً للمفتاح، وحدد تاريخ انتهاء الصلاحية إذا رغبت في ذلك.
- حدد الصلاحيات المصرح بها عبر خانات الاختيار:
messages:send: إرسال الرسائل والقوالب عبر واتساب والقنوات.contacts:read/contacts:write: قراءة وتحديث بيانات العملاء والوسوم.tickets:read/tickets:manage: جلب التذاكر وتغيير حالتها وأولويتها.
- (اختياري) أضف عناوين الـ IP الخاصة بخوادمك في حقل
IP Allowlist. - انقر على "توليد المفتاح".
- يظهر لك المفتاح السري الكامل لمرة واحدة فقط؛ احرص على نسخه وحفظه في بيئة متغيرات النظام الآمنة لديك (.env)؛ فلن تتمكن من رؤيته كاملاً مرة أخرى لأسباب أمنية.
تحذير: لا تشارك مفتاح الـ API أبداً في مستودعات الكود المفتوحة (GitHub) أو كود الواجهات الأمامية للعميل (Frontend)؛ حيث يمنح المفتاح وصولاً مباشراً لقنوات التواصل الخاصة بشركتك.
4. نظام أحداث الويب هوك (Webhooks Subscriptions)
يتيح لك نظام الويب هوك في سين إرسال إشعارات فورية (HTTP POST) إلى خوادمك فور وقوع أحداث تشغيلية في مساحة العمل:
أهم الأحداث المدعومة (Supported Events)
message.received: عند استلام رسالة جديدة من العميل عبر أي قناة.message.delivered/message.read: عند وصول الرسالة لهاتف العميل أو قراءتها من قِبل العميل.ticket.created: عند فتح تذكرة جديدة لأول مرة.ticket.status_changed: عند تغيير حالة التذكرة (مثل إغلاقها أو إعادة فتحها).broadcast.completed: عند اكتمال إرسال حملة بث جماعي بالكامل.
التحقق من توقيع الويب هوك (Signature Verification)
لحماية خوادمك من الهجمات الإلكترونية، تُرسل سين ترويسة توقيع رقمي مشفرة بـ HMAC SHA-256 عبر الترويسة:X-Seen-Signature: <hmac_sha256_hash>
تسمح لخادمك بالتحقق من أن الطلب صادر بالفعل من منصة سين الرسمية ولم يتم التلاعب به.
5. أمثلة برمجية لاستدعاء واجهة إرسال الرسائل
أ) استدعاء باستخدام cURL
curl -X POST https://seen-api.neop.co/api/user/v1/messages/send \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel_id": 12,
"recipient": "+966501234567",
"message_type": "text",
"text": "مرحباً محمد، تم تأكيد طلبك رقم #8921 بنجاح!"
}'
ب) استدعاء باستخدام Python (Requests)
import requests
url = "https://seen-api.neop.co/api/user/v1/messages/send-template"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
payload = {
"channel_id": 12,
"recipient": "+966501234567",
"template_name": "order_shipping_update",
"language": "ar",
"variables": {
"1": "محمد العتيبي",
"2": "9823145",
"3": "شركة سمسا"
}
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
6. الربط الذكي عبر بروتوكول MCP (Model Context Protocol)
تُعد منصة سين رائدة في تبني بروتوكول سياق النموذج الموحد المطور لتمكين نماذج الذكاء الاصطناعي من إدارة التذاكر:
- من خلال تبويب مفاتيح MCP، يمكنك إنشاء مفتاح وتوصيله بأدواتك الذكية المفضلة.
- يُوفر خادم Seen MCP أدوات جاهزة (
Tools) تشمل:send_message: إرسال رد فوري على العميل.get_ticket_details: استرجاع سياق التذكرة والرسائل السابقة.assign_ticket: تحويل التذكرة لموظف بشري مختص.list_contacts: الاستعلام عن سجلات العملاء.
7. جدول أكواد الحالة ومعالجة الأخطاء (HTTP Status Codes)
| كود الحالة | المعنى البرمجي | السبب المحتمل | الحل الموصى به |
|---|---|---|---|
| 200 OK | نجاح الطلب | تم تنفيذ العملية بنجاح. | متابعة المعالجة الطبيعية. |
| 400 Bad Request | خطأ في المدخلات | رقم هاتف غير صحيح أو معلمات قالب ناقصة. | فحص جسم الطلب وتصحيح المعطيات. |
| 401 Unauthorized | غير مصرح | مفتاح API مفقود أو ملغى أو منتهي الصلاحية. | توليد مفتاح جديد والتأكد من ترويسة Bearer. |
| 403 Forbidden | صلاحيات غير كافية | المفتاح لا يملك الصلاحية المحددة للعملية. | تعديل صلاحيات المفتاح في لوحة التحكم. |
| 429 Too Many Requests | تجاوز معدل الطلبات | تم تجاوز سقف الطلبات في الدقيقة (Rate Limit). | تطبيق استراتيجية التراجع الأسي (Exponential Backoff). |
| 500 Server Error | خطأ غير متوقع | تعطل مؤقت في خوادم المعالجة. | التواصل مع فريق الدعم ومراجعة سجلات الطلبات. |
الأسئلة الشائعة حول الواجهات البرمجية
ما هو سقف الطلبات الافتراضي (Rate Limit) لكل مفتاح API؟
يبلغ الحد الافتراضي لمفاتيح الـ API القياسية 60 طلباً في الدقيقة لكل مساحة عمل. ويمكن للمنشآت ذات الأحجام الكبرى رفع هذا السقف عبر باقات المؤسسات (Enterprise).
هل يمكنني استخدام مفتاح API واحد لربط تطبيقات متعددة؟
من الناحية التقنية نعم، ولكن من أفضل الممارسات الأمنية إنشاء مفتاح API مستقل لكل نظام أو متجر متصل وتسميته باسمه؛ مما يسهل عليك تتبع سجلات كل تطبيق في تبويب API Logs وإلغاء مفتاح تطبيق معين عند الحاجة دون تعطيل باقي الأنظمة.
كيف أختبر الويب هوك محلياً أثناء مرحلة التطوير؟
يمكنك استخدام أدوات الأنفاق الآمنة مثل ngrok لتوليد عنوان HTTPS مؤقت يوجه الطلبات إلى خادمك المحلي على المنفذ (e.g. localhost:3000) ووضعه كعنوان Webhook URL في منصة سين لاختبار الأحداث فورياً.
