الإرشادات العشر لنظام الفوترة الوطني: ما تعنيه كل منها للأنظمة المرتبطة

حين تقرر أن يرسل برنامجك المحاسبي فواتيره إلى نظام الفوترة الوطني مباشرة، يصبح نظامك مسؤولًا عن أمور كان موقع النظام يتولاها عنك. ولهذا خصصت دائرة ضريبة الدخل والمبيعات في دليلها التقني صفحة لقائمة قصيرة اسمها «الإرشادات»، وهي ما نسميه في هذا المقال الإرشادات العشر لنظام الفوترة الوطني. عشرة بنود في صفحة واحدة، لكل بند عنوان وسطر أو سطران من الوصف.

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

ما الإرشادات العشر لنظام الفوترة الوطني ومن تخاطب

ترد الإرشادات في الصفحة 104 من «الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)»، الإصدار 1.5 الصادر في 12 مايو 2026 عن مديرية شؤون الفوترة، قسم الدعم الفني، في دائرة ضريبة الدخل والمبيعات. وموقعها قرب آخر الدليل له دلالة، فهي تأتي بعد شرح بنية الملف وطريقة الإرسال وشكل الاستجابة، وتجمع خلاصتها التشغيلية في جدول واحد.

وتخاطب هذه الإرشادات نظام المكلف الذي يرسل الفواتير عبر الواجهة البرمجية، لأنها جزء من الدليل التقني للربط. ويقول «دليل إجراءات الانضمام إلى نظام الفوترة الوطني الإلكتروني» الصادر عن الدائرة إنه «يتوجب على المكلف التنسيق مع مبرمج النظام أو مزود الحلول التقنية المعتمد لديه لاستكمال المتطلبات الفنية»، والمقصود هنا المزوّد الذي يتعامل معه المكلف، لا قائمة مزوّدين تعتمدها الدائرة. فإذا كان برنامجك يتولى الإرسال، فهذه الإرشادات تصف ما يجب أن يفعله برنامجك، وما يجب أن تتأكد منه أنت.

هذه هي العناوين العشرة بترتيبها في الدليل، ومعها خلاصة ما يطلبه كل إرشاد وما يعنيه لنظامك.

الإرشادان الأول والثاني: ما يحدث قبل أن تغادر الفاتورة نظامك

1. الالتزام بمعيار البيانات

نص الإرشاد أنه «يجب أن يكون ملف الفاتورة بصيغة XML مطابق لمعيار UBL 2.1، وأي خلل في البنية يؤدي إلى رفض الفاتورة». والكلمة المهمة هنا «البنية»، فالمقصود شكل الملف قبل قيمه.

ومن أمثلة البنية التي يحددها الدليل أن يبدأ كل ملف بالمقدمة نفسها، وأن يحمل الحقل cbc:ProfileID القيمة reporting:1.0 في كل فاتورة، وأن يأتي وسم الفتح <Invoice> بكامل خصائصه في سطر واحد. فإن انقسم هذا الوسم على أكثر من سطر ظهرت رسالة Invalid Invoice Minification (ص102). ثم يُرمَّز الملف بترميز Base64 ويوضع داخل ملف JSON قبل الإرسال.

عمليًا، هذا الإرشاد مسؤولية من بنى البرنامج أكثر منه مسؤولية المحاسب. لكن من المفيد أن تعرف أن الرفض هنا يأتي من شكل الملف نفسه، فلا يصلحه تعديل رقم أو مبلغ. وتجد تفصيل المعيار في مقال معيار UBL 2.1 في نظام الفوترة الوطني.

2. التحقق قبل الإرسال

يطلب الدليل التأكد من صحة البيانات قبل الإرسال، ويضرب لذلك أمثلة هي المجاميع والضرائب ورقم المكلف ورقم المشتري والحقول الإلزامية، ويذكر الغاية صراحة، وهي «تقليل أخطاء 400».

والمعنى العملي أن يفحص نظامك الفاتورة بنفسه قبل أن يرسلها، بدل أن ينتظر النظام ليرفضها. ومن الأسئلة التي يجيب عنها هذا الفحص ما يلي.

