API Omniscol — رموز المصادقة

Premium

API Omniscol: توفر Omniscol واجهة API من نوع REST موثقة بمعيار OpenAPI للتكامل بين الأنظمة، مثل لوحة تحكم خارجية أو عرض مخصص أو مزامنة مع نظام ERP أو نظام معلومات أو وكيل ذكاء اصطناعي عبر MCP. تُدار رموز الوصول، المحصورة في نقاط الوصول المختارة عند إنشائها، من الواجهة في الحسابات التي توفر هذا التكامل.

API Omniscol هي واجهة API من نوع REST موثقة بمعيار OpenAPI. تُستخدم للتكامل بين الأنظمة: لوحة تحكم خارجية، أو عرض مخصص، أو مزامنة مع نظام ERP أو نظام معلومات، أو وكيل ذكاء اصطناعي عبر MCP.

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

المفتاح والرمز: كائنان مختلفان

تميز Omniscol بين كائنين لا ينبغي الخلط بينهما.

المفتاح كائن دائم يُحفظ لدى Omniscol. ويجمع ما يلي:

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

المعرّف والتسمية وتاريخ الانتهاء معلومات إدارية: المعرّف مجرد مرجع عام وليس عنصرًا سريًا. أما السر فهو المادة الوحيدة للتوقيع: يُولَّد عشوائيًا عند إنشاء المفتاح، ويبقى على الخادم، ولا يمكن تعديله، ولا يُعرض ولا يُرسل أبدًا، لا عند الإنشاء ولا في قائمة المفاتيح. وحتى لو تسرب فلن يكفي لتزوير رمز: فالتوقيع يجمعه مع ملح خاص بالحساب وسر للخادم لا يغادران Omniscol أبدًا.

الرمز هو JWT (JSON Web Token) مستقل، موقّع بسر المفتاح. وهو ما تسلّمونه إلى النظام الخارجي. يتضمن محتواه الموقّع الحساب المعني، وقائمة نقاط الوصول المسموح بها، والمفتاح المشتق منه، وتاريخ انتهائه الخاص.

بعبارة أخرى: المفتاح يوقّع، والرمز موقَّع. يمكن للمفتاح الواحد أن يوقّع عدة رموز، وكلها قابلة للتحقق بالسر نفسه، ولذلك تُلغى كلها معًا إذا اختفى المفتاح.

لا تخزّن Omniscol الرمز: تولّده وتعرضه مرة واحدة، ثم تعيد التحقق منه عند كل استدعاء بإعادة حساب توقيعه انطلاقًا من سر المفتاح (HMAC SHA-256). ولذلك لا يمكن تغيير أي إذن يحمله الرمز دون هذا السر.

إنشاء رمز

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

  1. إنشاء مفتاح — أدخلوا تسمية واضحة، وتاريخ انتهاء إذا كان الوصول مؤقتًا. يمكن تعديل تسميته وتاريخ انتهائه لاحقًا، أما سر التوقيع فلا.
  2. توليد رمز — اختاروا المفتاح، وحددوا نقاط الوصول المسموح بها، وإن رغبتم فاختاروا تاريخ انتهاء خاصًا بالرمز، ثم ولّدوا JWT.

عند التوليد، تعرض Omniscol الرمز مرة واحدة فقط. انسخوه فورًا إلى مدير أسرار: لن يُعرض مرة أخرى. تاريخ انتهاء الرمز مكتوب في محتواه الموقّع، ولا يمكن تعديله لاحقًا. لتغيير هذا التاريخ، ولّدوا رمزًا جديدًا.

هناك إذن مستويان للانتهاء، مستقلان عن بعضهما:

  • انتهاء المفتاح — يمكن تعديله من قائمة المفاتيح؛ وعند بلوغه تُرفض جميع الرموز المشتقة من هذا المفتاح (يفشل الاستدعاء برمز 401)؛
  • انتهاء الرمز — يُحدد عند التوليد ويُكتب في JWT، ولا يمكن تعديله بعد ذلك.

نقاط الوصول المسموح بها

لا يتيح الرمز الوصول إلا إلى نقاط الوصول المحددة عند توليده: لا تفترضوا أبدًا أنه يغطي واجهة API كلها. تُنقل القائمة المسموح بها داخل الرمز ويُتحقق منها عند كل استدعاء؛ ويُرفض (401) كل استدعاء موجه إلى نقطة وصول غير مسموح بها.

إلى جانب نقاط الوصول الفردية، تقترح قائمة الاختيار اختصارات حسب الوحدة:

  • اختيار وحدة وحدها يسمح بـكل نقاط الوصول فيها؛
  • الصيغ حسب العملية — قراءة وتعديل وإنشاء وحذف — تقصر الوحدة على نوع واحد من الاستدعاءات.

وهكذا يمنح تحديد "الجداول الزمنية [قراءة]" كل صلاحيات قراءة الجداول الزمنية دون فتح أي كتابة، ودون تحديد كل نقطة وصول على حدة. التزموا بأقل قدر ممكن: لا تمنحوا إلا الوحدات والعمليات الضرورية فعلًا للتكامل.

استخدام رمز

