نقطة
الكتابات/blog/2026/05
● Blog16 مايو 2026·6 دقيقة

Odoo والموجة 24 من ZATCA: كل عقبة فاتورة واجهناها في تطبيقات سعودية حقيقية

الموجة 24 تبدأ في 30 يونيو 2026 للمنشآت السعودية بإيرادات 375-750 ألف ريال. هذه خمس عقبات فعلية في Odoo + فاتورة، وقائمة تجهيز من عشر نقاط.

أنيس مروشي
·EN · FR · AR

Odoo والموجة 24 من ZATCA: كل عقبة فاتورة واجهناها في تطبيقات سعودية حقيقية

إذا كانت إيرادات منشأتك السعودية بين 375,000 و 750,000 ريال سنوياً، وتشغّل نظام Odoo — فأمامك ما يقارب ستة أسابيع لتكون متوافقاً مع المرحلة الثانية من ZATCA.

الموعد النهائي للموجة 24 هو 30 يونيو 2026. أما الموجة 23 (شريحة 750 ألف – 1 مليون ريال) فقد انتهت في 31 مارس 2026، ومعنى ذلك أن الهيئة دخلت مرحلة التطبيق الصارم، لا مرحلة الاستيعاب. التأخر يعني عقوبات تبدأ من 5,000 ريال وتصل إلى 50,000 ريال عن كل مخالفة، إضافة إلى الألم التشغيلي الناتج عن رفض كل فاتورة B2B فور إرسالها.

نفّذنا عدة عمليات ربط بين Odoo و ZATCA المرحلة الثانية في الرياض وجدة والدمام خلال آخر 18 شهراً، ووجدنا أن الأخطاء الخمس نفسها تتكرر في كل مشروع. هذه المقالة هي الموجز الذي كنا نتمنى لو حصلنا عليه قبل أول تطبيق.

للحصول على شرح تنظيمي شامل، راجع دليلنا الكامل للفوترة الإلكترونية ZATCA / فاتورة 2026. أما هذه المقالة فتفترض أنك تعرف ما هي المرحلة الثانية، وتركّز على الألغام الخاصة بـ Odoo تحديداً.

لماذا الربط بين Odoo و ZATCA معقّد فعلاً؟

المملكة العربية السعودية هي السوق الثاني عالمياً لـ Odoo من حيث عدد الشركاء — حوالي 204 شركاء معتمدين، خلف الولايات المتحدة فقط (~250) — من أصل أكثر من 170,000 عميل Odoo حول العالم. هذه الكثافة لها سبب: Odoo يناسب الشريحة المتوسطة في السعودية (دعم العربية RTL، تعدد الشركات، التصنيع والتجزئة والخدمات في منصة واحدة، تسعير معقول مقارنة بـ SAP).

لكن المرحلة الثانية من ZATCA لم تُصمَّم وفق نموذج بيانات Odoo. الاحتكاك يظهر في ثلاث نقاط:

  1. بنية بوابة فاتورة. بوابة فاتورة هي واجهة الهيئة لإعداد الأجهزة. أنت تطلب معرّف ختم تشفيري (CSID) لكل دفتر مبيعات، ثم تفعّل الجهاز إما في البيئة التجريبية (المحاكاة) أو الإنتاج. عمليات المقاصة والإبلاغ تتم عبر XML و API مع تحقق صارم من مخطط UBL 2.1 — لا يوجد تجاوز يدوي.
  2. جهاز لكل دفتر يومية. كل دفتر مبيعات في Odoo (نقاط البيع، المتجر الإلكتروني، خدمات B2B، التصنيع، إلخ) يحتاج جهاز ZATCA خاص به على البوابة. المجموعات السعودية متعددة الشركات قد تنتهي بإعداد 8-15 جهازاً داخل بيئة Odoo واحدة.
  3. الفترة التجريبية إلزامية. تشترط ZATCA تشغيل التكامل بالكامل على بيئة المحاكاة، توليد فواتير اختبارية، ثم الترقية إلى الإنتاج. والترقية نفسها بوابة أحادية الاتجاه — التفاصيل بعد قليل.

أضِف إلى ذلك تقارير الهجري، رواتب متوافقة مع GOSI، وتكاملات مع مدى و Apple Pay و STC Pay، وستجد أن "تثبيت بسيط لوحدة ZATCA" يتحوّل إلى مشروع ستة أسابيع.

العقبات الخمس التي تؤذي فعلاً

مرتّبة حسب عدد المرات التي كلّفتنا فيها إعادة نشر. هذه العقبات تظهر مرة أخرى في قسم الأسئلة الشائعة أسفل المقالة.