• هل تساوي مجاميع الرأس مجموع البنود؟ هذا ما تفحصه رسالة Total General Amount is Not Correct، المشروحة في مقال رسالة Total General Amount is Not Correct.
• هل الرقم الضريبي للبائع صحيح، وهل يتوافق نوع الفاتورة مع رقمه الضريبي وتسلسل مصدر الدخل الذي يرسل عليه؟
• هل بيانات المشتري مكتملة بالقدر الذي يطلبه نوع الفاتورة؟
• هل امتلأت الحقول الإلزامية كلها؟ يميّز الدليل هذه الحقول بالتظليل الأصفر في جداوله، كما يشرح مقال الحقول الإجبارية والاختيارية في نظام الفوترة الوطني.

والربط بين هذا الإرشاد ورمز 400 ربط ذكره الدليل نفسه، فرمز 400 هو الرمز الذي يعود حين يكون في قيم ملف XML خطأ تفصّله رسالة EINV_MESSAGE. وتقرأ طريقة التعامل مع هذه الرسائل في مقال خطأ 400 في نظام الفوترة الوطني.

الإرشادان الثالث والرابع: إعادة الإرسال وقراءة الاستجابة

3. إدارة إعادة الإرسال

يقول الدليل إنه «عند فشل الإرسال يجب إعادة الإرسال باستخدام نفس ID و UUID لتجنب إنشاء فاتورة جديدة أو تكرار البيانات». وسبب هذا الشرط أن هوية الفاتورة في النظام هي الزوج معًا، أي رقم الفاتورة في cbc:ID والمعرّف الفريد في cbc:UUID. فإذا أعدت الإرسال بمعرّف جديد، فأنت في نظر النظام ترسل فاتورة أخرى.

والفائدة العملية لهذا الشرط تظهر حين لا تعرف هل وصلت الفاتورة الأولى أم لا. فإذا كانت قد قُبلت فعلًا، فإن إعادة إرسالها بالرقم نفسه والمعرّف نفسه تعيد الحالة ALREADY_SUBMITTED ومعها رمز QR الأصلي، فلا تتكرر الفاتورة. ويشرح مقال المعرّف الفريد UUID في نظام الفوترة الوطني هذا الزوج بالتفصيل، ويتناول مقال مستقل في هذه السلسلة حالة ALREADY_SUBMITTED نفسها.

4. التعامل مع الاستجابة

نص الإرشاد أنه «لا يُعتمد على Status Code فقط، وإنما يجب الاعتماد على قيمة EINV_STATUS لتحديد حالة الفاتورة النهائية». ففي رد النظام طبقتان. الأولى رمز الحالة التقني للطلب، وهو يخبرك أن الطلب وصل وعولج تقنيًا. والثانية EINV_STATUS، وهي الحالة الرسمية للفاتورة نفسها.

ويذكر الدليل ثلاث قيم لهذه الحالة، وعلى نظامك أن يتصرف على أساسها.

• SUBMITTED، ومعناها أن الفاتورة قُبلت وعاد معها رمز QR.
• ALREADY_SUBMITTED، ومعناها أن الفاتورة نفسها أُرسلت من قبل بالرقم والمعرّف نفسيهما، ويعود معها رمز QR الأصلي.
• NOT_SUBMITTED، ومعناها أن الفاتورة رُفضت. وفي هذه الحالة لا يكون رمز الحالة 200، وتأتي قيم رمز QR والمعرّف والرقم والفاتورة الموقّعة فارغة.

ويضيف الدليل في ملاحظاته التشغيلية شرطًا يكمل هذا الإرشاد، وهو التحقق من وجود رمز QR في العنصر EINV_QR لاكتمال استلام الفاتورة واعتمادها. فالقاعدة العملية لنظامك ألا يعدّ الفاتورة مقبولة إلا إذا اجتمع أمران، حالة تدل على القبول، ورمز QR موجود في الرد.

الإرشادان الخامس والسادس: حفظ البيانات الأساسية وإدارة الأخطاء

5. تخزين البيانات الأساسية

يطلب الدليل أن يحفظ نظامك أربع قيم هي ID وUUID وQR Code وEINV_STATUS، والغاية بنص الدليل «لضمان التتبع وإعادة الاسترجاع عند الحاجة».

ولكل قيمة من الأربع سبب عملي. فرقم الفاتورة ومعرّفها هما ما تحتاجه لإعادة الإرسال بالهوية نفسها، ولربط فاتورة الإرجاع بفاتورتها الأصلية. ورمز QR هو ما يجب أن يظهر على فاتورة البائع. وحالة الفاتورة هي ما يحسم هل قُبلت أم لا. ومن لم يحفظ رمز QR يستطيع استعادته بإعادة إرسال الفاتورة نفسها، لأن الحالة ALREADY_SUBMITTED تعيد الرمز الأصلي، وهذا هو الطريق الموثق في الدليل لاستعادة رمز لم يُحفظ.

