تصغير ملف XML في نظام الفوترة الوطني: ما يشترطه الدليل التقني وما لا يذكره

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

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

ما معنى تصغير ملف XML في نظام الفوترة الوطني

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

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

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

نص الدليل التقني عن الوسم الأول في ملف الفاتورة

يشرح الدليل الرسالة في سطرين (ص102). وهذا نصه كما ورد.

«يدل بأن أول Tag موجود في ال XML مكتوب بشكل خاطئ أو مكتوب بأكثر من سطر ويجب أن يكون على سطر واحد بينهما مسافات.»

يحمل هذا النص ثلاثة أحكام يحسن أن تقرأها منفصلة.

1. موضع الشرط هو الوسم الأول في الملف. والمقصود به وسم البداية للعنصر الجذري <Invoice …>، وهو أول وسم يلي سطر التعريف، والوسم الذي يحمل مساحات الأسماء.
2. للخطأ سببان لا سبب واحد. وهما أن يكون الوسم «مكتوبًا بشكل خاطئ»، أو أن يكون «مكتوبًا بأكثر من سطر». ولا يفصّل الدليل ما يعدّه كتابة خاطئة، لكنه يطلب في الصفحة 10 أن تأتي بداية الملف كما يعرضها، فأقرب ما يُفهم به السبب الأول أن تخرج البداية عن ذلك النص. وهذه قراءة منا لا عبارة من الدليل.
3. الصيغة المطلوبة سطر واحد تفصل المسافاتُ بين أجزائه. فعبارة «بينهما مسافات» تعني في قراءتنا أن اسم العنصر ومساحات الأسماء تتتابع في السطر نفسه، تفصل بينها مسافات لا فواصل أسطر. ولا يحدد الدليل عدد هذه المسافات.

هذا كل ما في الدليل عن التصغير. فالنص لا يتجاوز الوسم الأول إلى غيره من عناصر الملف، ولا يذكر حجمًا للملف، ولا يطلب حذف المسافات من أي موضع آخر.

كيف يظهر الوسم الجذري في مثال الصفحة 10

يعرض الدليل في الصفحة 10 بداية ملف الفاتورة ويطلبها كما هي. وهي في الصفحة المطبوعة سطر التعريف، ثم وسم Invoice موزعًا على أربعة أسطر، ثم عنصر ProfileID.

• سطر التعريف <?xml version="1.0" encoding="UTF-8"?> في سطر مستقل.
• وسم البداية للعنصر Invoice بعد سطر التعريف، وقد طبعه الدليل موزعًا على أربعة أسطر، في كل سطر مساحة أسماء.
• العنصر cbc:ProfileID بالقيمة reporting:1.0 في سطر مستقل بعد الوسم.

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

وشرح مساحات الأسماء الأربع وقيمة ProfileID ودور كل منها خارج موضوع هذا المقال، وتجده في مقال معيار UBL 2.1 في نظام الفوترة الوطني. ويكفي هنا أن الدليل يطلب هذه البداية كما هي، وأن الشرط الشكلي الذي يوثقه عليها هو بقاء وسم Invoice في سطر واحد.

ما لا يذكره الدليل عن تصغير ملف XML

كلمة «تصغير» تفتح أسئلة كثيرة يطرحها المبرمج حين يبني ملف الفاتورة. والدليل التقني (الإصدار 1.5) لا يجيب عن أي منها بنص. والجدول الآتي يجمعها، ويفرّق في كل صف بين ما ورد في الدليل وما نقترحه نحن عمليًا.

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

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

لماذا لا تضغط الملف كله في سطر واحد احتياطًا

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

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

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

خطوات آمنة قبل ترميز Base64

يلخص الدليل الخطوة الأولى من إرسال الفاتورة في جملة واحدة (ص96). فبعد تجهيز الفاتورة بصيغة XML يُرمَّز الملف بنظام Base64 ويُدرج في ملف JSON مع رقم المستخدم والمفتاح السري. وتستعمل الجملة في الصورة لفظًا آخر لهذه الخطوة، والمقصود بها الترميز، وهو لا يجعل الملف سريًا.

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

