الواجهات البرمجية (API)، الويب هوك ومفاتيح MCP في منصة سين

تُعد وحدة الواجهات البرمجية والتكامل الخارجي في منصة سين بوابتك لبناء منظومة متكاملة لخدمة العملاء وأتمتة المبيعات. تتيح لك الواجهات البرمجية المعتمدة ربط منصة سين بسلاسة مع أنظمة إدارة علاقات العملاء، ومتاجر التجارة الإلكترونية (سلة، زد، Shopify)، وأنظمة تخطيط الموارد، والتطبيقات المصرفية، وصولاً إلى وكلاء الذكاء الاصطناعي المستقلين عبر بروتوكول سياق النموذج (Model Context Protocol - MCP).

1. البنية المعمارية للواجهات البرمجية وعنوان الخدمة الأساسي

تعتمد منصة سين على معيار RESTful الصارم مع تبادل البيانات بصيغة JSON وترميز UTF-8 القياسي:

العنوان الأساسي للإنتاج: — https://seen-api.neop.co/api/user/v1

بروتوكول المصادقة والأمان

تتم مصادقة كافة الطلبات البرمجية عبر ترويسة HTTP القياسية باستخدام رمز حامل المفتاح:

Authorization: Bearer sec_live_9f8e7d6c5b4a3210...
Content-Type: application/json
Accept: application/json

2. التبويبات الأربعة الرئيسية في وحدة الواجهات البرمجية

توفر منصة سين في شاشة الواجهة البرمجية الخارجية أربعة تبويبات متخصصة تلبي كافة احتياجات المطورين:

أ) توثيق الـ API التفاعلي

مستندات برمجية حية تستعرض كافة المسارات، ومواصفات الطلبات، ونماذج لحمولات الإرسال والاستجابة بكافة اللغات.
يتيح لك تجربة استدعاء المسارات مباشرة من المتصفح والتحقق من صحة الاستجابة في ثوانٍ.

ب) مفاتيح الـ API وإدارة الحصص

توليد مفاتيح برمجية جديدة مع تخصيص اسم وصفي لكل مفتاح (مثال: Salla Store Webhook Key أو Mobile App Integration).
تحديد الصلاحيات الدقيقة: منح المفتاح صلاحيات محددة فقط (مثل إرسال الرسائل فقط، أو قراءة جهات الاتصال فقط).
إدارة الحصص وسقف الطلبات: تحديد سقف الطلبات في الدقيقة (rate_limit_per_minute)، وتحديد الحصة الشهرية واليومية لاستهلاك الرسائل.
القائمة البيضاء لعناوين IP: ميزة أمان مصرفية تتيح حصر قبول الطلبات فقط من عناوين IP الخاصة بخوادمك، ورفض أي طلب قادم من عنوان آخر حتى لو كان يحمل المفتاح الصحيح.

ج) سجلات وتيليمتري الطلبات اللحظية

سجل رقمي فوري يوثق كل استدعاء برمجي يصل إلى مساحة عملك.
يعرض مسار الطلب، وقت الاستجابة بالمللي ثانية، كود الحالة البرمجية (200, 400, 429, 500)، وعنوان IP المصدر.
عند النقر على أي سجل، تفتح لك نافذة فحص تفصيلية تستعرض حمولة الطلب الكاملة ورد الخادم بدقة لتسهيل تشخيص الأخطاء ومعالجتها فورياً.

د) مفاتيح بروتوكول سياق النموذج للذكاء الاصطناعي

قسم مبتكر صُمم خصيصاً لربط نماذج الذكاء الاصطناعي ووكلاء LLM (مثل Claude Desktop، وCursor، وأدوات OpenAI Agents) بمنصة سين كأدوات تنفيذية مستقلة.
يتيح للوكلاء الذكيين قراءة التذاكر، إرسال الرسائل، الاستعلام عن جهات الاتصال، وتعيين المحادثات ذاتياً ضمن بيئة آمنة ومراقبة.

3. خطوات إنشاء مفتاح API وتأمينه

انتقل إلى الواجهة البرمجية وافتح تبويب مفاتيح API.
انقر على زر "إنشاء مفتاح جديد".
أدخل اسماً تعريفياً للمفتاح، وحدد تاريخ انتهاء الصلاحية إذا رغبت في ذلك.
حدد الصلاحيات المصرح بها عبر خانات الاختيار:
- messages:send: إرسال الرسائل والقوالب عبر واتساب والقنوات.
- contacts:read / contacts:write: قراءة وتحديث بيانات العملاء والوسوم.
- tickets:read / tickets:manage: جلب التذاكر وتغيير حالتها وأولويتها.
(اختياري) أضف عناوين الـ IP الخاصة بخوادمك في حقل IP Allowlist.
انقر على "توليد المفتاح".
يظهر لك المفتاح السري الكامل لمرة واحدة فقط؛ احرص على نسخه وحفظه في بيئة متغيرات النظام الآمنة لديك؛ فلن تتمكن من رؤيته كاملاً مرة أخرى لأسباب أمنية.