6. إدارة الأخطاء

نص الإرشاد «تسجيل جميع الأخطاء بشكل تفصيلي داخليًا، مع عرض رسالة مبسطة للمستخدم النهائي». فهو يطلب أمرين في آن واحد، سجلًا كاملًا للفريق التقني، ورسالة مفهومة لمن يصدر الفاتورة.

ويساعد شكل الرد على تطبيق هذا الإرشاد. ففي العنصر EINV_RESULTS ثلاث مجموعات هي INFO وWARNINGS وERRORS، وكل عنصر فيها يحمل النوع والحالة والرمز EINV_CODE والفئة EINV_CATEGORY والرسالة EINV_MESSAGE. والتطبيق العملي أن يحفظ نظامك هذه العناصر كما وصلت، ثم يعرض للمحاسب جملة واضحة تقول له ما الحقل الذي يحتاج تصحيحًا. ومن أمثلة الدليل نفسه خطأ رمزه totalGeneralTaxesAmount وفئته invoice ورسالته Total General Amount is Not Correct. ولقراءة الأخطاء ورموزها مجتمعة، راجع مقال أخطاء نظام الفوترة الوطني.

الإرشادات السابع والثامن والتاسع: الأمان والانقطاع والتوقيت الزمني

7. الأمان

يطلب الدليل «حماية بيانات الربط مثل Client_ID و Secret_Key وعدم تخزينها بشكل مكشوف داخل الكود البرمجي». ويضيف تحت العنوان نفسه أن مسؤولية الحفاظ على سرية رقم المستخدم والمفتاح السري وعدم مشاركتهما تقع على عاتق المكلف، وأنه «يتحمّل كامل المسؤولية عن أي استخدام غير مصرح به».

وهاتان القيمتان يولّدهما النظام حين يختار المكلف «ربط الأجهزة» ويحدد تسلسل مصدر الدخل، فكل زوج منهما مرتبط بتسلسل مصدر دخل واحد. وهما يُرسلان في ترويسة كل طلب إرسال. والتطبيق العملي أن تُحفظ القيمتان في مكان محمي من إعدادات النظام، لا في نص البرنامج، وألا تُرسلا في رسائل البريد أو المحادثات. وتجد طريقة إنشائهما في مقال رقم المستخدم والمفتاح السري في نظام الفوترة الوطني، وإذا كان الخطأ في إحداهما فالرمز المعتاد هو 403، كما يشرح مقال خطأ 403 في نظام الفوترة الوطني.

8. معالجة الانقطاع

نص الإرشاد «عند حدوث Timeout أو فشل اتصال يجب إعادة المحاولة دون توليد UUID جديد». وهو تطبيق للإرشاد الثالث على حالة بعينها، هي الحالة التي لا يصلك فيها رد أصلًا، فلا تعرف هل وصلت الفاتورة أم لم تصل.

ومن أمثلة هذه الحالة رمز 504، الذي يعني بحسب الدليل أن نظامك لم يتمكن من الوصول إلى نظام الفوترة الوطني، والسبب إما جدار الحماية لدى المكلف وإما موقع الدائرة. وتفصيله في مقال خطأ 504 في نظام الفوترة الوطني. ولا يحدد الدليل عدد مرات إعادة المحاولة ولا المدة بين كل محاولة وأخرى، فهذا قرار يتخذه من يبني النظام. الثابت الوحيد في النص هو أن المعرّف لا يتغير بين المحاولات.

9. التوقيت الزمني

هذا الإرشاد ننقله كما ورد حرفيًا، «استخدام تنسيق زمني موحد (Standard Time Format) لتجنب اختلافات المعالجة بين الأنظمة».

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

الإرشاد العاشر: تتبع العمليات (Audit Trail)

نص الإرشاد «تسجيل جميع العمليات (إرسال، استجابة، إعادة إرسال) لضمان التتبع والتدقيق». والفرق بينه وبين الإرشاد الخامس أن الخامس يحفظ النتيجة النهائية لكل فاتورة، أما العاشر فيحفظ القصة كاملة، أي كل محاولة إرسال وكل رد وكل إعادة إرسال، بترتيبها.

