مثال XML لفاتورة بضريبة خاصة في نظام الفوترة الوطني

مثال XML لفاتورة بضريبة خاصة في نظام الفوترة الوطني هو المثال الذي يورده الدليل التقني الصادر عن دائرة ضريبة الدخل والمبيعات، الإصدار 1.5، في قسم «فاتورة المبيعات الخاصة» من الصفحة 57 إلى الصفحة 71. ويعرض المثال ملف الفاتورة كاملًا في ست كتل، من رأس الفاتورة حتى البنود. وأوضح ما يميزه عن مثال فاتورة ضريبة المبيعات العامة موضعان، هما رمز نوع الفاتورة، وكتلتا الضريبة في كل بند.

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

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

مثال XML لفاتورة بضريبة خاصة في نظام الفوترة الوطني كتلةً كتلة

يقسم الدليل المثال إلى ست كتل يرمز لها بالحروف من A إلى F، بالترتيب نفسه الذي يتبعه في مثالي فاتورة الدخل وفاتورة ضريبة المبيعات العامة. ويلخص الجدول موضع كل كتلة في الدليل وما تحمله في فاتورة الضريبة الخاصة.

وقبل الكتل الست يأتي سطر التعريف بالملف، ثم وسم الجذر <Invoice …> بنطاقاته، ثم عنصر cbc:ProfileID بالقيمة reporting:1.0. وهذه الأسطر مشتركة بين أنواع الفواتير كلها، ويجب أن يُكتب وسم الجذر في سطر واحد، وتفصيلها في مقال معيار UBL 2.1 في نظام الفوترة الوطني.

هيكل الملف في مقطع واحد مشروح

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

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="…" xmlns:cac="…" xmlns:cbc="…" xmlns:ext="…">  <!-- وسم الجذر في سطر واحد -->
<cbc:ProfileID>reporting:1.0</cbc:ProfileID>

<!-- A: معلومات الفاتورة الأساسية -->
<cbc:ID>…</cbc:ID>                          <!-- رقم الفاتورة -->
<cbc:UUID>…</cbc:UUID>                      <!-- معرّف يولّده نظامك ويحفظه -->
<cbc:IssueDate>…</cbc:IssueDate>            <!-- تاريخ بصيغة yyyy-mm-dd -->
<cbc:InvoiceTypeCode name="013">388</cbc:InvoiceTypeCode>  <!-- الخانة الثالثة 3 = ضريبة خاصة -->
<cbc:Note>…</cbc:Note>                      <!-- اختياري -->
<cbc:DocumentCurrencyCode>JOD</cbc:DocumentCurrencyCode>
<cbc:TaxCurrencyCode>JOD</cbc:TaxCurrencyCode>
<cac:AdditionalDocumentReference><cbc:ID>ICV</cbc:ID><cbc:UUID>…</cbc:UUID></cac:AdditionalDocumentReference>  <!-- عداد الفاتورة -->

<!-- B: البائع -->
<cac:AccountingSupplierParty>…</cac:AccountingSupplierParty>
<!-- C: المشتري -->
<cac:AccountingCustomerParty>…</cac:AccountingCustomerParty>
<!-- D: تسلسل مصدر الدخل -->
<cac:SellerSupplierParty>…</cac:SellerSupplierParty>

<!-- E: مجاميع الفاتورة -->
<cac:AllowanceCharge>…</cac:AllowanceCharge>       <!-- مجموع خصومات البنود -->
<cac:TaxTotal>…</cac:TaxTotal>                     <!-- مجموع الضريبة العامة وحدها -->
<cac:LegalMonetaryTotal>…</cac:LegalMonetaryTotal>

<!-- F: البنود، كتلة لكل بند -->
<cac:InvoiceLine>
  <cbc:ID>…</cbc:ID>                        <!-- رقم البند، لا يتكرر في الفاتورة -->
  <cbc:InvoicedQuantity unitCode="PCE">…</cbc:InvoicedQuantity>
  <cbc:LineExtensionAmount …>…</cbc:LineExtensionAmount>
  <cac:TaxTotal>
    <cbc:TaxAmount …>…</cbc:TaxAmount>              <!-- الضريبة العامة وحدها -->
    <cbc:RoundingAmount …>…</cbc:RoundingAmount>    <!-- البند + الخاصة + العامة -->
    <cac:TaxSubtotal>…</cac:TaxSubtotal>            <!-- الأولى: OTH بلا Percent -->
    <cac:TaxSubtotal>…</cac:TaxSubtotal>            <!-- الثانية: VAT مع Percent -->
  </cac:TaxTotal>
  <cac:Item><cbc:Name>…</cbc:Name></cac:Item>
  <cac:Price>…</cac:Price>                  <!-- سعر الوحدة قبل الضريبة وخصم البند -->
