أخطاء XML في الفاتورة الإلكترونية

تظهر «أخطاء XML في الفاتورة الإلكترونية» عندما يرفض نظام هيئة الزكاة والضريبة والجمارك (ZATCA) ملف الفاتورة قبل أن يصل إلى مرحلة قواعد العمل. هذه أخطاء بنيوية في تركيب الملف نفسه: وسم ناقص، ترتيب خاطئ لعناصر UBL، فضاء أسماء غير صحيح، أو ملف لا يطابق مخطط XSD. القارئ هنا مطوّر أو مسؤول تقني يبني التكامل مع منصة فاتورة، ويحتاج إلى رسالة الخطأ التي سيراها والحل الدقيق لكل حالة.

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

الفرق بين الخطأ البنيوي وخطأ قواعد العمل

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

الخطأ البنيوي يعني أن المحلّل (parser) لا يستطيع قراءة الملف أو أن الملف لا يطابق مخطط XSD المعتمد. أمثلته: وسم لم يُغلق، عنصر في غير موضعه ضمن تسلسل UBL، بادئة فضاء أسماء غير معرّفة، أو ترميز أحرف غير مدعوم. النظام يردّ هنا بأخطاء من نوع تحليل XML أو فشل التحقق من المخطط.

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

القاعدة العملية: إذا رأيت رسالة فيها كلمة schema أو parse أو namespace، فأنت في الطبقة البنيوية. إذا رأيت رمزًا يبدأ بـ BR أو رسالة عن عدم تطابق مبالغ، فأنت في طبقة قواعد العمل. هذا المقال يغطي الأولى. للثانية، راجع الدليل المخصص لأخطاء التحقق على مستوى القواعد.

لماذا يهمّ هذا الترتيب للمطوّر

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

1. أخطاء تركيب XML غير الصالح (Malformed XML)

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

رسالة الخطأ النمطية التي ستراها من المحلّل تشبه: Premature end of file أو The element type "cbc:ID" must be terminated by the matching end-tag. هذه الرسالة تشير دائمًا إلى موضع محدد في الملف، فاقرأ رقم السطر والعمود الذي يذكره.

في المثال التالي، وسم cbc:ID لم يُغلق، وهو سبب مباشر لرسالة عدم اكتمال الوسم:

<!-- خطأ: الوسم cbc:ID لم يُغلق -->
<cac:AccountingSupplierParty>
  <cac:Party>
    <cbc:ID>300012345600003
    <cbc:Name>مؤسسة المثال</cbc:Name>
  </cac:Party>
</cac:AccountingSupplierParty>

الإصلاح إغلاق الوسم بشكل صريح. كل عنصر يُفتح يجب أن يُغلق بوسم مطابق تمامًا في الاسم والبادئة:

<!-- صحيح -->
<cac:AccountingSupplierParty>
  <cac:Party>
    <cbc:ID>300012345600003</cbc:ID>
    <cbc:Name>مؤسسة المثال</cbc:Name>
  </cac:Party>
</cac:AccountingSupplierParty>

الرموز المحجوزة داخل القيم النصية

سبب خفي لتكسّر الملف هو إدراج رمز محجوز داخل قيمة نصية دون تهريب. الرموز & و< و> لها معنى خاص في XML. اسم شركة فيه «و» إنجليزية بالرمز & يكسر الملف فورًا.

<!-- خطأ: الرمز & غير مهرَّب -->
<cbc:RegistrationName>Ahmad & Sons Co.</cbc:RegistrationName>

<!-- صحيح: استخدم الكيان &amp; -->
<cbc:RegistrationName>Ahmad &amp; Sons Co.</cbc:RegistrationName>

القاعدة: بدّل & بـ &، و< بـ <، و> بـ > داخل أي محتوى نصي. لو كانت القيمة تحوي رموزًا كثيرة، استخدم قسم CDATA بدلًا من التهريب اليدوي. لاحظ أن منصة فاتورة لا تقبل CDATA في كل الحقول، فاحصره في الحقول النصية الحرة.

تعدّد عنصر الجذر

