نظرة عامة: المصادقة والمفاتيح والنطاقات

تتيح الواجهة البرمجية العامة لجديرون لنظام تخطيط الموارد (ERP) أو نظام الموارد البشرية أو منصة البيانات لديك إرسال كل السجلات الأساسية في مساحة عملك وقراءتها: الهيكل التنظيمي والوظيفي، والوظائف، والموظفون، والمرشحون، والشواغر، والطلبات، والمقابلات، والعروض. تُبلغ خطافات الويب أنظمتك بكل تغيير، ويحمّل الإدراج المجمّع حتى 1,000 سجل في الطلب الواحد لأغراض الترحيل، ويبثّ سجل التدقيق إلى نظام SIEM لديك.

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

العنوان الأساسي والصيغة

• المسار الأساسي: https://<نطاق جديرون لديك>/api/v1، مثل https://jadiroon.com/api/v1.
• صيغة JSON فقط في الطلب والاستجابة (Content-Type: application/json). أسماء الحقول بصيغة camelCase، والنص ثنائي اللغة بصيغة { "ar": "…", "en": "…" }، والأوقات بصيغة ISO 8601 بتوقيت UTC.
• الوصف القابل للقراءة آليًا متاح في /api/v1/openapi.json (OpenAPI 3.1، بلا مفتاح). وتعرضه صفحة مرجع الواجهة البرمجية.
• المعرّفات والترقيم والأخطاء ومنع التكرار تتبع الأعراف.

التكاملات ومفاتيح الواجهة البرمجية

التكامل عميل آلي له اسم، مثل "Oracle HCM – الإنتاج". ويملك:

• نطاق صلاحيات (الوحدات التي يحق له قراءتها أو تغييرها)،
• مفتاح واجهة برمجية واحدًا أو أكثر،
• قائمة عناوين IP مسموحة اختيارية،
• صفرًا أو أكثر من نقاط استقبال خطافات الويب.

لا يدير التكاملات إلا من يحمل دور مسؤول مساحة العمل المقفل، من الإعدادات ← التكاملات (انظر التكاملات). تحتاج كل بيئة (مثل مساحة عمل للاختبار وأخرى للإنتاج) إلى تكامل ومفاتيح خاصة بها.

المفاتيح

• يبدأ المفتاح بـ jdr_live_ ويليه 40 حرفًا ورقمًا. ويظهر مرة واحدة عند إنشائه؛ ولا يحفظ جديرون إلا بصمة SHA-256 وأول 12 حرفًا (البادئة التي تراها في القائمة وفي سجل التدقيق).
• يمكن أن يكون للمفتاح تاريخ انتهاء. ويتلقى المفتاح الملغى أو المنتهي 401 unauthorized.
• يمكن أن يحمل التكامل عدة مفاتيح في الوقت نفسه، فتستطيع التدوير دون انقطاع: أنشئ مفتاحًا جديدًا وانشره، وتحقق من وقت آخر استخدام، ثم ألغِ القديم.
• احفظ المفاتيح في مخزن أسرار، ولا تضعها في الشيفرة المصدرية أو تطبيقات المتصفح.

المصادقة

أرسل المفتاح رمزًا من نوع Bearer في كل طلب:

curl https://jadiroon.com/api/v1/ping -H "Authorization: Bearer $JADIROON_KEY"

لا يحتاج GET /api/v1/ping إلى أي صلاحية، ويرد بالتكامل الذي يتبعه المفتاح، فهو مناسب كأول طلب:

{ "ok": true, "actor": { "kind": "integration", "integrationId": "cmv…", "name": "Oracle HCM – production", "keyPrefix": "jdr_live_8Gq" }, "workspaceId": "cmv…" }

النطاقات (الصلاحيات)

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

قواعد تأتي مع الكتالوج:

• التنفيذ يشمل العرض للوحدة نفسها. ولا يتضمن recruitment.candidate.contact أي صلاحية أخرى.
• المفتاح الذي لا يملك الصلاحية التي تحتاجها النقطة يتلقى 403 forbidden، وتسرد details.required المفاتيح المطلوبة.
• تتبع خطافات الويب النطاق نفسه: لا تتلقى نقطة الاستقبال إلا أحداث الموارد التي يستطيع تكاملها قراءتها.
• تسرد صفحة كل مورد الصلاحية الدقيقة لكل نقطة، وكذلك المرجع (x-permission).

حدود المعدل

• 600 طلب في الدقيقة لكل مفتاح، تُحسب في نوافذ ثابتة مدتها دقيقة مشتركة بين جميع الخوادم.
• فوق الحد ترد الواجهة البرمجية بـ 429 rate_limited مع الترويسة Retry-After (الثواني المتبقية حتى النافذة التالية). انتظر هذه المدة ثم تابع.
• يُحسب طلب الإدراج المجمّع طلبًا واحدًا أيًّا كان عدد صفوفه.
• لكل مفتاح رصيده الخاص؛ وتدوير المفاتيح لا يؤثر في رصيد غيرها.

قائمة عناوين IP المسموحة

يستطيع مسؤول مساحة العمل حصر التكامل في عناوين IP أو نطاقات CIDR (IPv4 أو IPv6)، من تبويب الوصول في التكامل. والطلب القادم من أي عنوان آخر يتلقى 403 forbidden ("Request IP is not on the integration allowlist"). والقائمة الفارغة تسمح بكل العناوين لتكامل مساحة العمل. أما تكامل القراءة على مستوى النشر فيجب أن تكون له قائمة دائمًا.

العنوان الذي يُفحص هو عنوان IP العام للعميل كما يراه الخادم. في سحابة جديرون يأتي من حافة الاستضافة التي تستبدل ترويستي X-Forwarded-For وX-Real-IP، فلا يستطيع العميل تزويره بإرسال هاتين الترويستين. وفي النشر الذاتي يضبط المشغّل TRUSTED_PROXY على عدد الوكلاء العكسيين (reverse proxies) أمام جديرون (مثل 1) أو على قائمة مفصولة بفواصل بعناوين IP الوكلاء أو نطاقات CIDR الخاصة بهم؛ فيُقرأ عنوان العميل من يمين X-Forwarded-For متجاوزًا هؤلاء الوكلاء، وتُهمل القيم التي أضافها العميل على اليسار. يجب على النشر الذاتي خلف وكيل ضبط TRUSTED_PROXY. فدونه لا يثق النشر بأي ترويسة تمرير: يتلقى كل تكامل له قائمة عناوين 403 forbidden، وتُطبَّق حدود تسجيل الدخول على كل حساب بدل كل عنوان (فمن يعرف البريد الإلكتروني لحساب يستطيع إبقاء ذلك الحساب محدود المعدّل).

استجابات توقف كل الطلبات

ما الذي يُسجَّل

• تُسجَّل كل عملية كتابة في سجل تدقيق مساحة العمل بالفاعل تكامل · (اسم التكامل)، مع بادئة المفتاح وعنوان IP ووكيل المستخدم للطلب. وتظهر في الإعدادات ← سجل التدقيق وفي لوحة السجل التاريخي للسجل.
• لا تُسجَّل عمليات القراءة.
• تُسجَّل تغييرات المفاتيح والصلاحيات والقائمة المسموحة ونقاط الاستقبال بإجراءات settings.integration.*.

الخطوة التالية

• الأعراف: المعرّفات، والمعرّفات الثابتة (slug)، والترقيم، وupdatedSince، وسجل المحذوفات، والأخطاء، ومنع التكرار.
• دليل المزامنة مع ERP: اربط سجلاتك بالمعرّفات الخارجية وأبقِ الطرفين متطابقين.
• الترحيل المجمّع: تحميل قوى عاملة قائمة.
• خطافات الويب وفهرس الأحداث.
• سجل التدقيق لأنظمة SIEM.
• صفحات المراحل، من الإعداد والتهيئة إلى التهيئة الوظيفية.