1. انتهاء صلاحية رمز OTP خلال دقيقتين أثناء إعداد الجهاز

عند إعداد جهاز دفتر مبيعات عبر بوابة فاتورة، ترسل ZATCA رمز OTP عبر البريد الإلكتروني أو الرسائل النصية تنتهي صلاحيته خلال 120 ثانية. يجب إدخاله داخل معالج ZATCA في Odoo قبل انتهائه.

عملياً: مسؤول المالية الذي يملك الوصول إلى بوابة فاتورة ومسؤول Odoo يجب أن يكونا معاً (أو على مكالمة مشاركة شاشة مباشرة) أثناء الإعداد. محاولة إنجاز العملية بشكل غير متزامن — "سأرسل لك الرمز على واتساب" — فشلت معنا أكثر من مرة بسبب تأخّر تسليم الرسائل وحده.

الحل البديل: جهّز معالج Odoo حتى الخطوة التي تطلب فيها OTP، ثم اطلب الرمز. بذلك تكسب الـ 120 ثانية كاملة.

2. التبديل أحادي الاتجاه من البيئة التجريبية إلى الإنتاج

التبديل بين البيئات في ZATCA غير قابل للعودة. بمجرد ترقية جهاز دفتر يومية في Odoo من المحاكاة إلى الإنتاج، لا يمكنك إعادته. وإذا فشل التحقق من مخطط XML على أول فاتورة حقيقية — مثلاً بسبب رقم تسجيل ضريبي يحوي مسافة زائدة، أو حقل عنوان مشترٍ ينقصه وسم UBL المسمى streetName — فلا يمكنك ببساطة إعادة المحاولة من البيئة التجريبية. ستحتاج إلى تصعيد عبر دعم ZATCA لإلغاء تفعيل الجهاز وإعادة إعداده، وهذا استغرق منا 3-7 أيام عمل في حالات سابقة.

التخفيف: ولّد على الأقل 50-100 فاتورة تمثيلية في المحاكاة (B2B، B2C، إشعارات دائنة، إشعارات مدينة، عملات أجنبية، أصناف مجانية) وتأكد من أن كل واحدة تجتاز المقاصة قبل تفعيل التبديل. بيئة المحاكاة تتصرف بنفس طريقة الإنتاج في التحقق — استخدمها.

3. إعدادات متعددة الشركات في السعودية تضاعف عدد الأجهزة

تشغّل المجموعات التجارية السعودية في الغالب عدة كيانات قانونية داخل بيئة Odoo واحدة — شركة قابضة، ذراع تجزئة، ذراع مقاولات، كيان عقاري. كل كيان له تسجيل ضريبي خاص. كل تسجيل ضريبي يحتاج إعداد فاتورة منفصل. وكل دفتر مبيعات داخل الكيان يحتاج جهازه الخاص.

رأينا بيئة Odoo واحدة تحتاج 14 جهازاً عبر 4 شركات ودفاتر نقاط البيع والإلكتروني و B2B. ذلك يعني 14 نافذة OTP، 14 معرّف CSID يجب تخزينها بأمان، و 14 قرار تبديل للإنتاج. خصّص وقتاً لها — ووثّق مكان تخزين CSID لكل جهاز قبل البدء، لا بعده.

4. تشغيل خاطئ للفترة التجريبية = غرامات على فواتير اختبارية

هذه عقبة شرسة. تتوقع بوابة فاتورة أن تفعّل بوابة المحاكاة في مرحلة محددة من رحلة الإعداد — بعد الاختبار في البيئة التطويرية، وقبل الانتقال للإنتاج. إذا أعدّ فريقك خطأً نقطة نهاية الإنتاج بينما الجهاز ما زال في وضع المحاكاة (أو العكس)، فقد تُصنّف بعض الفواتير الاختبارية كإرسال فعلي على ملف جهاز خاطئ — والإرسالات الفعلية غير المتوافقة تستوجب غرامات.

[verify] رأينا عميلاً واحداً تلقى إشعاراً رسمياً بسبب هذا الخطأ بالتحديد؛ تنازلت ZATCA عن الغرامة بعد أن قدّمنا سجلات التكامل التي تثبت النية، لكن القرار يبقى تقديرياً للمفتش. تعامَل مع تفعيل وضع المحاكاة على أنه بوابة تحكم رسمية في التغيير: شخص واحد يضغط الزر، التغيير موثّق في متتبّع المشروع، ولا تصل أي معاملات مُعلَّمة كإنتاج إلى الـ API قبل اجتياز البوابة.