ملف XML صالح له عنصر جذر واحد فقط. بعض المولّدات تكتب وسم <Invoice> مرتين بالخطأ عند تجميع دفعة، فينتج ملف بجذرين. رسالة الخطأ تكون من نوع The markup in the document following the root element must be well-formed. الحل توليد ملف واحد لكل فاتورة، أو لف الدفعة في غلاف واحد إن كانت الواجهة تدعم الإرسال المجمّع.

2. عناصر UBL ناقصة أو في ترتيب خاطئ

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

الخطأ الشائع: وضع cbc:IssueDate بعد cbc:InvoiceTypeCode بينما يفرض المخطط العكس. رسالة الخطأ النمطية: Invalid content was found starting with element 'cbc:IssueDate'. One of '{...}' is expected. هذه الرسالة تخبرك بالضبط أي عنصر كان النظام يتوقعه في ذلك الموضع.

<!-- خطأ: IssueDate جاء قبل ID، والترتيب المعياري يبدأ بـ ID -->
<Invoice>
  <cbc:ProfileID>reporting:1.0</cbc:ProfileID>
  <cbc:IssueDate>2026-06-24</cbc:IssueDate>
  <cbc:ID>INV-001</cbc:ID>
</Invoice>

الإصلاح إعادة العناصر إلى الترتيب الذي يفرضه المخطط. في UBL يأتي cbc:ProfileID ثم cbc:ID ثم cbc:UUID ثم cbc:IssueDate:

<!-- صحيح: الترتيب يطابق تسلسل المخطط -->
<Invoice>
  <cbc:ProfileID>reporting:1.0</cbc:ProfileID>
  <cbc:ID>INV-001</cbc:ID>
  <cbc:UUID>3cf5ee18-ee25-4ea1-bf7b-9b2c4d4f...</cbc:UUID>
  <cbc:IssueDate>2026-06-24</cbc:IssueDate>
</Invoice>

العناصر الإلزامية المفقودة

بعض العناصر إلزامية في كل فاتورة. غيابها يسبب رسالة من نوع cvc-complex-type.2.4.b: The content of element 'Invoice' is not complete. One of '{...}' is expected. أكثر العناصر التي تُنسى:

• cbc:ProfileID الذي يحدد نوع المعالجة (إبلاغ أو فسح).
• cbc:UUID المعرّف الفريد للفاتورة.
• cac:AdditionalDocumentReference الذي يحمل رمز الاستجابة السريعة والتجزئة (hash).
• cbc:InvoiceTypeCode مع سمة name التي تصف نوع الفاتورة.

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

3. أخطاء فضاءات الأسماء (Namespaces: cac / cbc / ext)

فضاءات الأسماء (namespaces) هي أكثر مصدر للأخطاء يربك المطوّرين الجدد على UBL. كل بادئة في الفاتورة تنتمي إلى فضاء أسماء معيّن يجب الإعلان عنه بدقة في عنصر الجذر. أي اختلاف في الرابط، أو بادئة غير معرّفة، يفشل الملف.

البادئات الثلاث الأساسية في فاتورة UBL السعودية:

• cbc للمكوّنات الأساسية المشتركة (CommonBasicComponents): القيم البسيطة مثل المعرّف والتاريخ والمبلغ.
• cac للمكوّنات المجمّعة المشتركة (CommonAggregateComponents): الكتل المركّبة مثل بيانات المورّد وبنود الفاتورة.
• ext للامتدادات (CommonExtensionComponents): يحمل التوقيع الرقمي ضمن UBLExtensions.

الخطأ الأكثر شيوعًا هو استخدام بادئة دون الإعلان عنها في الجذر. رسالة الخطأ: The prefix "cbc" for element "cbc:ID" is not bound. المعنى أن المحلّل وجد بادئة بلا تعريف.

<!-- خطأ: لم يُعلَن عن cbc و cac في الجذر -->
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:ID>INV-001</cbc:ID>
  <cac:AccountingSupplierParty>...</cac:AccountingSupplierParty>
</Invoice>

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

<!-- صحيح: كل البادئات معلَنة في الجذر -->
<Invoice
  xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
  xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
  xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
  xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2">
  <cbc:ID>INV-001</cbc:ID>
</Invoice>

خطأ الفضاء الافتراضي الخاطئ