</cac:InvoiceLine>
</Invoice>

وأهم ما يلفت في المقطع موضعان. الأول رمز النوع في رأس الملف، والثاني كتلتا cac:TaxSubtotal داخل كل بند.

رأس الفاتورة ورمز النوع 013

أول ما يميز ملف الضريبة الخاصة رمز النوع. فقيمة العنصر cbc:InvoiceTypeCode هي 388 لأن الفاتورة جديدة، والسمة name تحمل رقمًا من ثلاث خانات. الخانة الأولى لنوع التعامل، والثانية لطريقة الدفع، والثالثة لعائلة الضريبة. وقيمة الخانة الثالثة في فواتير الضريبة الخاصة 3، مقابل 1 لفاتورة الدخل و2 لفاتورة ضريبة المبيعات العامة.

يستخدم مثال الدليل الرمز 013، أي فاتورة محلية نقدية. ويضيف الدليل في الصفحة 59 أمثلة من سطر واحد لأنواع أخرى، هي 323 لترانزيت ذمم، و513 لتنازل داخل المناطق الحرة نقدي، و423 لتجارة خارجية ذمم. ولا يتضمن الدليل مثالًا كاملًا لفاتورة ذمم أو لأي نوع غير محلي.

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

وتحمل عناصر الرأس الأخرى البيانات الآتية.

• رقم الفاتورة والمعرّف الفريد. يشكّل cbc:ID وcbc:UUID معًا مفتاحًا رئيسيًا للفاتورة. ويولّد نظامك المعرّف ويحفظه ليعيد استخدامه عند إعادة الإرسال، وتفصيله في مقال المعرّف الفريد UUID في نظام الفوترة الوطني.
• تاريخ الفاتورة. يُكتب بصيغة yyyy-mm-dd كما في جميع أمثلة XML في الدليل، وتفصيله في مقال صيغة تاريخ الفاتورة في نظام الفوترة الوطني.
• الملاحظة. عنصر cbc:Note اختياري، أي مظلل بالأخضر في قالب الدليل.
• العملة. القيمة الافتراضية JOD في عنصري العملة، وينص الدليل على أن «تغيير نوع العملة يكون على مستوى كامل الفاتورة فقط».
• عداد الفاتورة. يحمل cac:AdditionalDocumentReference المعرّف ICV وقيمة العداد، وهو بحسب الدليل «عداد يتم إنشاؤه من قبل المكلف للفواتير الإلكترونية يبدأ بشكل تسلسلي من 1 الى ما لانهاية». وتفصيله في مقال عداد الفاتورة ICV في نظام الفوترة الوطني.

البائع والمشتري وتسلسل مصدر الدخل

تحمل الكتلة B بيانات البائع، وهي رمز الدولة JO، والرقم الضريبي في cbc:CompanyID، ومخطط الضريبة VAT، واسم البائع كما سُجل لدى الدائرة. وتفصيل الحقول في مقال بيانات البائع في فاتورة نظام الفوترة الوطني.

وتحمل الكتلة C بيانات المشتري. فنوع رقم التعريف في السمة schemeID هو NIN للرقم الوطني، أو PN للرقم الشخصي لغير الأردني، أو TN للرقم الضريبي. ولا يتجاوز الرمز البريدي 5 خانات، ويُكتب رمز المحافظة من قائمة الدليل. ويصبح اسم المشتري إجباريًا إذا كانت الفاتورة ذممًا، أو كانت نقدية وقيمتها «أكثر من 10 آلاف دينار أو ما يعادلها بالعملات الأجنبية». وتفصيل الكتلة في مقال بيانات المشتري في ملف فاتورة نظام الفوترة الوطني.

أما الكتلة D فعنصر واحد، هو cbc:ID داخل cac:SellerSupplierParty، وقيمته تسلسل مصدر الدخل للبائع. ويذكر الدليل في الصفحة 101 من أسباب خطأ HTTP 500 «خطأ في الرقم الضريبي أو تسلسل مصدر الدخل»، وبدرجة أقل الخطأ في Client_ID أو Secret_Key، ويضيف أنه يمكن أن تكون نسبة الضريبة في الملف «ليست ضمن نسب الضريبة المعتمدة لدى الدائرة». وتفصيل هذا العنصر في مقال تسلسل مصدر الدخل في نظام الفوترة الوطني.