تحذير: لا تشارك مفتاح الـ API أبداً في مستودعات الكود المفتوحة أو كود الواجهات الأمامية للعميل؛ حيث يمنح المفتاح وصولاً مباشراً لقنوات التواصل الخاصة بشركتك.

4. نظام أحداث الويب هوك

يتيح لك نظام الويب هوك في سين إرسال إشعارات فورية إلى خوادمك فور وقوع أحداث تشغيلية في مساحة العمل:

أهم الأحداث المدعومة

message.received: عند استلام رسالة جديدة من العميل عبر أي قناة.
message.delivered / message.read: عند وصول الرسالة لهاتف العميل أو قراءتها من قِبل العميل.
ticket.created: عند فتح تذكرة جديدة لأول مرة.
ticket.status_changed: عند تغيير حالة التذكرة (مثل إغلاقها أو إعادة فتحها).
broadcast.completed: عند اكتمال إرسال حملة بث جماعي بالكامل.

التحقق من توقيع الويب هوك

لحماية خوادمك من الهجمات الإلكترونية، تُرسل سين ترويسة توقيع رقمي مشفرة بـ 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

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

6. الربط الذكي عبر بروتوكول MCP

تُعد منصة سين رائدة في تبني بروتوكول سياق النموذج الموحد المطور لتمكين نماذج الذكاء الاصطناعي من إدارة التذاكر:

من خلال تبويب مفاتيح MCP، يمكنك إنشاء مفتاح وتوصيله بأدواتك الذكية المفضلة.
يُوفر خادم Seen MCP أدوات جاهزة (Tools) تشمل:
- send_message: إرسال رد فوري على العميل.
- get_ticket_details: استرجاع سياق التذكرة والرسائل السابقة.
- assign_ticket: تحويل التذكرة لموظف بشري مختص.
- list_contacts: الاستعلام عن سجلات العملاء.

7. جدول أكواد الحالة ومعالجة الأخطاء

كود الحالة	المعنى البرمجي	السبب المحتمل	الحل الموصى به
200 OK	نجاح الطلب	تم تنفيذ العملية بنجاح.	متابعة المعالجة الطبيعية.
400 Bad Request	خطأ في المدخلات	رقم هاتف غير صحيح أو معلمات قالب ناقصة.	فحص جسم الطلب وتصحيح المعطيات.
401 Unauthorized	غير مصرح	مفتاح API مفقود أو ملغى أو منتهي الصلاحية.	توليد مفتاح جديد والتأكد من ترويسة Bearer.
403 Forbidden	صلاحيات غير كافية	المفتاح لا يملك الصلاحية المحددة للعملية.	تعديل صلاحيات المفتاح في لوحة التحكم.
429 Too Many Requests	تجاوز معدل الطلبات	تم تجاوز سقف الطلبات في الدقيقة.	تطبيق استراتيجية التراجع الأسي.
500 Server Error	خطأ غير متوقع	تعطل مؤقت في خوادم المعالجة.	التواصل مع فريق الدعم ومراجعة سجلات الطلبات.

الأسئلة الشائعة حول الواجهات البرمجية

ما هو سقف الطلبات الافتراضي لكل مفتاح API؟

يبلغ الحد الافتراضي لمفاتيح الـ API القياسية 60 طلباً في الدقيقة لكل مساحة عمل. ويمكن للمنشآت ذات الأحجام الكبرى رفع هذا السقف عبر باقات المؤسسات.

هل يمكنني استخدام مفتاح API واحد لربط تطبيقات متعددة؟

من الناحية التقنية نعم، ولكن من أفضل الممارسات الأمنية إنشاء مفتاح API مستقل لكل نظام أو متجر متصل وتسميته باسمه؛ مما يسهل عليك تتبع سجلات كل تطبيق في تبويب API Logs وإلغاء مفتاح تطبيق معين عند الحاجة دون تعطيل باقي الأنظمة.

كيف أختبر الويب هوك محلياً أثناء مرحلة التطوير؟

يمكنك استخدام أدوات الأنفاق الآمنة مثل ngrok لتوليد عنوان HTTPS مؤقت يوجه الطلبات إلى خادمك المحلي على المنفذ (e.g. localhost:3000) ووضعه كعنوان Webhook URL في منصة سين لاختبار الأحداث فورياً.

الواجهات البرمجية (API) والويب هوك