5. تقارير الهجري + طبقة رواتب GOSI

المرحلة الثانية من ZATCA نفسها لا تشترط الهجري — التواريخ الميلادية مقبولة في فاتورة XML. لكن فريقك المالي السعودي سيتوقع التقارير الشهرية والربعية بـالهجري، ووحدة رواتب GOSI يجب أن تحتسب الاشتراكات على دورات رواتب هجرية. توطين Odoo القياسي (l10n_sa, l10n_sa_edi, l10n_sa_hr_payroll) يغطي الأساسيات لكنه يحتاج في الغالب قوالب تقارير مخصصة — وحالات الحافة في تحويل الهجري/الميلادي (طول شهر رمضان، تداخل نهاية السنة) تظهر عند إقفال الشهر.

هذه ليست عقبة مانعة للموجة 24 بذاتها، لكنها ستكون تصعيد الأسبوع الثاني بعد الانتقال للإنتاج — خطّط لها الآن.

قائمة التجهيز من عشر نقاط

انسخ هذه القائمة إلى أداة إدارة المشاريع لديك. نستخدمها في كل تطبيق سعودي لـ Odoo:

  1. تأكد من أن التسجيل الضريبي نشط ومطابق تماماً لاسم السجل التجاري السعودي.
  2. احصر كل دفاتر المبيعات التي ستصدر فواتير: نقاط البيع، المتجر الإلكتروني، خدمات B2B، بيع بين الشركات، المشاريع، التصنيع. كل واحد = جهاز ZATCA.
  3. ثبّت / حدّث وحدة Odoo l10n_sa_edi بإصدار يطابق نسخة Odoo لديك (17 أو 19). راجع سجل التغييرات للوحدة بحثاً عن أي تغييرات كاسرة.
  4. تحقّق من بيانات المشترين الرئيسية: كل عميل B2B يجب أن يحوي رقم التسجيل الضريبي، الاسم القانوني الكامل بالعربية والإنجليزية، وعنواناً متوافقاً مع UBL (المدينة، الرمز البريدي، الشارع، رقم المبنى).
  5. أنشئ حسابات بوابة فاتورة لكل كيان قانوني. اختبر تسجيل الدخول لكل حساب قبل الحاجة إلى OTP.
  6. أعدّ كل الأجهزة في البيئة التطويرية أولاً. اختبر تحت ضغط بإشعارات دائنة، فواتير عملات أجنبية، إعفاءات ضريبية على مستوى الصنف.
  7. أرسل 50-100 فاتورة محاكاة عبر البوابة. التقط واستعرض كل استجابة مقاصة XML.
  8. أحكم تخزين CSID: كل CSID سرّ. استخدم مخزن المعاملات المشفّر في Odoo أو مدير أسرار خارجي — لا تستخدم ورقة Google Sheet مشتركة.
  9. جدوِل التبديل للإنتاج خارج ساعات الذروة. الجمعة سيئ (عطلة الأسبوع في السعودية)؛ اختر صباح الثلاثاء أو الأربعاء حتى يكون دعم ZATCA متاحاً بالكامل عند الحاجة.
  10. درّب اثنين من فريق المالية على قراءة استجابات فشل المقاصة. أكواد الخطأ ليست من Odoo — بل من ZATCA — وفريقك يحتاج إلى فرزها دون تصعيد كل خطأ إلى تقنية المعلومات.

نمط البنية الذي توصي به نقطة

ننشر تكامل ZATCA المرحلة الثانية على Odoo في ثلاث بيئات بأسماء واضحة، مع بوابة ترقية مدروسة بين كل واحدة والأخرى:

[1] تطويرية         [2] محاكاة             [3] إنتاج
(قاعدة بيانات      (قاعدة بيانات          (قاعدة بيانات
Odoo dev)        →   Odoo staging)     →   Odoo prod)
+ ZATCA sandbox      + ZATCA simulation     + ZATCA production
- إعادة تهيئة         - إعادة تهيئة          - بوابة أحادية
  غير محدودة           غير محدودة             الاتجاه

البوابة 1 → 2: اختبار كل دفاتر المبيعات بفواتير تجريبية، التحقق من كل مخططات XML للمقاصة، إصدار كل معرفات CSID بنجاح في sandbox.

البوابة 2 → 3: اجتياز 50+ فاتورة تمثيلية في المحاكاة، توقيع فريق المالية على مخرجات UBL بالعربية/الإنجليزية، وضع الأسرار في مدير أسرار الإنتاج (وليس ir.config_parameter كنص عادي)، ووجود دليل تشغيل للتراجع — رغم أن التراجع الكامل غير ممكن، فإن التراجع الجزئي (تعطيل دفاتر يومية محددة عبر Odoo دون إرجاع جهاز ZATCA) هو ما يمنحك الأمان التشغيلي.

