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