تقييم API الأرشفة: الأخطاء وإعادة المحاولة والتكرار وحدود الاستخدام

حين يقارن مهندس التكامل أو مدير تقنية المعلومات بين عروض أنظمة أرشفة، يُطلب منه غالبًا رأي في «جودة الواجهة البرمجية». عبارة «يوفر API مفتوحًا وموثقًا» تظهر في كل العروض تقريبًا، ولا تقول شيئًا عما سيحدث في الليلة التي ينقطع فيها الاتصال أثناء إرسال ثلاثة آلاف فاتورة. ما يلي معايير قابلة للاختبار، مبنية على معايير HTTP المعتمدة، وقائمة اختبارات يمكن تنفيذها في يوم عمل واحد على بيئة تجريبية.

لماذا تقيّم الفشل لا النجاح؟

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

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

الأخطاء: ما الذي يجب أن تعيده الواجهة؟

ثلاثة متطلبات أساسية تكتبها في كراسة الشروط:

• رموز حالة صحيحة: خطأ في الطلب نفسه (حقل ناقص، نوع ملف غير مسموح) يعيد رمزًا من فئة 4xx، وخطأ في الخادم يعيد رمزًا من فئة 5xx. واجهة تعيد 200 مع رسالة «فشل» داخل الجسم تجبر المطوّر على قراءة كل استجابة نصيًا، وتخفي الأخطاء عن أدوات المراقبة.
• جسم خطأ ثابت البنية: حقول معروفة في كل خطأ: نوع الخطأ، ووصف مختصر، وتفصيل خاص بهذه الحالة، ومعرّف يسمح بتتبعها في سجلات المورد. يعرّف المعيار RFC 9457 صيغة «تفاصيل المشكلة» لواجهات HTTP بحقول type وtitle وstatus وdetail وinstance، ويمكن أن يكون مرجعًا مفيدًا، وإن لم يكن إلزاميًا.
• أخطاء تحدد الحقل: «بيانات غير صالحة» لا تساعد. «حقل رقم الفاتورة مطلوب لنوع المستند فواتير الموردين» يوفر ساعة تحقيق.

إعادة المحاولة: أي خطأ يُعاد ومتى؟

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

المعيار RFC 6585 يعرّف الرمز 429 بأنه إرسال طلبات كثيرة خلال مدة معينة، وينص على أن الاستجابة يجوز أن تتضمن ترويسة Retry-After تحدد مدة الانتظار قبل طلب جديد. الواجهة الجيدة تستعملها، والعميل الجيد يحترمها.

التكرار: السؤال الذي يكشف نضج الواجهة

الصف الأخير في الجدول أعلاه هو أصعب حالة: أرسل الربط المستند، وانقطع الاتصال قبل أن يصل الرد. هل حُفظ المستند أم لا؟ إن أعاد الربط الإرسال والمستند محفوظ فعلًا، فستحصل على نسختين. إن لم يُعِد والمستند غير محفوظ، فقدته.

يعرّف المعيار RFC 9110 الطريقة «متساوية الأثر» (idempotent) بأنها التي يكون أثر تكرار الطلب نفسه على الخادم مثل أثر إرساله مرة واحدة، ويعدّ منها GET وPUT وDELETE، بينما POST ليست كذلك. ولأن إنشاء مستند جديد يتم غالبًا بطلب POST، تحتاج الواجهة آلية إضافية لمنع التكرار. الآليات الشائعة:

اسأل المورد صراحة: أي هذه الآليات تدعمها الواجهة؟ وأرني ذلك في بيئة الاختبار. الجواب «النظام لا يسمح بالتكرار» دون شرح الآلية ليس جوابًا.

حدود الاستخدام: موثقة ومعلنة ومنفصلة للترحيل

كل واجهة لها حدود، سواء وُثقت أم لا. المهم أن تكون معروفة قبل التشغيل. مثال على توثيق جيد من منصة أخرى: توثيق Microsoft لحدود حماية الخدمة في Dataverse يذكر الحدود الافتراضية بالأرقام، وأنها تُقاس في نافذة متحركة مدتها خمس دقائق، وأن تجاوزها في Web API يعيد 429 مع Retry-After بعدد الثواني، وينبه إلى أن الأرقام قابلة للتغيير. هذا مستوى الوضوح الذي تطلبه من أي مورد.

ما تسأل عنه تحديدًا:

• ما الحدود: عدد الطلبات في مدة زمنية، أم حجم البيانات، أم الطلبات المتزامنة، أم كلها؟ وهل تختلف بين الاستضافة السحابية المشتركة والخاصة وخوادم الجهة؟
• هل الحد لكل حساب تقني أم للمؤسسة كلها؟ إن كان للمؤسسة، فربط ERP قد يؤثر على ربط CRM.
• هل يوجد مسار أو إعداد مختلف للترحيل الأولي والأحجام الكبيرة، أم يمر الترحيل عبر الواجهة نفسها بالحدود نفسها؟
• كيف تُعلَن الحدود في الاستجابة: رمز 429 وترويسة Retry-After، أم شيء آخر؟

قائمة اختبارات التقييم

نفّذ هذه الاختبارات على بيئة تجريبية يوفرها المورد، بحساب تقني مخصص، وسجّل النتيجة لكل منها. الأولوية «حرجة» تعني أن الفشل فيها يجب أن يُعالج قبل القبول.

مثال: دفعة فواتير ليلية

الحد الأدنى من أمان الواجهة

التقييم هنا ليس مراجعة أمنية كاملة، لكن أربعة أسئلة لا تُترك:

• المصادقة: بأي آلية؟ وهل للرموز صلاحية زمنية؟ وكيف تُجدد أو تُلغى؟
• الحساب التقني: هل يمكن تقييده بمجلدات وأنواع مستندات بعينها بدل صلاحية شاملة؟
• النقل: هل الاتصال مشفر دائمًا؟ يتيح وثيقة التشفير أثناء النقل بـ TLS 1.3 وأثناء التخزين بـ AES-256.
• الأثر: هل تظهر كل عملية عبر الواجهة في سجل التدقيق كما تظهر عمليات المستخدمين؟

للمراجعة الأمنية الأوسع للمورد، راجع استبيان الأمن التقني الذي يُرسل إلى موردي أنظمة الأرشفة.

واجهة وثيقة في هذا الإطار

يوفر وثيقة REST API للتوصيل مع الأنظمة المؤسسية التي لا يتكامل معها مباشرة، مثل Odoo وMicrosoft Dynamics وأنظمة الموارد البشرية وCRM، وكذلك ربط مزود التوقيع الإلكتروني المعتمد لدى الجهة بالتوقيع الذي يدعمه وثيقة ضمن مسار الاعتماد. ويتكامل مباشرة مع Microsoft 365 وSAP ERP وOracle والبريد الإلكتروني وActive Directory/LDAP. وكل عملية تُسجَّل في سجل تدقيق محمي بالتجزئة وقابل للتصدير. أما آلية منع التكرار وبنية الأخطاء وحدود الاستخدام لبيئتك فتُطلب مكتوبة في العرض الفني وتُختبر بالقائمة أعلاه؛ واطلب ذلك في العرض التوضيحي أو في تجربة إثبات المفهوم.

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

حوّل الاختبارات إلى شرط في العرض

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