من يبني الربط بين برنامج محاسبي ونظام الفوترة الوطني يبدأ عادة من الدليل التقني الصادر عن دائرة ضريبة الدخل والمبيعات، ويجد فيه أمثلة XML كاملة لفواتير البيع والإرجاع ونماذج للرد وجزءًا من شيفرة بلغة C#. والسؤال الذي يطرحه المطوّر سريعًا هو هل يصلح نسخ أمثلة الدليل التقني لنظام الفوترة الوطني كما هي إلى ملف الإرسال. الجواب المباشر أن هذه الأمثلة تشرح البنية جيدًا، لكن بعض قيمها ونصوصها لا يصلح للنسخ الحرفي.
يلاحظ من يقرأ الإصدار 1.5 من الدليل صفحة صفحة ستة مواضع من هذا النوع، هي معرّفات فريدة مكتوبة بصيغة غير قياسية، وعلامات اقتباس مكررة في أمثلة الضريبة الخاصة، وأمثلة إرجاع لا تطابق فواتيرها الأصلية، ونص يختلف في وصف صيغة التاريخ، وسطر جلسة في مثال C#، وعنوان نموذج في صفحة 100 لا يطابق النموذج الذي تحته. ويضاف إليها رمز محافظة ناقص في جدول واحد.
يعرض هذا المقال كل موضع بالصفحة التي ورد فيها، وما يظهر في المثال، ولماذا يفشل نسخه، وما الذي تكتبه بدلًا منه. والغرض عملي بحت، فالدليل هو المرجع الرسمي للربط، وهذه الملاحظات تساعدك على قراءته بدقة.
لماذا لا تُنسخ أمثلة الدليل التقني لنظام الفوترة الوطني كما هي
يفرّق الدليل نفسه بين ثلاثة أنواع من العناصر في كل نموذج فاتورة، ويشرح ذلك بالألوان (ص12). فالعناصر المظللة بالأصفر متغيرات إجبارية يعبئها نظام البائع، والمظللة بالأخضر متغيرات اختيارية، «وباقي العناصر وصف ثابت بدون تغيير». وطريقة قراءة هذا التظليل مشروحة في مقال الحقول الإجبارية والاختيارية في نظام الفوترة الوطني.
هذا التقسيم يحدد ما تأخذه من المثال وما لا تأخذه. الوصف الثابت تنقله كما هو، أما المتغيرات فتملؤها من بيانات فاتورتك. والمواضع التي يتناولها هذا المقال يقع بعضها في القيم التوضيحية التي وُضعت مكان المتغيرات، وبعضها في الوصف المكتوب حول المثال. فإذا نسخت الملف كله دفعة واحدة، فأنت تنقل هذه القيم معه.
ويضيف الإرشاد الأول من الإرشادات العشر في الدليل (ص104) سببًا آخر للحذر، فهو يشترط أن يلتزم ملف XML بمعيار UBL 2.1، وأي خلل في البنية يؤدي إلى رفض الفاتورة. وتفاصيل المعيار وما يشترطه في مقال معيار UBL 2.1 في نظام الفوترة الوطني.
ملخص المواضع التي تحتاج انتباهًا في أمثلة الدليل
يجمع الجدول التالي المواضع كلها مع صفحاتها في الإصدار 1.5، ثم تشرح الأقسام بعده كل موضع على حدة.
مرِّر الجدول أفقيًا لعرض بقية الأعمدة
المعرّفات الفريدة في صفحتي 14 و98
المعرّف الفريد في الحقل cbc:UUID هو نصف المفتاح الأساسي للفاتورة مع رقمها في الحقل cbc:ID، ويولّده نظام المكلف لا نظام الفوترة. ويلاحظ في المثال صفحة 14 أن المجموعة الأخيرة من المعرّف ناقصة، إذ لا تضم إلا إحدى عشرة خانة. ويلاحظ في نموذج رد الحالة SUBMITTED صفحة 98 أن قيمة الحقل EINV_INV_UUID تحتوي أحرفًا لا تنتمي إلى النظام الست عشري.
لا نعيد كتابة القيمتين هنا عمدًا، حتى لا تُنسخا من هذا المقال أيضًا. والمشكلة في نسخهما لا تقف عند الصيغة. فالمعرّف المنسوخ من مثال قيمة واحدة ثابتة، وإذا استعمله برنامجك لأكثر من فاتورة فقد خرج عن وظيفة المعرّف أصلًا، وهي أن يميّز كل فاتورة عن غيرها.
البديل أن يولّد نظامك معرّفًا لكل فاتورة بصيغة قياسية، ويحفظه مع سجلها قبل أول إرسال، ويعيد استعماله في كل إعادة إرسال للفاتورة نفسها. وهذه القاعدة مشروحة بالتفصيل في مقال المعرّف الفريد UUID في نظام الفوترة الوطني.
علامات الاقتباس المكررة في أمثلة الضريبة الخاصة
في ملف XML تُكتب قيمة كل سمة بين علامتي اقتباس، علامة تفتحها وعلامة تغلقها. ويلاحظ في أمثلة فاتورة الضريبة الخاصة أن بعض السمات كُتبت بعلامات مضاعفة، فلا يعود الملف سليم البنية إذا نُسخ كما هو.
- سطر نظام الضريبة في بند الفاتورة. في الصفحات 69 و82 و91 و93 تظهر السمتان
schemeAgencyIDوschemeIDبعلامتي اقتباس مضاعفتين حول كل قيمة. - سمة العملة على المبالغ. في صفحتي 68 و81 تنتهي قيمة السمة
currencyIDبعلامتي اقتباس بدل علامة واحدة.
الصيغة السليمة لسطر نظام الضريبة موجودة في الدليل نفسه، في جدول بنود فاتورة ضريبة المبيعات العامة (ص41 إلى ص43)، حيث يُكتب كل من schemeAgencyID="6" وschemeID="UN/ECE 5153" بعلامة اقتباس واحدة على كل جانب. وتستخدم أمثلة الدليل للسمة currencyID القيمة JO في جميع المبالغ. ولا يذكر الدليل هل يقبل النظام قيمة أخرى في هذه السمة، لذلك لا نبني على ذلك شيئًا هنا.
ولأن هذا الموضع يقع في أمثلة الضريبة الخاصة تحديدًا، فمن المفيد أن تراجع بنية سطر الضريبة الخاصة نفسه، وهو سطر بنظام ضريبة OTH يأتي قبل سطر الضريبة العامة ولا يحمل عنصر نسبة. وشرحه في مقال الضريبة الخاصة في ملف فاتورة نظام الفوترة الوطني.
أمثلة فاتورة الإرجاع لا تطابق فواتيرها الأصلية
فاتورة الإرجاع في نظام الفوترة الوطني مرتبطة بفاتورة بيع أصلية، ويضع الدليل لهذا الارتباط قواعد واضحة. فكتلة المرجع cac:BillingReference تحمل رقم الفاتورة الأصلية ومعرّفها الفريد، ويحمل الحقل cbc:DocumentDescription إجمالي الفاتورة الأصلية. ورقم البند واسمه وسعر الوحدة تُكتب «كما هو في الفاتورة الأصلية». وينص الدليل على أنه «يجب أن تتوافق بيانات المشتري في فاتورة الإرجاع مع بياناته في فاتورة البيع الأصلية المرتبطة بها» (ص26 وص49 وص76).
المشكلة أن أمثلة الإرجاع في الدليل (ص24 وص25 وص30 وص47 وص55 وص56 وص74) لا تتطابق مع أمثلة البيع التي تسبقها. ويلاحظ فيها ما يلي.
- مثال إرجاع فاتورة الدخل (ص24 وص25). قيمة
cbc:DocumentDescriptionفيه 64.000، في حين أن إجمالي فاتورة الدخل الأصلية في مثالها 109.000. - مثال إرجاع فاتورة ضريبة المبيعات العامة (ص47 وص56). يشير المرجع إلى معرّف فريد يختلف عن معرّف الفاتورة الأصلية في مثالها، ويظهر فيه البند المعفى ذو التصنيف
Zفي الفاتورة الأصلية بالتصنيفSونسبة 10%. - مثال إرجاع فاتورة الضريبة الخاصة (ص74). يحمل بيانات الرأس نفسها التي في مثال إرجاع ضريبة المبيعات العامة.
- كتلة المشتري في مثال الإرجاع العام (ص49 وص50). تظهر فيها نسخة متداخلة من القالب لا تصلح بنيتها للنسخ.
هذه الأمثلة تصلح لفهم مكان كل عنصر في فاتورة الإرجاع، لكنها لا تصلح مرجعًا للقيم. فإذا بنيت اختبارك على مثال البيع ثم على مثال الإرجاع كما هما في الدليل، فأنت ترسل إرجاعًا يشير إلى فاتورة لا تطابقه. والبديل أن تبني الإرجاع دائمًا من سجل الفاتورة الأصلية المحفوظ عندك، فتأخذ منه رقمها ومعرّفها وإجماليها وبيانات المشتري وأرقام البنود وأسماءها وأسعارها، ثم تكتب الكميات المرجعة وحدها.
ويتصل بهذا الموضع أن مجاميع الإرجاع تغطي الجزء المراد إرجاعه فقط، وأن خصم الإرجاع الجزئي يكون جزءًا من الخصم الكلي للبند «حسب الكمية المرجعة» كما ينص الدليل (ص30 وص55). وإذا ظهر لك خطأ في المجاميع بعد الإرسال، فقواعد احتسابها في مقال رسالة Total General Amount is Not Correct في نظام الفوترة الوطني.
صيغة تاريخ الفاتورة بين النص والأمثلة
يصف الدليل صيغة الحقل cbc:IssueDate في عدة صفحات، ولا يأتي الوصف بالترتيب نفسه في كل مرة. ففي الصفحات 12 و24 و58 يذكر النمط yyyy-mm-dd ويرافقه مثال مكتوب بترتيب مختلف عنه. وفي صفحة 33 يرد نمط يضع اليوم قبل الشهر بعد السنة، وفي صفحتي 46 و73 يرد نمط يبدأ باليوم.
أما أمثلة XML نفسها فمتفقة كلها. فكل تاريخ في كل مثال مكتوب بالترتيب سنة ثم شهر ثم يوم، وهو كذلك الترتيب الذي يستعمله معيار UBL والمعيار الدولي ISO 8601. لذلك اكتب التاريخ بالصيغة yyyy-mm-dd كما في جميع أمثلة XML في الدليل، ولا تعتمد أي ترتيب آخر ورد في النص الوصفي بديلًا عنها. ويدعم ذلك الإرشاد التاسع في الدليل، ونصه «استخدام تنسيق زمني موحد (Standard Time Format) لتجنب اختلافات المعالجة بين الأنظمة». وتفصيل هذه الصيغة موضوع مقال صيغة تاريخ الفاتورة في نظام الفوترة الوطني.
مثال C# في صفحة 96 وسطر الجلسة
يقدّم الدليل مثالًا بلغة C# يوضح شكل طلب الإرسال، وهو مفيد في هذا الجانب. فالطلب يُرسل بطريقة POST إلى العنوان https://backend.jofotara.gov.jo/core/invoices/، ويحمل في ترويساته رقم المستخدم في Client-Id والمفتاح السري في Secret-Key ونوع المحتوى Content-Type: application/json. ويحمل جسم الطلب ملف الفاتورة بعد ترميزه بصيغة Base64 تحت المفتاح invoice.
لكن المثال يضيف إلى هذه الترويسات سطرًا رابعًا هو ترويسة Cookie تحمل قيمة جلسة. هذه القيمة ليست من مكونات الطلب التي يشرحها الدليل، فهو يعدّ في صفحة 10 ثلاثة مكونات فقط هي رقم المستخدم والمفتاح السري وملف الفاتورة. لذلك طمسنا قيمتها في الصورة أعلاه، ولا تنسخ هذا السطر إلى برنامجك ولا ترسل أي قيمة جلسة مع الطلب.
وفي المثال كذلك سطر يضبط مهلة الاتصال. وقرار المهلة يعود إلى تصميم نظامك، والثابت في الدليل هو ما تفعله حين تنقضي المهلة. فالإرشاد الثامن ينص على أنه «عند حدوث Timeout أو فشل اتصال يجب إعادة المحاولة دون توليد UUID جديد».
وما دام الحديث عن الترويسات، فالدليل يضع حماية رقم المستخدم والمفتاح السري على المكلف كاملة، ويقول إنه «يتحمّل كامل المسؤولية عن أي استخدام غير مصرح به». ويطلب الإرشاد السابع ألا تُكتب هاتان القيمتان صراحة داخل الشيفرة. فإذا اقتبست بنية المثال، فاقرأ القيمتين من إعدادات محمية في نظامك لا من نص الشيفرة.
عنوان النموذج في صفحة 100
يعرض الدليل في صفحة 100 شرح الحالة NOT_SUBMITTED، ثم يورد تحته نموذج ملف الرد. ويلاحظ أن العنوان فوق النموذج يقول إنه رد حالة ALREADY_SUBMITTED، مع أن النموذج نفسه هو رد الحالة NOT_SUBMITTED.
الفرق بين الحالتين كبير. فالحالة ALREADY_SUBMITTED تعني أن الفاتورة نفسها برقمها ومعرّفها الفريد سبق قبولها، ويعيد النظام معها رمز الاستجابة السريع الأصلي. أما NOT_SUBMITTED فتعني رفض الفاتورة، ولا يكون رمز الحالة فيها 200، وتأتي حقول الرمز والمعرّف والرقم والفاتورة الموقعة EINV_SINGED_INVOICE فارغة بالقيمة null.
إذا بنيت معالجة الرد في برنامجك على عنوان النموذج، فقد تعامل الفاتورة المرفوضة معاملة فاتورة مقبولة سابقًا. والبديل أن تقرأ القيمة في الحقل EINV_STATUS نفسه، فالإرشاد الرابع ينص على الاعتماد عليها لتحديد حالة الفاتورة النهائية لا على رمز الحالة وحده. وما تفعله بعد هذه الحالة مشروح في مقال حالة NOT_SUBMITTED في نظام الفوترة الوطني.
رمز محافظة البلقاء في جدول الضريبة الخاصة
يحمل الحقل cbc:CountrySubentityCode في بيانات المشتري رمز المحافظة، وهو حقل اختياري حسب تظليل الدليل. ويلاحظ في جدول رموز المحافظات ضمن نموذج فاتورة الضريبة الخاصة (ص63) أن رمز البلقاء مطبوع بلا الحرف الأول، والرمز الصحيح هو JO-BA. فإذا نقلت قائمة الرموز إلى برنامجك من هذا الجدول تحديدًا، فصحح هذا الرمز قبل استعماله. والقائمة كاملة بالرموز الاثني عشر في مقال رموز المحافظات في فاتورة نظام الفوترة الوطني.
طريقة آمنة للإفادة من أمثلة الدليل
لا يعني ما سبق أن تترك الأمثلة جانبًا، فهي أوضح ما في الدليل لفهم ترتيب العناصر. والخطوات التالية اقتراح عملي من قيود لاستعمالها دون نقل ما فيها من مواضع، وكل خطوة منها مبنية على قاعدة مذكورة في الدليل.
- خذ البنية والوصف الثابت من القالب. انقل العناصر غير المظللة كما هي، ومنها مقدمة الملف والعنصر
cbc:ProfileIDبالقيمةreporting:1.0، واجعل وسم الفاتورة الافتتاحي في سطر واحد كما يشترط الدليل (ص102). - املأ كل متغير من بيانات الفاتورة الفعلية. لا تُبقِ في ملفك أي قيمة توضيحية من المثال، سواء كانت رقمًا ضريبيًا أو اسمًا أو مبلغًا أو معرّفًا.
- ولّد المعرّف الفريد واحفظه. اجعله معرّفًا بصيغة قياسية لكل فاتورة، يُحفظ قبل أول إرسال ويُعاد استعماله عند إعادة الإرسال.
- احسب المجاميع من البنود. طبّق معادلات الدليل على بنود فاتورتك، ولا تنقل أرقام المجاميع من المثال.
- ابنِ الإرجاع من سجل الفاتورة الأصلية، لا من مثال الإرجاع في الدليل.
- اكتب التاريخ بالصيغة yyyy-mm-dd، كما في جميع أمثلة XML في الدليل.
- افحص سلامة بنية الملف قبل الترميز. استعمل فحصًا يكشف علامات الاقتباس المكررة وأي وسم غير مغلق، لأن الإرشاد الأول ينص على أن أي خلل في البنية يؤدي إلى رفض الفاتورة.
- اقرأ الرد من EINV_STATUS، لا من رمز الحالة وحده، ولا من عناوين النماذج.
ويبقى الدليل التقني هو المرجع عند أي اختلاف، والإصدار الذي يستند إليه هذا المقال هو 1.5. فإذا صدر إصدار أحدث، فراجع هذه المواضع فيه من جديد، فقد يتغير بعضها.
كيف يتعامل قيود مع ملف الفاتورة
كل ما سبق عمل يقع على نظام المكلف، ويتولاه البرنامج المحاسبي المربوط بنظام الفوترة الوطني. ويعمل تكامل قيود مع نظام الفوترة الوطني على هذه الطبقة كما يلي.
- بناء الملف. يبني قيود ملف الفاتورة بصيغة UBL 2.1 مع المعرّف الفريد، ويرسله إلى نظام الفوترة الوطني دون أي تدخل يدوي.
- فحص الحقول قبل الإرسال. يفحص قيود كل فاتورة على مستوى الحقول لحظة إنشائها، ومنها الرقم الضريبي ونوع المستند وطريقة الدفع ونسبة ضريبة المبيعات العامة واكتمال البنود، وينبهك بأي خطأ قبل إرسالها لتقليل حالات الرفض.
- حالة كل فاتورة. تعيد الدائرة حالة الفاتورة ورسالة الخطأ، ويعرضها قيود في لوحة الحالة، ومنها «مرسلة» و«مرسلة مسبقًا» و«لم تُرسل» مع رسالة الخطأ.
- إعادة الإرسال. تعرض لوحة الحالة الفواتير التي لم تُرسل وتحتاج إلى إعادة إرسال، وحين تعيد إرسالها تُرسل بالمعرّف UUID نفسه.
ولصورة أوسع عن النظام وطريقة ربط منشأتك به، اقرأ مقال نظام الفوترة الوطني الإلكتروني في الأردن، أو تعرّف على ما يقدمه قيود في صفحة نظام الفوترة الوطني.
فوترة إلكترونية ومحاسبة متكاملة في نظام واحد
قيود متكامل مع نظام الفوترة الوطني (JoFotara). تُصدر فاتورتك بالدينار الأردني من قيود فتُقيَّد في دفاترك تلقائيًا وتُرسل إلى النظام، وبعد قبولها يعود عليها رمز QR من دائرة ضريبة الدخل والمبيعات.
الأسئلة الشائعة
هل أمثلة XML في الدليل التقني لنظام الفوترة الوطني ملفات جاهزة للإرسال؟
تشرح الأمثلة بنية الملف وترتيب عناصره، لكنها ليست ملفات جاهزة. فبعض قيمها توضيحية، وفي بعضها مواضع لا تصلح للنسخ، مثل المعرّفات غير القياسية في صفحتي 14 و98 وعلامات الاقتباس المكررة في أمثلة الضريبة الخاصة.
ما صيغة تاريخ الفاتورة الصحيحة في ملف XML؟
تُكتب الصيغة yyyy-mm-dd، أي السنة ثم الشهر ثم اليوم، كما في جميع أمثلة XML في الدليل التقني. والنص الوصفي في بعض الصفحات يذكر ترتيبًا مختلفًا، فلا تعتمده بديلًا.
هل أرسل ترويسة Cookie كما في مثال C# في الدليل؟
لا ترسلها. يكتفي الطلب بثلاث ترويسات هي Client-Id وSecret-Key وContent-Type، أما سطر Cookie في مثال صفحة 96 فيحمل قيمة جلسة ليست من مكونات الطلب التي يشرحها الدليل.
هل أستطيع بناء فاتورة الإرجاع من مثال الإرجاع في الدليل؟
تستطيع أن تأخذ منه البنية فقط. فأمثلة الإرجاع في الدليل لا تطابق أمثلة البيع التي تسبقها في الإجمالي والمعرّف، والإرجاع الفعلي يُبنى من سجل الفاتورة الأصلية المحفوظ في نظامك.
نموذج الرد في صفحة 100 يقول ALREADY_SUBMITTED، فما الحالة الصحيحة؟
يعرض النموذج رد الحالة NOT_SUBMITTED، أي فاتورة مرفوضة تأتي فيها حقول الرمز والمعرّف والرقم والفاتورة الموقعة فارغة. والحكم على الفاتورة يكون دائمًا من قيمة EINV_STATUS في الرد.
ما رمز محافظة البلقاء في ملف الفاتورة؟
رمزها JO-BA. ويظهر الرمز في جدول الضريبة الخاصة صفحة 63 ناقصًا الحرف الأول، فصححه إذا نقلت القائمة من ذلك الجدول.
المراجع
- دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026، ص10 وص12 وص14 وص24 إلى ص26 وص30 وص33 وص41 إلى ص43 وص46 إلى ص50 وص55 وص56 وص58 وص63 وص68 وص69 وص73 وص74 وص76 وص81 وص82 وص91 وص93 وص96 وص98 وص100 وص102 وص104.
