يرسل برنامجك المحاسبي الفاتورة إلى نظام الفوترة الوطني عبر الواجهة البرمجية، فيعود رد، وقد يتبعه إرسال ثانٍ إذا رُفضت الفاتورة أو انقطع الاتصال. تتبع العمليات في نظام الفوترة الوطني هو أن يحتفظ نظامك بأثر مكتوب لكل خطوة من هذه الخطوات، وهو عنوان الإرشاد العاشر في الدليل التقني الصادر عن دائرة ضريبة الدخل والمبيعات، ونصه «تسجيل جميع العمليات (إرسال، استجابة، إعادة إرسال) لضمان التتبع والتدقيق».
الجواب المختصر أن الدليل يطلب ثلاثة أمور متصلة، أن يحفظ نظامك لكل فاتورة أربع قيم هي ID وUUID وQR Code وEINV_STATUS، وأن يسجل الأخطاء تفصيليًا في الداخل مع رسالة مبسطة للمستخدم، وأن يسجل كل إرسال واستجابة وإعادة إرسال. أما شكل هذا التسجيل ومكانه ومدة بقائه فلا يحددها الدليل. هذا المقال موجّه إلى من يبني ربط نظام محاسبي أو نظام موارد مؤسسية مع نظام الفوترة الوطني أو يراجعه، ويجمع الإرشادات الثلاثة في تصميم واحد يمكن تطبيقه، مع فصل واضح بين ما ينص عليه الدليل وما نقترحه نحن.
ما معنى تتبع العمليات في نظام الفوترة الوطني
ترد الإرشادات العشر في الصفحة 104 من «الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)»، الإصدار 1.5 الصادر في 12 مايو 2026 عن مديرية شؤون الفوترة في دائرة ضريبة الدخل والمبيعات. وعنوان الإرشاد العاشر فيها «تتبع العمليات (Audit Trail)». ويتصل به إرشادان قبله في الجدول نفسه، الخامس وعنوانه «تخزين البيانات الأساسية»، والسادس وعنوانه «إدارة الأخطاء».
يجيب كل إرشاد من الثلاثة عن سؤال مختلف بحسب قراءتنا. فالخامس يحدد ما يبقى محفوظًا عن الفاتورة في حالتها الأخيرة، والسادس يحدد كيف يُعامل الخطأ داخل النظام وأمام المستخدم، والعاشر يحدد أن تبقى كل عملية مرت بها الفاتورة مسجلة بترتيبها. والفرق بين الخامس والعاشر هو الفرق بين صورة الفاتورة الآن وتاريخها كاملًا، فقد تنتهي فاتورة بالحالة SUBMITTED بعد رفض أول ثم إعادة إرسال، والقيم الأربع تحفظ النتيجة الأخيرة، أما سجل العمليات فيحفظ الطريق إليها.
ويبقى هذا الإرشاد تقنيًا يخص نظامك المرتبط. فهو غير سجل فواتير البيع الورقي أو المحوسب الذي تشترطه المادة (6) من نظام تنظيم شؤون الفوترة والرقابة عليها، وغير مدة الاحتفاظ بالفواتير التي تنظمها المادة (8) من النظام نفسه، وتفصيلها في مقال الاحتفاظ بفواتير نظام الفوترة الوطني. ولا يربط الدليل التقني الإرشاد العاشر بأي مدة.
النصوص التي يقوم عليها التصميم كما وردت في الدليل
قبل أي تصميم، هذه نصوص الإرشادات ذات الصلة كما وردت في الصفحة 104، ومعها ما يترتب على كل منها في نظام يرسل الفواتير. والإرشادان التاسع والسابع داخلان هنا لأن الأول يحكم وقت كل عملية مسجلة، والثاني يحكم ما لا يجوز أن يظهر مكشوفًا.
العمود الأخير قراءتنا التطبيقية للنص، لا جزء منه. وللإرشادات العشر كلها بالترتيب، مع شرح كل منها، راجع مقال الإرشادات العشر لنظام الفوترة الوطني.
القيم الأربع لكل فاتورة ومن أين تأتي في الرد
القيم التي يسميها الإرشاد الخامس لا تأتي كلها من المصدر نفسه. فاثنتان يولّدهما نظامك قبل الإرسال، واثنتان يعيدهما نظام الفوترة الوطني في الرد. ومعرفة مصدر كل قيمة تحدد متى تُحفظ.
مرِّر الجدول أفقيًا لعرض بقية الأعمدة
ينص الدليل في ملاحظاته التشغيلية على أن رقم الفاتورة في النظام «لا يقتصر على رقم الـ ID فقط، وإنما يتكوّن من الـ ID والـ UUID معًا كمفتاح رئيسي». وينبه إلى أن ترك المعرّف يتولد تلقائيًا دون تخزينه قد يؤدي إلى تكرار الفواتير عند إعادة الإرسال، «لذلك يجب تخزينه وإعادة استخدامه». ويترتب على ذلك أمر عملي في التتبع، وهو أن المعرّفين يجب أن يكونا محفوظين في نظامك قبل أن يخرج الطلب الأول، لا بعد أن يعود الرد. وتفصيل هذه النقطة في مقال المعرّف الفريد UUID في نظام الفوترة الوطني.
ويضيف الدليل في الملاحظات نفسها حفظ رقم البند ID لكل سلعة كما ورد في فاتورة البيع، لأن فواتير الإرجاع تُطابق عليه. أما الفاتورة الموقّعة التي يعيدها النظام في العنصر EINV_SINGED_INVOICE فلا يذكرها الإرشاد الخامس ضمن القيم الأربع، فحفظها قرار تصميمي يعود إليك. وما تحفظه وتعرضه بعد قبول الفاتورة تحديدًا مشروح في مقال حالة SUBMITTED في نظام الفوترة الوطني.
ما يسجله نظامك في كل إرسال واستجابة وإعادة إرسال
يسمي الإرشاد العاشر ثلاثة أنواع من العمليات، ولا يحدد الحقول التي يحملها كل سطر في السجل. لذلك فالجدول التالي اقتراح من قيود لتصميم سطر السجل، وكل حقل فيه مأخوذ من عنصر موثق في الدليل أو من نص إرشاد، ومصدره مذكور بجانبه.
وفي كل عنصر من عناصر EINV_RESULTS خمسة حقول بحسب الدليل، هي type وstatus وEINV_CODE وEINV_CATEGORY وEINV_MESSAGE. ومثال الدليل نفسه خطأ رمزه totalGeneralTaxesAmount وفئته invoice ورسالته Total General Amount is Not Correct. وتسجيل الحقول الخمسة كما وصلت دون اختصار هو ما يجعل السجل نافعًا عند المراجعة، لأن الرسالة وحدها قد لا تكفي لمعرفة الحقل المقصود.
أما ما لا يدخل السجل فأوله بيانات الربط. فرقم المستخدم Client ID والمفتاح السري Secret Key يُرسلان في ترويسة كل طلب، والإرشاد السابع يطلب حمايتهما، والدليل يحمّل المكلف «كامل المسؤولية عن أي استخدام غير مصرح به». فإذا قررت تسجيل الطلب كما خرج، فاقتراحنا أن تستبعد الترويستين Client-Id وSecret-Key منه قبل الكتابة. وطريقة إنشاء القيمتين مشروحة في مقال رقم المستخدم والمفتاح السري في نظام الفوترة الوطني.
أربعة مسارات لفاتورة واحدة كما تظهر في التتبع
تختلف أسطر السجل باختلاف ما يحدث للفاتورة بعد إرسالها. وهذه المسارات الأربعة مبنية على الحالات والرموز التي يوثقها الدليل، وما يُسجل في كل منها.
المسار الأول، إرسال ينتهي بالقبول
يسجل نظامك سطر الإرسال، ثم يعود الرد بالقيمة SUBMITTED في EINV_STATUS، فيُسجل سطر الاستجابة ومعه عناصر EINV_RESULTS. ولا يكتمل القبول بقراءة الحالة وحدها، فالدليل يطلب التحقق من وجود رمز QR في العنصر EINV_QR لاكتمال عملية استلام الفاتورة واعتمادها. بعد ذلك تُحدَّث القيم الأربع للفاتورة، ويُظهر الرمز على فاتورة البائع.
المسار الثاني، إرسال ينتهي بالرفض
يعود الرد بالقيمة NOT_SUBMITTED، ورمز الاستجابة الفني فيه ليس 200، وتأتي قيم رمز QR والمعرّف ورقم الفاتورة والفاتورة الموقّعة null. هنا يظهر سبب أخذ المعرّفين في السجل من نظامك لا من الرد. ويُسجل سطر الاستجابة بعناصر ERRORS كاملة، وتُعرض للمستخدم رسالة مبسطة. وبعد تصحيح البيانات تُعاد الفاتورة بالرقم والمعرّف نفسيهما كما يطلب الإرشاد الثالث، فيُسجل سطر جديد من نوع إعادة إرسال، ولا يُمحى سطر الرفض الأول. ولمعنى هذه الحالة وخطوات معالجتها راجع مقال حالة NOT_SUBMITTED في نظام الفوترة الوطني.
وقد يعود الرد برمز غير 400، ولكل رمز أسباب مختلفة في الدليل. فالدليل يربط الرمز 403 بخطأ في Client_ID أو Secret_Key، ويربط الرمز 500 بخطأ في الرقم الضريبي أو تسلسل مصدر الدخل، «وبدرجة أقل» بخطأ في Client_ID أو Secret_Key، ويذكر أيضًا احتمال ألا تكون نسبة الضريبة في ملف XML ضمن النسب المعتمدة لدى الدائرة. وتسجيل رمز الاستجابة الفني في كل سطر هو ما يجعل هذه الحالات مميزة عن أخطاء القيم التي يفصّلها الرمز 400 في EINV_MESSAGE.
المسار الثالث، انقطاع دون رد مقروء
إذا انتهت المهلة أو فشل الاتصال، كما في الرمز 504 الذي يربطه الدليل بتعذر الوصول إلى النظام بسبب جدار الحماية لدى المكلف أو موقع الفوترة الرئيسي، فلا توجد قيمة EINV_STATUS تُسجل. يكفي هنا سطر الإرسال ومعه النتيجة الفنية، ثم سطر إعادة الإرسال. وينص الإرشاد الثامن على أنه «عند حدوث Timeout أو فشل اتصال يجب إعادة المحاولة دون توليد UUID جديد». ولا يحدد الدليل عدد المحاولات ولا الفاصل بينها. وتفصيل هذا الخطأ في مقال خطأ 504 في نظام الفوترة الوطني.
المسار الرابع، إعادة إرسال تعود بالحالة ALREADY_SUBMITTED
تعني هذه الحالة بحسب الدليل أن الفاتورة بالرقم والمعرّف نفسيهما أُرسلت من قبل، ويعود معها رمز QR الأصلي. وهذا هو الطريق الموثق لاستعادة رمز لم يُحفظ. ويُسجل سطر الاستجابة هذا مثل غيره، ويُحفظ الرمز العائد في القيم الأربع إن لم يكن محفوظًا. وشرح الحالة كاملًا في مقال حالة ALREADY_SUBMITTED في نظام الفوترة الوطني.
الرسالة التفصيلية للفريق والرسالة المبسطة للمستخدم
يطلب الإرشاد السادس أمرين في وقت واحد. الأول سجل داخلي تفصيلي لكل خطأ، وهو ما يحتاجه المطوّر أو مزود الحلول التقنية لمعرفة العنصر المخالف. والثاني رسالة مبسطة للمستخدم النهائي، وهو المحاسب أو الموظف الذي أصدر الفاتورة ولا يحتاج إلى رمز EINV_CODE ليعرف ما يصححه.
رسائل الأخطاء في الرد مكتوبة بالإنجليزية، وبعضها بأخطاء إملائية كما وردت في الدليل. والجدول التالي يعرض رسائل يذكرها الدليل ضمن أخطاء الرمز 400، ومعها صياغة مبسطة نقترحها للمستخدم. الصياغة المقترحة من عندنا، والرسالة الأصلية تبقى في السجل الداخلي كما وصلت.
ولربط كل رسالة بالأخرى، نقترح أن تحمل الرسالة المبسطة إشارة قصيرة إلى سطر السجل، مثل رقم الفاتورة ووقت العملية، حتى يجد فريق الدعم الخطأ الكامل حين يرسل إليه المستخدم ما رآه. ولقراءة EINV_MESSAGE وموقعه في الرد بالتفصيل، راجع مقال خطأ 400 في نظام الفوترة الوطني.
ما لا يحدده الدليل التقني في تتبع العمليات
نص الإرشاد العاشر سطر واحد، ونص الخامس والسادس سطران. وثمة أمور يحتاجها من يبني السجل لا يجيب عنها الدليل، ومن المهم ألا يُملأ هذا الفراغ بقواعد تُنسب إلى الدائرة. هذه المسائل لا يحددها الدليل التقني في إصداره 1.5.
- شكل السجل ومكان حفظه. لا يحدد الدليل هل يكون السجل جدولًا في قاعدة بيانات أو ملفًا نصيًا أو غير ذلك.
- مدة بقاء السجل. لا يحدد الدليل مدة لبقاء سجل العمليات أو سجل الأخطاء، ولا يربطهما بمدة الاحتفاظ بالفواتير.
- من يطلع على السجل. لا ينص الدليل على صلاحيات الاطلاع، وإن كان الإرشاد السابع يفرض ألا تظهر بيانات الربط مكشوفة.
- التنسيق الزمني بعينه. يطلب الإرشاد التاسع تنسيقًا زمنيًا موحدًا ولا يسمي في نصه تنسيقًا محددًا. أما تاريخ الفاتورة في العنصر cbc:IssueDate فيُكتب بصيغة yyyy-mm-dd كما في جميع أمثلة XML في الدليل.
- عدد مرات إعادة المحاولة والفاصل بينها. يحدد الدليل أن تتم إعادة المحاولة دون معرّف جديد، ولا يحدد عددها ولا توقيتها.
- نص الرسالة المبسطة. يطلب الدليل أن تكون الرسالة مبسطة، ولا يقترح صياغتها.
كل ما سبق قرار تصميمي يعود إلى منشأتك وإلى المبرمج أو مزود الحلول التقنية الذي تتعامل معه. فدليل إجراءات الانضمام الصادر عن الدائرة يقول إنه «يتوجب على المكلف التنسيق مع مبرمج النظام أو مزود الحلول التقنية المعتمد لديه لاستكمال المتطلبات الفنية». وإذا احتجت إلى جواب رسمي عن مسألة لم يحسمها الدليل، فهو يحيلك إلى لجنة الدعم الفني لشؤون الفوترة في دائرة ضريبة الدخل والمبيعات عبر موقع الدائرة.
قائمة فحص قبل تشغيل الربط
هذه أسئلة يمكن أن يراجع بها المطوّر أو المحاسب المسؤول تصميم التتبع في نظامه قبل إرسال أول فاتورة فعلية. كل سؤال منها مبني على إرشاد مذكور أعلاه.
- هل يُحفظ رقم الفاتورة ID والمعرّف UUID في نظامك قبل أول إرسال؟
- هل تُحفظ لكل فاتورة القيم الأربع ID وUUID وQR Code وEINV_STATUS؟
- هل يُسجل كل إرسال وكل رد وكل إعادة إرسال في سطر مستقل، دون أن يُمحى ما قبله؟
- هل يحمل كل سطر وقت العملية بتنسيق زمني موحد بين أنظمتك؟
- هل يُسجل رمز الاستجابة الفني وقيمة EINV_STATUS معًا، ويُحكم على الفاتورة بالثانية؟
- هل تُسجل عناصر EINV_RESULTS بحقولها الخمسة كما وصلت؟
- هل يرى المستخدم رسالة مبسطة بدل الرسالة الفنية، مع إشارة تربطها بسطر السجل؟
- هل يخلو السجل من رقم المستخدم والمفتاح السري؟
- هل يتحقق النظام من وجود رمز QR في EINV_QR قبل اعتبار الفاتورة مقبولة، ويُظهر الرمز على فاتورة البائع؟
- هل تُعاد الفاتورة بعد الرفض أو الانقطاع بالرقم والمعرّف نفسيهما؟
ما يعرضه قيود من حالة فواتيرك
إذا كان برنامجك المحاسبي هو من يرسل الفواتير، فهو من يطبق هذه الإرشادات. ويعمل تكامل قيود مع نظام الفوترة الوطني على هذه الطبقة كما يلي.
- فحص قبل الإرسال. يفحص قيود كل فاتورة على مستوى الحقول لحظة إنشائها، وهي الرقم الضريبي، ونوع المستند وطريقة الدفع، ونسبة ضريبة المبيعات العامة، واكتمال البنود، وينبهك بأي خطأ قبل إرسالها لتقليل حالات الرفض.
- حالة كل فاتورة أمامك. تعيد الدائرة حالة الفاتورة ورسالة الخطأ، ويعرضها قيود في لوحة الحالة، ومنها «مرسلة» و«مرسلة مسبقًا» و«لم تُرسل» مع رسالة الخطأ.
- إعادة إرسال بالمعرّف نفسه. تعرض لوحة الحالة الفواتير التي لم تُرسل وتحتاج إلى إعادة إرسال، وحين تعيد إرسالها تُرسل بالمعرّف UUID نفسه. وإعادة الإرسال خطوة تقوم بها أنت من لوحة الحالة.
أما رمز QR فتعيده الدائرة بعد قبول الفاتورة، ويظهر على الفاتورة التي يصدرها قيود. ولصورة أوسع عن النظام وطريقة ربط منشأتك به، اقرأ مقال نظام الفوترة الوطني الإلكتروني، أو تعرّف على ما يقدمه قيود في نظام الفوترة الوطني.
فوترة إلكترونية ومحاسبة متكاملة في نظام واحد
ينبهك قيود بأي خطأ في حقول الفاتورة قبل إرسالها إلى نظام الفوترة الوطني، ويعرض حالة كل فاتورة في لوحة الحالة.
الأسئلة الشائعة
ما المقصود بتتبع العمليات في نظام الفوترة الوطني؟
يقصد به الإرشاد العاشر في الدليل التقني الصادر عن دائرة ضريبة الدخل والمبيعات، وعنوانه «تتبع العمليات (Audit Trail)». ونصه «تسجيل جميع العمليات (إرسال، استجابة، إعادة إرسال) لضمان التتبع والتدقيق»، وهو موجّه إلى النظام الذي يرسل الفواتير عبر الواجهة البرمجية.
ما القيم التي يجب أن يحفظها نظامي لكل فاتورة؟
يطلب الإرشاد الخامس حفظ أربع قيم هي رقم الفاتورة ID والمعرّف الفريد UUID ورمز QR وحالة الفاتورة EINV_STATUS، «لضمان التتبع وإعادة الاسترجاع عند الحاجة». وتضيف الملاحظات التشغيلية في الدليل حفظ رقم البند لكل سلعة لاستعماله في فواتير الإرجاع.
هل يحدد الدليل مدة لبقاء سجل العمليات؟
لا يحدد الدليل التقني أي مدة لبقاء سجل العمليات أو سجل الأخطاء. ومدة الاحتفاظ بالفواتير نفسها مسألة أخرى تنظمها المادة (8) من نظام تنظيم شؤون الفوترة والرقابة عليها، ولا يربط الدليل بينهما.
لماذا لا أعرض للمستخدم رسالة الخطأ كما وصلت من النظام؟
يطلب الإرشاد السادس تسجيل الأخطاء تفصيليًا داخل النظام مع عرض رسالة مبسطة للمستخدم النهائي. فالرسالة الأصلية تبقى في السجل للفريق التقني، ويرى من أصدر الفاتورة جملة تقول له ما الذي يصححه.
هل أسجل رقم المستخدم والمفتاح السري في سجل العمليات؟
نقترح ألا تفعل ذلك. فالإرشاد السابع يطلب حماية بيانات الربط وعدم تخزينها مكشوفة داخل الكود البرمجي، والدليل يحمّل المكلف كامل المسؤولية عن أي استخدام غير مصرح به، فإذا سجلت الطلب فاستبعد منه الترويستين اللتين تحملان القيمتين.
ماذا أسجل إذا انقطع الاتصال قبل وصول الرد؟
تسجل سطر الإرسال ومعه النتيجة الفنية، إذ لا توجد قيمة EINV_STATUS في هذه الحالة، ثم تسجل سطر إعادة الإرسال. وينص الإرشاد الثامن على إعادة المحاولة دون توليد UUID جديد، ولا يحدد الدليل عدد المحاولات ولا الفاصل بينها.
المراجع
- دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026، ص96 وص97 إلى ص102 وص104.
- دائرة ضريبة الدخل والمبيعات، دليل إجراءات الانضمام إلى نظام الفوترة الوطني الإلكتروني، إصدار 2026.
- نظام تنظيم شؤون الفوترة والرقابة عليها رقم (34) لسنة 2019 وتعديلاته، المادتان (6) و(8).
