مثال XML لفاتورة مبيعات نقدية في نظام الفوترة الوطني مشروحًا

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

المثال فاتورة جديدة محلية نقدية لمكلف مسجل في ضريبة المبيعات العامة، رمزها في الملف 388 مع الخاصية name="012"، وفيها بندان، الأول خاضع بالفئة S ونسبة 7.00، والثاني معفى بالفئة Z. وما تقرؤه هنا خريطة شارحة للمثال، لا ملف جاهز للنسخ. ولم نختبر إرسال هذا المثال ولا أي جزء منه إلى النظام، لأن الدليل لا يذكر بيئة تجريبية مفتوحة للمكلفين أو المطورين، كما يوضح مقال اختبار إرسال الفواتير إلى نظام الفوترة الوطني دون بيئة رسمية.

ما الذي يمثله مثال XML لفاتورة مبيعات نقدية في نظام الفوترة الوطني

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

يحدد نوع الفاتورة عنصر واحد في الترويسة يحمل معلومتين. فقيمة العنصر cbc:InvoiceTypeCode تبيّن إن كانت الفاتورة جديدة (388) أو فاتورة إرجاع (381)، والخاصية name رمز من ثلاث خانات. الخانة الأولى نوع التعامل، والصفر فيها للفاتورة المحلية. والثانية طريقة الدفع، فالرقم 1 للنقدي والرقم 2 للذمم. والثالثة عائلة الضريبة، والرقم 2 فيها لضريبة المبيعات العامة. فالرمز 012 يعني فاتورة محلية نقدية من عائلة المبيعات العامة، ولا يصلح تعميمه على غيرها، لأن الرمز يتغير مع نوع التعامل وعائلة الضريبة معًا.

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

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

خريطة الكتل في المثال

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

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

ما يسبق الكتل في ملف الفاتورة

يبدأ كل ملف بسطر التعريف، ثم عنصر الجذر Invoice بفضاءات الأسماء الأربعة، ثم العنصر cbc:ProfileID بالقيمة reporting:1.0 في كل فاتورة (ص10). ويشترط الدليل أن يكون وسم Invoice الافتتاحي في سطر واحد، وإلا رُفض الملف برسالة Invalid Invoice Minification (ص102). وهذه الأسطر وصف ثابت ينقله نظامك كما هو، وقد شرحها المقال المذكور في القسم السابق بالتفصيل.

الترويسة (A) في فاتورة المبيعات النقدية

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

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

<cbc:ID><!-- رقم الفاتورة في نظامك --></cbc:ID>
<cbc:UUID><!-- معرّف فريد يولّده نظامك ويحفظه --></cbc:UUID>
<cbc:IssueDate><!-- التاريخ بصيغة yyyy-mm-dd --></cbc:IssueDate>
<cbc:InvoiceTypeCode name="012">388</cbc:InvoiceTypeCode>
<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>

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

كتلة البائع (B)

تعرّف كتلة cac:AccountingSupplierParty بالمكلف الذي يصدر الفاتورة، وتحمل أربع قيم، هي رمز الدولة JO، والرقم الضريبي للبائع في cbc:CompanyID، والقيمة VAT في معرّف مخطط الضريبة، واسم البائع في cbc:RegistrationName كما هو مسجل لدى دائرة ضريبة الدخل والمبيعات.

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

كتلة المشتري (C) في الفاتورة النقدية

كتلة cac:AccountingCustomerParty أكثر كتل المثال تأثرًا بطريقة الدفع. ويعرض الدليل قالبها ومثالها في الصفحتين 36 و37، وعناصرها كما يلي.

• نوع معرّف المشتري في الخاصية schemeID، وهو إجباري، وقيمه NIN للرقم الوطني وPN للرقم الشخصي لغير الأردني وTN للرقم الضريبي. أما رقم المعرّف نفسه فمظلل بالأخضر، ويُكتب بالأرقام فقط.
• الرمز البريدي في cbc:PostalZone، وهو اختياري وحده الأعلى 5 خانات.
• رمز المحافظة في cbc:CountrySubentityCode، وهو اختياري، مثل JO-AM لعمّان وJO-IR لإربد.
• رقم الهاتف في cbc:Telephone، وهو اختياري، ويقبل الأرقام فقط بين 9 أرقام و14 رقمًا.
• اسم المشتري في cbc:RegistrationName.

واسم المشتري هو موضع الفرق بين الفاتورة النقدية وفاتورة الذمم. ففي فاتورة الذمم يجب الاسم دائمًا، أما في الفاتورة النقدية فيجب إذا زادت قيمتها على «10 آلاف دينار أو ما يعادلها بالعملات الأجنبية» (ص101). وحين يغيب في هذه الحالة تكون الرسالة Bayer name is missing بالتهجئة التي كتبها الدليل. ويبقى الرقم الضريبي للمشتري إجباريًا في فواتير المناطق التنموية، وهي خارج هذا المثال. والتفاصيل في مقال بيانات المشتري في ملف فاتورة نظام الفوترة الوطني.

