API لأنظمة إدارة المشاريع: متى تحتاجه وماذا تسأل عنه
كل مورد يرد على بند الواجهة البرمجية بـ«ممتثل»، ثم يظهر الفرق بعد التعاقد. هذا الدليل لمسؤولي تقنية المعلومات يحدد متى تحتاجون API، وما الذي تفحصونه في توثيقه وجلسته التقنية، ومن يصون التكامل بعد بنائه.
تحتاج API لأنظمة إدارة المشاريع حين يجب أن يتبادل نظام آخر البيانات مع نظام المشاريع بانتظام ودون تدخل بشري، أو أن يتصرف فور وقوع حدث، أو أن تبني المنشأة تطبيقًا أو أتمتة فوقه. أما النقل لمرة واحدة أو التقرير الشهري أو النظام القديم الذي لا يملك واجهة، فيكفيه التصدير أو الملف المجدول. وعند التقييم لا تسأل «هل لديكم API؟» بل افحص ثماني مسائل في التوثيق وجلسة تقنية: التغطية، والمزامنة التدريجية، والمصادقة، والصلاحيات، والحدود، والإصدارات، وبيئة الاختبار، والمراقبة، ثم اكتب في العقد من يصون التكامل بعد بنائه.
في كراسات الشروط يتكرر بند «يوفر النظام واجهة برمجية API»، ويرد عليه كل مورد بـ«ممتثل». البند لا يكشف شيئًا؛ فواجهة تقرأ قائمة المشاريع فقط وواجهة تغطي كل ما في النظام بصلاحيات دقيقة كلتاهما API. هذا الدليل لمسؤول تقنية المعلومات الذي سيُسأل لاحقًا لماذا تعثر التكامل: متى تحتاج الواجهة فعلًا، وما الذي تقرؤه في توثيقها، وما الذي تختبره بيدك قبل الترسية.
هل تحتاج API فعلًا؟ ابدأ من التدفق لا من التقنية
قبل تقييم أي واجهة، اكتب قائمة التدفقات: ما البيانات التي تنتقل بين نظام المشاريع وكل نظام آخر، وفي أي اتجاه، وبأي إيقاع، وما الذي يحدث إن تأخرت. بعض هذه التدفقات يحتاج API، وبعضها يُحل بطريقة أبسط وأرخص صيانة:
- لااستيراد أو تصدير لمرة واحدة ضمن نقل البيانات
- نعمهل الغرض تحليل وتقارير بكميات كبيرة فقط؟
- نعمطبقة بيانات للتقارير أو تحديث مجدول لأداة التحليل
- لاهل يوفر النظام الآخر واجهة أو يستطيع استدعاء واجهة؟
- لاملف مجدول بصيغة متفق عليها، مع سجل ومطابقة
- نعمهل يجب التصرف فور وقوع حدث؟
- نعمWebhook يُبلغ بالحدث، وAPI لقراءة التفاصيل أو الكتابة
- لاAPI بمزامنة دورية تدريجية (ما تغير منذ آخر مرة)
- نعم
- لا
- نعم
ولاحظ الاستثناء في الشكل: الهوية والدخول لا تُبنى عادة بواجهة خاصة، بل بمعايير مثل SAML وOpenID Connect ومزامنة الدليل، كما تشرح صفحة التكاملات. من يطلب API لإنشاء المستخدمين من نظام الموارد البشرية قد يحتاج في الحقيقة مزامنة Active Directory الموجودة أصلًا.
API مقابل التصدير والملفات المجدولة
الفرق ليس في الحداثة بل في خمسة أشياء تهم من سيشغّل التكامل سنوات:
| المعيار | API | ملف مجدول | تصدير يدوي |
|---|---|---|---|
| حداثة البيانات | عند الطلب، أو فور الحدث مع Webhooks | بإيقاع الجدولة | حين يتذكر أحد |
| معالجة الخطأ | لكل سجل رد برمز خطأ يمكن معالجته برمجيًا | الملف كله ينجح أو يفشل ما لم يُصمم خلاف ذلك | يكتشفه الإنسان إن اكتشفه |
| الأمن | رمز بنطاق صلاحية محدد، وكل طلب مسجل | ملف يمر بمسار نقل يجب تأمينه وحذفه بعد الاستخدام | ملف على جهاز موظف |
| الاعتماد على النظام الآخر | يحتاج قدرة على الاستدعاء أو الاستقبال | يكفي أن يصدّر أو يقرأ ملفًا | لا شيء |
| كلفة الصيانة | كود يُصان عند تغير أي من النظامين | صيغة ملف تُصان، ومطابقة دورية | وقت موظف كل مرة |
القاعدة العملية: اختر أبسط طريقة تحقق حداثة البيانات المطلوبة فعلًا. تقرير أسبوعي لا يبرر تكاملًا لحظيًا، وترحيل ساعات معتمدة للرواتب قبل الإقفال لا يحتمل تصديرًا يدويًا. وتصف صفحة التكاملات هذه الطرق كلها في النظام: REST API، وWebhooks، ومعايير الهوية، وملفات مجدولة للأنظمة القديمة، وطبقة بيانات للتقارير، والاستيراد والتصدير. ومتى يُفضل الحدث على الاستعلام الدوري، وكيف يُصمم المستقبل ليتحمل التكرار والتأخر، تفصّله مقالة Webhooks في إدارة المشاريع.
حالات تبرر API في إدارة المشاريع
من واقع ما تطلبه المنشآت، هذه الحالات التي يصعب حلها دون واجهة برمجية:
- إنشاء المشروع من نظام آخر: عقد يُرسى في نظام العقود أو فرصة تُكسب في نظام العملاء، فيُنشأ المشروع برمزه وعميله وقيمته دون إعادة إدخال. تفاصيل الحالة الأخيرة في ربط إدارة المشاريع مع CRM.
- تحويل طلبات نظام الخدمة إلى مهام: بلاغ في نظام تذاكر يحتاج عملًا مخططًا، فيُنشأ مهمة ويعود إليه تقدمها.
- تدفقات مالية منتظمة: الالتزامات والمصروفات الفعلية إلى ميزانيات المشاريع، ورموز مراكز التكلفة في الاتجاه الآخر، وهي موضوع دليل ربط نظام إدارة المشاريع مع ERP.
- بوابات أو تطبيقات داخلية: شاشة مخصصة لإدارة أو لجهة خارجية تعرض جزءًا من بيانات المشاريع أو تستقبل تحديثات منها، بصلاحيات أضيق من النظام.
- تحديثات بالجملة وأتمتة داخلية: سكربت يغلق مهام دورية أو يحدّث حقلًا في مئات المشاريع بعد قرار تنظيمي، بدل تعديلها يدويًا.
أما لوحات التحليل على كميات كبيرة، فغالبًا تناسبها طبقة بيانات للتقارير أكثر من الواجهة التشغيلية، وتفصيل ذلك في دليل ربط بيانات المشاريع مع Power BI.
قراءة التوثيق: ثماني مسائل تقيّمها
اطلب التوثيق قبل العرض لا بعده، وأعطه لمطوّر سيبني التكامل فعلًا، لا لمن سيوقّع على الكراسة. وهذه المسائل الثماني وما تبحث عنه في كل منها:
| المسألة | ما تبحث عنه | إجابة مقنعة | علامة تستدعي التوقف |
|---|---|---|---|
| التغطية | هل تصل الواجهة إلى كل كيان تحتاجه تدفقاتك، بالعمليات التي تحتاجها (قراءة، إنشاء، تحديث)، بما فيها الحقول المخصصة والمرفقات؟ | قائمة موارد وعمليات منشورة، والحقول المخصصة تظهر في الاستجابة | «كل شيء متاح» دون قائمة، أو الحقول المخصصة غير مقروءة |
| المزامنة التدريجية | هل يمكن طلب ما تغير منذ تاريخ محدد، مع تقسيم النتائج على صفحات؟ | فلترة بتاريخ التعديل، وتقسيم صفحات موثق | لا طريقة إلا قراءة كل شيء في كل مرة |
| المصادقة | أي مسارات OAuth 2.0 مدعومة؟ هل توجد رموز مخصصة للتكاملات لا ترتبط بموظف؟ ما عمر الرمز وكيف يُجدد ويُلغى؟ | رموز للتكاملات بنطاقات، وإلغاء فوري من الواجهة | مفتاح ثابت واحد بصلاحية كاملة، أو اسم مستخدم وكلمة مرور موظف |
| الصلاحيات | هل يخضع كل طلب لصلاحيات صاحب الرمز، بما فيها إخفاء الحقول الحساسة؟ | الطلب المحظور يُرفض برمز خطأ واضح ويُسجل | الواجهة ترى كل شيء لأن «التكامل حساب نظام» |
| الحدود | كم طلبًا في الفترة؟ كيف يُبلغ التجاوز؟ هل تختلف في التشغيل الداخلي؟ | حدود موثقة، ورد صريح عند التجاوز يمكن للكود التعامل معه | حدود غير معلنة تُكتشف في الإنتاج |
| الإصدارات | كيف تُرقم الواجهة؟ كيف يُعلن التغيير الكاسر؟ وكم تبقى النسخة القديمة؟ | سياسة مكتوبة، وسجل تغييرات، وإشعار مسبق | «نحدّث باستمرار» دون إشعار أو نسخ |
| بيئة الاختبار | هل هي منفصلة عن الإنتاج؟ وبنفس إصداره؟ ومن يملأها ببيانات تجريبية؟ | بيئة مستقلة ببيانات تجريبية وإصدار مطابق | الاختبار على الإنتاج «بحذر» |
| المراقبة والسجل | هل يُسجل كل طلب بالتكامل والوقت والعملية؟ هل يرى فريقك الأخطاء؟ | سجل قابل للبحث، وتسجيل في سجل التدقيق | لا أثر للطلبات إلا في خوادم المورد |
وثلاثة تفاصيل صغيرة يغفل عنها كثيرون وتكلف لاحقًا: صيغة التواريخ في الاستجابة (يُفضل معيار موحد مثل ISO 8601 مع المنطقة الزمنية، والهجري للعرض لا للتبادل)، وسلامة النصوص العربية في الإرسال والاستقبال والبحث، وصيغة وصف الواجهة: هل يُنشر وصف آلي مثل مواصفة OpenAPI يولّد منه فريقك أدواته، أم توثيق نصي فقط؟ الثاني ليس عيبًا بذاته، لكن الأول يختصر وقت البناء والاختبار.
اختبار عملي في جلسة تقنية قبل الترسية
التوثيق يقول ما يجب أن يحدث، والجلسة التقنية تكشف ما يحدث. اطلب من كل مورد مؤهل وصولًا إلى بيئة الاختبار، أو جلسة ينفذ فيها مطوركم الخطوات بنفسه:
- أنشئ رمز تكامل بنطاق ضيق: قراءة المشاريع والمهام فقط. تأكد أن الإنشاء بنفس الرمز يُرفض.
- اقرأ قائمة كبيرة على صفحات: ثم اطلب ما تغير منذ ساعة فقط. قارن العدد بما تراه في الواجهة.
- أنشئ مهمة باسم عربي فيه همزات وتشكيل وحقل مخصص: ثم ابحث عنها من الواجهة الرسومية. هل الاسم سليم؟ وهل الحقل المخصص محفوظ؟
- حاول قراءة مشروع مقيد لا يملك الرمز صلاحيته: يجب أن يُرفض أو لا يظهر، لا أن يظهر بحقول فارغة.
- حدّث حقلًا ثم افتح سجل التدقيق: هل يظهر التعديل منسوبًا إلى التكامل بالقيمة قبل وبعد؟
- تجاوز الحد عمدًا بحلقة طلبات: ماذا يعود؟ في معيار HTTP يُستخدم الرمز 429 لكثرة الطلبات كما في RFC 6585. هل تعرف من الرد متى تعيد المحاولة؟
- ألغِ الرمز من الواجهة: هل يتوقف فورًا في الطلب التالي؟
- اسأل عن آخر تغيير كاسر: متى كان، وكيف أُبلغ العملاء، وكم بقيت النسخة القديمة. الإجابة بمثال حقيقي أقوى من سياسة مكتوبة.
سجّل النتائج في بطاقة واحدة لكل مورد: ثماني خطوات، لكل منها ناجح أو جزئي أو فاشل مع ملاحظة. إن تعذرت الجلسة قبل الترسية، فاجعلها شرطًا لقبول العرض الفني لا وعدًا لما بعد التعاقد.
الأمن في التكاملات: كل رمز باب إلى بياناتكم
التكامل مستخدم لا ينام، ولا يلاحظ أحد إن أساء أحد استعمال رمزه. لذلك تُطبق عليه قواعد المستخدم وأكثر:
- رمز مستقل لكل تكامل، لا رمز مشترك بين أنظمة، حتى يمكن إلغاء واحد دون إيقاف الباقي.
- نطاق صلاحية يقتصر على ما يحتاجه التدفق: نظام الرواتب يقرأ الساعات المعتمدة ولا يرى الميزانيات.
- تقييد عناوين IP المسموح لها بالاتصال إلى خوادم التكامل المعتمدة.
- حفظ الأسرار في خزنة أسرار لا في ملف إعدادات، وتدويرها دوريًا وعند مغادرة من اطلع عليها.
- مالك مسمى لكل تكامل في سجل التكاملات، وإيقاف رمزه عند إيقاف التكامل.
- مراجعة دورية لرموز التكاملات كما تُراجع صلاحيات المستخدمين.
ومصطلحات المصادقة التي ستظهر في التوثيق، مثل مسارات منح الرموز ومنها مسار بيانات اعتماد العميل للتكامل بين خادمين، معرّفة في معيار OAuth 2.0 (RFC 6749). وتذكر صفحة الأمن المؤسسي وصفحة API في النظام تقييد عناوين IP، ونطاقات الصلاحية لكل رمز، وتسجيل كل طلب في سجل التدقيق. وأسئلة الأمن الأوسع للمورد في دليل قراءة استبيان أمن المورد.
من يصون التكامل بعد بنائه؟
أكثر التكاملات لا تفشل يوم الإطلاق، بل بعد سنة: تحديث في أحد النظامين، أو رمز انتهت صلاحيته، أو حقل أضيف في طرف ولم يُضف في الآخر. والسبب أن أحدًا لم يُكلَّف بصيانته. قسّم المسؤوليات قبل البناء:
- مورد نظام المشاريعاستقرار الواجهةإشعار التغييرات الكاسرةبيئة الاختباردعم أخطاء الواجهة
- تقنية المعلومات في المنشأةكود التكامل أو إشرافهمراقبة الإخفاقاتالأسرار والرموزاختبار التحديثات
- مالك النظام الآخرإشعار تغييراتهحقوله ومعانيهامطابقة البيانات
- مكتب المشاريعتعريفات الحقولقرار تغيير التدفقتبليغ المستخدمين
وما يُكتب في العقد: سياسة إصدارات الواجهة ومدة الإشعار قبل أي تغيير كاسر، وهل يشمل الدعم أخطاء الواجهة نفسها، ومن يملك كود التكاملات التي يبنيها المورد وتوثيقها، وكيف يُسعّر تعديل تكامل بعد تغير النظام الآخر. وتقدير تكلفة كل واجهة قبل التعاقد موضوع دليل تكلفة تكامل نظام إدارة المشاريع.
سيناريو: شركة خدمات تقنية تربط نظام التذاكر
شركة افتراضية لخدمات تقنية المعلومات في الرياض، بنحو 120 مهندسًا و60 مشروعًا لدى عملائها، تدير البلاغات في نظام تذاكر والمشاريع في نظام منفصل. المشكلة: بعض البلاغات تتحول إلى أعمال مخططة (ترقية، نقل خدمة)، فتُنسخ يدويًا إلى المشاريع، ثم لا يعرف موظف الخدمة متى ستنتهي.
بدأ فريق تقنية المعلومات بطلب «API كامل في الاتجاهين»، ثم رسم التدفقات فوجد ثلاثة فقط: بلاغ يُصنف «عمل مخطط» يُنشئ مهمة في المشروع المرتبط بالعميل، وتغير حالة المهمة أو موعدها يعود إلى البلاغ، وساعات المهمة المعتمدة تُقرأ شهريًا للفوترة. التدفق الأول يحتاج API للإنشاء يستدعيه نظام التذاكر عند التصنيف. الثاني يُبنى على حدث من نظام المشاريع يقرأ بعده التكامل التفاصيل ويحدث البلاغ. والثالث لا يحتاج لحظية؛ تكفيه قراءة دورية تدريجية قبل الإقفال.
في الجلسة التقنية اكتشف الفريق أمرين لم يظهرا في الكراسة: أن رمز التكامل يجب أن يرى مشاريع كل العملاء لكن دون الحقول المالية، فصُمم له دور بصلاحيات مخصصة؛ وأن رقم البلاغ يحتاج حقلًا مخصصًا في المهمة يُقرأ ويُكتب عبر الواجهة للربط بين السجلين ومنع الإنشاء المكرر. كلاهما حُسم قبل البناء، وكُتب في وثيقة تصميم التكامل مع مالك لكل تدفق.
أين يقف النظام من هذه المسائل؟
تصف صفحة الواجهة البرمجية API وWebhooks في نظام إدارة المهام والمشاريع ما يلي: واجهة REST بصيغة JSON تغطي المشاريع والمهام والساعات والميزانيات والمخاطر والمخرجات والمستخدمين وبيانات التقارير، للقراءة والإنشاء والتحديث وفق الصلاحيات؛ ومصادقة عبر OAuth 2.0 أو رموز وصول مخصصة للتكاملات بنطاقات صلاحية لكل رمز، مع تقييد عناوين IP؛ وتنفيذ كل طلب بصلاحيات صاحب الرمز وتسجيله في سجل التدقيق؛ وحدودًا للطلبات تُضبط حسب نموذج التشغيل وتحددها المنشأة في التشغيل على سيرفراتها؛ وبيئة اختبار منفصلة ببيانات تجريبية؛ وWebhooks موقعة بأمثلة منها اعتماد مشروع وقبول مخرج واعتماد جدول زمني. وتضيف صفحة التكاملات سجل تكامل لكل عملية بنتيجتها، وإعادة محاولة تلقائية وتنبيهًا عند تكرار الفشل.
ومن حيث المستويات: الواجهة نفسها ميزة قائمة؛ وبناء تكامل مع نظام محدد مشروع تكامل ينفذه فريق المورد ضمن التنفيذ أو فريقكم بالتوثيق والبيئة التجريبية؛ وتصميم دور التكامل وصلاحياته وحقول الربط تهيئة؛ وأي نقطة اتصال أو منطق لا تغطيه الواجهة الحالية تطوير مخصص يُقدّر نطاقه كما في صفحة التخصيص. أما سياسة ترقيم الإصدارات ومدة الإشعار، والعمليات على كل مورد بالتفصيل، وصيغة وصف الواجهة، فاطلبها كتابيًا في الجلسة التقنية كما تطلبها من أي مورد.
الأسئلة الشائعة
نادرًا. الحدث يخبر النظام الآخر بأن شيئًا حدث، لكنه غالبًا يحتاج بعده قراءة التفاصيل أو كتابة نتيجة، وهذا عمل الواجهة. كما أن المزامنة الدورية بالواجهة تلتقط ما فات إن تعطل المستقبل وقت الحدث. وتصميم المستقبل نفسه مسؤولية من يبني التكامل.
يعتمد على قدرة فريقكم ومن سيصون التكامل. إن كان لديكم مطورون سيبقون مسؤولين عن النظامين، فبناؤه داخليًا بالتوثيق وبيئة الاختبار يسرّع التعديل لاحقًا. وإن لم يكن، فبناؤه من المورد ضمن التنفيذ أسلم، بشرط أن يُسلَّم توثيقه ويُحدد من يعدّله بعد التسليم.
حساب المستخدم مرتبط بموظف: يتغير بتغير دوره، ويُعطل عند مغادرته فيتوقف التكامل فجأة، ويختلط نشاطه في السجل بنشاط الموظف. رمز التكامل مستقل بنطاق محدد ومالك مسمى، ويُلغى أو يُدوّر دون أثر على أحد.
الواجهة نفسها لا تختلف في وظيفتها، لكن يتغير ما حولها: الربط يتم داخل شبكة المنشأة غالبًا دون فتح منافذ خارجية، وحدود الطلبات تحددها المنشأة، وتطبيق الإصدارات الجديدة يُجدول معها، فيصبح اختبار التكاملات على بيئة الاختبار قبل كل تحديث مسؤولية مشتركة.
بدل «يوفر النظام API»، اكتب التدفقات المطلوبة واتجاهها وإيقاعها، واطلب قائمة الموارد والعمليات، وسياسة الإصدارات، وطريقة المصادقة والصلاحيات، وبيئة اختبار، وجلسة تقنية ينفذ فيها فريقكم خطوات محددة. هكذا يصبح الرد قابلًا للتحقق لا مجرد «ممتثل».
الخلاصة: قيّم الواجهة بالتدفقات التي ستحملها
الواجهة البرمجية ليست ميزة تُعد، بل التزام يُصان. ابدأ بقائمة التدفقات لتعرف أيها يحتاج API فعلًا، ثم قيّم التوثيق بالمسائل الثماني، ونفّذ خطوات الاختبار بيد مطوركم، واكتب قبل التوقيع من يملك كل تكامل ومن يُبلغ بالتغيير.
وإن أردتم أن يرى فريقكم التقني التوثيق وبيئة الاختبار على تدفقاتكم الفعلية، فأرسلوا قائمة الأنظمة وما تريدون تبادله معها عبر صفحة التواصل لترتيب جلسة تقنية.