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

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

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

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

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

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

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

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

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

إرسال محتوى الطلب. أرسل JSON مع الترويسة Content-Type: application/json (الأمر curl -d يرسل نوع نموذج ما لم تُضف هذه الترويسة). حين يكون المحتوى اختياريًا، لا ترسل شيئًا (أو {}) لتُطبَّق القيم الافتراضية. المحتوى الذي يتعذّر على الخادم قراءته يُرفض ولا يُنفَّذ الإجراء: JSON غير صالح، أو حقل بنوع خاطئ، يعيد 400 بمفتاح مثل error.request.invalid_json أو error.request.body_field مع اسم الحقل؛ ونوع محتوى غير JSON يعيد 415 error.request.not_json. لا يُعامَل أبدًا كأنه طلب بلا محتوى.

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

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

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

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

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

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

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

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

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

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

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

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