البرنامج التعليمي لتكامل واجهة برمجة تطبيقات Odoo REST وXML-RPC: توصيل أي نظام

يعرض Odoo نموذج بياناته بالكامل من خلال واجهات برمجة التطبيقات الخارجية، مما يجعل من الممكن التكامل مع أي نظام تقريبًا --- منصات التجارة الإلكترونية، وأدوات إدارة علاقات العملاء، وبرامج ذكاء الأعمال، وتطبيقات الهاتف المحمول، والتطبيقات المخصصة. يغطي هذا البرنامج التعليمي جميع بروتوكولات API الثلاثة (XML-RPC، وJSON-RPC، وREST)، وطرق المصادقة، وعمليات CRUD، وأنماط التكامل في العالم الحقيقي مع أمثلة التعليمات البرمجية وأفضل الممارسات.

الوجبات السريعة الرئيسية

• يوفر Odoo ثلاثة بروتوكولات لواجهة برمجة التطبيقات: XML-RPC (الأكثر نضجًا)، وJSON-RPC (صديق للمتصفح)، وREST (Odoo 19، متوافق مع OpenAPI)
• تتطلب جميع واجهات برمجة التطبيقات المصادقة باستخدام اسم قاعدة البيانات واسم المستخدم وكلمة المرور أو مفتاح واجهة برمجة التطبيقات
• تتبع عمليات CRUD نمطًا ثابتًا عبر جميع البروتوكولات: البحث والقراءة والإنشاء والكتابة وإلغاء الارتباط
• تستخدم مرشحات المجال صيغة التدوين البولندية للاستعلامات المعقدة
• يعمل ترقيم الصفحات واختيار الحقل والعمليات المجمعة على تحسين الأداء لمجموعات البيانات الكبيرة

مقارنة بروتوكول API

المصادقة

مصادقة XML-RPC

تستخدم مصادقة XML-RPC عملية مكونة من خطوتين: المصادقة للحصول على معرف المستخدم (uid)، ثم استخدام هذا المعرف الفريد للمكالمات اللاحقة.

يصل استدعاء المصادقة إلى نقطة النهاية /xmlrpc/2/common بالطريقة authenticate، ويمرر اسم قاعدة البيانات واسم المستخدم وكلمة المرور وكائن فارغ. الرد هو معرف المستخدم الرقمي. تستخدم جميع مكالمات البيانات اللاحقة /xmlrpc/2/object مع أسلوب execute_kw، لتمرير قاعدة البيانات، وuid، وكلمة المرور، واسم النموذج، واسم الطريقة، والوسائط.

مصادقة JSON-RPC

يستخدم JSON-RPC المصادقة المستندة إلى الجلسة من خلال نقطة النهاية /web/session/authenticate. نص الطلب هو كائن JSON يحتوي على jsonrpc: "2.0"، وطريقة call، ومعلمات تحتوي على db، وlogin، وpassword. تتضمن الاستجابة معرف الجلسة في ملف تعريف الارتباط الذي يصادق على الطلبات اللاحقة.

مصادقة REST API (Odoo 19)

تدعم REST API مفاتيح API التي تم إنشاؤها في الواجهة الخلفية لـ Odoo:

1. انتقل إلى الإعدادات > المستخدمون > مفاتيح واجهة برمجة التطبيقات
2. قم بإنشاء مفتاح جديد بأذونات محددة
3. قم بتضمين المفتاح في رأس Authorization: Bearer

تتبع نقاط نهاية REST النمط /api/{model} للمجموعات و/api/{model}/{id} للسجلات الفردية.

العمليات الخام

البحث والقراءة

العملية الأكثر شيوعًا هي البحث عن السجلات ذات المعايير المحددة وقراءة قيم الحقول الخاصة بها.

مرشحات النطاق تستخدم التدوين البولندي (تدوين البادئة) مع عوامل التشغيل:

شروط الدمج: استخدم & (AND)، و| (OR)، و! (NOT) كعوامل تشغيل للبادئة:

• AND: ['&', ['state', '=', 'sale'], ['amount_total', '>', 1000]] يطابق أوامر البيع التي تزيد عن 1000
• أو: ['|', ['state', '=', 'sale'], ['state', '=', 'done']] يتطابق مع أي من الحالتين
• المجمع: ['&', ['state', '=', 'sale'], '|', ['partner_id', '=', 5], ['partner_id', '=', 10]]

اختيار الحقل: اطلب فقط الحقول التي تحتاجها لتقليل حجم الحمولة وتحسين الأداء. قم بتمرير المعلمة fields مع قائمة بأسماء الحقول. إذا تم حذفها، يتم إرجاع كافة الحقول.

