قبل الشراء افحص الواجهة نفسها لا وصفها: هل تغطي العمليات التي يحتاجها نظامكم فعلًا، وكيف تُصدر المفاتيح وتُحصر صلاحيتها وتُسحب، وما حدود الاستدعاء وماذا يحدث عند تجاوزها، وكيف تُقرأ البيانات على دفعات ومن نقطة آخر تغيير، وكيف تُعلن الإصدارات الجديدة وكم يبقى القديم. ثم جرّب ثلاثة اختبارات في بيئة تجربة: حالتكم الفعلية من أولها إلى آخرها، وحدود الصلاحية والخطأ، وأثر تغيير الإعدادات على ما تعيده الواجهة.
القرار في النهاية واحد من ثلاثة: تقبل الواجهة كما هي، أو تقبلها بشروط مكتوبة في العرض، أو ترفض بناء التكامل عليها وتختار ربطًا أبسط أو إجراءً يدويًا بالمرجع.
«لدينا واجهة ربط» ليست معلومة
كل مورد أنظمة زوار تقريبًا سيقول إن لديه واجهة برمجية. الجملة صحيحة غالبًا، ولا تعني شيئًا عن سؤالك أنت: هل يستطيع نظام الصيانة أو المشتريات لديكم أن ينشئ طلب زيارة ويقرأ حالته، بالحقول التي تحتاجها البوابة، دون أن يتعطل حين يغيّر مسؤول النظام اسم حالة أو يضيف حقلًا؟
ما يذكره موقعنا عن واجهاتنا محدد بنطاقه. بحسب صفحة التكامل مع الأنظمة والأجهزة، تُتاح واجهات API لإنشاء طلبات الزيارة أو قراءة حالتها أو سحب بيانات التقارير ضمن نطاق يُحدد في المشروع: تُسمّى فيه العمليات ومن يستدعيها والبيانات التي يصل إليها. ويُعطى كل تكامل مفتاحه وصلاحيته، ويُسجَّل استخدامه، ويبقى محصورًا في البيانات المتفق عليها. هذا يعني أن الواجهة بند يُقيَّم ويُسعَّر، لا ميزة جاهزة تُفترض. وهو ما يجعل الفحص قبل الشراء ضروريًا مع أي مورد، بما فيه نحن.
هذا المقال لا يكتب بند التكامل نفسه. ذلك موضوع بطاقة التكامل ذات الحقول العشرة وحالات فشلها وقبولها. هنا نسبقه بخطوة: هل الواجهة التي سيُبنى عليها البند تستحق أن يُبنى عليها؟
ثلاثة أشياء تطلبها قبل أي فحص
- وثيقة مرجعية للعمليات التي تحتاجونها: لا كتيّبًا تسويقيًا. لكل عملية: المسار أو الاسم، والمدخلات بحقولها وأنواعها وما هو إلزامي منها، والمخرجات، ورموز الخطأ، ومثال طلب ورد. إن كانت الوثيقة الكاملة تُسلَّم بعد اتفاقية سرية فهذا مقبول، أما ألا توجد وثيقة فليس مقبولًا.
- وصول إلى بيئة تجربة: بمفتاح تجريبي وبيانات وهمية، منفصلة عن أي بيئة تشغيل. بيئة التجربة المنفصلة عن التشغيل ممارسة تذكرها صفحة الاستضافة وأمن البيانات لتجربة التعديلات دون بيانات حقيقية. اسأل هل يمكن إتاحتها لفريقكم في مرحلة التقييم، أو في أول مرحلة من المشروع على الأقل.
- سياسة الإصدارات والتغيير: كيف يُعلن التغيير الذي يكسر التوافق، وبأي مهلة، وكم يبقى الإصدار السابق متاحًا، وأين سجل التغييرات.
أرسل مع الطلب قائمة بالعمليات التي يحتاجها نظامكم بلغة العمل لا بلغة البرمجة. مثلًا: «ينشئ نظام الصيانة طلب زيارة لفريق مقاول عند اعتماد أمر عمل خارجي، ويقرأ حالة كل فرد حتى الدخول». القائمة تحصر الفحص فيما يهمك، وتمنع المورد من إجابتك بقائمة عمليات لا تحتاجها.
قائمة فحص الواجهة: اثنا عشر بندًا
ما تفحصه في واجهة نظام الزوار قبل الشراء
اكتب أمام كل بند: مستوفى، أو مستوفى بشرط يُكتب في العرض، أو غير مستوفى. البنود ١ و٣ و٤ و١١ حاسمة: غياب أحدها يكفي لعدم بناء التكامل على الواجهة كما هي.
| البند | ما تفحصه | علامة الخطر |
|---|---|---|
| ١. تغطية عملياتكم | كل عملية في قائمتكم يقابلها استدعاء موثق: إنشاء الطلب، وإضافة الأفراد، وقراءة الحالة، وسحب بيانات التقارير | «يمكن إضافتها لاحقًا» لعملية أساسية |
| ٢. الحقول والنص العربي | الاسم بالعربية واللاتينية، وصيغة الجوال، ورقم الهوية بأنواعه، وحقول الفئة والمنطقة والمرجع، وحفظ النص العربي دون تشويه | أسماء عربية تعود رموزًا غير مقروءة، أو حقول مخصصة لا تظهر في الواجهة |
| ٣. المفاتيح والمصادقة | مفتاح لكل تكامل لا مفتاح عام، ومن يصدره، وكيف يُجدَّد ويُسحب فورًا، وأن الاتصال مشفّر | مفتاح واحد مشترك لكل الأنظمة، أو سحبه يحتاج طلب دعم |
| ٤. حصر الصلاحية | المفتاح مقيد بعمليات وبيانات محددة، وبالموقع في المجموعات متعددة المصانع | مفتاح نظام مصنع واحد يقرأ زوار كل المواقع |
| ٥. سجل الاستخدام | كل استدعاء مسجل بالوقت والمفتاح والعملية والنتيجة، ومن يطّلع على السجل لديكم | السجل لدى المورد وحده دون طريقة للاطلاع عليه |
| ٦. حدود الاستدعاء | الحد الموثق لعدد الاستدعاءات في الفترة، والرد عند تجاوزه، وهل يكفي لذروة بداية الوردية أو سحب تقرير شهري | حدود غير موثقة تُكتشف حين يُرفض الطلب صباح يوم التوقف |
| ٧. القراءة على دفعات | تقسيم النتائج إلى صفحات، والفلترة بالموقع والفترة، والقراءة «من آخر تغيير» بدل سحب الكل كل مرة | لا طريقة لقراءة ما تغيّر إلا بسحب السجل كاملًا |
| ٨. نموذج الخطأ | رموز ثابتة تفرّق بين خطأ في البيانات وخطأ مؤقت في الخادم، ورسالة تشرح الحقل الخاطئ | رد واحد عام لكل الأخطاء، فلا يعرف نظامكم هل يعيد المحاولة |
| ٩. منع الإنشاء المزدوج | حقل لمرجعكم (رقم أمر العمل مثلًا) يمنع إنشاء طلبين للحدث نفسه إذا أُعيد الإرسال | إعادة الإرسال بعد انقطاع تنشئ طلبًا ثانيًا لا يُكتشف إلا عند البوابة |
| ١٠. الأوقات والمنطقة الزمنية | صيغة موحدة للتاريخ والوقت بمنطقتها الزمنية، وفصل وقت الوصول عن وقت الدخول والمغادرة | أوقات بلا منطقة زمنية، أو وقت واحد يخلط الوصول بالدخول |
| ١١. الإصدارات والتغيير | رقم إصدار في الاستدعاء، ومهلة إشعار مكتوبة قبل التغيير الكاسر، وفترة بقاء الإصدار السابق، وسجل تغييرات | «نحدّث الواجهة مع النظام» دون إصدارات |
| ١٢. الأحداث الصادرة | هل تُرسل الواجهة إشعارًا لنظامكم عند تغيّر الحالة، أم يجب أن يسأل نظامكم دوريًا؟ وبأي تواتر مقبول؟ | لا أحداث صادرة ولا حد واضح لتواتر السؤال الدوري |
البند الثاني عشر سؤال مفتوح لا شرط جاهز. لا يذكر موقعنا أحداثًا فورية صادرة إلى الأنظمة الأخرى، فاطلب من أي مورد، بما فيه نحن، أن يوضح كتابةً هل تتوفر، أو يحدد البديل: سؤال دوري بتواتر متفق عليه يدخل في حساب حدود الاستدعاء في البند السادس.
ثلاثة اختبارات في بيئة التجربة
الوثيقة تخبرك بما يُفترض أن يحدث، وبيئة التجربة تخبرك بما يحدث فعلًا. ثلاثة اختبارات تكفي لكشف أغلب ما لا تقوله الوثيقة، ويمكن أن ينفذها مطوّر واحد:
| الاختبار | ما تنفذه | ما يجب أن تراه |
|---|---|---|
| أ. حالتكم من أولها إلى آخرها | من بيانات وهمية تشبه بياناتكم: طلب لفريق من خمسة أفراد بأسماء عربية، مرتبط بمرجع أمر عمل. ثم يُعتمد من واجهة المستخدم، ثم تُقرأ الحالة حتى «مسموح» | كل حقل وصل كما أُرسل، والحالة لكل فرد مستقلة، وعدد الاستدعاءات اللازمة معقول لحجم عملكم |
| ب. الحدود والأخطاء | مفتاح محصور بموقع يحاول القراءة من موقع آخر، وطلب ناقص حقلًا إلزاميًا، واستدعاءات متتابعة تتجاوز الحد المعلن، ثم إعادة إرسال الطلب نفسه بالمرجع نفسه | رفض موثق لكل حالة برمز يميّزها، وكل محاولة في سجل الاستخدام، ولا طلب ثانٍ بالمرجع نفسه |
| ج. أثر تغيير الإعدادات | يطلب مسؤول النظام في بيئة التجربة إضافة حقل إلى الفئة، وتغيير الاسم الظاهر لحالة، ثم تعيد استدعاء القراءة نفسها | الحالة تعود برمز ثابت لا يتغير بتغيير اسمها الظاهر، والحقل الجديد لا يكسر قراءة الحقول القديمة |
الاختبار الثالث خاص بأنظمة الزوار أكثر من غيرها. أنواع الزيارات والحقول ومسارات الاعتماد وأسماء الحالات تتغير بالإعدادات بيد فريق المصنع، وهذا مطلوب ومتاح كما تشرح صفحة مستويات التخصيص. لكن التكامل الذي يقرأ الاسم الظاهر للحالة بدل رمزها سينكسر في اليوم الذي يعدّل فيه مسؤول النظام كلمة. اكتشف ذلك في التجربة لا بعد التشغيل.
نجاح الاختبارات يثبت أن واجهة نظام الزوار صالحة، لا أن نظامكم يستطيع استدعاءها. الطرف الآخر يحتاج عملًا من مالكه أو مورده، ومسارًا شبكيًا مفتوحًا بين النظامين، خصوصًا إن كان أحدهما داخل بيئة المصنع والآخر مستضافًا. هذه كلها شروط تُحصر في تقييم التوافق وتُسعَّر، ولا يغطيها فحص الواجهة.
ما يُطلب قبل التوقيع وما يُشترط في العقد
ليس كل مورد يتيح بيئة تجربة قبل التعاقد، وبعضهم لا يسلّم الوثيقة الكاملة قبل اتفاقية سرية. هذا لا يُسقط المورد تلقائيًا، لكنه ينقل الفحص من مرحلة التقييم إلى شرط في العرض. فرّق بين الحالتين:
- قبل التوقيع، كحد أدنى: قائمة العمليات التي يغطيها المورد مقابل قائمتكم، وإجابة مكتوبة عن البنود ٣ و٤ و٦ و١١، ومثال طلب ورد حقيقي لعملية واحدة على الأقل.
- في العرض إن تعذّر الفحص الكامل: تسليم الوثيقة المرجعية وإتاحة بيئة التجربة في أول مرحلة من المشروع، وتنفيذ الاختبارات الثلاثة قبل بدء بناء الربط، وحق المنشأة في إيقاف بند التكامل أو تعديله إن لم تستوفِ الواجهة البنود الحاسمة، دون أن يمس ذلك بقية العرض.
- في العقد على أي حال: مهلة الإشعار قبل أي تغيير كاسر، وفترة بقاء الإصدار السابق، ومن يتحمل كلفة تعديل الربط إن تغيّرت الواجهة.
الشرط الثاني ممكن عمليًا لأن التكامل بند منفصل في العرض. صفحة التكلفة وعوامل التسعير تضع التكاملات بندًا مستقلًا بعد تقييم التوافق، فيمكن تأجيله أو تعديله دون إعادة تسعير المشروع كله.
مثال: واجهة جيدة على الورق
مهندس تكامل يفحص واجهة قبل ربط نظام الصيانة
مثال توضيحي افتراضيمثال توضيحي افتراضي، وليس نتيجة تشغيل موثقة لعميل. يريد المصنع أن ينشئ نظام الصيانة طلبات زيارة المقاولين آليًا. قدّم المورد وثيقة من صفحات قليلة ومفتاحًا لبيئة تجربة، وقال إن الواجهة «مستقرة ومستخدمة».
- قائمة الفحصالبنود ١ و٣ و٤ مستوفاة، والحد في البند السادس موثق ويكفي. لكن البند الحادي عشر غائب: لا رقم إصدار في الاستدعاء، والتحديث «مع النظام».
- الاختبار أنجح، مع ملاحظة أن اسم الفرد اللاتيني إلزامي في الواجهة رغم أنه اختياري في الشاشة. فطُلب توضيح، وتبيّن أنه إعداد في الفئة يمكن تعديله.
- الاختبار بإعادة إرسال الطلب بالمرجع نفسه أنشأت طلبًا ثانيًا، فالواجهة لا تستخدم حقل المرجع لمنع التكرار.
- الاختبار جالحالة تعود برمز ثابت، والحقل الجديد ظهر دون أن يكسر شيئًا. هذا أهم ما طمأن الفريق.
- القرارقبول بشروط. يُضاف إلى العرض منع الإنشاء المزدوج بالمرجع قبل بدء الربط، وإشعار مكتوب بمهلة متفق عليها قبل أي تغيير كاسر. ويُختبر الشرطان ضمن قبول التكامل.
أسئلة متكررة
ليس بالضرورة. اطلب الحد الأدنى قبل التوقيع: قائمة العمليات المغطاة، وإجابات مكتوبة عن المفاتيح والصلاحية والحدود والإصدارات، ومثال طلب ورد. ثم اجعل الاختبارات الثلاثة شرطًا في أول مرحلة من المشروع، مع حقكم في إيقاف بند التكامل إن لم تنجح.
يكفي في أغلب حالات الزيارات، لأن قرارات الاعتماد تُقاس بالدقائق لا بالثواني. المهم أن يُتفق على التواتر، وأن تسمح حدود الاستدعاء به في الذروة، وأن تدعم الواجهة القراءة «من آخر تغيير» حتى لا يُسحب السجل كاملًا في كل مرة.
هذا سؤال يجب أن تأتي إجابته مكتوبة. الأسلم أن يكون لكل تكامل مفتاح مستقل محصور بعملياته، وأن يُسحب فورًا عند الحاجة دون انتظار. وأن يكون سجل استخدامه متاحًا لكم، لا لدى المورد وحده.
لدينا، تُحدد العمليات المطلوبة ضمن نطاق المشروع بعد تقييم التوافق، ويظهر التكامل بندًا مستقلًا في العرض. ولدى أي مورد آخر، اسأل: هل للاستخدام رسوم متكررة أو حد يرفع الكلفة بزيادة الاستدعاءات؟ وأدخل الإجابة في مقارنة العروض.
سحب بيانات التقارير عبر الواجهة ممكن ضمن نطاق يُحدد، لا كوصول مفتوح لكل شيء. حدد ما يحتاجه التحليل فعلًا: أعداد وأزمنة بلا بيانات شخصية غالبًا. وراجع ذلك مع سياسة الاطلاع والاحتفاظ لديكم قبل طلب الحقول.