الربط مع منصة مقيم: دليل هندسي للإقامة

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

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

هذا المقال يشرح ما يعنيه «الربط مع مقيم» هندسياً، ولماذا معظم ما يُباع تحت هذا الاسم هو إعادة بيع وصول لا تكامل، وكيف تبني الطبقة التي تحتاجها فعلاً.

ما هي منصة مقيم ولماذا تختلف عن قوى ومدد

مقيم منصة تشغّلها شركة علم بالتعاون مع المديرية العامة للجوازات. مجالها هو كل ما يتعلق بالجوازات والإقامة للعمالة الوافدة:

• إصدار الإقامة وتجديدها ونقل المعلومات
• تأشيرات الخروج والعودة: إصدار، إلغاء، تمديد، إعادة طباعة
• تأشيرات الخروج النهائي
• تحديث بيانات جواز السفر وتمديد صلاحيته
• تقارير حالة المقيم والتحقق من التأشيرات

الخلط الشائع أن الشركات تعامل مقيم وقوى ومدد كثلاث بوابات متكافئة. ليست كذلك. لكل منها جهة مالكة مختلفة ونطاق مختلف:

الفارق ليس تصنيفياً. إنه ترتيب تنفيذي، وهذا هو جوهر المشكلة الهندسية.

سلسلة الاعتماديات التي تكسر معظم التكاملات

المعاملات في مقيم ليست مستقلة. هناك ترتيب صارم، وتجاهله هو السبب الأول للرفض:

رخصة عمل سارية (قوى)
        ↓
   تجديد الإقامة (مقيم)
        ↓
تأشيرة خروج وعودة (مقيم)
        ↓
   صلاحية الجواز تغطي المدة

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

النتيجة العملية: لا يمكن لنظامك أن يعامل «جدّد الإقامة» كاستدعاء واحد. عليه أن يتحقق من الحالة الأولى قبل محاولة الثانية، وإلا فأنت تدفع مقابل معاملة مرفوضة وتترك بيانات نظامك تدّعي نجاحاً لم يحدث.

هذا بالضبط النمط الذي شرحناه في الربط مع منصة قوى وأنظمة الموارد البشرية — وهو المتطلب السابق لأي عمل على مقيم.

الحقيقة غير المريحة: لا توجد واجهة برمجية عامة

ابحث عن «Muqeem API» وستجد عشرات النتائج: وحدات أودو، تكاملات جسر وزنHR ومناي تك، شركات تبيع «ربط فوري». ما لن تجده هو توثيق رسمي عام لنقاط النهاية.

السبب أن مقيم لا تعرض واجهة برمجية ذاتية الخدمة. الوصول البرمجي يمر عبر قنوات التكامل الرسمية لشركة علم — منصة «رابط» أو باقة تكامل مكافئة — ويتطلب:

1. اشتراك منشأة فعّال في مقيم من النوع الشامل (باقة العمليات وحدها لا تكفي للربط)
2. تفعيل صلاحية التكامل على حساب المنشأة
3. اعتمادات رسمية تُصدر باسم المنشأة، لا باسم المزوّد
4. تكلفة إضافية على الاشتراك — تشير مصادر المزوّدين إلى نطاق ١٢–٢٠٪ فوق قيمة الاشتراك مقابل تفعيل الربط
5. نموذج نقاط: كل معاملة تستهلك رصيداً من باقة المنشأة

النقطة الثالثة هي الأهم تجارياً وأكثر ما يُغفل. الاعتمادات ملك المنشأة. حين يبيعك مورّد «تكامل مقيم»، فهو في الغالب يبني موصّلاً فوق اشتراكك أنت. هذا مشروع، لكنه يعني أن الربط ليس ميزة حصرية لمنتجه — إنه شيء تملكه أنت ويمكن نقله.

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

أين تفشل التكاملات فعلياً

بعد سلسلة من مشاريع الربط مع المنصات الحكومية السعودية، الأعطال تتكرر بأربعة أشكال — ولا علاقة لأي منها بجودة الشيفرة:

١. انجراف الحالة الصامت

نظام الموارد البشرية يخزّن تاريخ انتهاء الإقامة كحقل. الجوازات هي مصدر الحقيقة. إن جُددت إقامة يدوياً عبر البوابة، أو أُلغيت تأشيرة، أو نُقلت كفالة — فحقلك أصبح خاطئاً ولا شيء يخبرك.

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

type MuqeemState = {
  iqamaNumber: string;
  iqamaExpiry: string;      // هجري في المصدر — حوّله مرة واحدة عند الحدود
  passportExpiry: string;
  exitReentryStatus: 'none' | 'active' | 'expired';
};
 