ترقيم الصفحات: استخدم معلمات offset وlimit لترقيم الصفحات النتائج. مثال: offset: 20, limit: 20 يُرجع السجلات 21-40.

إنشاء السجلات

قم بإنشاء سجلات عن طريق استدعاء الأسلوب create باستخدام قاموس قيم الحقول. يجب تضمين الحقول المطلوبة. تقوم الاستجابة بإرجاع معرف السجل الذي تم إنشاؤه حديثًا (أو مجموعة من المعرفات لإنشاء الدُفعات).

مثال: يتطلب إنشاء جهة اتصال حقل name على الأقل. تتضمن الحقول الاختيارية email، phone، company_id، street، city، state_id، country_id، والحقول المخصصة.

بالنسبة للسجلات ذات الصلة (one2many أو Many2many)، استخدم مجموعات أوامر خاصة:

تحديث السجلات

قم بتحديث السجلات عن طريق استدعاء الأسلوب write بمعرف (معرفات) السجل وقاموس الحقول التي تم تغييرها. قم بتضمين الحقول التي تحتاج إلى التغيير فقط --- تحتفظ الحقول المحذوفة بقيمها الحالية.

يتم دعم التحديثات المجمعة: قم بتمرير قائمة المعرفات لتحديث سجلات متعددة بنفس القيم في مكالمة واحدة.

حذف السجلات

احذف السجلات عن طريق استدعاء الأسلوب unlink بمعرف (معرفات) السجل. تُرجع الطريقة True عند النجاح.

كن حذرًا عند الحذف — فالعديد من سجلات Odoo محمية بموجب قواعد العمل. على سبيل المثال، ستؤدي محاولة حذف فاتورة مُرحَّلة إلى ظهور خطأ. استخدم طريقة العمل المناسبة بدلاً من ذلك (على سبيل المثال، button_cancel قبل الحذف).

أنماط التكامل في العالم الحقيقي

مزامنة طلبات التجارة الإلكترونية

مزامنة الطلبات من منصة التجارة الإلكترونية الخارجية إلى Odoo:

1. استطلاع للطلبات الجديدة: استعلم عن واجهة برمجة تطبيقات التجارة الإلكترونية للطلبات منذ آخر طابع زمني للمزامنة
2. مطابقة العملاء: ابحث عن جهات اتصال Odoo عبر البريد الإلكتروني؛ إنشاء إذا لم يتم العثور عليه
3. إنشاء أمر مبيعات: أنشئ الطلب باستخدام معلومات العميل والخطوط والشحن والدفع
4. تأكيد الطلب: اتصل بـ action_confirm لمعالجة الطلب من خلال سير العمل
5. تحديث التجارة الإلكترونية: أرسل مرجع طلب Odoo مرة أخرى إلى منصة التجارة الإلكترونية

مزامنة المخزون

حافظ على مزامنة مستويات المخزون بين Odoo والقناة الخارجية:

1. اقرأ مستويات المخزون: اتصل بـ search_read على stock.quant باستخدام مرشحات الموقع
2. ** دفع التحديثات **: إرسال تغييرات الكمية إلى القناة الخارجية
3. التعامل مع الحجوزات: حساب المخزون المحجوز (ملتزم بالأوامر المعلقة)
4. جدولة المزامنة: قم بالتشغيل كل 15-30 دقيقة للحفاظ على الدقة

استيراد عميل محتمل لإدارة علاقات العملاء (CRM).

استيراد العملاء المحتملين من منصات التسويق إلى Odoo CRM:

1. جلب العملاء المتوقعين: اسحب العملاء المتوقعين الجدد من واجهة برمجة تطبيقات منصة التسويق
2. إلغاء التكرار: ابحث في Odoo عن جهات الاتصال الموجودة عبر البريد الإلكتروني أو الهاتف
3. إنشاء عملاء محتملين: قم بإنشاء سجلات في crm.lead مع تتبع المصدر
4. التعيين: استخدم قواعد تعيين العميل المتوقع في Odoo أو قم بالتعيين بناءً على المنطق المخصص

تصدير البيانات المالية

تصدير البيانات المالية إلى منصة ذكاء الأعمال:

1. تصدير مخطط الحسابات: اقرأ account.account للتعرف على بنية الحساب
2. تصدير إدخالات دفتر اليومية: اقرأ account.move.line باستخدام مرشحات التاريخ
3. تصدير الأرصدة: استخدم read_group لتجميع الأرصدة حسب الحساب والفترة
4. الجدول: يتم تشغيله يوميًا بعد انتهاء فترة إغلاق المحاسبة

معالجة الأخطاء