وينبغي أن يتفق رمز النوع مع تسجيل المكلف لدى الدائرة. فمن يرسل نوع فاتورة لا يتناسب مع رقمه الضريبي أو تسلسل مصدر الدخل الخاص به، يتلقى بحسب الدليل رسالة This user is not authorized to submit this type of invoice.

مجاميع الفاتورة في الكتلة E

تجمع الكتلة E ثلاثة عناصر على مستوى الفاتورة، هي الخصم، والضريبة، والإجماليات. ويحدد الدليل محتوى كل منها بمعادلة، كما في الجدول.

والنقطة التي تخص الضريبة الخاصة في هذه الكتلة أن cac:TaxTotal على مستوى الفاتورة يحمل مجموع الضريبة العامة في البنود وحدها، ولا تدخل فيه الضريبة الخاصة. لكن الضريبة الخاصة تدخل في إجمالي الفاتورة، لأن الدليل يكتبه بصيغة «اجمالي الفاتورة = (اجمالي الفاتورة قبل الخصم − مجموع قيمة الخصم + مجموع الضريبة الخاصة + مجموع قيمة الضريبة العامة)»، وهو يساوي مجموع cbc:RoundingAmount في البنود.

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

وتحت كل مبلغ يكرر الدليل ملاحظة التقريب نفسها، وهي «يمكن التقريب لغاية (3) خانات عشرية و بحد أعلى (9) خانات عشرية بحيث أن الفرق يكون أقل من أو يساوي (0.001)». وإن رُفضت فاتورة لأن مجاميعها لا تتطابق، فارجع إلى مقال رسالة Total General Amount is Not Correct.

كتلة OTH قبل كتلة الضريبة العامة في كل بند

الكتلة F هي البنود، وتتكرر فيها cac:InvoiceLine لكل سلعة أو خدمة. وترتيب عناصر البند في القالب هو رقم البند، ثم الكمية، ثم cbc:LineExtensionAmount، ثم كتلة الضريبة، ثم اسم السلعة، ثم السعر وخصم البند. والقواعد العامة للبند في مقال بنود الفاتورة InvoiceLine في نظام الفوترة الوطني.

والفرق كله داخل كتلة الضريبة cac:TaxTotal. ففيها كتلتان فرعيتان من نوع cac:TaxSubtotal بدل كتلة واحدة، والأولى منهما للضريبة الخاصة.

• الكتلة الأولى للضريبة الخاصة. يُكتب فيها مبلغ الضريبة الخاصة للبند في cbc:TaxAmount، والفئة S، ومخطط الضريبة OTH، ولا يوجد فيها عنصر cbc:Percent.
• الكتلة الثانية للضريبة العامة. يُكتب فيها مبلغ ضريبة المبيعات العامة، والفئة، ونسبة الضريبة العامة في cbc:Percent، ومخطط الضريبة VAT.

ويحسم الدليل طبيعة الضريبة الخاصة في جملة يكررها في الصفحتين 68 و81، وهي «الضريبة الخاصة هي قيمة يتم إدخالها دون عمليات حسابية». فالملف لا يحمل نسبة للضريبة الخاصة، بل مبلغًا يحسبه نظام البائع ويكتبه كما هو.

ثم تُحسب الضريبة العامة على قيمة البند مضافًا إليها الضريبة الخاصة. ويكتب الدليل المعادلة بالصيغة الآتية.

taxAmount = ((LineExtensionAmount + Special Tax) * taxPercent)

ويترتب على ذلك أمران في رأس كتلة الضريبة داخل البند. فعنصر cbc:TaxAmount يحمل الضريبة العامة وحدها، وعنصر cbc:RoundingAmount يحمل المبلغ الإجمالي للبند شاملًا الضريبتين، أي LineExtensionAmount + SpecialTax + GeneralTax. وشرح الكتلتين عنصرًا عنصرًا مع أرقام مثال الدليل في مقال الضريبة الخاصة في ملف فاتورة نظام الفوترة الوطني.

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

ما يختلف عن مثال فاتورة ضريبة المبيعات العامة

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

ومثال فاتورة ضريبة المبيعات العامة نفسه مشروح في مقال مستقل من سلسلة مركز المطورين، وكذلك مثال إرجاع فاتورة بضريبة خاصة.

ما لا تنقله من مثال الدليل

أمثلة الدليل توضيحية، وليست ملفات مجرّبة جاهزة للإرسال. وفي مثال الضريبة الخاصة مواضع محددة تمنع نسخه كما هو.

