- اطلب من واجهات API لنظام إدارة الوثائق سبع مجموعات من العمليات: الوثائق وملفاتها وإصداراتها، والبحث والاستعلام بالمعرّف الخارجي، والملفات المجمعة، والإجراءات والاعتمادات، والتحقق من الصلاحيات، والقوائم المرجعية، وسجل التدقيق. وليست كلها لازمة لكل جهة، فرتّبها بحسب سيناريوهات الربط لديك.
- الضوابط أهم من عدد العمليات: حساب تكامل لكل نظام بصلاحيات محدودة، والعمل باسم المستخدم الفعلي حين يعرض نظام آخر وثيقة لموظف، وتسجيل كل استدعاء في سجل التدقيق.
- اطلب الأحداث (Webhooks) إلى جانب الاستدعاء، ومنها أحداث تُنسى عادة: اعتماد إصدار جديد، وإتلاف وثيقة أو تجميدها.
- اطلب أن يُعلن المورد حدود الواجهات كتابةً (حجم الملف، وعدد الطلبات، والتصفح بين النتائج)، وسياسة إصدارات تمنع كسر تكاملاتك مع كل تحديث، وتوثيقًا بمواصفة قابلة للقراءة الآلية.
- لا تقبل الواجهات وصفًا في العرض. اطلب بيئة اختبار وحساب تجريبي، ونفّذ فيها خمس عمليات بنفسك قبل التعاقد.
هذه المقالة لمدير تقنية المعلومات والبنية التحتية الذي يقيّم نظام أرشفة وإدارة وثائق، ويعرف أن النظام سيرتبط بأنظمة أخرى: التخطيط المالي، والموارد البشرية، والاتصالات الإدارية، وبوابات الخدمات. السؤال هنا ليس «هل لدى النظام API؟»، فكل مورد سيجيب بنعم، بل «ما العمليات والضوابط التي أطلبها كتابةً، وكيف أتحقق منها؟». أما تفاصيل ربط بعينه، مثل ربط الأرشفة بنظام ERP، فتجدها في مقالة ربط الأرشفة بـ ERP دون تكرار الإدخال.
ابدأ من سيناريوهات الربط، لا من قائمة العمليات
قائمة عمليات طويلة في طلب العرض تجلب إجابات «مطابق» طويلة، ولا تخبرك هل تستطيع تنفيذ ما تحتاجه فعلًا. ابدأ بكتابة سيناريوهات الربط المتوقعة في السنوات الأولى، ولكل سيناريو ثلاثة أسطر: من يبادر، وما الذي ينتقل، وما النتيجة المطلوبة. مثلًا:
- نظام يرسل وثيقة إلى الأرشيف: يعتمد النظام المالي أمر شراء، فيرسل ملفه وبياناته إلى الأرشيف، ويحتفظ بمعرّف الوثيقة المؤرشفة.
- نظام يعرض وثائق الأرشيف لمستخدميه: موظف في نظام الموارد البشرية يفتح ملف موظف، فيرى قائمة وثائقه من الأرشيف ويفتح ما تسمح له صلاحياته به.
- الأرشيف يُعلم نظامًا آخر بتغيير: اعتُمد إصدار جديد من عقد، أو أُتلفت وثيقة بعد انتهاء مدتها، فيجب أن يعرف النظام المرتبط ذلك.
- نظام يطلق إجراءً في الأرشيف: بوابة خدمات تستقبل طلبًا بمرفقاته، وتبدأ في الأرشيف مسار مراجعة، ثم تستقبل النتيجة.
كل سيناريو يحتاج إلى مجموعة من العمليات والضوابط. حين تجمعها تحصل على قائمة مرتبة بالأولوية، وتعرف أي العمليات تختبرها أولًا. وإن كان لديك نظام اتصالات إدارية، فحدود المسؤولية بينه وبين الأرشيف تسبق تصميم أي واجهة، وتجدها في مقالة تحديد مسؤولية الاتصالات الإدارية والأرشفة.
جدول العمليات المطلوبة
الجدول التالي يجمع العمليات التي تحتاجها سيناريوهات الربط الشائعة في الأرشفة. العمود الأخير يفرق بين ما تطلبه في كل الأحوال، وما تطلبه إن وُجد السيناريو الذي يحتاجه.
| المجموعة والعملية | لماذا تحتاجها | ما تسأل عنه تحديدًا | الأولوية |
|---|---|---|---|
| الوثائق: إنشاء وثيقة بملفها وبياناتها الوصفية في خطوة واحدة | كل سيناريو إرسال يبدأ بها | هل تُطبق الحقول الإلزامية وقواعد التحقق نفسها التي تُطبق على المستخدم؟ هل تُرفض الوثيقة الناقصة برسالة واضحة؟ | أساسية |
| الوثائق: رفع الملفات الكبيرة على أجزاء | المخططات والتسجيلات والملفات الممسوحة الكبيرة | ما الحد الأعلى لحجم الملف؟ هل يُستأنف الرفع بعد انقطاع؟ | حسب السيناريو |
| الإصدارات: إضافة إصدار، وقراءة الإصدار المعتمد أو إصدار بعينه | حتى لا يُنشأ عقد جديد كلما عُدّل العقد نفسه | كيف يُميَّز الإصدار المعتمد من المسودة في الاستجابة؟ | أساسية |
| البيانات الوصفية: قراءة وتحديث حقول محددة | تحديث حالة المعاملة أو رقم مرتبط دون إعادة رفع الملف | هل يُسجل التحديث في سجل الوثيقة بالقيمة قبل التعديل وبعده؟ | أساسية |
| الاستعلام بالمعرّف الخارجي | النظام المرسل يعرف معرّفه هو، لا معرّف الأرشيف | هل يمكن جعل المعرّف الخارجي فريدًا ومنع تكراره؟ | أساسية |
| البحث: بالحقول، وفي النص، مع ترتيب النتائج والتصفح بينها | عرض قائمة وثائق داخل نظام آخر | هل تُطبق صلاحيات المستخدم على النتائج والعدادات؟ هل يدعم البحث العربي بالصيغ نفسها التي في الواجهة؟ | أساسية |
| الملفات المجمعة: إنشاء ملف، وإضافة وثيقة إليه، وقراءة الناقص | ملف الموظف أو المشروع أو المورد يُبنى من أكثر من نظام | هل تُقرأ قائمة المستندات الناقصة عبر الواجهة؟ | حسب السيناريو |
| الإجراءات: بدء مسار اعتماد، وقراءة حالته ونتيجته | بوابة أو نظام خارجي يطلق مراجعة في الأرشيف | هل تصل النتيجة حدثًا أم باستعلام دوري؟ هل يُسجل المسار باسم من طلب البدء؟ | حسب السيناريو |
| الصلاحيات: التحقق من صلاحية مستخدم على وثيقة، والعمل باسمه | عرض الوثيقة لموظف في نظام آخر دون تجاوز صلاحياته | كيف يعرف الأرشيف المستخدم الفعلي خلف حساب التكامل؟ | أساسية |
| القوائم المرجعية: أنواع الوثائق والتصنيفات والقوائم الموحدة | حتى لا تُكتب القيم نصًا حرًا في النظام الآخر | هل تُقرأ القوائم بالمعرّف والاسم العربي معًا؟ | أساسية |
| سجل التدقيق: قراءة سجل وثيقة أو عمليات حساب تكامل | التحقيق في خطأ أو مراجعة ما فعله التكامل | هل تُقرأ عمليات حساب التكامل وحده؟ ومن يحق له ذلك؟ | حسب السيناريو |
| رابط العرض: رابط يفتح الوثيقة في معاين الأرشيف | بديل آمن لتنزيل الملف في النظام الآخر | هل يطلب الرابط دخول المستخدم؟ هل له مدة صلاحية؟ | حسب السيناريو |
الملاحظة الأخيرة في الشرح تستحق التوقف. بعض الموردين يعرضون واجهة حذف كاملة دليلًا على اكتمال الواجهات. في الأرشفة، هذه نقطة ضعف لا قوة. اطلب أن تمر أي إزالة عبر مسار الإتلاف المنضبط، وأن تقتصر واجهة التكامل على طلب إدراج الوثيقة في قائمة الاستحقاق إن احتجت إلى ذلك.
التكرار الصامت: عملية الإنشاء التي تُنفذ مرتين
أكثر عيوب التكامل شيوعًا لا يظهر في العرض التوضيحي. النظام المالي يرسل فاتورة إلى الأرشيف، وتنقطع الشبكة قبل وصول الرد، فيعيد المحاولة. هل أصبحت في الأرشيف فاتورتان؟ إن كانت الإجابة نعم، فستجد بعد أشهر وثائق مكررة بمعرّفات مختلفة، وقوائم نواقص خاطئة.
اطلب واحدًا من حلين، ويُفضّل الاثنان:
- معرّف خارجي فريد: يُضبط حقل المعرّف الخارجي فريدًا لنوع الوثيقة، فترفض الواجهة الإنشاء الثاني وتعيد معرّف الوثيقة الموجودة بدل إنشاء نسخة.
- مفتاح منع التكرار (Idempotency Key): يرسل النظام المرسل مفتاحًا مع كل طلب إنشاء، وإن تكرر المفتاح أعادت الواجهة نتيجة الطلب الأول نفسها.
واختبر ذلك بنفسك في بيئة الاختبار: أرسل الطلب نفسه مرتين، وانظر ماذا يحدث. وكيف تُعالج الطلبات التي فشلت فعلًا، بإعادة المحاولة والتنبيه والمطابقة الدورية، تفصّله مقالة إدارة أخطاء تبادل الوثائق بين الأنظمة.
المصادقة والتفويض: من يستدعي، وباسم من؟
الواجهة باب إلى الأرشيف كله، ويجب أن تُضبط كما تُضبط أبواب المستخدمين أو أشد. اطلب الضوابط التالية كتابةً:
- حساب تكامل لكل نظام: لا حساب مشترك بين النظام المالي والموارد البشرية. إن تسرب مفتاح أحدهما، أو تعطل، يُوقف وحده دون أن يتوقف الآخر.
- صلاحيات محدودة بالعمليات والتصنيفات: حساب النظام المالي يضيف وثائق في تصنيفات مالية محددة، ولا يقرأ ملفات الموظفين. وحساب يرسل فقط لا يحتاج صلاحية البحث.
- آلية مصادقة معيارية: مثل رموز الوصول وفق إطار OAuth 2.0، الذي يتيح منحة «بيانات اعتماد العميل» لنظام يتصل باسمه هو، أو آلية أخرى يوثقها المورد. المهم أن تكون الرموز محدودة المدة، وأن تُستبدل المفاتيح دوريًا دون توقف الخدمة، وأن تُلغى فورًا عند الحاجة.
- العمل باسم المستخدم الفعلي: حين يعرض نظام الموارد البشرية ملف موظف لمدير، يجب أن يطبق الأرشيف صلاحيات المدير نفسه، لا صلاحيات حساب التكامل الواسعة. اسأل كيف يتحقق ذلك: بالدخول الموحد مع الهوية المؤسسية، أو بتمرير هوية المستخدم في طلب موقع، أو بفحص الصلاحية قبل العرض.
- التسجيل: كل استدعاء يُسجل بحساب التكامل، والمستخدم الذي نُفذ باسمه إن وُجد، والعملية، والوثيقة، والنتيجة. وفتح وثيقة من نظام آخر يظهر في سجل الاطلاع كأي اطلاع.
- قيود الشبكة: تقييد الاستدعاء بعناوين الأنظمة المعروفة، والتشفير أثناء النقل، خصوصًا حين يعمل النظام داخل شبكة الجهة ويُستدعى من أنظمة في شبكات أخرى.
هذه الضوابط تقابل ما يوفره النظام في أمن التكامل: حساب لكل نظام بصلاحيات محدودة، ووثائق واردة تأخذ صلاحيات تصنيفها، وإمكانية إيقاف أي تكامل دون التأثير على بقية النظام.
الأحداث: حين يجب أن يبادر الأرشيف
الاستدعاء يخدم نظامًا يعرف متى يسأل. لكن بعض التغييرات تقع داخل الأرشيف، ويحتاج نظام آخر إلى معرفتها. البديل عن الأحداث استعلام دوري كل بضع دقائق عن «ما الجديد؟»، وهو مكلف وبطيء ومعرض للفوات. اطلب قائمة أحداث موثقة، منها:
| الحدث | من يحتاجه | لماذا يُنسى |
|---|---|---|
| اعتماد إصدار جديد | النظام الذي يعرض رابط الوثيقة أو يعتمد على محتواها | يُفترض أن الرابط يشير دائمًا إلى الأحدث، وقد يشير إلى إصدار بعينه |
| انتهاء مسار اعتماد | النظام الذي أطلق المسار وينتظر النتيجة | يُصمم الإطلاق وتُنسى العودة بالنتيجة |
| تغيير حالة أو تصنيف | الأنظمة التي تبني على الحالة قرارًا | إعادة التصنيف قد تغير من يرى الوثيقة |
| تجميد الوثيقة لحجز قانوني | الأنظمة التي قد تطلب تعديلها أو إتلافها | نادر الحدوث، فلا يُختبر |
| إتلاف الوثيقة | كل نظام يحتفظ برابط إليها | بعد الإتلاف يبقى في النظام الآخر رابط مكسور لا يعرف أحد سببه |
ولكل حدث متطلبات تشغيلية: معرّف فريد للحدث حتى لا يُعالج مرتين، وتوقيع يثبت أن الحدث صادر من الأرشيف، وإعادة إرسال عند فشل الاستلام، ومحتوى محدود يحمل المعرّف ونوع التغيير فقط. النظام المستقبل يطلب التفاصيل بعدها عبر الواجهة، فتُطبق عليه الصلاحيات، ولا تنتقل بيانات حساسة في رسالة لم يُتحقق من وجهتها.
الحدود المعلنة: ما يجب أن يكتبه المورد بالأرقام
لكل واجهة حدود، وهذا طبيعي. المشكلة أن تكتشفها في الإنتاج. اطلب من المورد أن يكتب في العرض أو في التوثيق حدود واجهاته بأرقام، وألا يكتفي بعبارة «قابل للتوسع». لا توجد أرقام صحيحة لكل جهة، لكن الغائبة منها علامة على أنها لم تُقس:
- الحد الأعلى لحجم الملف في الطلب الواحد، وطريقة رفع ما يتجاوزه.
- عدد الطلبات المسموح في الدقيقة لكل حساب تكامل، وما يحدث عند تجاوزه. السلوك المعياري أن ترد الواجهة بالرمز 429 «طلبات كثيرة جدًا» وقد تحدد مدة الانتظار قبل إعادة المحاولة، كما وصفته المواصفة RFC 6585.
- عدد النتائج في الصفحة الواحدة، وطريقة التصفح بين الصفحات في نتائج كبيرة.
- مهلة الطلب قبل انتهائه، خصوصًا في العمليات الثقيلة مثل البحث في النص أو رفع ملف كبير.
- هل تُعالج بعض العمليات لاحقًا (مثل قراءة النصوص في الملف الممسوح)، وكيف يعرف النظام المرسل أن المعالجة اكتملت؟
وافصل بين واجهات التشغيل اليومي وأدوات الاستيراد الجماعي. ترحيل مئات الآلاف من الوثائق القديمة عبر واجهة صُممت لوثيقة كل بضع ثوانٍ قد يعطل التشغيل اليومي. اسأل هل للترحيل أداة أو مسار مستقل، وكيف تُضبط أولويته.
التوثيق وسياسة الإصدارات
الواجهة التي لا يفهمها فريقك إلا بسؤال المورد ستبقى معتمدة عليه في كل تعديل. اطلب:
- توثيقًا بمواصفة قابلة للقراءة الآلية: مثل مواصفة OpenAPI، التي تصف الواجهات بصيغة يفهمها الإنسان والأداة معًا، وتتضمن وصفًا للأحداث الواردة. يسمح ذلك لفريقك بتوليد أمثلة واختبارات دون انتظار المورد.
- أمثلة ببيانات عربية: حقول بأسماء عربية وتواريخ هجرية وأرقام بالصيغ التي تستخدمها جهتك، لأن مشكلات الترميز تظهر هنا لا في الأمثلة الإنجليزية.
- فهرس رموز الأخطاء: لكل خطأ رمز ورسالة ومعنى وما يجب على النظام المرسل فعله: إعادة المحاولة، أو التصحيح، أو التنبيه.
- سياسة إصدارات مكتوبة: رقم إصدار للواجهة، وضمان ألا يكسر تحديث النظام الإصدار الحالي، ومدة إشعار قبل إيقاف أي إصدار قديم يُتفق عليها في العقد، وسجل تغييرات لكل تحديث.
البند الأخير يرتبط بعقد الدعم. تحديث النظام الذي يغير سلوك واجهة دون إشعار يوقف تكاملاتك في يوم التحديث. لذلك اجعل اختبار التكاملات جزءًا من دورة كل تحديث، كما في مقالة إدارة تحديثات النظام دون إرباك المستخدمين والتكاملات.
بيئة الاختبار، وخمسة اختبارات قبل التعاقد
اطلب بيئة اختبار للتكامل، منفصلة عن الإنتاج، بإصدار النظام نفسه، مع حساب تكامل تجريبي وبيانات غير حقيقية، وإمكانية إعادة ضبطها. ستحتاج إليها طوال عمر النظام، لا في التنفيذ فقط: كل تكامل جديد وكل تحديث يُجرّب فيها أولًا.
وقبل التعاقد، اطلب حسابًا تجريبيًا ليوم أو يومين، واطلب من مطور في فريقك تنفيذ الاختبارات التالية بالتوثيق وحده، دون مساعدة المورد إلا عند الضرورة. قدرته على إنجازها بالتوثيق مؤشر على جودة التوثيق نفسه:
- إنشاء وثيقة ببيانات عربية
ملف PDF مع نوع الوثيقة وحقول عربية وتاريخ هجري، ثم قراءتها والتأكد من سلامة النص والتاريخ.
مطور الجهة - الإنشاء المكرر
إرسال الطلب نفسه مرتين بالمعرّف الخارجي نفسه، والتأكد من عدم نشوء وثيقتين.
مطور الجهة - الوثيقة الناقصة
إرسال وثيقة دون حقل إلزامي، وقراءة رسالة الخطأ: هل تحدد الحقل الناقص؟
مطور الجهة - الصلاحية باسم المستخدم
البحث باسم مستخدم تجريبي محدود الصلاحية، والتأكد من أن النتائج والعدادات لا تكشف وثائق خارج صلاحيته.
مطور الجهة والأمن السيبراني - الحدث والتسجيل
اعتماد إصدار جديد واستقبال الحدث في خادم اختبار، ثم مراجعة سجل التدقيق للعمليات السابقة كلها.
مطور الجهة
هذه اختبارات تقييم قبل الشراء. أما اختبار التكاملات الفعلية قبل الإطلاق، بحالات النجاح والفشل والحجم، فموضوع مقالة اختبار التكاملات قبل إطلاق مشروع الأرشفة.
أخطاء شائعة عند طلب واجهات API
- السؤال عن الوجود لا عن السلوك: «هل يوفر النظام واجهات REST؟» سؤال إجابته نعم دائمًا. اسأل عن العمليات بسيناريوهاتها، وعن سلوكها عند الخطأ والتكرار وتجاوز الحدود.
- حساب تكامل بصلاحيات مدير النظام: يختصر الوقت في التنفيذ، ويجعل أي خلل في النظام المرتبط خللًا في الأرشيف كله.
- تنزيل الملف وتخزينه في النظام الآخر: حل سريع للعرض، ينتج نسخة خارج الصلاحيات والاحتفاظ والإتلاف. اعرض بالرابط أو بالمعاين، واجعل التنزيل استثناءً.
- الاكتفاء بالاستعلام الدوري: يعمل في البداية، ثم يثقل النظامين مع نمو الحجم، ويفوّت التغييرات بين دورتين.
- نسيان من يبني الطرف الآخر: الواجهة يوفرها مورد الأرشفة، لكن استدعاءها من داخل النظام المالي أو الموارد البشرية عمل يقوم به مورد ذلك النظام أو فريقك. اكتب هذا في الخطة والميزانية من البداية.
- ترك سياسة الإصدارات خارج العقد: تُكتشف أهميتها في أول تحديث يغير سلوك واجهة.
الخطوة التالية: وثيقة متطلبات الواجهات
حوّل ما سبق إلى وثيقة قصيرة ترفقها بطلب العرض: سيناريوهات الربط بأسطرها الثلاثة، والعمليات المطلوبة لكل سيناريو من الجدول، وضوابط المصادقة والتسجيل، والأحداث المطلوبة، وطلب الحدود المعلنة والتوثيق وسياسة الإصدارات، وشرط بيئة الاختبار والحساب التجريبي. طرق الربط المتاحة في النظام موضحة في صفحة التكامل مع الأنظمة، والفرق بين ما يتحقق بالتهيئة وما يحتاج إلى تطوير خاص، مثل تصدير بصيغة يطلبها نظام بعينه، في صفحة التخصيص.
وإن كانت لديكم سيناريوهات ربط محددة، فأرسلوها مع أسماء الأنظمة المقابلة واطلبوا تقييم نطاق التكامل. نوضح لكل سيناريو ما تتيحه واجهات النظام، وما يحتاج تعاون مورد النظام الآخر، ونعرض الواجهات عمليًا على سيناريو من سيناريوهاتكم قبل القرار.
أسئلة شائعة
أنظمتنا القديمة لا تستطيع استدعاء واجهات حديثة، فهل يمنع ذلك الربط؟
لا بالضرورة. يمكن أن يُبنى الربط على ما يتيحه النظام القديم: ملفات تصدير دورية في مجلد متفق عليه، أو قاعدة وسيطة، أو مكوّن وسيط يقرأ من النظام القديم ويستدعي واجهات الأرشيف. الثمن توقيت أقل فورية وجهد متابعة أعلى. ويُحدد الخيار بعد فحص النظام القديم، ويظهر بندًا مستقلًا في نطاق التكامل.
هل نحتاج إلى منصة تكامل وسيطة بين الأرشيف وبقية الأنظمة؟
إن كانت لدى جهتك منصة تكامل قائمة تمر بها الأنظمة الأخرى، فالأنسب غالبًا أن يمر بها الأرشيف أيضًا، فتبقى المراقبة والسجلات في مكان واحد. وإن لم تكن، فلا يلزم إنشاؤها لتكاملين أو ثلاثة. المهم أن تكون المراقبة وإعادة المحاولة موجودة في مكان ما، لا أن يُفترض أن كل استدعاء سينجح.
من يملك الشفرة التي تُكتب لاستدعاء الواجهات؟
يُحدد ذلك في العقد. الشفرة التي يكتبها فريقك أو مورد النظام الآخر داخل أنظمتكم تتبع عقودها. أما ما يطوره مورد الأرشفة خصيصًا لجهتك، مثل مكوّن وسيط أو تحويل صيغة، فاطلب أن يُنص على ملكيته أو حق استخدامه، وعلى تسليم توثيقه، حتى لا يصبح نقطة اعتماد لا يعرفها غيره.
هل تكفي مواصفة الواجهات وحدها لتقدير تكلفة التكامل؟
لا. التكلفة تعتمد على الطرفين: ما يتيحه الأرشيف، وما يتيحه النظام المقابل، ومن يبني الاستدعاء، وعدد حالات الخطأ التي يجب معالجتها. لذلك يُقدّر كل تكامل بعد فحص واجهات النظام المقابل، ولا يصح قبول سعر ثابت لتكامل مع نظام لم يطّلع المورد على واجهاته.