ترويسة ملف الفاتورة في نظام الفوترة الوطني: مرجع العناصر

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

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

ما تحمله ترويسة ملف الفاتورة في نظام الفوترة الوطني

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

ترتيب العناصر في القالب كما يلي، والنقاط الثلاث مكان كل قيمة متغيرة يعبئها نظامك.

<cbc:ID>...</cbc:ID>
<cbc:UUID>...</cbc:UUID>
<cbc:IssueDate>yyyy-mm-dd</cbc:IssueDate>
<cbc:InvoiceTypeCode name="...">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 بأنه رقم مميز ينشئه نظام المكلف. ثم يجعل العنصرين معًا مفتاحًا رئيسيًا (Primary Key) يمنع تكرار الفاتورة. فالذي يميّز الفاتورة في النظام هو الزوج كاملًا، لا رقم الفاتورة وحده.

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

تاريخ الفاتورة

يُكتب التاريخ في العنصر cbc:IssueDate بالصيغة yyyy-mm-dd، أي السنة ثم الشهر ثم اليوم، كما في 2022-12-31. وهذه هي الصيغة المستخدمة في جميع أمثلة XML في الدليل. وقد يُظهر وصف الصيغة المنسوخ من ملف الدليل أجزاء التاريخ بترتيب مختلف في بعض الصفحات، فاعتمد صيغة الأمثلة. والتفصيل، ومعه الإرشاد التاسع عن التنسيق الزمني الموحد، في مقال صيغة تاريخ الفاتورة في نظام الفوترة الوطني.

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

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

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

الملاحظة

العنصر cbc:Note نص حر يضيف ملاحظة أو وصفًا للفاتورة، وهو العنصر الوحيد المظلل بالأخضر في الترويسة، أي أنه اختياري. وأهم ما فيه لمن يبني الملف أمران. الأول أن الملاحظة تغيب عن ترويسة فاتورة الإرجاع في ضريبة المبيعات العامة والخاصة، وتبقى اختيارية في إرجاع فاتورة الدخل. والثاني أن سبب الإرجاع لا يُكتب في الملاحظة، بل في عنصر آخر سيأتي ذكره.

رمزا العملة

تحمل الترويسة عنصرين للعملة، cbc:DocumentCurrencyCode لعملة المستند وcbc:TaxCurrencyCode لعملة الضريبة، والقيمة الافتراضية فيهما JOD. وينص الدليل على أن «تغيير نوع العملة يكون على مستوى كامل الفاتورة فقط»، ويعرض مثاله التغيير في هذين العنصرين معًا. ويسرد جدولًا بسبع عشرة عملة أخرى إلى جانب الدينار، فتصبح العملات ثماني عشرة. ولا يذكر الدليل عنصرًا لسعر الصرف ولا قاعدة للتحويل إلى الدينار، وما يقوله وما يسكت عنه في هذا الباب في مقال الفاتورة بعملة أجنبية في نظام الفوترة الوطني.

عداد الفاتورة

آخر الترويسة كتلة cac:AdditionalDocumentReference، وفيها عنصران. الأول cbc:ID بالقيمة الثابتة ICV، والثاني عنصر اسمه cbc:UUID لكنه لا يحمل المعرّف الفريد، بل قيمة العداد. ويصف الدليل العداد بأنه «عداد يتم إنشاؤه من قبل المكلف للفواتير الإلكترونية يبدأ بشكل تسلسلي من 1». وتشابه اسم العنصر مع المعرّف الفريد في أول الترويسة قد يسبب خلطًا عند البرمجة، ففرّق بينهما بموضع العنصر لا باسمه. وشرح العداد وحدود ما يقوله الدليل عن تسلسله في مقال عداد الفاتورة ICV في نظام الفوترة الوطني.

ما يتغير في الترويسة بين أنواع الفواتير

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

أما رقم الفاتورة والمعرّف الفريد والتاريخ والعداد فتأتي في المواضع كلها بالوصف نفسه. ويصف الدليل العداد بأنه «للفواتير الإلكترونية» بلفظ عام، دون أن يفرّق بين عائلة وأخرى أو بين فاتورة جديدة وإرجاع.

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

عناصر على مستوى الفاتورة لا تنتمي إلى الترويسة

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

• ما يسبق الترويسة. سطر التعريف بالملف، ثم العنصر الجذري Invoice الذي يجب أن يأتي وسمه الافتتاحي كاملًا في سطر واحد، ثم العنصر cbc:ProfileID بالقيمة reporting:1.0 في كل فاتورة. وهذه البنية مشروحة في مقال معيار UBL 2.1 في نظام الفوترة الوطني.
• ما يلي الترويسة. كتلة البائع، ثم كتلة المشتري، ثم كتلة تسلسل مصدر الدخل cac:SellerSupplierParty. ورقم البائع الضريبي واسم المشتري وتسلسل مصدر الدخل كلها خارج الترويسة.
• الخصم والضريبة على مستوى الفاتورة. العنصر cac:AllowanceCharge على مستوى الفاتورة مجموع خصومات البنود، والعنصر cac:TaxTotal على مستوى الفاتورة مجموع ضريبة المبيعات العامة في البنود، ولا يرد في فاتورة الدخل. والعنصران مرتبطان بالمجاميع، فيُراجعان معها لا مع الترويسة.
• سبب الإرجاع. يُكتب في العنصر cbc:InstructionNote داخل كتلة cac:PaymentMeans في فاتورة الإرجاع، وهو إجباري هناك. فلا تضعه في الملاحظة، وتفصيله في مقال سبب الإرجاع في نظام الفوترة الوطني.

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