// لا تكتب فوق الحالة المحلية. اعرض الفروقات.
function reconcile(local: MuqeemState, remote: MuqeemState) {
  const drift = (Object.keys(remote) as Array<keyof MuqeemState>)
    .filter((k) => local[k] !== remote[k])
    .map((field) => ({ field, local: local[field], remote: remote[field] }));
 
  return drift.length
    ? { status: 'drift' as const, drift, authority: 'muqeem' }
    : { status: 'in_sync' as const };
}

٢. التقويم الهجري

تواريخ الإقامة هجرية. نظامك ميلادي على الأرجح. التحويل عند كل عرض هو وصفة لأخطاء يوم واحد — وخطأ يوم واحد في تاريخ انتهاء إقامة يعني غرامة.

القاعدة: حوّل مرة واحدة عند حدود النظام، وخزّن الاثنين. اعرض الهجري لأن المستخدم والجهة الحكومية يتحدثان به، واحسب بالميلادي.

٣. استنفاد النقاط في منتصف العملية

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

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

٤. غياب مبدأ عدم التكرار

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

// سجّل النية قبل الاستدعاء، لا بعد الاستجابة.
async function issueExitReentry(employeeId: string, days: number) {
  const key = `exit-reentry:${employeeId}:${days}:${businessDate()}`;
 
  if (await ledger.has(key)) {
    return ledger.get(key); // نُفّذت مسبقاً — لا تستدعِ مجدداً
  }
 
  await ledger.reserve(key);          // يبقى محجوزاً حتى لو انقطعت الشبكة
  const result = await gateway.call('exit-reentry/issue', { employeeId, days });
  await ledger.settle(key, result);
 
  return result;
}

انقطاع الشبكة بعد إرسال الطلب وقبل وصول الرد هو الحالة التي تُنتج التكرار. الحجز المسبق يجعل هذه الحالة قابلة للاكتشاف بدل أن تكون مكلفة.

البنية التي نوصي بها

المسار الشائع — دفع منطق مقيم داخل نظام الموارد البشرية أو وحدة أودو — يبدو أسرع ويصبح أغلى. أي تغيير في القواعد الحكومية يعني ترقية للنظام كله.

البديل هو طبقة وسيطة رفيعة تملكها أنت:

نظام الموارد البشرية / أودو / نظامك الداخلي
              ↓  (واجهة داخلية مستقرة)
      طبقة الامتثال (تملكها أنت)
              ↓
   بوابة علم / رابط  →  مقيم  →  الجوازات

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

هذا هو النمط ذاته الذي دافعنا عنه في فخ نظام تخطيط الموارد: التكامل لا الاستبدال، ونفس الطبقة التي تخدم الربط مع مدد للرواتب. ابنِها مرة، وصِل بها ثلاث منصات.

ملاحظة على البيانات الشخصية

بيانات الإقامة والجوازات بيانات شخصية بالمعنى الوارد في نظام حماية البيانات الشخصية السعودي. أرقام الإقامة وصور الجوازات وتواريخ التأشيرات ليست حقولاً عادية.

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

قائمة تحقق قبل أن تبدأ

• اشتراك المنشأة في مقيم من نوع شامل وصلاحية التكامل مفعّلة
• الاعتمادات صادرة باسم المنشأة لا باسم المورّد
• تكلفة تفعيل الربط ونموذج استهلاك النقاط موثّقان كتابةً
• رخص العمل في قوى سارية قبل أي محاولة تجديد إقامة
• التحويل الهجري/الميلادي يحدث عند حدود النظام مرة واحدة
• مفاتيح تفرّد على كل عملية تغيّر الحالة، مسجّلة قبل الاستدعاء
• تصنيف الأخطاء يفرّق بين الرصيد والتحقق والشبكة
• مواءمة دورية تُنبّه على الفروقات بدل الكتابة فوقها

الخلاصة

«الربط مع مقيم» ليس مشروع واجهة برمجية. إنه مشروع مواءمة حالة بين ثلاثة أنظمة حكومية ونظامك، تحت قيود منصة لا تعرض واجهة عامة وتحاسبك على كل معاملة.

المنشآت التي تنجح في هذا لا تشتري موصّلاً أفضل. إنها تعامل الامتثال كطبقة تملكها — تفهم الاعتماديات، وتمنع التكرار، وتُظهر الانجراف بدل إخفائه.

إن كنت تدير عمالة وافدة على جداول بيانات، أو تحمل موصّل مقيم يفشل بصمت، فابدأ بترسيم أين تعيش الحالة اليوم وأين تنجرف. غالباً ما تكون النتيجة أصغر مما تخشى وأوضح مما تتوقع.

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