تسلسل مصدر الدخل (D)

الكتلة cac:SellerSupplierParty في الصفحة 38 قصيرة، فيها عنصر واحد هو cbc:ID، وقيمته تسلسل مصدر الدخل الذي يختاره المكلف عند إنشاء الربط من خيار «ربط الأجهزة». وكل رقم مستخدم ومفتاح سري مرتبطان بتسلسل واحد.

ولهذه القيمة أثر أكبر من حجمها في الملف، فالدليل يكتب في أسباب الخطأ 500 «خطأ في الرقم الضريبي أو تسلسل مصدر الدخل وبدرجة أقل يكون الخطأ في ال Client_ID أو ال Secret_Key» (ص101). وطريقة الوصول إلى التسلسل في مقال تسلسل مصدر الدخل في نظام الفوترة الوطني.

المجاميع (E) وما تضيفه ضريبة المبيعات العامة

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

<cac:AllowanceCharge>
  <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
  <cbc:AllowanceChargeReason><!-- سبب الخصم كما في المثال --></cbc:AllowanceChargeReason>
  <cbc:Amount currencyID="JO"><!-- مجموع خصومات البنود --></cbc:Amount>
</cac:AllowanceCharge>
<cac:TaxTotal>
  <cbc:TaxAmount currencyID="JO"><!-- مجموع ضريبة البنود --></cbc:TaxAmount>
</cac:TaxTotal>
<cac:LegalMonetaryTotal>
  <cbc:TaxExclusiveAmount currencyID="JO"><!-- مجموع الكمية مضروبة في سعر الوحدة --></cbc:TaxExclusiveAmount>
  <cbc:TaxInclusiveAmount currencyID="JO"><!-- مجموع RoundingAmount للبنود --></cbc:TaxInclusiveAmount>
  <cbc:AllowanceTotalAmount currencyID="JO"><!-- مجموع خصومات البنود --></cbc:AllowanceTotalAmount>
  <cbc:PayableAmount currencyID="JO"><!-- مجموع RoundingAmount للبنود --></cbc:PayableAmount>
</cac:LegalMonetaryTotal>

• خصم الرأس. الكتلة cac:AllowanceCharge في الرأس ليست خصمًا مستقلًا على الفاتورة، بل مجموع خصومات البنود، وقيمة cbc:ChargeIndicator فيها false. والنظام لا يقبل خصمًا حرًا على مستوى الفاتورة، فإن كان نظامك يخصم من الإجمالي فعليه أن يوزع الخصم على البنود قبل الإرسال، كما يشرح مقال خصم الفاتورة في نظام الفوترة الوطني.
• مجموع الضريبة. العنصر cbc:TaxAmount داخل cac:TaxTotal في الرأس هو «مجموع قيمة الضريبة العامة»، أي مجموع ضريبة البنود.
• المجاميع النقدية. في cac:LegalMonetaryTotal أربعة عناصر. TaxExclusiveAmount مجموع حاصل ضرب الكمية في سعر الوحدة، وTaxInclusiveAmount مجموع قيم RoundingAmount للبنود، وAllowanceTotalAmount مجموع خصومات البنود، وPayableAmount مجموع قيم RoundingAmount أيضًا. ويجب أن يساوي خصم الرأس وAllowanceTotalAmount كلاهما مجموع خصومات البنود.

وقيم المثال في الصفحة 40 هي 116.000 لإجمالي الفاتورة قبل الخصم والضريبة، و2.000 للخصم، و4.480 لمجموع الضريبة، و118.480 للمبلغ المستحق. ويتتبع مقال فاتورة فيها بند خاضع وبند معفى في نظام الفوترة الوطني هذه الأرقام من البندين خطوة خطوة، فلا نعيد الحساب هنا. ومن رسائل الخطأ المرتبطة بحساب المجاميع Total General Amount is Not Correct، وأسبابها في مقال رسالة Total General Amount is Not Correct.

ويتكرر تحت المبالغ في الدليل تنبيه التقريب «يمكن التقريب لغاية (3) خانات عشرية و بحد أعلى (9) خانات عشرية بحيث أن الفرق يكون أقل من أو يساوي (0.001)». وتستخدم أمثلة الدليل القيمة JO في الخاصية currencyID على كل مبلغ، ولا يذكر الدليل إن كانت قيم أخرى مقبولة فيها.

البنود (F) والفئة الضريبية لكل بند

