دليل الربط البرمجي

كل ما يلي هو نفس الواجهة التي تستخدمها شاشات المنتج نفسه. لا توجد «واجهة تكامل» منفصلة قد تتخلّف عن التطوير — التكامل يسجّل دخوله كرمز وصول، وتطبّق عليه المنصة نفس فحوص الترخيص والصلاحيات وعزل المستأجر التي تطبّقها على أي شخص.

١. أنشئ رمز وصول

من داخل التطبيق، افتح الإعدادات ← رموز API وأنشئ رمزاً. يُعرض السر مرة واحدة فقط، ويُخزَّن مجزّأً بخوارزمية SHA-256 فلا يمكن استرجاعه لاحقاً — فإن ضاع، ألغِ الرمز وأنشئ غيره.

• الصيغة. nxs_ يتبعها 32 حرفاً. أول 8 أحرف تُحفظ ظاهرة كبادئة تعريف، ليميّز المسؤول بين رمزين دون أن يرى سرّ أيٍّ منهما.
• النطاقات. يحمل كل رمز قائمة صريحة: tool:<id> يمنح قدرة واحدة، و* يمنح كل ما يملكه منشئ الرمز. ولا يتجاوز الرمز صلاحيات الشخص الذي أنشأه أبداً.
• حدّ الاستدعاء. لكل رمز على حدة، 60 استدعاءً في الدقيقة افتراضياً، ويمكن للمسؤول رفعه لتكامل عالي الحجم.
• الإلغاء. فوري من الشاشة نفسها. وكل استدعاء يحدّث last_used_at، فيسهل تمييز الرمز غير المستخدم قبل حذفه.

٢. استدعِ واجهة REST

تعرض كل وحدة قدراتها كاملة بصيغة JSON تحت /api/<module>/… على نطاق مؤسستك. المصادقة برمز حامل:

curl https://yourcompany.tarleaks.com/api/hr/employees \\
  -H "Authorization: Bearer nxs_your_token_here"

يُستنتج المستأجر من اسم النطاق، فلا حاجة لتمرير معرّف مستأجر، ولا سبيل للوصول إلى بيانات شركة أخرى برمزك.

٣. أو اربط أداة ذكاء اصطناعي عبر MCP

تتحدث كل وحدة أيضاً بروتوكول Model Context Protocol على /api/<module>/mcp، مع نقطة تجميعية واحدة تغطيها جميعاً. وجّه إليها Claude أو بيئة تطوير أو إطار عمل وكيل، فتصبح بيانات النظام قابلة للقراءة والتنفيذ — بنفس فحص الصلاحيات لكل أداة، وبسجل تدقيق لكل استدعاء.

تُولَّد قائمة الأدوات من فهرس مشترك واحد، فلا يمكن أن تنحرف واجهة MCP لأي وحدة عمّا تفعله الوحدة فعلياً.

اطلب شكل النتيجة، لا صفحاتها

تقبل أدوات القوائم كائن _shape لتجميع النتائج على الخادم بدل جلب آلاف السطور وعدّها بنفسك:

{ "_shape": {
     "group_by": "department",
     "measures": ["count", "avg:base_salary"],
     "where": { "status": "active" },
     "sort": "count:desc"
} }

يجري التجميع والتصفية على المجتمع الكامل لا على الصفحة الظاهرة. كما تحمل كل استجابة كتلة meta بالعدد الحقيقي للسطور وأسماء الأعمدة وأنواعها — اقرأها بدل عدّ ما تراه.

٤. اشترك في الأحداث بدل الاستطلاع المتكرر

تُنشر أحداث النظام — تعيين موظف، ترحيل مسيّر رواتب، إصدار شهادة، الرد على تذكرة، نتيجة حملة — على ناقل رسائل. تشترك التكاملات وتتفاعل، بدل السؤال المتكرر عمّا إذا كان شيء قد تغيّر.

٥. ما تحصل عليه دون عناء

• عزل المستأجرين. مفروض عند البوابة، وداخل كل خدمة، ومرة أخرى في قاعدة البيانات — لكل مستأجر قاعدة بيانات خاصة به.
• نفس صلاحيات الواجهة. لا يستطيع التكامل فعل ما لا يستطيعه الشخص الذي أنشأ رمزه.
• سجل تدقيق كامل. كل استدعاء منسوب إلى الرمز وإلى صاحبه، مع تسجيل القيمة قبل وبعد — وهو ما يجعل التكامل قابلاً للتشخيص والسؤال الرقابي قابلاً للإجابة.
• بوابة الترخيص. الوحدة غير المشمولة بخطتك تُجيب بالرمز 402 لا 404، فيكون السبب واضحاً بلا لبس.

أين بقية التوثيق

تُولَّد مراجع API لكل وحدة من المسارات الحيّة لنسختك أنت، فتطابق دائماً ما تشغّله. وتعرض أدلة الأدوار القدرات نفسها من الطرف الآخر — ما يفعله كل شخص على الشاشة، خطوة بخطوة.