وقيمة هذا السجل تظهر حين يُطرح سؤال عن فاتورة بعينها. متى أُرسلت أول مرة؟ وما الرد الذي عاد؟ وكم مرة أُعيد إرسالها قبل أن تُقبل؟ ومع السجل والقيم الأربع المحفوظة في الإرشاد الخامس يستطيع نظامك أن يجيب عن هذه الأسئلة دون تخمين.

الملاحظات التشغيلية التي ترافق الإرشادات في الدليل

تحت جدول الإرشادات مباشرة يضع الدليل أربع «ملاحظات تشغيلية مهمة». وهي تشرح بعض الإرشادات من زاوية أخرى، وتضيف قاعدة لا ترد في الجدول.

1. هوية الفاتورة زوج من قيمتين. يقول الدليل إن رقم الفاتورة في النظام «لا يقتصر على رقم الـ ID فقط، وإنما يتكوّن من الـ ID والـ UUID معًا كمفتاح رئيسي (Primary Key)». وهذا ما يجعل الإرشادين الثالث والثامن ممكنين.
2. المعرّف المولّد تلقائيًا يُحفظ ويُعاد استعماله. ينبه الدليل إلى أن عدم تخزين المعرّف المولّد تلقائيًا قد يؤدي إلى تكرار الفواتير عند إعادة الإرسال.
3. رمز QR شرط للاعتماد، ويُظهر على فاتورة البائع. يطلب الدليل التحقق من وجود الرمز في EINV_QR لاكتمال استلام الفاتورة واعتمادها، ويقول «يجب إظهار QR CODE رمز الاستجابة السريع على فاتورة البائع». والفعل في النص هو الإظهار.
4. رقم البند يُحفظ من فاتورة البيع. وهذه هي القاعدة الجديدة. فالدليل يطلب الاحتفاظ برقم ID الخاص بكل سلعة عند إصدار فاتورة البيع، لأن مطابقة السلع في فاتورة الإرجاع تتم على هذا الرقم. وفاتورة الإرجاع في نظام الفوترة الوطني تكون على الكميات، ولا تتجاوز الكمية المباعة.

أما التحقق من رمز QR بعد صدور الفاتورة، فيذكر الدليل أنه يتم من خلال تطبيق سند فقط، من خيار «التحقق من المستندات الرقمية».

قائمة مراجعة سريعة لنظامك قبل أول فاتورة

إذا كنت تراجع برنامجًا قبل اعتماده، أو تراجع ربطًا قائمًا، فهذه الأسئلة العشرة تختصر الإرشادات بالترتيب نفسه. وكل جواب بالنفي يدلك على الإرشاد الذي يحتاج إلى معالجة.

1. هل يخرج ملف الفاتورة بصيغة UBL 2.1، بالمقدمة نفسها، ووسم الفتح في سطر واحد؟
2. هل يفحص النظام المجاميع والضرائب والرقم الضريبي ورقم المشتري والحقول الإلزامية قبل الإرسال؟
3. عند فشل الإرسال، هل يعيد النظام الإرسال برقم الفاتورة نفسه ومعرّفها نفسه؟
4. هل يحكم النظام على الفاتورة من قيمة EINV_STATUS ووجود رمز QR، لا من رمز الحالة التقني وحده؟
5. هل يحفظ النظام لكل فاتورة رقمها ومعرّفها ورمز QR وحالتها؟
6. هل تُسجَّل الأخطاء كاملة داخليًا، وتُعرض للمستخدم رسالة مبسطة؟
7. هل رقم المستخدم والمفتاح السري محفوظان في مكان محمي، لا مكشوفين في نص البرنامج؟
8. عند انقطاع الاتصال، هل تتم إعادة المحاولة دون توليد معرّف جديد؟
9. هل تستعمل أنظمتك تنسيقًا زمنيًا موحدًا؟
10. هل يوجد سجل لكل عملية إرسال واستجابة وإعادة إرسال؟

ويضاف إليها سؤالان من الملاحظات التشغيلية. هل يظهر رمز QR على فاتورة البائع؟ وهل يحفظ النظام رقم البند لكل سلعة استعدادًا للإرجاع؟ وإذا احتجت إلى استفسار لا يجيب عنه الدليل، فالدليل نفسه يحيلك إلى لجنة الدعم الفني لشؤون الفوترة في دائرة ضريبة الدخل والمبيعات عبر موقع الدائرة.

ما الذي يتولاه قيود من هذه الإرشادات

الإرشادات العشر تصف عمل نظام المكلف، وهذا العمل يتولاه برنامجك المحاسبي إذا كان هو من يرسل الفواتير. ويعمل تكامل قيود مع نظام الفوترة الوطني على هذه الطبقة كما يلي.