لا تنتهي وظيفة الترويسة عند الإرسال، فبعض عناصرها يعود إليك في الرد. يذكر الدليل بين عناصر الرد EINV_NUM وهو رقم الفاتورة المرسل، وEINV_INV_UUID وهو المعرّف الفريد للفاتورة. أما حالة الفاتورة فتُقرأ من EINV_STATUS، لا من رمز الاستجابة الفني وحده.

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

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

ما لا يحدده الدليل في عناصر الترويسة

بعض الأسئلة التي تُطرح عند بناء الترويسة لا يجيب عنها الإصدار 1.5 من الدليل. ومعرفتها تمنعك من بناء نظامك على افتراض يُنسب إلى الدائرة وهو ليس من كلامها.

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

قائمة فحص لترويسة الملف قبل الإرسال

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

1. رقم الفاتورة موجود في cbc:ID، ومعرّف فريد في cbc:UUID محفوظ في نظامك مع الفاتورة.
2. عند إعادة الإرسال بعد فشل، يبقى الرقم والمعرّف كما كانا في المحاولة الأولى.
3. التاريخ بالصيغة yyyy-mm-dd، والتاريخ هو تاريخ إصدار الفاتورة.
4. قيمة cbc:InvoiceTypeCode هي 388 للفاتورة الجديدة و381 للإرجاع.
5. الخانة الثالثة في السمة name توافق تسجيلك لدى الدائرة، والخانتان الأولى والثانية توافقان نوع الفاتورة وطريقة الدفع.
6. في فاتورة الإرجاع، السمة name والعملة مطابقتان لما في الفاتورة الأصلية.
7. الملاحظة غائبة عن ترويسة الإرجاع في ضريبة المبيعات العامة والخاصة، وسبب الإرجاع في موضعه المخصص.
8. إذا غيّرت العملة فغيّرها في عنصري العملة معًا كما يعرض مثال الدليل، فتغيير العملة يكون للفاتورة كلها.
9. الكتلة الأخيرة تحمل ICV في cbc:ID وقيمة العداد في cbc:UUID، لا المعرّف الفريد.

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

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

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

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

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

ما ترويسة ملف الفاتورة في نظام الفوترة الوطني؟

تعني الترويسة العناصر التي تبدأ بها الفاتورة بعد سطر التعريف وقيمة ProfileID، ويسميها الدليل التقني «معلومات الفاتورة الأساسية». وهي رقم الفاتورة، والمعرّف الفريد، والتاريخ، ورمز نوع الفاتورة مع السمة name، والملاحظة، ورمزا العملة، وكتلة عداد الفاتورة ICV.

أي عناصر الترويسة اختياري؟

يظلل الدليل التقني الملاحظة cbc:Note وحدها بالأخضر في الترويسة، والأخضر في مفتاح ألوانه يدل على متغير اختياري. وسائر القيم المتغيرة في الترويسة مظللة بالأصفر، أي أنها إجبارية يعبئها نظام البائع.

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

تتطابق العناصر في الحالتين، ويقع الفرق في الخانة الأخيرة من السمة name، وهي 1 لفاتورة الدخل و2 لفاتورة ضريبة المبيعات العامة و3 للضريبة الخاصة. ويظهر فرق آخر في الإرجاع، إذ تغيب الملاحظة عن ترويسة إرجاع ضريبة المبيعات العامة والخاصة وتبقى اختيارية في إرجاع فاتورة الدخل.

ما الفرق بين cbc:UUID في أول الترويسة وcbc:UUID في كتلة ICV؟

يحمل العنصر الأول المعرّف الفريد للفاتورة، وهو مع رقم الفاتورة المفتاح الأساسي الذي يمنع تكرارها. أما العنصر الثاني فيقع داخل الكتلة AdditionalDocumentReference بعد القيمة الثابتة ICV، ويحمل عداد الفاتورة الذي يبدأ من 1.

هل أكتب سبب الإرجاع في الملاحظة؟

يحدد الدليل التقني لسبب الإرجاع موضعًا آخر، هو العنصر InstructionNote داخل الكتلة PaymentMeans في فاتورة الإرجاع، والسبب فيه إجباري. والملاحظة لا ترد أصلًا في ترويسة الإرجاع في ضريبة المبيعات العامة والخاصة.

هل يعيد نظام الفوترة الوطني شيئًا من الترويسة في رده؟

يعيد النظام في رده رقم الفاتورة المرسل في EINV_NUM والمعرّف الفريد في EINV_INV_UUID، إلى جانب حالة الفاتورة ورمز QR عند قبولها. وإذا أعيد إرسال فاتورة مقبولة بالرقم والمعرّف نفسيهما، جاءت الحالة ALREADY_SUBMITTED مع الرمز الأصلي.

المراجع

• دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026، ص12 إلى ص14 وص23 وص24 وص33 وص46 وص47 وص58 وص73 وص74 وص97 إلى ص107.