عند ربط نظام أعمال عن بُعد بالمنصة، لا تكون المشكلة عادةً في استدعاء الواجهة نفسه، بل في «من يحمل أي بيانات اعتماد، ومتى تنتهي صلاحيتها، وخلال أي مدة يظهر أثر إلغاء العضوية». هذه الثلاثة هي ما يحدد إن كان النظام سيظل سليمًا بعد أشهر. وفيما يلي ما نلتزم به على هذا المسار، وأين تقع الحدود.
مستويان من بيانات الاعتماد، والطويل الأجل لا يغادر الخادم
تصدر المنصة نوعين من الهوية. هوية خدمة الوحدة طويلة الأجل، وتبقى على خادم نظام الأعمال فقط، وتُستخدم لتبادل Launch Grant (POST /integration/v1/sso/launch-grants/exchange) وطلب رمز خدمة المثيل (POST /integration/v1/service-tokens). أما رمز خدمة المثيل فهو قصير الأجل: خمس دقائق كحد أقصى، وجمهور ثابت، ونطاقات مضيّقة على الطلب الحالي، ويُعاد مع no-store.
لذلك لا يستلم المتصفح بيانات اعتماد الوحدة أبدًا؛ فالواجهة تسلّم رمز الدخول الذي وصلها إلى خادمها فقط، ويجري كل تبادل على الخادم. وبخصوص الرموز قصيرة الأجل يحتفظ الـSDK بها حسب «المثيل + مجموعة النطاقات المطلوبة» لمدة 300 ثانية كحد أقصى، دون Refresh: يطلب رمزًا جديدًا عندما تنزل المدة المتبقية تحت هامش الأمان، ولا يحدث التبادل إلا مرة واحدة عند تعدد الاستدعاءات، ولا يُعاد استخدام الرمز بين المثيلات.
Launch تبادل لمرة واحدة، والناتج جلسة خاصة بنظامك
ما يحمله المستخدم القادم من المنصة هو رمز الدخول لا بيانات اعتماد طويلة الأجل. يتبادل الخادم الـGrant ويستهلكه بهوية خدمة الوحدة، ثم ينشئ جلسة محلية خاصة بنظام الأعمال؛ ولا تُخزَّن في الجلسة سوى الهوية المشتقة، دون رمز المنصة أو رمز الدخول أو Client Secret أو المطالبات الكاملة.
ويخضع التبادل وفحوص الجلسة للتحقق من التوقيع: يُستخدم JWKS الخاص بوقت تشغيل المنصة لفحص الخوارزمية والمصدر والجمهور ومدة الصلاحية وtoken_use والحساب والمثيل والنطاقات، مع مصدر مفاتيح يرفض إعادة التوجيه ويحدّ من حجم الاستجابة. ومن السهل الخلط هنا: حالة «الاتصال سليم» في صفحة الدخول تثبت فقط أن الخادم يستطيع قراءة المفاتيح العامة، ولا تثبت أن الزائر سجّل الدخول، ولا أن مسار Launch يعمل. افصل بين الثلاثة.
عند إلغاء العضوية، يجب أن تتقارب الجلسة المحلية
كون الجلسة على المنصة صالحة لا يعني أن الجلسة المحلية تستمر بلا نهاية. خلال جلسة طويلة، يجب أن تصل إزالة عضو أو تغيّر دور أو إيقاف مثيل إلى نظام الأعمال خلال مدة محدودة. والوسيلة فحص جماعي بهوية خدمة المثيل (POST /integration/v1/session-checks): تكون active صحيحة فقط عندما يكون المثيل وعضوية المثيل والحساب وعضوية الحساب كلها صالحة، أما غير الأعضاء والمستخدمون غير الموجودين فيعيدون active=false فلا يتسرّب وجود العضوية. ويتقارب كل نظام بحسب النافذة التي يعلنها، وعمليًا يمكن أن تكون نافذة الكتابة أقصر من نافذة القراءة.
إن لم تكفِ النطاقات، فأخفِق محليًا
يحمل كل طلب وقت تشغيل نطاقاته. ولا يعيد الـSDK بيانات اعتماد قابلة للاستخدام إلا عندما تغطي النطاقات الممنوحة فعليًا الطلب الحالي؛ وإلا يفشل محليًا ولا يرسل أي طلب أعمال. وتكمن قيمة هذه القاعدة في فصل «المنصة لم تصرّح» عن «فشل استدعاء المنصة»: فالأول مشكلة إعداد ينبغي أن تظهر فورًا، لا أن تتحول إلى خطأ غامض من الأعلى.
التكرار الآمن وإعادة المحاولة مسؤولية المستدعي
لا يعيد الـSDK أي طلب تلقائيًا. يجب أن يوفّر المستدعي مفتاحًا مستقرًا للتكرار الآمن في عمليات الكتابة، ولا يُعاد إرسال الطلب الفاشل؛ لأن «النتيجة غير معلومة» و«الفشل» حالتان مختلفتان، ونظام الأعمال وحده يعرف هل يعيد الإرسال أو يستعلم أو يخبر المستخدم. وفي الأخطاء، تُقابل Problem Details تصنيفات مستقرة (غير مصادق، ممنوع، تعارض، تجاوز الحد، خطأ خادم...) مع تعليم إمكانية الإعادة، ولا تصل بيانات الاعتماد ولا متن الاستجابة إلى السجلات أو تسلسل الأخطاء.
منتجان ومساران للحصول
لا يتساوى الـSDKان في طريقة الحصول، لذا تحقق أولًا من أيّهما يخصّك. في TypeScript / Node الحزمة @td-runlume/platform-integration-sdk على npm العام برخصة Apache-2.0 للاستخدام على الخادم. وفي Java الإحداثية app.runlume.platform:platform-integration-sdk-java تُقدَّم من مستودع Nexus الخاص بالمنصة وليست على Maven Central؛ ولا يجوز استخدامها إلا ببيانات اعتماد وترخيص تمنحهما المنصة، ولا يُعاد توزيع المنتجات. ويُستخدم مسار Java عادة مع Spring Boot Starter، إذ يجمع الـStarter مكوّنات الـSDK وخط التحقق من صلاحية الجلسة المحلية، ولا يوفّر نظام الأعمال سوى نقطتي توسعة: حدود الجلسة وقراءة مساحة العمل.
تتبع مسارات النقاط وأسماء النطاقات والقدرات المتاحة العقد والوثائق المتفق عليها عند التعاقد. يقتصر هذا المقال على الحدود التي يلتزم بها الخادم؛ ويمكن البدء من قدرات المنصة.