خطأ آخر دقيق: تعريف فضاء الأسماء الافتراضي برابط غير صحيح. لو كتبت xmlns برابط Invoice-1 بدل Invoice-2، سيقرأ المحلّل العناصر بفضاء خاطئ، فيفشل التحقق من المخطط دون رسالة واضحة عن السبب. تحقق من رقم الإصدار في كل رابط: العناصر الأساسية تنتهي بـ -2 في UBL 2.1.

الفرق بين عدم الإعلان والإعلان الخاطئ

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

4. فشل التحقق من المخطط (XSD Validation)

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

الأخطاء النمطية في هذه الطبقة:

• نوع بيانات خاطئ: وضع نص في حقل رقمي. رسالة: cvc-datatype-valid.1.2.1: '...' is not a valid value for 'decimal'.
• قيمة خارج القائمة المغلقة: رمز نوع فاتورة غير معتمد. رسالة: cvc-enumeration-valid: Value '...' is not facet-valid with respect to enumeration.
• عنصر زائد غير معرّف في المخطط: إضافة وسم لا يعرفه المعيار. رسالة: cvc-complex-type.2.4.a: Invalid content was found.

المثال التالي يضع قيمة نصية في حقل المبلغ، وهو حقل من نوع decimal:

<!-- خطأ: قيمة نصية في حقل رقمي -->
<cbc:PayableAmount currencyID="SAR">مئة وخمسون</cbc:PayableAmount>

<!-- صحيح: رقم عشري بفاصلة عشرية نقطية -->
<cbc:PayableAmount currencyID="SAR">150.00</cbc:PayableAmount>

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

قيم القوائم المغلقة (Enumerations)

عدة حقول في الفاتورة تقبل قيمًا من قائمة مغلقة فقط. أبرزها رمز نوع الفاتورة InvoiceTypeCode ورمز فئة الضريبة. وضع قيمة خارج القائمة يردّ خطأ enumeration. تحقق من القائمة المعتمدة في وثائق منصة فاتورة، ولا تخترع رموزًا.

مثال على رمز فئة ضريبة صحيح: S للخاضع للنسبة القياسية، Z للخاضع لنسبة صفرية، E للمعفى. أي حرف آخر يفشل التحقق.

أداة التحقق المحلي قبل الإرسال

لا ترسل الملف إلى منصة فاتورة لاكتشاف خطأ المخطط. تحقق محليًا أولًا. شغّل ملفك مقابل ملفات XSD الرسمية باستخدام محلّل يدعم التحقق، مثل xmllint:

xmllint --schema UBL-Invoice-2.1.xsd invoice.xml --noout

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

5. أخطاء الترميز (Encoding) ومشكلات الأحرف العربية

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

القاعدة الحاسمة: استخدم UTF-8 دائمًا، وأعلِن عنه صراحة في أول سطر. أي ترميز آخر مثل Windows-1256 يسبب رسالة Invalid byte 1 of 1-byte UTF-8 sequence عند وجود حرف عربي.

<!-- خطأ: إعلان ترميز خاطئ مع محتوى عربي -->
<?xml version="1.0" encoding="Windows-1256"?>

<!-- صحيح: UTF-8 معلَن صراحة -->
<?xml version="1.0" encoding="UTF-8"?>

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

علامة ترتيب البايتات (BOM)

مشكلة دقيقة أخرى هي علامة ترتيب البايتات (Byte Order Mark) التي يضيفها بعض المحرّرين في بداية ملف UTF-8. هذه العلامة بايتات غير مرئية قبل وسم XML الافتتاحي، وقد ترفضها بعض المحلّلات برسالة Content is not allowed in prolog. الحل حفظ الملف بترميز UTF-8 دون BOM.

الأحرف العربية في الحقول الإلزامية

تأكد أن الاسم التجاري العربي للمورّد والمشتري يُكتب نصًا عربيًا سليمًا داخل الحقل النصي، لا منقولًا حرفيًا بحروف لاتينية. منصة فاتورة تقبل النص العربي ما دام الترميز UTF-8 صحيحًا. التشوّه الذي تراه في النص المستخرَج هو عَرَض للترميز الخاطئ، لا خطأ في النص الأصلي.