1. ابنِ البداية من نص الصفحة 10 كما هو. ضع سطر التعريف، ثم وسم Invoice بمساحات أسمائه الأربع في سطر واحد، ثم ProfileID. والدليل يطلب هذه البداية كما هي.
2. افحص الوسم في الملف الناتج لا في الشيفرة التي تولّده. افتح الملف الذي سيُرسل فعلًا في محرر يعرض أرقام الأسطر. فإن كان الملف يبدأ بسطر التعريف كما في المثال، وجب أن يقع وسم Invoice كله، من <Invoice حتى علامة الإغلاق >، في سطر واحد، وهو في المثال السطر الذي يلي سطر التعريف.
3. انتبه لأدوات التنسيق التلقائي. بعض المحررات والمكتبات تعيد تنسيق ملفات XML لتسهيل قراءتها، وقد تقسم السطر الطويل إلى أسطر. فإن مر الملف بأداة كهذه، أعد فحص وسم Invoice بعدها.
4. افحص القيم قبل الإرسال. يطلب الإرشاد الثاني من إرشادات الدائرة التحقق من المجاميع والضرائب ورقم المكلف ورقم المشتري والحقول الإلزامية قبل الإرسال لتقليل أخطاء 400. وشرح هذا الإرشاد وأخواته في مقال الإرشادات العشر لنظام الفوترة الوطني.
5. ثبّت الملف، ثم رمّز النسخة التي فحصتها نفسها. ما تُرمّزه هو ما يصل إلى النظام. فإن عدّلت الملف بعد فحصه، أعد الفحص ثم الترميز من الملف المعدّل.
6. ضع الناتج في جسم الطلب. يوضع النص المرمّز قيمةً للمفتاح invoice في جسم الطلب بصيغة JSON، وتذهب القيمتان الأخريان في ترويسته، كما يشرح مقال ترميز Base64 في نظام الفوترة الوطني.

إن عادت الفاتورة مرفوضة بسبب الوسم الأول

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

1. اقرأ رسالة الخطأ كما وردت في الرد، في الحقل EINV_MESSAGE.
2. افتح الملف الذي أُرسل فعلًا، وتأكد أن وسم Invoice في سطر واحد، وأن بداية الملف تطابق نص الصفحة 10.
3. صحّح الملف، ثم أعد ترميزه بترميز Base64 من الملف المصحح.
4. أعد الإرسال برقم الفاتورة نفسه ومعرّفها الفريد نفسه، كما يطلب الإرشاد الثالث في الدليل. فالمفتاح الأساسي للفاتورة في النظام هو الرقم والمعرّف الفريد معًا، وسبب ذلك مشروح في مقال المعرّف الفريد UUID في نظام الفوترة الوطني.
5. احكم على النتيجة من قيمة EINV_STATUS في الرد، لا من رمز الحالة وحده.

والتفصيل الكامل لهذه الرسالة، من نصها إلى طريقة التحقق من إصلاحها، في مقالها المستقل في مركز الأخطاء.

تصغير ملف XML في نظام الفوترة الوطني حين تصدر فواتيرك من قيود

إن كنت تستخدم تكامل قيود مع نظام الفوترة الوطني، فلا تكتب ملف XML بنفسك ولا تجهّز جسم الطلب. يبني قيود ملف الفاتورة بصيغة UBL 2.1 مع معرّفها الفريد، ويرسله إلى نظام الفوترة الوطني دون تدخل يدوي، ولا يلزمك توقيع أو شهادة رقمية خاصة بك.

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

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

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

ما معنى تصغير ملف XML في نظام الفوترة الوطني؟

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

هل يجب أن يكون ملف الفاتورة كله في سطر واحد؟

لا يطلب الدليل التقني ذلك. فالشرط الذي يذكره يخص الوسم الأول وحده، ومثال الصفحة 10 نفسه يضع سطر التعريف وعنصر ProfileID كلًا في سطر مستقل.

هل يرفض النظام المسافات البادئة أو فواصل الأسطر بين العناصر الأخرى؟

لا يذكر الدليل التقني (الإصدار 1.5) حكمًا لها، لا بالقبول ولا بالرفض. والآمن أن تلتزم بالبداية كما يعرضها الدليل، وأن تختبر ما زاد على ذلك في برنامجك قبل أن تعتمد عليه.

متى أفحص وسم Invoice، قبل الترميز أم بعده؟

افحصه في ملف XML قبل ترميزه بترميز Base64، ثم رمّز النسخة التي فحصتها نفسها. فالترميز لا يغيّر شكل الملف، وما كان موزعًا على سطرين قبله يبقى كذلك بعده.

ماذا أفعل إذا رُفضت الفاتورة بسبب الوسم الأول؟

صحّح ملف XML بحيث يقع وسم Invoice في سطر واحد، ثم أعد ترميزه، ثم أعد الإرسال برقم الفاتورة ومعرّفها الفريد نفسيهما، واحكم على النتيجة من قيمة EINV_STATUS.

هل أحتاج إلى ضبط هذا الشرط إذا كنت أصدر فواتيري من قيود؟

يبني قيود ملف الفاتورة بصيغة UBL 2.1 ويرسله إلى نظام الفوترة الوطني دون تدخل يدوي، فلا تكتب الملف بنفسك. وإن رُفضت فاتورة، يعرض قيود رسالة الخطأ في لوحة الحالة لتعيد إرسالها بعد التصحيح.

المراجع

• دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026.