قليل جدًا من الشركات تعمل بنظام واحد. فحتى عندما يكون Odoo هو نظام ERP الأساسي، يحتاج عادةً إلى التواصل مع بوابة دفع، وشركة شحن، وبنك، ومتجر إلكتروني، وجهاز حضور، أو تطبيق قديم. وجودة هذه الروابط هي التي تحدد ما إذا كانت بياناتك موثوقة أم أن فريقك سيقضي كل شهر في مطابقة الفروقات يدويًا.
يقدم Odoo 19 Enterprise مجموعة أدوات متدرجة: موصلات مدمجة تُهيّأ من داخل التطبيقات، وواجهة API خارجية للمطورين، وقواعد أتمتة يمكنها استقبال خطافات الويب وإرسالها، واستيراد الملفات في الحالات التي يتعذر فيها الاتصال المباشر. وتأتي أدوات البرمجيات الوسيطة فوق ذلك عندما تحتاج إلى تنسيق العمل بين أنظمة كثيرة.
ملاحظة حول المصادر: يستند هذا المقال إلى وثائق Odoo الرسمية للإصدار 19.0 (مستودع odoo/documentation). وقد تتغير القوائم والخيارات وشروط الخطط بين الإصدارات وأنواع الاستضافة، لذا تحقق دائمًا من كل خطوة في قاعدة بيانات تجريبية أو منسوخة قبل تطبيقها في بيئة الإنتاج.
اختر نمط التكامل المناسب
ابدأ من حاجة العمل، لا من التقنية. اسأل: ما البيانات التي يجب نقلها، وفي أي اتجاه، وبأي سرعة، ومن يملك السجل الرئيسي؟ ثم اختر أخف خيار يلبي الحاجة.
- استخدم موصلًا مدمجًا عندما يدعم Odoo مزوّد الخدمة بالفعل، مثل مزوّد دفع مدرج، أو شركة شحن، أو مزوّد للمزامنة البنكية، أو موصل Amazon.
- استخدم واجهة API الخارجية عندما يحتاج تطبيق آخر إلى قراءة سجلات Odoo أو كتابتها وفق جدوله الخاص.
- استخدم خطاف ويب وارد عندما ينبغي لنظام خارجي أن يدفع حدثًا إلى Odoo لحظة وقوعه.
- استخدم خطاف ويب صادر عندما ينبغي لـ Odoo إخطار نظام آخر بعد حدوث تغيير، على سبيل المثال عند إنشاء سجل أو تحديث حقل.
- استخدم البرمجيات الوسيطة عندما تكون هناك عدة أنظمة معنية، أو عندما تحتاج البيانات إلى تحويل كبير، أو عندما تحتاج إلى إعادة محاولة ومراقبة مركزيتين.
- استخدم استيراد الملفات عندما لا يوفر الطرف الآخر سوى ملفات، مثل كشوف الحسابات البنكية بصيغ CAMT.053 أو OFX أو QIF أو CSV أو XLSX.
واجهة API الخارجية في Odoo 19: JSON-2 ومفاتيح API
يقدم Odoo 19 واجهة JSON-2 API، التي تتيح جزءًا من ORM عبر HTTP. وكل استدعاء هو طلب POST إلى نقطة نهاية بالصيغة /json/2/ يليها اسم النموذج ثم اسم الدالة، مثل الدالة search_read في النموذج res.partner. ويحمل متن الطلب وسائط الدالة بصيغة JSON.
تعتمد المصادقة على مفتاح API يُرسل في ترويسة Authorization كرمز من نوع bearer. ولا توجد خطوة تسجيل دخول منفصلة بمعرّف مستخدم وكلمة مرور، فالمفتاح يحدد هوية المستخدم، ويعمل التكامل بحقوق الوصول الخاصة بذلك المستخدم.
لإنشاء مفتاح يدويًا، افتح تفضيلات المستخدم، وانتقل إلى أمان الحساب واختر مفتاح API جديد. الوصف والمدة مطلوبان، ولا تُعرض قيمة المفتاح إلا مرة واحدة، لذا احفظها فورًا في خزنة آمنة للأسرار. وتنص الوثائق على أنه لا يمكن إنشاء مفاتيح لمدة تزيد على ثلاثة أشهر، لذا خطط لروتين تدوير المفاتيح منذ البداية.
عندما يستضيف خادم واحد عدة قواعد بيانات، تخبر الترويسة الاختيارية X-Odoo-Database نظام Odoo بقاعدة البيانات المستهدفة بالاستدعاء. وخلف الخادم الوكيل العكسي، تأكد من أن ترويسة Host تصل إلى Odoo بشكل صحيح.
يعمل كل استدعاء JSON-2 ضمن معاملة مستقلة في قاعدة البيانات: تُعتمد عند النجاح وتُلغى عند الخطأ. ولا يمكنك ربط عدة استدعاءات في معاملة واحدة، لذا فضّل دالة واحدة تنجز العمل المترابط، مثل search_read أو دالة عمل، بدلًا من استدعاءات صغيرة كثيرة قد تترك البيانات محدّثة جزئيًا.
تُعاد الأخطاء مع حالة HTTP من فئة 4xx أو 5xx ومتن JSON يتضمن اسمًا ورسالة. وينبغي أن يقرأ كود العميل لديك كليهما ويسجلهما.
واجهتا XML-RPC وJSON-RPC القديمتان: خطط لعملية الانتقال
تعتمد تكاملات قائمة كثيرة على نقاط النهاية الأقدم XML-RPC أو نقطة النهاية JSON-RPC. وفي Odoo 19 أصبحت هذه الواجهات مهجورة، وتقول الوثائق الرسمية إن من المقرر إزالتها في Odoo 22. وهي لا تزال تعمل اليوم، لكن ينبغي بناء المشاريع الجديدة على JSON-2، وحصر المشاريع القائمة ونقلها ضمن خارطة طريق الترقية لديك.
- احصر كل نص برمجي وموصل وأداة خارجية تستدعي نقاط النهاية القديمة.
- استبدل المصادقة باسم المستخدم وكلمة المرور بمفاتيح API مخصصة لكل تكامل.
- أعد كتابة التسلسلات متعددة الخطوات في استدعاءات مفردة حيثما أمكن، بسبب سلوك المعاملة الواحدة لكل استدعاء.
- اختبر النسخة المنقولة على قاعدة بيانات منسوخة قبل تحويل حركة بيئة الإنتاج إليها.
خطة الاشتراك مهمة أيضًا. إذ تنص الوثائق على أن الوصول إلى البيانات عبر واجهة API الخارجية متاح فقط في خطط تسعير Odoo المخصصة، وليس في خطة التطبيق الواحد المجانية أو الخطة القياسية. تحقق من اشتراكك قبل أن تصمم تكاملًا قائمًا على API على Odoo Online.
خطافات الويب وقواعد الأتمتة
تتيح قواعد الأتمتة لـ Odoo الاستجابة للأحداث دون وحدات مخصصة. وفي Odoo 19 Enterprise تديرها من Studio عبر قائمة الأتمتة، كما أن لخطافات الويب الواردة قائمة خاصة بها في Studio. ويمنحك وضع المطور تحكمًا أكبر، بما في ذلك اختيار النموذج المستهدف.
لإنشاء خطاف ويب وارد، أنشئ قاعدة بالمشغّل عند استقبال خطاف ويب. يُنشئ Odoo عنوان URL تلقائيًا، ويرسل النظام الخارجي طلب POST بحمولة JSON إلى ذلك العنوان. ويخبر كود السجل المستهدف نظام Odoo بالسجل الذي تشير إليه الحمولة، ويحدد تبويب الإجراءات المطلوب تنفيذها ما يحدث بعد ذلك، وعادةً ما يكون إجراء تنفيذ الكود عندما تحتاج إلى إنشاء سجلات بدلًا من تحديث سجل واحد.
فعّل خيار تسجيل الاستدعاءات أثناء البناء واستكشاف الأخطاء. فهو يسجل تاريخ الطلبات الواردة إلى العنوان، ويمكنك فتحه من الزر الذكي للسجلات في القاعدة.
تعامل مع عنوان URL الخاص بخطاف الويب كسرّ. إذ تحذر الوثائق من أن مشاركته قد تتيح وصولًا غير مقصود إلى قاعدة البيانات. وإذا انكشف، فاستخدم تدوير السر لإنشاء عنوان جديد وحدّث النظام الخارجي.
للإشعارات الصادرة، أضف إجراء إرسال إشعار خطاف ويب إلى القاعدة. فهو يرسل طلب POST بقيم الحقول التي تختارها إلى العنوان الذي تحدده، وتساعدك الحمولة النموذجية على التحقق من البنية قبل التشغيل الفعلي.
عند كتابة إجراءات تنفيذ الكود، استخدم الدالة log لكتابة الرسائل في جدول السجلات بقاعدة البيانات، حتى تكون الأعطال مرئية للمستخدمين الوظيفيين وليس في سجلات الخادم فقط.
Studio جزء من Odoo Enterprise. وفي Community لا توجد واجهة Studio، لذا تُلبّى الاحتياجات نفسها عادةً من خلال الإعدادات في وضع المطور أو من خلال وحدات مخصصة صغيرة يتولى صيانتها مطور.
الموصلات المدمجة للتكاملات الشائعة
قبل كتابة أي كود، تحقق مما إذا كان Odoo يغطي مزوّد الخدمة بالفعل. فالموصلات المدمجة تُصان مع كل إصدار، وهي عادةً الخيار الأكثر أمانًا.
- بوابات الدفع: هيّئها من التهيئة، ثم مزوّدو الدفع، في تطبيق المحاسبة أو الموقع الإلكتروني أو المبيعات. ومن المزوّدين المدرجين Stripe وAdyen وPayPal وPaymob وMollie وRazorpay وغيرهم. أدخل بيانات الاعتماد في تبويب بيانات الاعتماد واستخدم وضع الاختبار ببيانات اعتماد تجريبية (sandbox) أولًا، ويُفضَّل أن يكون ذلك على قاعدة بيانات منسوخة لحماية تسلسل أرقام الفواتير. ويجب أن تكون يومية الدفع من نوع بنك.
- شركات الشحن: فعّلها من إعدادات المخزون في قسم موصلات الشحن. ومن الموصلات المدعومة DHL Express وFedEx وUPS وSendcloud وEasyPost وغيرها. وتبدأ كل طريقة شحن في بيئة اختبار؛ والتحويل إلى بيئة الإنتاج يُنشئ ملصقات حقيقية قد تحاسبك عليها شركة الشحن، لذا تحقق من الأسعار والملصقات أولًا. ويسجل خيار تصحيح الطلبات الرسائل المتبادلة.
- البنوك: تستورد المزامنة البنكية المعاملات عبر مزوّدين خارجيين مثل Plaid وYodlee وSalt Edge وPonto وEnable Banking وBasiq، وتتطلب اشتراك Enterprise ساريًا. وحيثما لا يكون بنكك مدعومًا، استورد ملفات الكشوف من يومية البنك في لوحة معلومات المحاسبة.
- التجارة الإلكترونية والأسواق الإلكترونية: يشترك تطبيق التجارة الإلكترونية الخاص بـ Odoo في قاعدة البيانات نفسها، لذا لا حاجة إلى موصل. وبالنسبة لـ Amazon، يزامن موصل Amazon الطلبات في صورة أوامر بيع ويطابق المنتجات حسب المرجع الداخلي.
- أجهزة الحضور: يدعم تطبيق الحضور وضع الكشك على جهاز مخصص وتسجيل الحضور من الواجهة الخلفية. أما أجهزة البصمة من الموردين الآخرين فلا تغطيها الوثائق الرسمية، لذا تُربط عادةً عبر وحدة مخصصة أو برمجيات وسيطة تدفع تسجيلات الحضور إلى Odoo.
البرمجيات الوسيطة مثل n8n
تقع منصات البرمجيات الوسيطة مثل n8n بين Odoo والأنظمة الأخرى. وهي أدوات خارجية ليست جزءًا من Odoo، وتتواصل مع Odoo عبر واجهة API الخارجية وخطافات الويب نفسها الموضحة أعلاه.
وهي مفيدة عندما يجب أن يحدّث حدث واحد عدة أنظمة، أو عندما تكون مطابقة الحقول معقدة، أو عندما تريد تدفقًا مرئيًا مع معالجة مركزية للأخطاء وإعادة المحاولة. والمقابل هو مكوّن إضافي يجب استضافته وتأمينه ومراقبته وترقيته، مع بقاء شروط الخطة نفسها للوصول إلى API سارية.
قواعد التصميم: عدم التكرار ومعالجة الأخطاء والتسجيل
تنشأ معظم مشكلات التكامل من الرسائل المكررة والأعطال الجزئية والأخطاء الصامتة. صمم للتعامل معها منذ اليوم الأول.
- اجعل كل عملية كتابة غير متكررة الأثر (idempotent): احفظ المرجع الخارجي في سجل Odoo وتحقق منه قبل الإنشاء، حتى لا يؤدي خطاف ويب مُعاد إرساله أو استدعاء مُعاد إلى إنشاء طلب أو دفعة مكررة.
- حدد مالك كل حقل، ولا تسمح أبدًا لنظامين بالكتابة فوق القيمة نفسها.
- اجعل كل عملية عمل في استدعاء واحد حيثما أمكن، لأن كل استدعاء JSON-2 معاملة مستقلة.
- أعد المحاولة فقط عند الأعطال المؤقتة، مع فترات تأخير متزايدة، وأرسل الأعطال الدائمة إلى قائمة انتظار للمراجعة.
- سجّل الطلب والاستجابة ومرجع سجل Odoo لكل عملية تبادل، باستخدام تسجيل الاستدعاءات أو تصحيح الطلبات أو سجل البرمجيات الوسيطة.
- راقب الأحجام والأعطال يوميًا خلال الأسابيع الأولى، وطابق الإجماليات مثل الدفعات والشحنات والأرصدة البنكية بين الأنظمة.
قائمة مراجعة الأمان
- أنشئ مستخدمًا مخصصًا للتكامل لا يملك إلا حقوق الوصول التي يحتاجها التكامل، وأنشئ مفتاح API من ذلك المستخدم.
- استخدم مفتاحًا واحدًا لكل تكامل، وسجّل الغرض منه في الوصف، واختر مدة قصيرة، وقم بتدويره قبل انتهاء صلاحيته.
- احفظ المفاتيح وعناوين خطافات الويب في أداة لإدارة الأسرار، ولا تحفظها أبدًا في جداول بيانات أو رسائل دردشة أو كود مصدري.
- ألغِ المفاتيح وقم بتدوير أسرار خطافات الويب فورًا عند انتهاء العلاقة مع مورد أو عند الاشتباه في تسريب.
- استخدم HTTPS دائمًا، وابنِ كل تكامل واختبره على قاعدة بيانات منسوخة قبل تفعيله في بيئة الإنتاج.
كيف يمكن أن تساعدك 1CBMS
تصمم 1CBMS تكاملات Odoo 19 وتطبقها للشركات في مصر والعراق، بدءًا من تهيئة مزوّدي الدفع وشركات الشحن والتغذيات البنكية، مرورًا ببناء تكاملات JSON-2 API وخطافات الويب ونقل نصوص XML-RPC القديمة، وصولًا إلى ربط أجهزة الحضور والأنظمة الداخلية عبر وحدات مخصصة أو برمجيات وسيطة. نبدأ بتحديد ملكية البيانات وتدفقاتها، ونختبر كل شيء في قاعدة بيانات منسوخة، ونسلّم وثائق ومراقبة واضحة حتى يثق فريقك بالأرقام. تواصل معنا عبر www.1cbms.com لمراجعة منظومة تكاملاتك.