معيار UBL 2.1 في نظام الفوترة الوطني هو الهيكل الذي يجب أن يُبنى عليه ملف الفاتورة الإلكترونية بصيغة XML قبل إرساله إلى دائرة ضريبة الدخل والمبيعات. فقد نصّ الدليل التقني للربط مع النظام، في إصداره 1.5، على اعتماد معيار UBL 2.1 Invoice هيكلًا للفاتورة الإلكترونية، وجعل الالتزام به أول إرشاداته العشرة، وقرر أن أي خلل في بنية الملف يؤدي إلى رفض الفاتورة.
يشرح هذا المقال ما يعنيه المعيار عمليًا لمن يربط نظامه المحاسبي بـنظام الفوترة الوطني. ستعرف كيف تبدأ كل فاتورة، وما قيمة ProfileID الثابتة، وكيف تقرأ قوالب الدليل، وما الكتل التي يتكون منها الملف، وما الذي يُفحص بعد البنية. أما التفاصيل الدقيقة لكل كتلة فلها مقالات مستقلة في هذه السلسلة.
المقال موجّه للمبرمج الذي يبني ملف الفاتورة، وللمحاسب الذي يتابع ردود النظام ويريد أن يفهم سبب رفض فاتورة. أما من يصدر فواتيره من بوابة النظام مباشرة فيعبّئ نموذج الفاتورة على الشاشة، وخطوات ذلك في مقال إصدار فاتورة من نظام الفوترة الوطني.
ما هو معيار UBL 2.1 في نظام الفوترة الوطني
معيار UBL 2.1 مواصفة لكتابة الفاتورة ملفًا بصيغة XML، أي نصًا مقسّمًا إلى عناصر لكل منها اسم محدد وموضع محدد داخل غيره. وقد اختارت دائرة ضريبة الدخل والمبيعات هذا المعيار هيكلًا لفواتير نظام الفوترة الوطني، ونص الدليل التقني على ذلك في الصفحة 10.
«تم اعتماد معيار (UBL 2.1 Invoice) كهيكل للفاتورة الإلكترونية، والعناصر أدناه تمثل بداية ملف XML والمراجع اللازمة لمعالجة هذا الملف بحسب معيار (UBL 2.1)».
معنى ذلك أن الفاتورة التي يرسلها النظام المحاسبي عبر الواجهة البرمجية ملفٌ تتبع عناصره أسماء المعيار وبنيته، وأن الدائرة تفحص هذا الملف قبل أن تقبل الفاتورة. فالمعيار ليس شكلًا لعرض الفاتورة على المشتري، بل لغة مشتركة بين نظام البائع ونظام الفوترة الوطني.
وأسماء العناصر في قوالب الدليل تبدأ ببادئات، أبرزها اثنتان. فالعناصر التي تحمل قيمة واحدة، مثل رقم الفاتورة cbc:ID وتاريخها cbc:IssueDate، تبدأ بالبادئة cbc. والكتل التي تضم عناصر أخرى، مثل كتلة البائع cac:AccountingSupplierParty وسطر البند cac:InvoiceLine، تبدأ بالبادئة cac. وكل بادئة منهما مرتبطة بمساحة أسماء يعلنها الملف في أوله، كما يأتي في القسم التالي.
بداية الملف: سطر التعريف وعنصر Invoice وقيمة ProfileID
يحدد الدليل التقني الأسطر التي يبدأ بها كل ملف فاتورة، ويعرضها بالترتيب الآتي.
<?xml version="1.0" encoding="UTF-8"?>
<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:ProfileID>reporting:1.0</cbc:ProfileID>
ولكل سطر من هذه الأسطر دور واضح.
- سطر التعريف. يعلن أن الملف بصيغة XML في إصدارها 1.0، وأن ترميز حروفه
UTF-8. - عنصر الجذر Invoice. يحتضن الفاتورة كلها، ويعلن في وسمه الافتتاحي أربع مساحات أسماء، هي مساحة الفاتورة الأساسية
Invoice-2، ثمcacوcbcوext. - عنصر ProfileID. قيمته
reporting:1.0في كل فاتورة، فلا تتغير بين فاتورة دخل وفاتورة مبيعات، ولا بين فاتورة جديدة وفاتورة إرجاع.
هذه الأسطر وصف ثابت يُنسخ كما هو دون تعديل. والشرط الشكلي الوحيد الذي يوثقه الدليل فيها أن يبقى وسم Invoice الافتتاحي في سطر واحد، وإلا عاد الرد برسالة Invalid Invoice Minification. وقد عرضنا الوسم في المربع أعلاه على أكثر من سطر لضيق الشاشة فقط، أما في الملف فيُكتب سطرًا واحدًا.
ما يشترطه الدليل التقني: الالتزام بمعيار البيانات
أورد الدليل التقني في صفحاته الأخيرة عشرة إرشادات تشغيلية، أولها بعنوان «الالتزام بمعيار البيانات»، ونصه كما يلي.
«يجب أن يكون ملف الفاتورة بصيغة XML مطابق لمعيار UBL 2.1، وأي خلل في البنية يؤدي إلى رفض الفاتورة».
النص عام، فهو لا يحدد نوع الخلل ولا حجمه، ولا يستثني خللًا صغيرًا من الرفض. لذلك تعامل مع البنية على أنها شرط لا يقبل التجاوز، وابنِ الملف من القالب الصحيح لنوع فاتورتك، ولا تكتفِ بأن يبدو قريبًا منه.
كيف يظهر فحص المعيار في رد النظام
يعيد نظام الفوترة الوطني بعد كل إرسال ردًا فيه عنصر EINV_RESULTS، ويضم ثلاث قوائم هي INFO وWARNINGS وERRORS. وفي مثال الرد الناجح الذي يعرضه الدليل، تحمل قائمة INFO نتيجة فحص المعيار نفسه كما يلي.
"INFO": [{
"type": "INFO",
"status": "PASS",
"EINV_CODE": "XSD_VALID",
"EINV_CATEGORY": "XSD validation",
"EINV_MESSAGE": "Complied with UBL 2.1 standards"
}]فرمز النتيجة XSD_VALID وتصنيفها XSD validation، ونص رسالتها يقول إن الملف مطابق لمعايير UBL 2.1. أي أن مطابقة المعيار نتيجة يذكرها النظام صراحة في رده، لا افتراض تستنتجه من القبول.
أما حين تُرفض الفاتورة فتكون قيمة EINV_STATUS هي NOT_SUBMITTED، ويعود رمز QR والمعرّف الفريد ورقم الفاتورة بقيمة null، ولا يكون رمز الحالة 200. ويظهر سبب الرفض في رسالة EINV_MESSAGE داخل قائمة الأخطاء. وطريقة قراءة هذه الرسائل مشروحة في مقال خطأ 400 في نظام الفوترة الوطني.
والقاعدة التي يكررها الدليل في إرشاده الرابع أن تحكم على الفاتورة من قيمة EINV_STATUS، لا من رمز حالة الاتصال وحده.
العناصر المظللة والوصف الثابت في قوالب الدليل
يعرض الدليل لكل نوع من الفواتير قالب XML ملوّنًا. فالمظلل بالأصفر متغير إجباري يملؤه نظام البائع، والمظلل بالأخضر متغير اختياري، وغير المظلل وصف ثابت. وقراءة هذا التظليل عنصرًا عنصرًا موضوع مقال الحقول الإجبارية والاختيارية في نظام الفوترة الوطني.
ومن زاوية المعيار، القاعدة العملية أنك تملأ المتغيرات وحدها، وتنسخ الوصف الثابت كما هو. فقيم حرفية مثل reporting:1.0 وICV وVAT جزء من القالب الذي ينص الدليل على نسخه دون تغيير.
وما لا يظهر في القالب من عناصر المعيار لا يوثقه الدليل. فالمعيار العام أوسع من القالب الأردني، لكن الدليل يكتفي بالعناصر التي يعرضها، فلا تبنِ ملفك على عنصر لم يرد فيه.
وانتبه إلى أن أمثلة XML في الدليل توضيحية. فبعضها يحمل معرّفات فريدة بصيغة غير صحيحة، وبعضها في قوالب الضريبة الخاصة يحمل علامات تنصيص مكررة تجعل الملف غير سليم البنية إن نُسخ كما هو. استعمل الأمثلة لفهم الترتيب، وابنِ القيم من بيانات فاتورتك.
قوالب الفاتورة حسب نوع المكلف
لا يقدم الدليل قالبًا واحدًا لكل الفواتير، بل يقسمها بحسب تسجيل المكلف الضريبي، ويعطي لكل قسم قالبين، أحدهما لإنشاء الفاتورة والآخر لإرجاعها.
ويقرأ النظام نوع الفاتورة من عنصر cbc:InvoiceTypeCode. فقيمته 388 للفاتورة الجديدة و381 لفاتورة الإرجاع، وهي في حكم الإشعار الدائن. أما السمة name فرمز من ثلاث خانات، تدل الأولى على نوع التعامل، كالمحلي والتصدير، والثانية على طريقة الدفع، نقدًا أو ذممًا، والثالثة على نوع الضريبة كما في الجدول. وفئات الضريبة في فاتورة المبيعات مشروحة في مقال فئات الضريبة S وZ وO في نظام الفوترة الوطني.
والملف يعلن النوع، لكنه لا يقرره وحده. فما يجوز أن يحمله هذا الرمز يحدده تسجيل المكلف لدى الدائرة وتسلسل مصدر الدخل وواقع العملية. فإن أرسل مكلف نوعًا لا يتناسب مع تسجيله عاد الرد برسالة This user is not authorized to submit this type of invoice.
وفاتورة الإرجاع تعيد استخدام رمز name الخاص بالفاتورة الأصلية وعملتها، وتشير إليها برقمها ومعرّفها الفريد وإجمالي قيمتها، وتحمل سببًا للإرجاع لا يُترك فارغًا.
كتل ملف الفاتورة كما يعرضها الدليل التقني
بعد الأسطر الأولى يتكون ملف الفاتورة من كتل رئيسية، يلخص الجدول التالي ستًا منها وأبرز عناصر كل منها، دون أن يستوفي قواعدها التفصيلية.
مرِّر الجدول أفقيًا لعرض بقية الأعمدة
والمفتاح الذي يميّز الفاتورة في النظام هو رقم الفاتورة cbc:ID والمعرّف الفريد cbc:UUID معًا، لا رقم الفاتورة وحده. ويُكتب التاريخ بالصيغة yyyy-mm-dd كما في جميع أمثلة XML في الدليل، مع أن النص الوصفي في بعض صفحاته يذكر صيغًا أخرى.
ولكل كتلة من هذه الكتل مقال مستقل في سلسلة التوثيق التقني، منها مقال بيانات البائع في فاتورة نظام الفوترة الوطني، ومقال بيانات المشتري في ملف فاتورة نظام الفوترة الوطني، ومقال بنود الفاتورة InvoiceLine في نظام الفوترة الوطني، ومقال المعرّف الفريد UUID في نظام الفوترة الوطني.
كيف ينتقل ملف الفاتورة إلى النظام
لا يُرسل ملف XML كما هو، بل يُرمَّز بترميز Base64 ويوضع نصه في ملف JSON تحت المفتاح invoice، ويرافقه رقم المستخدم والمفتاح السري في ترويسة الطلب لا داخل الملف، وطريقة إنشائهما في مقال رقم المستخدم والمفتاح السري. ثم يعيد النظام نتيجة الإرسال، فإما قبول يعود معه رمز QR، وإما إشعار بأن الفاتورة أُرسلت سابقًا بالرقم والمعرّف نفسيهما، وإما قائمة أخطاء، وتفاصيل هذه الرحلة في مقال ترميز Base64 في نظام الفوترة الوطني ضمن هذه السلسلة.
ما يُفحص بعد بنية الملف
مطابقة الملف لمعيار UBL 2.1 شرط لقبول الفاتورة، لكنها لا تكفي وحدها. فالإرشاد الثاني في الدليل يطلب التحقق قبل الإرسال من المجاميع والضرائب والرقم الضريبي للمكلف ورقم المشتري والحقول الإجبارية. ويوثق الدليل رسائل رفض تتعلق بالقيم لا بالبنية، منها ما يلي.
- المجاميع. إذا لم يساوِ إجمالي الفاتورة مجموع بنودها عاد الرد بـرسالة Total General Amount is Not Correct، وطريقة إصلاحها في المقال نفسه.
- رقم البند. رقم كل بند يجب أن يكون فريدًا داخل الفاتورة، وإلا عادت رسالة
The ID number must be unique، وهي موضوع مقال تكرار رقم البند. - نسبة الضريبة. عند نسبة 0% لا يُستخدم التصنيف
S. أما النسبة التي لا تقع ضمن النسب المعتمدة لدى الدائرة فيذكرها الدليل بين أسباب خطأ 500 في نظام الفوترة الوطني. - الرمز البريدي. إن أرسلته فلا يتجاوز 5 خانات، وإلا عادت رسالة
Postal code length is incorrect. - نوع الفاتورة. يجب أن يتناسب مع الرقم الضريبي للمكلف وتسلسل مصدر الدخل، كما سبق في قسم القوالب.
فالملف السليم البنية قد يُرفض لقيمة خاطئة، والملف ذو القيم الصحيحة قد يُرفض لخلل في البنية. والفحص الجيد قبل الإرسال يغطي الجانبين معًا.
قائمة فحص قبل إرسال ملف الفاتورة
تجمع هذه القائمة ما يشترطه الدليل في البنية وما يرتبط بها من إرشاداته، لتراجعها قبل إرسال أول فاتورة من نظامك أو بعد أي تعديل على طريقة بناء الملف.
- يبدأ الملف بسطر التعريف بترميز
UTF-8. - وسم
Invoiceالافتتاحي في سطر واحد، ويعلن مساحات الأسماء الأربع كما وردت في الدليل. - قيمة
ProfileIDهيreporting:1.0. - القالب المستخدم يناسب نوع الفاتورة، دخلًا أو مبيعات أو مبيعات خاصة، إنشاءً أو إرجاعًا.
- كل متغير مظلل بالأصفر في القالب له قيمة، والوصف الثابت منسوخ دون تعديل.
- التاريخ بالصيغة
yyyy-mm-dd، ورقم كل بند فريد داخل الفاتورة. - المعرّف الفريد محفوظ قبل الإرسال، ويُعاد استخدامه نفسه مع الرقم نفسه عند إعادة الإرسال بعد فشل أو انقطاع.
- الحكم على النتيجة من
EINV_STATUS، مع حفظ رقم الفاتورة والمعرّف الفريد ورمز QR وحالة الفاتورة.
وإن رُفضت فاتورة فسجّل تفاصيل الخطأ داخليًا كما يطلب الإرشاد السادس، وأصلح السبب، ثم أعد الإرسال بالمعرّفين أنفسهما. وللاستفسارات التي لا يجيب عنها الدليل، يحيل الدليل إلى لجنة الدعم الفني لشؤون الفوترة في الدائرة.
كيف يبني قيود ملف الفاتورة
حين تُصدر الفاتورة من قيود لا تكتب ملف XML بيدك، ولا تراجع سطر التعريف ومساحات الأسماء. يبني قيود ملف الفاتورة بصيغة UBL 2.1 مع معرّفها الفريد، ويرسله إلى نظام الفوترة الوطني دون أي تدخل يدوي، عبر تكامل قيود مع نظام الفوترة الوطني.
- فحص قبل الإرسال. يفحص قيود كل فاتورة على مستوى الحقول لحظة إنشائها، وهي الرقم الضريبي، ونوع المستند وطريقة الدفع، ونسبة ضريبة المبيعات العامة، واكتمال البنود، وينبهك بأي خطأ قبل إرسالها لتقليل حالات الرفض.
- حالة كل فاتورة أمامك. تعيد الدائرة حالة الفاتورة ورسالة الخطأ، ويعرضها قيود في لوحة الحالة.
- إعادة إرسال بالمعرّف نفسه. تعرض لوحة الحالة الفواتير التي لم تُرسل وتحتاج إلى إعادة إرسال، وتُعاد بمعرّف UUID نفسه فلا تتكرر.
والفحص المسبق تنبيه لا ضمان، فهو يغطي الحقول الأربعة المذكورة، ويبقى قبول الفاتورة قرارًا لنظام الفوترة الوطني وحده. وبعد القبول يعود رمز QR من الدائرة، ويطبعه قيود على الفاتورة. وللصورة الكاملة عن النظام وطريقة ربط منشأتك به، اقرأ مقال نظام الفوترة الوطني الإلكتروني.
فوترة إلكترونية ومحاسبة متكاملة في نظام واحد
قيود متكامل مع نظام الفوترة الوطني (JoFotara). تُصدر فاتورتك بالدينار الأردني من قيود فتُقيَّد في دفاترك تلقائيًا وتُرسل إلى النظام، وبعد قبولها يعود عليها رمز QR من دائرة ضريبة الدخل والمبيعات.
الأسئلة الشائعة
ما هو معيار UBL 2.1 في نظام الفوترة الوطني؟
هو الهيكل الذي اعتمدته دائرة ضريبة الدخل والمبيعات لملف الفاتورة الإلكترونية بصيغة XML. ينص الدليل التقني 1.5 على أن ملف الفاتورة يجب أن يطابق هذا المعيار، وأن أي خلل في البنية يؤدي إلى رفض الفاتورة.
ماذا يحدث إذا خالف ملف الفاتورة معيار UBL 2.1؟
تُرفض الفاتورة بحسب الإرشاد الأول في الدليل التقني. وفي الرد المرفوض تكون قيمة EINV_STATUS هي NOT_SUBMITTED، ولا يعود رمز QR، ويظهر السبب في رسالة EINV_MESSAGE.
ما قيمة ProfileID في فاتورة نظام الفوترة الوطني؟
تكون قيمته reporting:1.0 في كل فاتورة، سواء كانت فاتورة دخل أو مبيعات أو مبيعات خاصة، جديدة أو إرجاعًا.
هل أنسخ بداية ملف XML كما وردت في الدليل؟
نعم، فسطر التعريف ووسم Invoice بمساحات أسمائه الأربع وعنصر ProfileID وصف ثابت يُنسخ دون تعديل. ويجب أن يبقى وسم Invoice الافتتاحي في سطر واحد، وإلا عادت رسالة Invalid Invoice Minification.
كيف أعرف أن الفاتورة اجتازت فحص المعيار؟
يذكر الرد الناجح ذلك صراحة في قائمة INFO، برمز XSD_VALID وتصنيف XSD validation ورسالة Complied with UBL 2.1 standards. أما الحكم النهائي على الفاتورة فيكون من قيمة EINV_STATUS.
هل يكفي أن يطابق الملف المعيار لتُقبل الفاتورة؟
لا يكفي ذلك وحده، فالنظام يفحص القيم أيضًا. ويوثق الدليل رسائل رفض للمجاميع غير الصحيحة، وتكرار رقم البند، ونسبة الضريبة، ونوع الفاتورة الذي لا يناسب تسجيل المكلف.
المراجع
- دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026.