اقرن ذلك بـتدقيق صادق لجاهزية الفوترة الإلكترونية قبل البدء. إطار التدقيق مكتوب لسياق El Fatoora التونسي، لكن البنية — جودة البيانات، نظافة البيانات الرئيسية، حصر الدفاتر، مسارات التصعيد — تنطبق نظيفة على ZATCA.

ملاحظة عن أمان Odoo

يستحق الذكر لأن الثقة مهمة في تكاملات المالية: بصمة Odoo في قواعد بيانات CVE منخفضة بشكل لافت — حوالي 53 CVE منشورة عن كامل المورد منذ 2017 (مقارنة بمئات في أنظمة ERP المماثلة). الأهم حديثاً هو CVE-2024-36259 — ثغرة كشف معلومات بعد المصادقة في وحدة البريد لـ Odoo 17، تم إصلاحها في إصدارات الصيانة اللاحقة.

نتيجتان عمليتان:

  • إذا كنت لا تزال على Odoo 16 أو إصدار فرعي غير مرقّع من Odoo 17، رقِّ قبل أن تبدأ إعداد ZATCA. لا تريد أن تكون مشغولاً بترقيع ERP الأساسي أثناء انتقال الموجة 24.
  • معظم تنبيهات أمن Odoo محصورة خلف اشتراك Enterprise نشط. إذا كنت تستخدم Community Edition، خصّص ميزانية إما للترقية إلى Enterprise أو لبناء عملية متابعة CVE خاصة بك — مع ساعة شهرية على الأقل لمراجعة الترقيع.

الأسئلة الشائعة

س1: متى بالضبط تستحق الموجة 24 من ZATCA؟ 30 يونيو 2026، للمنشآت التي تتراوح إيراداتها السنوية الخاضعة للضريبة بين 375,000 و 750,000 ريال. الموعد النهائي للموجة 23 (750 ألف – 1 مليون ريال) كان 31 مارس 2026 وهو الآن في مرحلة التطبيق.

س2: هل يمكنني تمديد رمز OTP لفاتورة بعد الدقيقتين؟ لا. ينتهي الرمز خلال 120 ثانية ولا توجد طريقة لتمديده. جهّز معالج Odoo حتى خطوة طلب OTP قبل أن تطلب الرمز، وستحصل على النافذة الكاملة.

س3: رقّينا دفتر يومية Odoo إلى الإنتاج بالخطأ — هل يمكن التراجع؟ ليس مباشرة. التبديل من البيئة التطويرية إلى الإنتاج أحادي الاتجاه. ستحتاج إلى فتح تذكرة دعم لدى ZATCA لإلغاء تفعيل الجهاز ثم إعادة إعداده. المتوسط في تجربتنا 3-7 أيام عمل، فلا ترقِّ ما لم تكن متيقّناً.

س4: نشغّل 4 شركات سعودية في بيئة Odoo واحدة — هل كل واحدة تحتاج إعداداً مستقلاً؟ نعم. كل كيان قانوني له تسجيل ضريبي خاص ويحتاج حساب بوابة فاتورة خاصاً، ومجموعة CSID خاصة، وإعداد جهاز لكل دفتر مبيعات. إعداد بأربع شركات و3 دفاتر مبيعات لكل شركة = 12 جهازاً.

س5: هل تتطلب ZATCA تقارير بالتقويم الهجري؟ لا — تقبل ZATCA التواريخ الميلادية في فاتورة XML. لكن فريقك المالي السعودي سيتوقع التقارير الإدارية الداخلية بالهجري، ورواتب GOSI تُحتسب على دورات هجرية. خطّط لقوالب تقارير Odoo مخصصة منذ اليوم الأول، لا في الشهر الثاني.

تحتاج مساعدة في الموجة 24؟

مع ستة أسابيع متبقية على الموعد النهائي، الجدول ضيق. إذا أردت متخصصاً في Odoo + السعودية يضغط على خطة الموجة 24 لديك، يحدد أيّ العقبات الخمس تعرّضك للخطر، ويحدد نطاقاً واقعياً للتسليم، احجز مكالمة استشارية مدتها 30 دقيقة مع فريقنا. سنخبرك بصراحة هل يمكنك تحقيق 30 يونيو أم أنك بحاجة إلى خطة بديلة.

مصادر موثوقة

قراءة ذات صلة