تبدأ البنود في الصفحة 41، ولكل بند كتلة cac:InvoiceLine برقم تسلسلي فريد داخل الفاتورة، وكمية، وسعر وحدة قبل الضريبة، وخصم، وقيمة البند بعد الخصم في cbc:LineExtensionAmount. وما يميز بند فاتورة المبيعات العامة كتلة cac:TaxTotal داخل البند، وفيها ضريبة البند في cbc:TaxAmount، وقيمة البند مع ضريبته في cbc:RoundingAmount، ثم cac:TaxSubtotal بالفئة والنسبة ومخطط الضريبة.

الصورة أعلاه البند الأول في المثال، وهو بند خاضع بالفئة S ونسبة 7.00. أما البند الثاني فمعفى، فئته Z ونسبته 0.00. وتعريف الفئات في جدول الصفحة 42 أن S للخاضع بأي نسبة غير الصفر، وZ للسلعة أو الخدمة المعفاة، وO للسلعة أو الخدمة الخاضعة لنسبة الصفر. وعند نسبة 0% لا يُستخدم التصنيف S؛ يُستخدم Z للمعفى وO للخاضع لنسبة الصفر. وتفصيل الفئات في مقال فئات الضريبة S وZ وO في نظام الفوترة الوطني.

وفي بنود هذا المثال ثلاث ملاحظات تخصه.

• النسبة 7.00 قيمة من قائمة النسب التي تقبلها الواجهة، وهذه القائمة قائمة تحقق لا جدول لنسب الضريبة، فلا يُستدل بالمثال على نسبة سلعة بعينها.
• العنصر cbc:TaxableAmount داخل cac:TaxSubtotal يظهر في قوالب الإرجاع وقوالب الضريبة الخاصة، ولا يظهر في قالب فاتورة المبيعات العامة الجديدة.
• وحدة الكمية في المثال PCE، ولا يذكر الدليل قائمة بوحدات أخرى ولا قاعدة لها.

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

ما يختلف فيه هذا المثال عن أمثلة الدليل الأخرى

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

قائمة فحص قبل بناء فاتورة مبيعات نقدية على هذا المثال

الغرض من المثال فهم البنية، أما القيم فتأتي من بيانات فاتورتك. وقبل أن يرسل نظامك أول فاتورة مبنية على مثال XML لفاتورة مبيعات نقدية في نظام الفوترة الوطني، تحقق من النقاط التالية.

1. سطر التعريف وعنصر الجذر منقولان كما في الصفحة 10، ووسم Invoice الافتتاحي في سطر واحد.
2. الرمز 012 مع القيمة 388 يتناسب مع تسجيلك في ضريبة المبيعات العامة، ومع كون التعامل محليًا والدفع نقدًا.
3. المعرّف الفريد يولّده نظامك بصيغة قياسية ويحفظه، فبعض أمثلة الدليل تورد معرّفات لا تطابق الصيغة القياسية (ص14 وص98).
4. التاريخ بصيغة yyyy-mm-dd.
5. اسم المشتري حاضر إذا زادت قيمة الفاتورة النقدية على 10 آلاف دينار أو ما يعادلها بالعملات الأجنبية.
6. تسلسل مصدر الدخل في الكتلة D هو التسلسل المرتبط برقم المستخدم والمفتاح السري اللذين يرسل بهما نظامك.
7. خصم الرأس ومجموع الخصم كلاهما يساوي مجموع خصومات البنود، ومجموع الضريبة في الرأس يساوي مجموع ضريبة البنود.
8. كل بند بنسبة 0% فئته Z أو O بحسب طبيعته، لا S.
9. أرقام البنود فريدة داخل الفاتورة، ومحفوظة لديك لأن فاتورة الإرجاع تطابق البنود بها.

وبعد الإرسال تحكم على الفاتورة من قيمة EINV_STATUS في الرد، لا من رمز حالة HTTP وحده. وللمواضع التي لا تُنسخ من أمثلة الدليل حرفيًا مقال مستقل هو أمثلة الدليل التقني لنظام الفوترة الوطني.

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

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

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

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

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

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

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

ما معنى الرمز 012 في فاتورة نظام الفوترة الوطني؟

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

متى يجب اسم المشتري في فاتورة المبيعات النقدية؟

يجب اسم المشتري في الفاتورة النقدية إذا زادت قيمتها على 10 آلاف دينار أو ما يعادلها بالعملات الأجنبية. أما في فاتورة الذمم فيجب الاسم في كل الأحوال.

لماذا تحمل فاتورة المبيعات العامة كتلة TaxTotal في رأسها؟

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

هل يعرض الدليل التقني مثالًا كاملًا لفاتورة مبيعات عامة بالذمم؟

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

بأي عملة تُكتب فاتورة المبيعات النقدية في المثال؟

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

المراجع

• دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026، ص10 وص12 وص13 وص14 وص32 إلى ص44 وص98 وص101 وص102.