6. أخطاء كتلة الامتداد والتوقيع (ext / UBLExtensions)

تحمل الفاتورة في المرحلة الثانية توقيعًا رقميًا داخل كتلة الامتداد ext:UBLExtensions. هذه الكتلة من أكثر مواضع الأخطاء البنيوية تعقيدًا، لأنها تجمع بين ترتيب صارم وبنية متداخلة عميقة. خطأ واحد في موضعها أو محتواها يفشل الملف بالكامل.

القاعدة الأولى: كتلة ext:UBLExtensions يجب أن تأتي في أول الفاتورة قبل أي عنصر cbc أو cac. وضعها بعد cbc:ID مثلًا يردّ خطأ ترتيب من المخطط. الموضع الصحيح مباشرةً بعد وسم الجذر:

<!-- صحيح: كتلة الامتداد أول عنصر داخل الفاتورة -->
<Invoice xmlns="..." xmlns:cac="..." xmlns:cbc="..." xmlns:ext="...">
  <ext:UBLExtensions>
    <ext:UBLExtension>
      <ext:ExtensionContent>
        <!-- التوقيع الرقمي هنا -->
      </ext:ExtensionContent>
    </ext:UBLExtension>
  </ext:UBLExtensions>
  <cbc:ProfileID>reporting:1.0</cbc:ProfileID>
  <cbc:ID>INV-001</cbc:ID>
</Invoice>

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

عدم تطابق التجزئة بسبب التطبيع (Canonicalization)

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

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

7. أخطاء قالب التوليد المتكررة

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

أكثر أخطاء القوالب شيوعًا:

• سمة ثابتة بقيمة خاطئة: قالب يكتب currencyID بقيمة مكتوبة يدويًا خاطئة في كل ملف. أصلح القالب مرة واحدة لا كل فاتورة.
• تنسيق تاريخ خاطئ: المخطط يفرض صيغة YYYY-MM-DD للتاريخ. قالب يكتب التاريخ بصيغة محلية مثل 24/06/2026 يفشل كل الملفات.
• فاصلة عشرية خاطئة: استخدام الفاصلة بدل النقطة في المبالغ. المخطط يقبل النقطة فقط: 150.00 لا 150,00.
• مسافات بادئة داخل القيم: قالب يضيف مسافات أو أسطرًا جديدة داخل قيمة نصية حساسة، فتفشل عند التحقق أو تكسر التجزئة.

المثال التالي يوضح خطأ تنسيق التاريخ، وهو من أكثر أخطاء القوالب انتشارًا في بيئتنا المحلية:

<!-- خطأ: صيغة تاريخ محلية لا يقبلها المخطط -->
<cbc:IssueDate>24/06/2026</cbc:IssueDate>

<!-- صحيح: صيغة ISO التي يفرضها UBL -->
<cbc:IssueDate>2026-06-24</cbc:IssueDate>

وقت الإصدار له حقل منفصل cbc:IssueTime بصيغة HH:MM:SS. لا تدمج التاريخ والوقت في حقل واحد، فلكل منهما عنصره ونوعه.

اختبار القالب على دفعة قبل الإطلاق

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

سيناريو عملي: تتبّع رسالة رفض من البداية للنهاية

لنطبّق المنهجية على حالة واقعية. وصلتك رسالة رفض من منصة فاتورة نصّها: cvc-complex-type.2.4.a: Invalid content was found starting with element 'cbc:TaxAmount'. كيف تشخّصها؟

أولًا، صنّف الطبقة. البادئة cvc- تعني أنك في طبقة التحقق من المخطط، لا التركيب ولا الفضاءات. الملف يُقرأ بنجاح لكنه يخالف بنية المخطط.

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

ثالثًا، قارن بملف صالح. في الملف الناجح، يأتي cbc:TaxAmount داخل cac:TaxTotal بترتيب محدد. في ملفك، اكتشفت أنه وُضع قبل عنصر إلزامي يسبقه. الإصلاح إعادة ترتيب العناصر داخل الكتلة.

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

هذا السيناريو يلخّص فلسفة المقال كاملةً: الرسالة تخبرك بالطبقة، الطبقة تحدد القسم، والمقارنة بملف صالح تكشف الفرق. لا تخمين، بل مسار.

