سيناريوهات الربط بين نظام نما والأنظمة الأخرى
مقدمة
يَرِد إلينا – بشكل شبه يومي – سؤالٌ من العملاء ومن الزملاء في فِرَق المبيعات والتجهيز والدعم الفني على هيئة:
«هل يمكن أن نَربط نظام نما مع النظام الفلاني؟»
وغالبًا ما يأتي السؤال مُجرَّدًا بلا تفاصيل، فيكون الردُّ السريع عليه بـ«نعم» أو «لا» ردًّا غيرَ دقيق؛ إذ إنّ إمكانيّة الربط – ومدى تكلفته – لا تتوقّف على قدرات نظام نما وحده، وإنّما تتوقّف كذلك على قدرات النظام الآخر، وعلى اتّجاه تدفُّق البيانات بين النظامين، وعلى مدى توفُّر واجهات برمجيّة (APIs) موثَّقة لدى الطرف الآخر.
ولذلك نُقدِّم في هذه الوثيقة إطارًا منهجيًّا للإجابة عن هذا السؤال؛ بحيث يَستطيع زميلُنا في فريق المبيعات أو التجهيز – بل والعميلُ نفسه – أن يَطرح الأسئلة الصحيحة قبل أن يَطلب عرضًا فنيًّا أو ماليًّا، فنَختصر بذلك دوراتٍ كثيرةً من الأخذ والرَّدّ، ونصل إلى قرارٍ سليمٍ في وقتٍ قصير.
ملخّص سريع
نظام نما مفتوحٌ افتراضيًّا للربط مع الأنظمة الأخرى عبر واجهةٍ برمجيّةٍ (REST API) موثَّقةٍ توثيقًا كاملًا بمواصفة OpenAPI 3.0، وهي متاحةٌ لكلِّ عميلٍ بلا أيّ رسومٍ إضافيّة. التكلفةُ الإضافيّة – إن وُجِدت – تنشأ عادةً من جهة النظام الآخر، لا من جهتنا.
السؤال المركزيّ: في أيِّ اتّجاهٍ تَسير البيانات؟
قبل أن نَبحث في الإمكانيّة الفنّيّة، ينبغي أن نُحدِّد اتّجاه التدفُّق بدقّة؛ فلكلِّ اتّجاهٍ متطلَّباته الخاصّة، وتختلف الجهةُ التي يقع عليها العبءُ الفنّيُّ والماليُّ تَبَعًا لذلك. وتنحصر الاتّجاهاتُ الممكنة في أربعة سيناريوهاتٍ رئيسة:
| # | السيناريو | المصدر | الوجهة | الجهة المسؤولة عن توفير الـ API |
|---|---|---|---|---|
| 1 | النظام الآخر يَقرأ من نما | نما | النظام الآخر | نما (متاح بالفعل) |
| 2 | النظام الآخر يَكتب في نما | النظام الآخر | نما | نما (متاح بالفعل) |
| 3 | نما يَكتب في النظام الآخر | نما | النظام الآخر | النظام الآخر |
| 4 | نما يَقرأ من النظام الآخر | النظام الآخر | نما | النظام الآخر (أو قاعدة بياناته) |
ولا بدَّ – قبل الإجابة على سؤال العميل – أن نَعرف أيَّ هذه السيناريوهات يَقصد، أو أيَّها يَجمع بينها؛ إذ كثيرًا ما يَحتاج التكاملُ إلى أكثر من اتّجاهٍ في آنٍ واحد (مثل: مزامنة الأصناف من نما إلى متجرٍ إلكترونيّ + استقبال الطلبات من المتجر إلى نما).
السيناريو الأوّل: النظام الآخر يَقرأ من نما
هذا أيسرُ السيناريوهات وأكثرُها شيوعًا. فنظام نما يوفِّر بالفعل واجهةً برمجيّةً كاملةً من نوع REST API تُغطّي جميع كيانات النظام (Entities)، مع توثيقٍ تلقائيٍّ بمواصفة OpenAPI 3.0 وواجهة Swagger UI تفاعليّة لاستكشاف الـ API وتجربته مباشرةً.
ولذلك فإنّ الإجابة شبهَ الجاهزة في هذا السيناريو هي:
نعم؛ يَستطيع النظامُ الآخر أن يَقرأ من نما مباشرةً عبر واجهة REST API الموجودة لدينا، دون الحاجة إلى أيِّ تطويرٍ إضافيٍّ من جانبنا، ودون أيِّ تكلفةٍ إضافيّة على العميل.
ويَكفي أن يَطّلع فريقُ النظام الآخر على دليل واجهة Nama ERP REST API، ويَستخرج مفتاحَ API من شاشة «بيانات اعتماد API» (API Credentials)، ثمّ يَبدأ في استدعاء نقاط النهاية مباشرةً.
متى نَحتاج إلى تطويرٍ إضافيّ؟
إذا طَلب النظامُ الآخر شكلًا غيرَ قياسيٍّ من البيانات – مثل تجميعةٍ خاصّةٍ من الحقول، أو نقطة نهايةٍ مُجمَّعةٍ تَدمج بيانات أكثرَ من كيانٍ في استجابةٍ واحدة – فحينئذٍ نحتاج إلى تطوير API مُخصَّصة، وهذا يَدخل في باب الخدمات مدفوعة الأجر (انظر فقرة «التكاليف الإضافيّة» أدناه).
الأسئلة الواجب طرحها على العميل في هذا السيناريو
- ما الكيانات (Entities) التي يَحتاج النظامُ الآخر إلى قراءتها؟ (فواتير المبيعات، الأصناف، العملاء، أرصدة المخازن، …)
- هل القراءةُ ستكون حسبَ الطلب (On-Demand) أم بصورةٍ دوريّةٍ (Polling) أم بناءً على حَدَثٍ (Webhook)؟
- هل يَحتاج إلى البيانات الكاملة، أم إلى الجديد/المُحدَّث منها فقط؟
السيناريو الثاني: النظام الآخر يَكتب في نما
هذا السيناريو أيضًا مدعومٌ بالكامل دون تطويرٍ إضافيٍّ من جانبنا؛ فواجهةُ REST API ذاتُها تَدعم عمليّاتِ الإنشاء والتعديل والحذف (Create / Update / Delete) لجميع الكيانات، مع التحقُّق من صحّة البيانات، وإدارة الحقول المرجعيّة، وغير ذلك ممّا هو موضَّحٌ في دليل الـ API.
والإجابة هنا أيضًا – في الغالب – هي:
نعم؛ يَستطيع النظامُ الآخر أن يَكتب في نما مباشرةً عبر واجهة REST API، دون أيِّ تطويرٍ إضافيٍّ ودون تكاليفَ إضافيّة.
ضع في حسبانك
كلُّ عمليّة كتابةٍ تَمرّ عبر منظومة الصلاحيّات والتحقُّقات الموجودة في نما (قواعد العمل، التحقُّق من الحقول الإلزاميّة، الاعتمادات…). فإن أرسل النظامُ الآخر بيانات ناقصةً أو مخالفةً لقواعد العمل، فستُرفَض الكتابةُ كما لو أنّ المستخدم أدخلَها يدويًّا. يَنبغي تنبيهُ فريقِ الطرف الآخر إلى ذلك حتى يَفهم رسائلَ الخطأ التي قد تَرِدُه.
الأسئلة الواجب طرحها على العميل في هذا السيناريو
- ما الكيانات التي سيَكتبها النظامُ الآخر؟
- ما الحقولُ المتوفِّرةُ لديه لكلِّ كيان؟ وهل تَكفي للوفاء بمتطلَّبات نما (الحقول الإلزاميّة، الحقول المرجعيّة…)?
- كيف ستُعالَج رسائلُ الخطأ؟ هل لدى النظام الآخر آليّةٌ لإعادة المحاولة، أم سيَعتمد على تدخُّلٍ بشريّ؟
السيناريو الثالث: نما يَكتب في النظام الآخر
هنا تَتغيَّر المعادلةُ تغيُّرًا جوهريًّا؛ إذ إنّ نما – بوصفه الطرفَ المُستدعِيَ (Caller) – يَحتاج إلى واجهةٍ برمجيّةٍ جاهزةٍ ومُحدَّدةِ الشكل لدى النظام الآخر يستطيعُ أن يُرسل إليها البيانات. ومن ثَمّ يصبح السؤالُ الأهمّ موجَّهًا للطرف الآخر لا لنا:
هل لديكم REST API جاهزة لاستقبال هذه البيانات؟ وما توثيقُها؟
وأفضلُ الأشكال – وأسرعُها في التنفيذ – أن تكون لدى الطرف الآخر مواصفة OpenAPI (سواء OpenAPI 3.0 أو الجيل السابق Swagger 2.0)؛ فهذه المواصفةُ تُجيب – بصورةٍ آليّةٍ – على معظم الأسئلة الفنّيّة التي قد تَعترضنا أثناء التطوير: ما نقاطُ النهاية المتاحة؟ ما الحقولُ في كلِّ طلب؟ ما أنواعُ البيانات؟ ما رموزُ الاستجابة المحتملة؟ ما آليّةُ المصادقة؟ وهكذا.
لماذا نُلِحُّ على OpenAPI تحديدًا؟
لأنّ نظام نما يُولِّد OpenAPI لكلِّ كياناته كما ذُكِر في دليل الـ API، ونحن نُؤمن أنّ هذه هي الطريقة المهنيّة الصحيحة لتوصيف الواجهات البرمجيّة في عصرنا الحاضر. وحين يَتمتّع كلا الطرفين بمواصفة OpenAPI واضحة، يَتقلّص زمنُ الربط من أسابيعَ إلى أيّامٍ – بل وإلى ساعاتٍ في بعض الأحيان.
إذا لم تتوفّر مواصفة OpenAPI
لا يَعني غيابُ OpenAPI استحالةَ الربط، ولكنّه يَعني أنّ على الطرف الآخر أن يُزوِّدنا بـ:
- توثيقٍ نصّيٍّ كاملٍ لكلِّ نقطةٍ من نقاط النهاية (URL، طريقة HTTP، رؤوس الطلب، نموذج الجسد، نموذج الاستجابة، رموز الأخطاء).
- أمثلةٍ عمليّةٍ لطلباتٍ ناجحةٍ وطلباتٍ فاشلةٍ (Request / Response samples).
- آليّةٍ موثَّقةٍ للمصادقة (Bearer Token، API Key، OAuth2…).
- بيئةِ اختبارٍ (Sandbox / Staging) يُمكننا الاختبارُ عليها قبل الانتقال إلى بيئة الإنتاج.
ومن دون هذه العناصر يَصير العملُ تخمينًا، وتَتضخّم تقديراتُ الوقت والتكلفة تضخُّمًا غيرَ مبرَّر.
الأسئلة الواجب طرحها على العميل في هذا السيناريو
- هل النظامُ الآخر يُوفِّر REST API يستقبل البيانات المطلوبة؟
- هل يَملك توثيقًا بصيغة OpenAPI / Swagger؟ وإن لم يَكن، فما البديل؟
- ما آليّةُ المصادقة المطلوبة؟ وهل تَحتاج إلى تفعيلٍ أو اتّفاقٍ مُسبَقٍ مع الطرف الآخر؟
- هل ثَمّةَ حدودٌ على معدّل الاستدعاءات (Rate Limits)؟
- هل توجد بيئةُ اختبار؟
السيناريو الرابع: نما يَقرأ من النظام الآخر
ينطبق على هذا السيناريو ما سَبق ذِكرُه في السيناريو الثالث؛ فالطرف المُستدعِي هو نما، ولا بدَّ من توفُّر واجهةٍ مُحدَّدةِ الشكل لدى الطرف الآخر. غير أنّه ثَمّةَ حالةً خاصّةً تستحقّ التفصيلَ، وهي: النظام القديم الذي لا يَملك REST API على الإطلاق.
الحالة الخاصّة: نظامٌ قديمٌ بلا REST API – الربط عبر قاعدة البيانات
تُوجد في السوق – لا سيّما لدى المؤسّسات الكبيرة – أنظمةٌ قديمةٌ راسخةٌ لا تُوفِّر واجهاتٍ برمجيّةً حديثة (REST/SOAP)؛ كالإصدارات القديمة من Oracle E-Business Suite، وبعض أنظمة الإدارة المخصّصة (Custom-Built ERPs) المكتوبة بلغاتٍ قديمة. وفي مثل هذه الحالات قد يَطلب العميلُ أن يَكون الربطُ عبر قاعدة البيانات مباشرةً.
الشَّرطان الأساسيّان لقَبول هذا النوع من الربط
- أن يُوفِّر العميلُ صلاحيّةَ الوصول (Access) إلى قاعدة البيانات؛ ويُفضَّل أن يكون مستخدمًا منفصلًا مخصَّصًا لنظام نما، مقتصرَ الصلاحيّات على الجداول التي يَحتاجها فعلًا.
- أن يُساعدنا الفريقُ التقنيُّ للنظام الآخر في فَهم الجداول والمخطَّط (Schema): ما الجداولُ التي نقرأ منها؟ ما العلاقاتُ بينها؟ ما دلالةُ كلّ عمود؟ ما المؤشِّراتُ (Flags) التي تَدُلّ على أنّ السجلَّ مُعتمَدٌ أو ملغًى أو في حالة المسوّدة؟
الكتابةُ المباشرة في قاعدة بيانات النظام الآخر: خطٌّ أحمر
نَتجنَّب – من حيث المبدأ – أن يَكتب نظامُ نما مباشرةً في قاعدة بيانات نظامٍ آخر؛ لأنّ ذلك يَتجاوز جميعَ قواعد العمل والتحقُّقات والمحفِّزات (Triggers) المنطقيّة التي بَناها مهندسو ذلك النظام، فيُؤدِّي – غالبًا – إلى فسادٍ في البيانات يَصعب اكتشافُه إلّا بعد فوات الأوان.
ولا نَقبل هذا النوعَ من الربط إلّا إذا اجتمع شرطان:
- أن يُصرِّح الفريقُ التقنيُّ للنظام الآخر تصريحًا واضحًا بأنّ هذه هي الطريقةُ المُعتمَدة لديهم للكتابة.
- أن يُساعدنا الفريقُ ذاتُه في تفاصيل التنفيذ: ما الجداولُ التي نَكتب فيها؟ ما الأعمدةُ الإلزاميّة؟ ما الحقولُ المحسوبة؟ هل ثَمّةَ Triggers ينبغي أن تَعمل قبل/بعد الكتابة؟ هل توجد مفاتيحُ تسلسليّةٌ (Sequences) ينبغي استدعاؤها قبل الإدراج؟
وفي معظم الحالات يَنتهي بنا الأمرُ إلى القراءة فقط من قاعدة بيانات النظام الآخر، مع إعادة الكتابة بشكلٍ ملائمٍ في نما.
مثالٌ عمليّ
أحدُ السيناريوهات الشائعة عند الربط مع إصدارات Oracle EBS القديمة: أن يَقرأ نما حركاتِ الفواتير وأرصدةَ الموردين من جداول EBS مباشرةً، ثمّ يَستخدمها لإغناء التقارير والشاشات داخل نما، دون أن يَكتب فيها شيئًا.
الأسئلة الواجب طرحها على العميل في حالة الربط عبر قاعدة البيانات
- ما نوعُ قاعدة البيانات وإصدارُها؟ (Oracle، SQL Server، MySQL، …)
- هل يوجد توثيقٌ لمخطَّط (Schema) الجداول المعنيّة؟
- هل يَملك الفريقُ التقنيُّ للنظام الآخر القدرةَ على دعمنا أثناء التحليل؟
- هل سيُتاح لنا الوصولُ بأمانٍ كافٍ (VPN، IP Whitelisting، حساب مستخدمٍ مُقيَّد…)?
- هل البياناتُ التي نَحتاجها مُحدَّثةٌ في الوقت الحقيقيّ (Real-Time)، أم تَكفينا مزامنةٌ دوريّة؟
مَن يَتحمَّل التكلفة؟
في ضوء ما سَبق، يُمكن تَلخيصُ السياسة الماليّة لربط نما مع الأنظمة الأخرى في النقاط التالية:
ما هو متاحٌ بلا تكلفةٍ إضافيّة
- استخدامُ واجهة REST API القياسيّة لنما بجميع كياناته وجميع عمليّات CRUD: متاحٌ لكلِّ عميلٍ عنده النظام، بلا أيِّ رسومٍ إضافيّة، ودون الحاجة إلى تطويرٍ من جانبنا.
- توثيقُ الـ API بمواصفة OpenAPI 3.0 وواجهة Swagger UI: متاحٌ تلقائيًّا داخل النظام.
- المساعدةُ الفنّيّةُ السريعةُ والبسيطة لفريق الطرف الآخر (إجابةُ سؤالٍ هنا أو هناك، توضيحُ بُنيةِ طلبٍ معيَّن): نُقدِّمها مجّانًا في معظم الأحيان من بابِ حُسنِ الجوار التقنيّ.
ما يَحتاج إلى عَرضٍ ماليّ
ثَمّةَ ثلاثُ حالاتٍ شائعةٍ تَستوجب عرضًا ماليًّا منفصلًا:
- طلبُ تدريبٍ مُتخصِّصٍ لفريق التطوير لدى الطرف الآخر؛ كأن يَطلب العميلُ ورشةَ عملٍ كاملةً لشرح آليّة الربط وأفضل ممارساته.
- تطويرُ API جديدةٍ مُخصَّصة بشكلٍ معيَّنٍ غيرِ مدعومٍ في الـ API القياسيّ؛ كأن يَطلب العميلُ نقطةَ نهايةٍ مُجمَّعةً (Composite Endpoint) تَدمج بيانات أكثرَ من كيانٍ في استجابةٍ واحدةٍ بصيغةٍ مخصَّصة.
- أن تَتولّى نماسوفت تطويرَ طرف الاستدعاء كاملًا (السيناريو الثالث أو الرابع)؛ أي أن نَكتب نحنُ – لا فريقُ العميل – الكودَ الذي يَستدعي API الطرف الآخر، أو يَقرأ من قاعدة بياناته. هذا عملٌ تطويريٌّ كاملٌ يَتطلَّب تحليلًا وتصميمًا وتنفيذًا واختبارًا، ولذلك يَدخل في باب الخدمات مدفوعة الأجر.
ملاحظةٌ على الحالة الثالثة
تَختلف تكلفةُ هذه الحالة اختلافًا كبيرًا تَبعًا لجودة توثيق الطرف الآخر؛ فربطٌ مع نظامٍ يَملك OpenAPI Spec واضحةً وبيئةَ Sandbox قد يَستغرق أيّامًا قليلة، بينما ربطٌ مع نظامٍ قديمٍ بلا توثيقٍ قد يَستغرق أسابيعَ أو أشهرًا. ولذلك يَنبغي – عند بناء عرضٍ ماليٍّ لهذه الحالة – أن نَطلب من العميل أوّلًا أن يُزوِّدنا بتوثيق الطرف الآخر؛ حتى يَكون التقديرُ مَبنيًّا على معلوماتٍ حقيقيّة، لا على افتراضات.
قائمةٌ مُختصَرةٌ للزملاء قبل الردِّ على العميل
يَنبغي – قبل الردِّ على العميل بإمكانيّة الربط أو عدمها، وقبل بناء أيّ عرضٍ ماليّ – أن نَستجلي الإجابات التالية:
- اتّجاهُ التدفُّق: مَن يَقرأ من مَن؟ ومَن يَكتب في مَن؟ (أحد السيناريوهات الأربعة أعلاه أو مزيجٌ منها)
- الكياناتُ المعنيّة: ما الكيانات التي ستَتدفّق بياناتُها؟ (فواتير، أصناف، عملاء، قيود محاسبيّة، …)
- التواترُ الزمنيّ: مزامنةٌ آنيّةٌ (Real-Time)، أم دوريّةٌ (Batch)، أم بناءً على حَدَثٍ (Webhook)؟
- قدراتُ الطرف الآخر: هل يَملك REST API؟ وهل يَملك OpenAPI Spec؟ هل يَملك بيئةَ اختبار؟
- آليّةُ المصادقة: مدعومةٌ من الطرفين؟ هل تَحتاج إلى اتّفاقٍ مُسبَق؟
- الفريقُ التقنيُّ للطرف الآخر: متعاونٌ ومتاحٌ للنقاش، أم تَعذُّرٌ في الوصول إليه؟
- هل يَتطلَّب الأمرُ ربطًا عبر قاعدة البيانات (وهو احتمالٌ يَنبغي عَدُّه استثناءً لا قاعدةً)؟
متى ما اكتملت لدينا الإجاباتُ على هذه الأسئلة، صار في وُسعنا – بكلِّ ثقة – أن نُجيب العميلَ إجابةً دقيقةً عن إمكانيّة الربط، ومُدّتِه التقديريّة، وتكلفتِه إن وُجدت.
مراجعُ ذات صِلة
- Nama ERP REST API – Full Developer Guide — الدليل التقنيُّ الكاملُ لاستخدام واجهة نما البرمجيّة (بالإنجليزيّة).
- Attendance Machines Integration — مثالٌ تطبيقيٌّ على ربط نظام نما مع أجهزة الحضور والانصراف.