للمطورين

توثيق API و MCP

Referencia completa para desarrolladores

المحتوى

MCP · المساعدات الذكية

اربط مساعدك الذكي بـ ScreenLeads

يتيح خادم MCP لمساعد مثل Claude أو أي عميل متوافق الاستعلام عن بياناتك في ScreenLeads باللغة الطبيعية، ضمن صلاحيات بيانات اعتمادك.

بيانات الاتصال

نقطة نهاية MCP

https://mcp.pre.screenleads.com/mcp

نقل HTTP ‏(JSON-RPC).

فحص الصحة

https://mcp.pre.screenleads.com/health

يجب أن يعيد ok: true و backendAuthMode: passthrough.

بيئة الخادم

https://api.pre.screenleads.com

يمرّر MCP بيانات اعتمادك إلى الـ API بوضع passthrough.

وضع الأمان

passthrough

لا يخزّن MCP أي بيانات اعتماد عامة: يرى مساعدك فقط ما يراه مفتاحك.

ابدأ في 4 خطوات

1
تحقق من فحص الصحة
افتحه في المتصفح وتأكد أنه يعيد ok: true.
2
جهّز عميل MCP
سجّل الخادم بعنوان ‎/mcp مع ترويسة Authorization ‏(Bearer بمفتاحك) وترويسة X-ScreenLeads-Client-Id. بعض العملاء يديرون الترويسات من الواجهة بدل JSON.
3
اعرض قائمة الأدوات
تأكد من ظهور أدوات الشركات والهوية البصرية والأجهزة والإعلانات والعروض والخطط والرموز والفواتير والوسائط والويبهوك.
4
نفّذ استعلاماً حقيقياً
مثلاً screenleads_health_check، أو اسأل باللغة الطبيعية عن صلاحيات مفتاحك.

الإعداد والأمثلة

إعداد عميل MCP ‏(JSON)

{
  "mcpServers": {
    "screenleads": {
      "url": "https://mcp.pre.screenleads.com/mcp",
      "headers": {
        "Authorization": "Bearer <SCREENLEADS_API_KEY>",
        "X-ScreenLeads-Client-Id": "<SCREENLEADS_CLIENT_ID>"
      }
    }
  }
}

cURL · استدعاء موثَّق

curl -X POST https://mcp.pre.screenleads.com/mcp \
  -H 'Authorization: Bearer <SCREENLEADS_API_KEY>' \
  -H 'X-ScreenLeads-Client-Id: <SCREENLEADS_CLIENT_ID>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "screenleads_health_check", "arguments": {} }
  }'

ما الذي يستطيع مساعدك الاستعلام عنه

الشركات والهوية البصرية

الشركات المرئية والشعارات ورموز العلامة.

الأجهزة والإعلانات

الشاشات والإعلانات المسندة وتشخيص التشغيل.

العروض الترويجية

العروض النشطة ورموز QR والتفعيل والإيقاف.

الخطط والرموز

الخطط المرئية وحزم الرموز والرصيد والحركات.

الفوترة

فواتير شركتك المرئية وآخر عمليات الدفع.

الويبهوك والصلاحيات

التكاملات المهيأة وصلاحيات مفتاحك.

جرّب هذه الأسئلة

ما صلاحيات مفتاح الـ API الخاص بي؟ وهل يستطيع تعديل الإعلانات؟
اعرض الشركات التي يمكن لمستخدمي رؤيتها.
راجع الإعلانات المسندة إلى الجهاز 1 وهل ترتبط بها عروض.
احسب رصيد الرموز الحالي واعرض آخر الحركات.
حضّر تعديل الإعلان 15 لكن لا تنفّذه حتى أؤكد.

الأمان والنطاق

وضع passthrough: تُمرَّر بيانات اعتمادك إلى الـ API؛ لا يخزّن MCP بيانات اعتماد إدارية عامة.
لا يستطيع مساعدك الاستعلام إلا عمّا يسمح به مفتاحك في الخادم.
الكتابة على خطوتين: يعيد MCP معاينة ولا يُنفِّذ إلا بعد تأكيدك الصريح.
تُحجب الرموز وكلمات المرور والأسرار في ردود الـ MCP.

REST API

التكامل مع واجهة ScreenLeads

الشركات والأجهزة والإعلانات والعروض والخطط والرموز والفواتير — دائماً ضمن صلاحيات بيانات اعتمادك.

بيانات الاتصال

بيئة الخادم (PRE)

https://api.pre.screenleads.com

بيئة ما قبل الإنتاج للتحقق من تكاملك قبل الإطلاق.

المصادقة

X-API-KEY + X-ScreenLeads-Client-Id

مفتاح API من ScreenLeads مقيَّد بعميلك أو شركتك. يُقبل أيضاً كـ Authorization: Bearer.

كيف تحصل على بيانات الاعتماد

1
أنشئ أو اختر عميل API
في ScreenLeads، يمثّل عميل الـ API تكاملك.
2
أنشئ مفتاح API بصلاحيات
قراءة أو كتابة، وعند الحاجة مقيَّد بشركة واحدة (companyScope).
3
احفظ rawKey و client_id
هما القيمتان الوحيدتان اللتان يحتاجهما تكاملك؛ لا حاجة لتسجيل دخول متكرر. يمكن إلغاء المفتاح أو تدويره من الخادم.
4
استدعِ الـ API بالترويستين
أرسل مفتاح الـ API و client_id مع كل طلب.

أمثلة

cURL · طلب بمفتاح API

curl https://api.pre.screenleads.com/companies \
  -H 'X-API-KEY: <SCREENLEADS_API_KEY>' \
  -H 'X-ScreenLeads-Client-Id: <SCREENLEADS_CLIENT_ID>'

cURL · تسجيل دخول JWT (للاختبارات الداخلية فقط)

curl -X POST https://api.pre.screenleads.com/auth/login \
  -H 'Content-Type: application/json' \
  --data '{"username":"usuario@screenleads.com","password":"PASSWORD"}'

الأمان

استخدم مفتاح API مقيَّداً بالعميل أو الشركة: يمكن إلغاؤه أو تدويره دون توقف الخدمة.
لا تلصق مفاتيح API أو الرموز أو كلمات المرور في المحادثات أو المستندات المشتركة أو لقطات الشاشة.
رمز JWT يعمل لكنه ينتهي ويعتمد على جلسة مستخدم: اجعله للاختبارات الداخلية فقط.

{ "mcpServers": { "screenleads": { "url": "https://mcp.pre.screenleads.com/mcp", "headers": { "Authorization": "Bearer <SCREENLEADS_API_KEY>", "X-ScreenLeads-Client-Id": "<SCREENLEADS_CLIENT_ID>" } } } }

curl -X POST https://mcp.pre.screenleads.com/mcp \ -H 'Authorization: Bearer <SCREENLEADS_API_KEY>' \ -H 'X-ScreenLeads-Client-Id: <SCREENLEADS_CLIENT_ID>' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ --data '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "screenleads_health_check", "arguments": {} } }'