• بناء الملف والمعرّف. يبني قيود ملف الفاتورة بصيغة UBL 2.1 مع المعرّف الفريد، ويرسله إلى نظام الفوترة الوطني دون أي تدخل يدوي.
• فحص قبل الإرسال. يفحص قيود كل فاتورة على مستوى الحقول لحظة إنشائها، وهي الرقم الضريبي، ونوع المستند وطريقة الدفع، ونسبة ضريبة المبيعات العامة، واكتمال البنود، وينبهك بأي خطأ قبل إرسالها لتقليل حالات الرفض.
• حالة كل فاتورة أمامك. تعيد الدائرة حالة الفاتورة ورسالة الخطأ، ويعرضها قيود في لوحة الحالة، ومنها «مرسلة» و«مرسلة مسبقًا» و«لم تُرسل» مع رسالة الخطأ.
• إعادة إرسال بالمعرّف نفسه. تعرض لوحة الحالة الفواتير التي لم تُرسل وتحتاج إلى إعادة إرسال، وحين تعيد إرسالها تُرسل بالمعرّف UUID نفسه. وإعادة الإرسال خطوة تقوم بها أنت من لوحة الحالة.

أما رمز QR فتعيده الدائرة بعد قبول الفاتورة، ويظهر على الفاتورة التي يصدرها قيود. ويبقى الإرشاد السابع على عاتقك كما يقول الدليل، فسرية رقم المستخدم والمفتاح السري مسؤولية المكلف. ولصورة أوسع عن النظام وطريقة ربط منشأتك به، اقرأ مقال نظام الفوترة الوطني الالكتروني، أو تعرّف على ما يقدمه قيود في نظام الفوترة الوطني.

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

ما الإرشادات العشر لنظام الفوترة الوطني؟

هي عشرة إرشادات تشغيلية في الصفحة 104 من الدليل التقني الصادر عن دائرة ضريبة الدخل والمبيعات، الإصدار 1.5. وعناوينها الالتزام بمعيار البيانات، والتحقق قبل الإرسال، وإدارة إعادة الإرسال، والتعامل مع الاستجابة، وتخزين البيانات الأساسية، وإدارة الأخطاء، والأمان، ومعالجة الانقطاع، والتوقيت الزمني، وتتبع العمليات (Audit Trail).

لمن تُوجَّه هذه الإرشادات؟

تُوجَّه إلى نظام المكلف الذي يرسل الفواتير عبر الواجهة البرمجية، لأنها جزء من الدليل التقني للربط. ويطلب دليل إجراءات الانضمام الصادر عن الدائرة من المكلف التنسيق مع مبرمج النظام أو مزود الحلول التقنية الذي يتعامل معه لاستكمال المتطلبات الفنية.

هل يكفي أن يعود رمز الحالة 200 لأعرف أن الفاتورة قُبلت؟

لا يكفي ذلك. ينص الإرشاد الرابع على عدم الاعتماد على رمز الحالة وحده، وعلى الاعتماد على قيمة EINV_STATUS لتحديد حالة الفاتورة النهائية، ويطلب الدليل كذلك التحقق من وجود رمز QR في العنصر EINV_QR.

كم مرة يعيد النظام المحاولة عند انقطاع الاتصال؟

لا يحدد الدليل التقني عدد المحاولات ولا المدة بينها. الذي يحدده هو أن إعادة المحاولة تتم دون توليد معرّف UUID جديد، وبرقم الفاتورة نفسه.

ما القيم التي يطلب الدليل حفظها لكل فاتورة؟

يطلب الإرشاد الخامس حفظ أربع قيم هي رقم الفاتورة ID والمعرّف الفريد UUID ورمز QR وحالة الفاتورة EINV_STATUS. وتضيف الملاحظات التشغيلية حفظ رقم البند لكل سلعة لاستعماله في فواتير الإرجاع، ويضيف الإرشاد العاشر سجلًا كاملًا لعمليات الإرسال والاستجابة وإعادة الإرسال.

من المسؤول عن سرية رقم المستخدم والمفتاح السري؟

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

المراجع

• دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026، ص7 وص8 وص10 وص97 إلى ص102 وص104.
• دائرة ضريبة الدخل والمبيعات، دليل إجراءات الانضمام إلى نظام الفوترة الوطني الإلكتروني، إصدار 2026.