• علامات اقتباس مكررة. يلاحظ في الصفحة 68 أن سمة العملة في قيمة الضريبة الخاصة مكتوبة currencyID="JO""، وفي أمثلة الصفحة 69 تتكرر علامات الاقتباس حول schemeAgencyID وschemeID. وملف XML بهذه الصورة لا يكون سليم البنية. وجمعنا هذه المواضع وغيرها في مقال أمثلة الدليل التقني لنظام الفوترة الوطني.
• قيمة سمة العملة. تستخدم أمثلة الدليل القيمة JO في currencyID على كل مبلغ، ولا يذكر الدليل هل تُقبل قيمة أخرى. فلا تبنِ على افتراض غير مذكور.
• المعرّف الفريد. لا تأخذ معرّف المثال، بل ولّد معرّفًا لكل فاتورة في نظامك واحفظه.
• بيانات البائع والسلعة. استبدل أسماء المثال وأرقامه ببيانات منشأتك وسلعك المسجلة لدى الدائرة.
• نسبة الضريبة العامة في المثال. النسبة 10 في المثال للتوضيح، وليست حكمًا على سلعة بعينها.

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

كيف يتعامل قيود مع ملف الفاتورة

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

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

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

خطوات بناء ملف الفاتورة من هذا المثال

إن كنت تبني الملف في برنامجك، فهذا ترتيب عملي يتبع كتل الدليل، ويضع الفحوص الخاصة بالضريبة الخاصة في مواضعها.

1. اكتب سطر التعريف ووسم الجذر. ضع الوسم بنطاقاته في سطر واحد، ثم cbc:ProfileID بالقيمة reporting:1.0.
2. املأ الرأس. رقم الفاتورة، ومعرّف فريد جديد تحفظه، والتاريخ بصيغة yyyy-mm-dd، ورمز النوع بخانة ثالثة قيمتها 3 مع القيمة 388، والعملة، وعداد الفاتورة.
3. أضف البائع والمشتري وتسلسل مصدر الدخل. تأكد أن تسلسل مصدر الدخل هو المرتبط ببيانات الربط التي تستخدمها، وأن اسم المشتري موجود حين يشترطه الدليل.
4. ابنِ كل بند. احسب قيمة البند بعد الخصم، ثم اكتب مبلغ الضريبة الخاصة في كتلة OTH بلا نسبة، ثم احسب الضريبة العامة على قيمة البند مضافًا إليها الضريبة الخاصة.
5. راجع رأس كتلة الضريبة في البند. الضريبة العامة وحدها في cbc:TaxAmount، والضريبتان مع قيمة البند في cbc:RoundingAmount.
6. اجمع الكتلة E من البنود. الخصم من خصومات البنود، والضريبة العامة من البنود، والإجمالي من مجموع cbc:RoundingAmount.
7. رمّز الملف وأرسله. حوّل الملف إلى Base64، وضعه في جسم JSON، وأرسله مع رأسي بيانات الربط، كما يشرح مقال بناء طلب إرسال الفاتورة إلى نظام الفوترة الوطني. ثم احكم على النتيجة من EINV_STATUS لا من رمز حالة HTTP وحده.

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

هل مثال XML لفاتورة بضريبة خاصة في الدليل التقني جاهز للإرسال؟

لا يصلح المثال للإرسال كما هو. فهو توضيحي، وفيه علامات اقتباس مكررة في الصفحتين 68 و69 تجعل الملف غير سليم البنية إذا نُسخ حرفيًا. ابنِ الملف ببيانات منشأتك واتبع بنية الكتل الست.

أين تأتي كتلة الضريبة الخاصة داخل البند؟

تأتي كتلة الضريبة الخاصة بمخطط OTH أولًا داخل cac:TaxTotal في البند، ثم تليها كتلة الضريبة العامة بمخطط VAT. وكلتاهما من نوع cac:TaxSubtotal.

هل تحمل كتلة OTH نسبة للضريبة الخاصة؟

لا تحمل كتلة OTH أي عنصر نسبة. فالدليل ينص على أن «الضريبة الخاصة هي قيمة يتم إدخالها دون عمليات حسابية»، فيُكتب مبلغها في cbc:TaxAmount كما هو.

ما الذي يحمله TaxTotal في رأس فاتورة الضريبة الخاصة؟

يحمل مجموع الضريبة العامة في البنود وحدها، ولا تدخل فيه الضريبة الخاصة. أما إجمالي الفاتورة فيشمل الضريبتين، ويساوي مجموع cbc:RoundingAmount في البنود.

ما رمز نوع الفاتورة في مثال الدليل؟

يستخدم المثال الرمز 013 في السمة name مع القيمة 388، أي فاتورة محلية نقدية جديدة. وتدل الخانة الثالثة 3 على عائلة الضريبة الخاصة.

هل توجد بيئة اختبار رسمية لتجربة هذا الملف؟

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

المراجع

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