هناك طريقتان معتادتان لإرسال الرمز إلى API:

  • ترويسة HTTP: Authorization: Bearer <jeton> (موصى بها).
  • سلسلة الاستعلام: ?auth=<jeton> (مفيدة لتصحيح الأخطاء، لكنها تظهر في سجلات HTTP — يُستحسن تجنبها في بيئة الإنتاج).

مثال curl، يُكيَّف مع نقطة وصول فعلية مأخوذة من OpenAPI:

curl -H "Authorization: Bearer $TOKEN" \
  https://votre-ecole.omniscol.com/api/<module>/<point-acces>

وثائق OpenAPI

تعرض شاشة استيراد / تصدير رابط OpenAPI 3.1 الذي يفتح المواصفات المتاحة للحساب في Swagger Editor. ستجدون فيها:

  • قائمة نقاط الوصول المتاحة في API،
  • مخططات البيانات المتبادلة،
  • الطرق والمعاملات،
  • الاستجابات المتوقعة.

يقدّم حسابكم المواصفات أيضًا مباشرة، دون مصادقة:

  • /api/guest/openapi.json — المواصفات بصيغة JSON؛
  • /api/guest/openapi.yaml (أو /api/guest/openapi?yaml=true) — المحتوى نفسه بصيغة YAML؛
  • /api/guest/school_schema.json — مخطط JSON لبيانات الحساب.

إلغاء وصول

يتم الإلغاء على مستوى المفتاح لا الرمز المفرد.

تعرض الشاشة المفاتيح التي استُخدمت لتوليد رموز. حذف مفتاح يمحو سر توقيعه لدى Omniscol: ومن ثم لا يمكن التحقق من أي توقيع مشتق من هذا السر، ويفشل كل استدعاء يقدّم رمزًا صادرًا عن هذا المفتاح برمز 401. غياب السر هو ما يبطل الرموز، لا قائمة إلغاء.

بالنسبة إلى إدارة الأنظمة المعلوماتية، هناك نتيجتان:

  • لا يوجد إلغاء رمز برمز. لا تحتفظ Omniscol برموز JWT الصادرة ولا يمكنها تعطيل أحدها بمفرده: يبقى الرمز الذي سبق توليده صالحًا حتى انتهاء مدته الخاصة، أو حتى حذف مفتاحه أو انتهاء صلاحيته.
  • تعديل انتهاء مفتاح يؤثر فورًا في جميع رموزه: تبكير هذا التاريخ يقطع الوصول عن كل الرموز الصادرة عن المفتاح.

ممارسة جيدة: احذفوا دون انتظار كل مفتاح يُشتبه في تسربه، ثم أنشئوا مفتاحًا بديلًا بتسمية واضحة.

مفتاح لكل جهة ولكل استخدام

بما أن الإلغاء يتم حسب المفتاح، خصصوا مفتاحًا لكل تكامل (برنامج خارجي = مفتاح). لا يوقّع سر المفتاح إلا رموزه الخاصة: فحذف هذا المفتاح لا يبطل إلا وصول التكامل المعني، دون المساس بالتكاملات الأخرى.

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

في أي تكاملات يُستخدم

تُستخدم API عادةً في:

  • أنظمة العرض الرقمي المخصصة (إضافة إلى لوحات العرض الأصلية في Omniscol؛ راجعوا صفحة تخصيص اللوحات)،
  • لوحات التحكم الخارجية التي تجمع Omniscol ومصادر أخرى،
  • الموصلات أو المزامنات مع نظام ERP أو نظام معلومات مهني،
  • وكلاء الذكاء الاصطناعي المتوافقين مع MCP الذين يستخدمون Omniscol عبر خادم MCP؛ راجعوا صفحة MCP — ربط وكيل ذكاء اصطناعي خارجي.

للوصول المفوَّض إلى خدمة خارجية معرَّفة (رمز محدود النطاق، وموافقة المستخدم، وإمكانية الإلغاء بتعطيل العميل)، فضّلوا خادم OAuth2 في Omniscol: راجعوا صفحة OAuth2 / OIDC (المزوّد).

طريقة العمل

توليد رمز API

  1. يتيح رمز المصادقة لنظام خارجي (لوحة تحكم، أو عرض رقمي، أو وكيل ذكاء اصطناعي عبر MCP) الاستعلام عن نقاط الوصول في API التي حددتموها.

  2. انتقلوا إلى وحدة الإدارة ← استيراد / تصدير، ثم افتحوا شاشة المشاركة بالنقر على مشاركة. سترون فيها المفاتيح الموجودة وتسمياتها وتواريخ انتهائها إن وجدت.

  3. أنشئوا مفتاحًا عند الحاجة. أدخلوا تسمية واضحة (لوحة تحكم المالية، عرض ردهة الاستقبال، وكيل ذكاء اصطناعي Claude desktop) وتاريخ انتهاء إذا كان التكامل مؤقتًا. يمكنكم تعديل تاريخ انتهاء المفتاح لاحقًا.

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

  5. ولّدوا الرمز، ثم انسخوا فورًا JWT المعروض. لن يُعرض مرة أخرى ولا يمكن تعديل تاريخ انتهائه. استخدموه بعد ذلك في ترويسة HTTP Authorization: Bearer <jeton>.

  6. لإلغاء الوصول، احذفوا المفتاح المقابل. تصبح الرموز المشتقة من هذا المفتاح غير صالحة.

انظر أيضًا