- API لأنظمة العيادات يُقيَّم بوثائقه وبيئة اختباره، لا بعبارة «النظام يدعم API». اطلب قبل التعاقد ملف مواصفات الواجهة، وقائمة الأحداث، وسياسة الإصدارات، ودخولًا فعليًا إلى بيئة اختبار.
- احكم على الواجهة بسبعة محاور: التغطية (أي بيانات تُقرأ وتُكتب)، والمصادقة والصلاحيات، وWebhooks للأحداث، والحدود والأداء، والتوثيق وبيئة الاختبار، والإصدارات والتوافق، والدعم والملكية.
- أهم اختبار: أن تمر الكتابة عبر الـAPI بقواعد العمل نفسها التي تمر بها الواجهة، مثل منع تعارض المواعيد وكشف الملف المكرر.
- ما تثبته في الاختبار يُكتب في العقد: مهلة الإشعار قبل إيقاف إصدار، ومن يصون التكامل عند التحديث، وهل للاستخدام رسوم، وتصدير البيانات عبر الواجهة عند الخروج.
هذه المقالة لمدير تقنية المعلومات الذي سيُسأل بعد التعاقد: لماذا لا نستطيع ربط تطبيقنا أو موقعنا أو نظامنا المحاسبي بالنظام الجديد؟ تعطيك ما تطلبه في وثائق الـAPI، والسؤال الذي يكشف الإجابة الشكلية في كل محور، والدليل الذي تقبله، واختبارًا عمليًا ينفذه مطورك في بيئة الاختبار قبل التوقيع.
ما الذي تعنيه API وWebhooks في نظام العيادات؟
واجهة برمجة التطبيقات (API) هي الباب الذي تستخدمه أنظمتك الأخرى لتقرأ من نظام العيادات أو تكتب فيه دون تدخل موظف: الموقع يعرض المواعيد المتاحة ويحجز، والتطبيق يعرض النتائج والفواتير، ونظام المحاسبة يستلم القيود. الشائع في الأنظمة الحديثة واجهة REST بصيغة JSON، يرسل فيها نظامك طلبًا ويستلم ردًا.
أما Webhooks فهي الاتجاه المعاكس: بدل أن يسأل نظامك كل دقيقة «هل هناك جديد؟»، يرسل نظام العيادات رسالة إلى عنوان تحدده أنت لحظة وقوع حدث، مثل إلغاء موعد أو اعتماد نتيجة أو استلام دفعة. REST للسؤال والتنفيذ، وWebhooks للإخبار. التكامل الجيد يحتاج الاثنين.
لا تخلط بين معايير التبادل الصحية وواجهة النظام: دعم HL7 وASTM لأجهزة المختبر، وDICOM للأشعة، والربط مع منصة نفيس، شيء، وواجهة مفتوحة لأنظمتك أنت شيء آخر. نفيس مثلًا تعتمد تبادل رسائل وفق دليل التنفيذ المنشور على بوابة نفيس المبني على HL7 FHIR R4، ودعم النظام له لا يعني أن تطبيقك يستطيع الحجز فيه. اسأل عن كل منهما منفصلًا.
المحور الأول: التغطية، أي بيانات تُقرأ وتُكتب؟
أول سؤال ليس «هل يوجد API؟» بل «ماذا يغطي؟». كثير من الواجهات تتيح قراءة المرضى والمواعيد وتتوقف هناك. ابدأ من التكاملات التي تخطط لها، ثم اطلب من المورد أن يحدد لكل كيان: قراءة، أو كتابة، أو حدث، أو غير متاح.
| الكيان | استخدام نموذجي | قراءة | كتابة | حدث Webhook | ما تسأل عنه تحديدًا |
|---|---|---|---|---|---|
| المرضى | تطبيق المركز، والـCRM | مطلوب | مطلوب | مفيد | هل تمر الإضافة بكشف الملف المكرر نفسه؟ |
| الأوقات المتاحة | الحجز من الموقع والتطبيق | مطلوب | — | — | هل تحترم مدد الخدمات وقواعد الجدولة وإجازات الأطباء؟ |
| المواعيد | الحجز والإلغاء والتأكيد | مطلوب | مطلوب | مطلوب | هل يُرفض الموعد المتعارض برسالة خطأ واضحة؟ |
| الفواتير والدفعات | بوابة الدفع، والمحاسبة | مطلوب | حسب الحاجة | مطلوب | هل تُسجل الدفعة الخارجية على الفاتورة الصحيحة وتُقفل رصيدها؟ |
| النتائج والتقارير | تطبيق المريض | مطلوب | — | مطلوب | هل تُتاح النتيجة بعد اعتمادها فقط وبقواعد الإفراج نفسها؟ |
| المطالبات وحالتها | لوحات المالية وذكاء الأعمال | مفيد | — | مفيد | هل تظهر أسباب الرفض مصنفة؟ |
| الأصناف والمخزون | ERP والمشتريات | مفيد | حسب النطاق | مفيد | من المرجع للأصناف والأسعار: النظام الطبي أم الـERP؟ |
| الأطباء والجداول | الموقع والموارد البشرية | مطلوب | حسب النطاق | — | هل تُقرأ التخصصات والفروع وأيام العمل؟ |
العمود الأخير هو الأهم. واجهة تكتب موعدًا دون أن تمر بقواعد الجدولة تنتج مواعيد متعارضة لا يكتشفها أحد إلا عند حضور مريضين. القاعدة التي تطلبها: الكتابة عبر الـAPI تخضع لقواعد العمل نفسها في الواجهة، وتُسجل في سجل التدقيق باسم النظام المتصل. وإن كان تكاملك مع المحاسبة أو ERP تحديدًا، فتفاصيل ما يُرحّل ومطابقة دليل الحسابات في مقالة ربط النظام الطبي بالمحاسبة أو ERP.
ما تطلبه في كل محور: المتطلب والسؤال والدليل
الجدول التالي هو قائمة ما تطلبه قبل التعاقد. العمود الأخير يحدد الدليل الذي يكفي، والفرق كبير بين «مذكور في العرض» و«جرّبه مطورك».
| المحور | المتطلب | السؤال الذي تطرحه | الدليل المقبول |
|---|---|---|---|
| التغطية | قراءة وكتابة للكيانات التي تحتاجها | «ما الذي تفعله الواجهة ولا يتاح عبر الـAPI؟» | جدول الكيانات والعمليات من المورد، ومقارنته بملف المواصفات |
| التغطية | قواعد العمل نفسها عند الكتابة | «ماذا يحدث لو حجزتُ موعدًا متعارضًا عبر الـAPI؟» | تجربة في بيئة الاختبار ورسالة الخطأ |
| المصادقة | OAuth 2.0 أو مفاتيح منفصلة لكل نظام متصل | «هل يمكن إصدار مفتاح لتطبيق الحجز لا يرى الملف الطبي؟» | إنشاء مفتاح محدود النطاق وتجربته |
| المصادقة | تدوير المفاتيح وإلغاؤها وتسجيل الطلبات | «كيف نلغي مفتاحًا تسرب، وأين نرى طلباته؟» | تنفيذ الإلغاء، وسطر من سجل الطلبات |
| Webhooks | قائمة أحداث موثقة واشتراك لكل نظام | «ما الأحداث المتاحة؟ وهل أختار ما يستقبله كل نظام؟» | قائمة الأحداث بأمثلة الرسائل |
| Webhooks | توقيع الرسائل وإعادة المحاولة | «كيف أتحقق أن الرسالة منكم؟ وماذا لو كان نظامي متوقفًا ساعة؟» | التحقق من توقيع رسالة فعلية، ووصف سياسة الإعادة |
| الحدود والأداء | حدود طلبات معلنة وتقسيم النتائج إلى صفحات | «كم طلبًا في الدقيقة؟ وكيف أسحب بيانات سنة؟» | الحدود مكتوبة في الوثائق، ورد الواجهة عند تجاوزها |
| التوثيق | ملف مواصفات قابل للقراءة الآلية مع أمثلة ورموز أخطاء | «هل لديكم ملف OpenAPI أو ما يعادله؟» | الملف نفسه، واستيراده في أداة مطورك |
| بيئة الاختبار | Sandbox منفصلة ببيانات تجريبية | «متى نحصل على الدخول؟ وهل يمكن إعادة ضبط البيانات؟» | دخول فعلي قبل التعاقد |
| الإصدارات | إصدارات مرقمة ومهلة قبل إيقاف القديم | «كم مهلة الإشعار قبل إيقاف إصدار؟ وأين سجل التغييرات؟» | سياسة إصدارات مكتوبة، وبند في العقد |
| الدعم والملكية | مراقبة للتكاملات ومسؤول عن الأعطال | «من يكتشف فشل التكامل: نحن أم أنتم؟ ومن يصون التكامل المخصص بعد التحديث؟» | لوحة مراقبة التكاملات، وبند الصيانة والملكية |
| التكلفة | وضوح رسوم الاستخدام | «هل للـAPI رسوم منفصلة أو حد لعدد الطلبات في الباقة؟» | سطر واضح في عرض السعر |
المحور الثاني: المصادقة والصلاحيات لكل نظام متصل
من الأخطاء الشائعة في تكاملات المنشآت الصحية أن يُربط نظام خارجي بحساب مستخدم عادي، غالبًا بصلاحيات مدير، لأن الواجهة لا تتيح غير ذلك. النتيجة: تطبيق الحجز يستطيع نظريًا قراءة الملف الطبي لكل المرضى، وإن تسربت كلمة مروره فلا أحد يعرف أي طلب جاء منه.
ما تطلبه:
- هوية مستقلة لكل نظام متصل: عميل OAuth 2.0 أو مفتاح API خاص بتطبيق الحجز، وآخر للمحاسبة، وثالث للـCRM، لا حساب مشترك.
- نطاق محدد لكل هوية: تطبيق الحجز يقرأ الأوقات ويكتب المواعيد، ولا يرى التشخيص. نظام المحاسبة يقرأ الفواتير والقيود فقط. مبدأ الحد الأدنى من الصلاحيات يُطبق على الأنظمة كما يُطبق على الموظفين.
- الاتصال المشفر وتقييد المصدر: TLS لكل طلب، وإمكانية قصر مفتاح النظام الداخلي على عناوين شبكتك.
- تدوير وإلغاء فوري: تغيير المفتاح دوريًا دون توقف التكامل، وإلغاؤه فورًا عند الشك في تسربه.
- تسجيل كل طلب: أي نظام، وأي عملية، وعلى أي سجل، ومتى، وبأي نتيجة، ضمن الضوابط الأمنية التي تنطبق على المستخدمين.
البيانات التي تمر عبر الواجهة بيانات صحية حساسة كالتي تُعرض على الشاشة، وضوابطها جزء من تقييم الأمن كله، كما في مقالة أمن أنظمة إدارة العيادات: 20 ضابطًا ودليل كل ضابط.
المحور الثالث: Webhooks التي يمكن الاعتماد عليها
الـWebhook الذي يُرسل مرة واحدة ويُنسى إن فشل يصنع تكاملًا يعمل في العرض ويفقد رسائل في الواقع. اسأل عن ست خصائص:
- قائمة أحداث موثقة: إنشاء الموعد وإلغاؤه وتعديله، وتسجيل الوصول، واعتماد النتيجة، وإصدار الفاتورة، واستلام الدفعة، ورفض المطالبة، ونفاد الصنف. لكل حدث مثال للرسالة.
- توقيع رقمي: يتحقق نظامك من أن الرسالة جاءت من النظام الطبي لا من طرف ينتحله.
- إعادة المحاولة: عند تعذر الوصول إلى نظامك تُعاد الرسالة على فترات، ثم تُسجل فاشلة ويمكن إعادة إرسالها بعد إصلاح السبب.
- معرّف فريد لكل حدث: حتى يتجاهل نظامك الرسالة المكررة إن وصلت مرتين بسبب إعادة المحاولة.
- وقت الحدث داخل الرسالة: لأن الرسائل قد تصل بغير ترتيب وقوعها، فيعتمد نظامك على وقت الحدث لا وقت الوصول.
- اشتراك لكل نظام: تطبيق المريض يستقبل النتائج والمواعيد، والمحاسبة تستقبل الفواتير والدفعات، ولا يستقبل كل نظام كل شيء.
في الرسالة نفسها سؤال تصميم: هل تحمل البيانات كاملة، أم معرّف السجل فقط ثم يطلب نظامك التفاصيل؟ الثانية أكثر أمانًا لأن البيانات لا تغادر إلا لمن يملك صلاحية قراءتها، وتحتاج طلبًا إضافيًا. المهم أن تعرف أيهما قبل أن يبدأ مطورك.
مسار طلب نموذجي: حجز من موقع المركز حتى إلغائه من واتساب
المسار التالي يجمع REST وWebhooks في تكامل واحد شائع، ويصلح أساسًا لاختبار مطورك في بيئة الاختبار:
- طلب الأوقات المتاحةالموقع يطلب أوقات طبيب وخدمة في فرع لتاريخ محدد، بمفتاح لا يرى إلا الجدولةالموقع ← النظام
- إنشاء الموعدالموقع يرسل الموعد بمعرّف منع التكرار، والنظام يطبق قواعد الجدولة وكشف الملف المكرر، فيقبل أو يرفض برسالة خطأ واضحةالنظام يتحقق
- حدث «موعد جديد»Webhook موقّع إلى الـCRM أو التطبيق لإرسال التأكيد، مع معرّف الحدث ووقتهالنظام ← أنظمتك
- إلغاء من قناة أخرىالمريض يلغي بالرد على تذكير واتساب، فيتحرر الوقت في الجدولالمريض والنظام
- حدث «إلغاء موعد»Webhook يحدّث الموقع والتطبيق، ويعيد عرض الوقت متاحًا لغيرهالنظام ← أنظمتك
المحاور الرابع والخامس: الحدود والأداء، والتوثيق وبيئة الاختبار
الحدود والأداء
حدود الطلبات تحمي أداء النظام للمستخدمين، وهي مشروعة. المشكلة أن تكون غير معلنة فتكتشفها يوم يتوقف تطبيقك. اطلب: الحد لكل مفتاح في الدقيقة، والرد الذي يصلك عند تجاوزه ومتى تعيد المحاولة، وتقسيم النتائج الكبيرة إلى صفحات، وطريقة سحب بيانات فترة طويلة لأغراض التقارير أو أدوات ذكاء الأعمال دون إرهاق النظام أثناء الدوام، وإمكانية رفع الحد للتكاملات الكبيرة. وإن كان تكاملك يسأل النظام كل دقيقة عن الجديد، فهذه علامة أنك تحتاج Webhook بدل الاستعلام المتكرر.
التوثيق وبيئة الاختبار
التوثيق الجيد يسمح لمطور لم يتحدث مع المورد أن يبني تكاملًا بسيطًا في يوم. علاماته:
- ملف مواصفات قابل للقراءة الآلية (مثل OpenAPI) يستورده مطورك في أدواته
- مثال طلب ورد لكل عملية، ومنها أمثلة الأخطاء
- قائمة رموز الأخطاء ومعناها وما يفعله نظامك عند كل منها
- صيغة التواريخ والمنطقة الزمنية، وترميز النصوص العربية في الأسماء والعناوين
- معرّفات ثابتة للفروع والأطباء والخدمات، لا أسماء قد تتغير
- بيئة اختبار منفصلة ببيانات تجريبية واقعية، يمكن إعادة ضبطها، ومفاتيح تُصدر في اليوم نفسه
- سجل تغييرات مؤرخ لكل إصدار
إن كان المورد يرسل التوثيق «بعد التعاقد» فقط، فاطلب على الأقل جدول المحتويات وقائمة الكيانات والأحداث، واتفاقية عدم إفصاح إن لزم. لا توقّع على واجهة لم يرها مطورك.
المحوران السادس والسابع: الإصدارات والتوافق، والدعم والملكية
التكامل الذي يعمل اليوم قد يتعطل بعد تحديث. لذلك تسأل عن ثلاثة التزامات قبل التعاقد:
- إصدارات مرقمة وتغييرات غير كاسرة: الإضافة إلى الإصدار الحالي (حقل جديد، أو حدث جديد) لا تكسر تكاملك، والتغيير الكاسر يأتي في إصدار جديد يعمل بجوار القديم.
- مهلة مكتوبة قبل إيقاف إصدار: مدة كافية لمطورك ليحدّث التكامل، مع إشعار مكتوب وسجل تغييرات. اكتب المدة في العقد.
- توقيت التحديثات حسب خيار النشر: في السحابة المُدارة يحدّث المورد النظام، فاسأل كيف يُختبر تكاملك قبل ذلك. وفي النشر على خوادمك أو في سحابة خاصة يُجدول التحديث معك، فاختبره أولًا في بيئة Staging.
أما الدعم والملكية فتحسمها أسئلة مباشرة: من يكتشف فشل التكامل، هل توجد لوحة تعرض الرسائل الناجحة والفاشلة وسبب الفشل، ومن يتلقى التنبيه؟ ومن يملك التكامل المخصص الذي يبنيه المورد لك، ومن يصونه عند كل تحديث، وبأي تكلفة؟ وهل يمكنك تصدير بياناتك كاملة عبر الواجهة إن قررت المغادرة؟ ترتيب التكاملات نفسها في مجمع، وما تربطه أولًا وما تؤجله، موضوع مقالة خريطة التكاملات لمجمع طبي.
اختبار الساعتين الذي ينفذه مطورك قبل التوقيع
ادخل بيئة الاختبار واطلب من مطورك تنفيذ هذه المهام بنفسه، مستخدمًا الوثائق فقط، ودون مساعدة المورد إلا عند التعثر. سجّل الوقت ومواضع التعثر، فهي مؤشر على ما سيحدث في المشروع الحقيقي.
- الحصول على صلاحية الدخول
إصدار مفتاح أو عميل OAuth بنطاق «الجدولة فقط»، ثم محاولة قراءة ملف طبي به. المتوقع: رفض صريح.
المطور - قراءة الأوقات وإنشاء موعد
تنفيذ الخطوتين الأولى والثانية من المسار السابق، ثم محاولة موعد متعارض، ثم تكرار الطلب بمعرّف منع التكرار نفسه.
المطور - استقبال Webhook والتحقق منه
تسجيل عنوان استقبال، وإلغاء الموعد من واجهة النظام، والتحقق من توقيع الرسالة ووصولها.
المطور - اختبار الفشل
إيقاف عنوان الاستقبال، وإلغاء موعد آخر، ثم إعادة تشغيله: هل أعيدت الرسالة؟ وأين ظهرت في لوحة المراقبة؟
المطور ومدير التقنية - سحب بيانات كبيرة
طلب فواتير شهر كامل بالتقسيم إلى صفحات، وملاحظة الحدود والرد عند تجاوزها.
المطور - مراجعة السجل
فتح سجل الطلبات والتدقيق، والتأكد أن كل ما سبق مسجل باسم النظام المتصل.
مدير التقنية
إن تعثر المطور في أكثر من مهمتين بسبب نقص الوثائق لا بسبب خطأ منه، فاحسب ذلك في تقدير مدة التكامل وتكلفته، أو اطلب من المورد استكمال الوثائق قبل التوقيع. وبعد التعاقد يمر كل تكامل بمراحل مطابقة البيانات والبناء في بيئة الاختبار والاختبار المشترك والمراقبة، كما في خطوات تنفيذ التكامل.
إجابات تستحق التوقف
«نعطيكم دخولًا مباشرًا إلى قاعدة البيانات»: هذا ليس API. يتجاوز قواعد العمل والصلاحيات والسجل، وينكسر مع أول تغيير في بنية الجداول بعد التحديث.
«الـAPI متاح عند الطلب» دون وثائق: غالبًا يعني أن كل تكامل مشروع تطوير منفصل بتكلفته ومدته.
«نصدّر لكم ملفًا يوميًا»: قد يكفي للتقارير، ولا يكفي للحجز أو الدفع أو أي شيء يحتاج لحظته.
مفتاح واحد بصلاحيات كاملة لكل الأنظمة: لا يمكن تقييده ولا تتبعه، وإلغاؤه يوقف كل التكاملات معًا.
إن كان نظامك الحالي لا يوفر واجهة أصلًا، فبدائل الربط وحدودها ومتى يصبح ذلك سببًا للاستبدال في مقالة ماذا تفعل إذا كان نظامك الطبي لا يوفر API؟
كيف تختبر واجهة المنصة بهذه القائمة
توفر المنصة REST API بصيغة JSON مع بيئة اختبار منفصلة، بمصادقة OAuth 2.0 أو مفاتيح لكل نظام متصل بصلاحيات محددة، وإصدارات مرقمة، وحدود طلبات قابلة للرفع للتكاملات الكبيرة، وسجل لكل طلب. وترسل Webhooks موقعة للأحداث مع إعادة المحاولة واختيار الأحداث لكل نظام، ولكل تكامل لوحة مراقبة للرسائل الناجحة والفاشلة. وما لا يغطيه الإعداد، مثل تكامل بمنطق خاص بمنشأتك، يُنفذ ضمن مستويات التخصيص ويُحدد نطاقه ومدته في المشروع.
قبل أن تقرر: أرسل لنا قائمة الأنظمة التي تريد ربطها، ونرد بما يتبادله كل نظام وطريقة الربط، ونفتح لمطورك بيئة الاختبار لينفذ اختبار الساعتين بنفسه. ناقش تكامل المنصة مع أنظمتك واطلب دخول بيئة الاختبار.
أسئلة شائعة
هل يحتاج المركز الصغير إلى تقييم الـAPI أصلًا؟
إن لم يكن لديك موقع يحجز أو تطبيق أو نظام محاسبي منفصل، فالأولوية للتكاملات الجاهزة مثل واتساب وبوابة الدفع. لكن اسأل سؤالًا واحدًا على الأقل: هل تستطيع تصدير بياناتك كاملة عبر واجهة موثقة؟ لأنك ستحتاجه عند التوسع أو المغادرة.
ما الفرق بين التكامل الجاهز والتكامل عبر الـAPI؟
التكامل الجاهز يبنيه المورد مع نظام شائع ويُفعّل بالإعداد، مثل بوابة دفع معروفة. والتكامل عبر الـAPI يبنيه مطورك أو المورد مع نظام خاص بك. الأول أسرع وأقل تكلفة، والثاني ضروري لما لا يتوفر له تكامل جاهز.
هل يمكن لشركة أخرى أن تبني تطبيقنا على واجهة النظام؟
نعم إن كانت الواجهة موثقة وتغطي ما يحتاجه التطبيق، وهذا من أسباب طلب الوثائق قبل التعاقد. تأكد من أن الشركة تحصل على مفتاح بنطاق التطبيق فقط، وأن مسؤولية صيانة التطبيق عند تحديث الواجهة محددة بينكم.
كم يستغرق بناء تكامل عبر API؟
يعتمد على عدد الكيانات والاتجاه وتعقيد المطابقة بين النظامين. تكامل قراءة بسيط قد يُنجز في أيام إذا كانت الوثائق جيدة، وتكامل بالاتجاهين مع مطابقة أكواد وحسابات يحتاج أسابيع. اختبار الساعتين يعطيك تقديرًا أدق من أي وعد.
هل تكفي واجهة FHIR بدل واجهة النظام الخاصة؟
FHIR مناسب لتبادل البيانات السريرية مع أنظمة صحية أخرى بمعيار مشترك، لكن تكاملات التشغيل اليومي مثل الأوقات المتاحة والفواتير والمخزون تحتاج غالبًا واجهة النظام نفسها. اسأل المورد أي البيانات متاحة بكل منهما.