كيف يساعدك قيود في تجنّب أخطاء XML

قيود برنامج محاسبة سحابي يولّد ملف الفاتورة الإلكترونية بالكامل نيابة عنك، فلا تكتب XML يدويًا ولا تتعامل مع فضاءات الأسماء أو ترتيب عناصر UBL. هذا يلغي فئة الأخطاء البنيوية كاملةً من جذرها. وإليك ما يقدّمه قيود تحديدًا في هذا الجانب:

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

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

منهجية تشخيص منظّمة لأي خطأ XML

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

1. اقرأ نص الرسالة كاملًا: رسالة الخطأ تذكر غالبًا اسم العنصر ورقم السطر. لا تتجاهلها وتبدأ بالتخمين.
2. صنّف الطبقة: هل الكلمة المفتاحية parse، أم namespace، أم cvc، أم BR؟ هذا يحدد القسم الذي تعمل فيه.
3. تحقق محليًا بـ xmllint: شغّل الملف مقابل XSD الرسمي قبل أي إرسال. تلتقط معظم الأخطاء دون شبكة.
4. قارن بملف صالح معروف: احتفظ بفاتورة نجحت سابقًا كمرجع، وقارن البنية لا القيم.
5. افحص الترميز أخيرًا: إن كانت الرسالة عن بايتات أو prolog، فالمشكلة في الترميز أو BOM لا في المحتوى.

هذا الترتيب يعكس خط المعالجة نفسه: من التركيب إلى الفضاءات إلى المخطط إلى الترميز. اتباعه يحوّل التشخيص من بحث عشوائي إلى مسار محدد.

قائمة فحص سريعة قبل أي إرسال

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

• الإعلان عن الترميز UTF-8 في أول سطر، والملف محفوظ فعليًا بهذا الترميز دون علامة BOM.
• كل البادئات cbc وcac وext معلَنة في عنصر الجذر بالروابط الرسمية الدقيقة.
• كل وسم مفتوح له وسم إغلاق مطابق، وكل رمز محجوز مهرَّب داخل القيم النصية.
• العناصر مرتّبة وفق تسلسل المخطط، وكل العناصر الإلزامية موجودة.
• حقول المبالغ تحمل سمة currencyID، والأرقام بفاصلة عشرية نقطية، والتواريخ بصيغة ISO.
• الملف اجتاز xmllint مقابل XSD الرسمي محليًا قبل الإرسال.
• التوقيع وُلّد كآخر خطوة، ولم يُعدَّل الملف بعده.

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

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

ما الفرق بين خطأ XML وخطأ التحقق في الفاتورة الإلكترونية؟

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

ماذا تعني رسالة prefix is not bound؟

تعني أنك استخدمت بادئة فضاء أسماء مثل cbc أو cac دون الإعلان عنها في عنصر الجذر. الحل إضافة إعلان xmlns:cbc وxmlns:cac وxmlns:ext في وسم الجذر بالروابط الرسمية الدقيقة.

لماذا تظهر الأحرف العربية مشوّهة في الفاتورة؟

السبب دائمًا تقريبًا ترميز خاطئ. تأكد أن الملف محفوظ بترميز UTF-8 فعليًا، وأن الإعلان في أول سطر هو encoding="UTF-8"، وأنه لا توجد علامة ترتيب بايتات BOM في بداية الملف.

هل يجب أن أتحقق من الملف محليًا قبل إرساله إلى الهيئة؟

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

ما ترتيب البادئات cac و cbc و ext الصحيح في UBL؟

cbc للقيم البسيطة مثل المعرّف والتاريخ والمبلغ، وcac للكتل المركّبة مثل بيانات المورّد والبنود، وext للامتدادات التي تحمل التوقيع الرقمي. الترتيب داخل كل تسلسل يفرضه المخطط، والعنصر في غير موضعه يفشل التحقق حتى لو كانت قيمته صحيحة. راجع فاتورة XML والتنسيق التقني لمعرفة بنية الملف كاملة.

هل أحتاج إلى كتابة XML يدويًا للالتزام بالفاتورة الإلكترونية؟

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