أخطاء واجهة برمجة التطبيقات الشائعة

تحديد المعدل

لا يفرض Odoo حدود معدل واجهة برمجة التطبيقات (API) بشكل افتراضي، ولكن يجب أن تطبق عمليات نشر الإنتاج حدود المعدل على مستوى الوكيل العكسي. بالنسبة إلى Odoo.sh، تنطبق الحدود الافتراضية لمنع إساءة الاستخدام. تصميم عمليات التكامل مع فترات استقصاء معقولة وعمليات مجمعة.

استراتيجية إعادة المحاولة

تنفيذ التراجع الأسي للأخطاء العابرة:

1. أعد المحاولة أولاً بعد ثانية واحدة
2. أعد المحاولة الثانية بعد 4 ثوانٍ
3. أعد المحاولة الثالثة بعد 16 ثانية
4. قم بالتسجيل والتنبيه بعد الحد الأقصى لعدد المحاولات

تحسين الأداء

عمليات الدفعة

تفضيل العمليات المجمعة على معالجة السجلات الفردية:

• create يقبل قائمة قواميس القيمة لإنشاء الدُفعات
• write يقبل قائمة المعرفات للتحديثات المجمعة
• search_read مع ترقيم الصفحات أكثر كفاءة من مكالمات read الفردية

اختيار الحقل

قم دائمًا بتحديد المعلمة fields لتجنب تحميل البيانات غير الضرورية. يؤدي تحميل جميع الحقول في نموذج يحتوي على أكثر من 50 عمودًا إلى إنشاء حمل كبير، خاصة للنماذج مثل sale.order أو account.move.line.

التخزين المؤقت

ذاكرة التخزين المؤقت تغير البيانات ببطء محليًا:

• كتالوج المنتجات (يتم التحديث كل ساعة)
• قائمة العملاء (التحديث عند إشعار التغيير)
• معدلات الضرائب والمواقف المالية (تحديث يوميا)

خدمات التكامل ECOSIRE

يتطلب بناء عمليات تكامل موثوقة فهم كل من النظام الخارجي ونموذج بيانات Odoo. تغطي [خدمات تكامل Odoo] (/services/odoo/integration) من ECOSIRE تصميم واجهة برمجة التطبيقات (API)، وتطوير الموصل، ورسم خرائط البيانات، والمراقبة المستمرة. بالنسبة للمؤسسات التي تربط منصات التجارة الإلكترونية، يتعامل تكامل Shopify-Odoo وموصلات السوق مع السيناريوهات الأكثر شيوعًا.

القراءة ذات الصلة

• دليل تكامل واجهة برمجة تطبيقات Odoo
• خطوط أنابيب ETL لبيانات تخطيط موارد المؤسسات: Odoo وShopify
• دليل نشر Docker Odoo
• دليل تطوير وحدة Odoo المخصصة
• أمان واجهة برمجة التطبيقات: المصادقة والترخيص

ما هو بروتوكول واجهة برمجة التطبيقات (API) الذي يجب أن أختاره للتكامل الجديد؟

بالنسبة للمشاريع الجديدة على Odoo 19، استخدم REST API. وهو يتبع معايير HTTP، ويحتوي على وثائق يتم إنشاؤها تلقائيًا، ويدعم مفاتيح API للمصادقة. بالنسبة لـ Odoo 17 أو 18، يعد XML-RPC هو الخيار الأكثر موثوقية وتوثيقًا جيدًا. يعد JSON-RPC هو الأفضل لعمليات التكامل المستندة إلى المتصفح أو تطبيقات JavaScript.

هل هناك حد للسعر على واجهة برمجة تطبيقات Odoo الخارجية؟

لا يفرض Odoo نفسه حدودًا للمعدلات. ومع ذلك، فإن عمليات نشر Odoo.sh لها حدود على مستوى البنية التحتية، ويجب أن تطبق عمليات النشر ذاتية الاستضافة تحديد المعدل على مستوى الوكيل العكسي (Nginx). تصميم عمليات التكامل لاستخدام العمليات المجمعة وفترات الاستقصاء المعقولة بغض النظر عن الحدود.

هل يمكنني تشغيل سير العمل (تأكيد الطلب، نشر الفاتورة) من خلال واجهة برمجة التطبيقات؟

نعم. استخدم الأسلوب execute_kw مع اسم أسلوب سير العمل. على سبيل المثال، اتصل بـ action_confirm على طلب البيع لتأكيده، أو action_post على الحساب.نقل لترحيل إدخال دفتر اليومية. تفرض أساليب سير العمل نفس قواعد العمل التي تطبقها واجهة المستخدم.