بناء طلب إرسال الفاتورة إلى نظام الفوترة الوطني: XML إلى JSON

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

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

ترتيب بناء طلب إرسال الفاتورة إلى نظام الفوترة الوطني

يرسم الدليل التقني مسار الإرسال في مخطط واحد (ص9). يخرج الطلب من نظام المكلف بترويسة تحمل رقم المستخدم (Client ID) والمفتاح السري (Secret Key)، وجسم فيه ملف XML يمر بترميز Base64 ثم يوضع في ملف JSON. وتعود النتيجة واحدة من ثلاث، هي Submitted أو Already Submitted ومعهما الفاتورة الموقعة ورمز الاستجابة السريع (QR Code)، أو Error ومعها قائمة الأخطاء.

إذا فصّلنا هذا المخطط على ما يقوله الدليل في مواضع أخرى، يصبح الترتيب كما يلي.

1. توليد ملف الفاتورة بصيغة UBL 2.1 XML، بسطر التعريف والعنصر الجذري كما في ص10.
2. كتابة الوسم الجذري <Invoice …> على سطر واحد.
3. حفظ الملف بترميز UTF-8 الذي يعلنه سطر التعريف.
4. ترميز الملف كاملًا بترميز Base64.
5. وضع الناتج في جسم JSON تحت المفتاح invoice، وتجهيز الترويسات.
6. الإرسال بطريقة POST ثم قراءة قيمة EINV_STATUS في الرد.

الترتيب هنا ليس اختيارًا شكليًا. فالترميز مثلًا يقع على الملف كما هو لحظة ترميزه، وأي تصحيح بعده لا يصل إلى النظام ما لم تُعِد الترميز. وتفاصيل العنوان والترويسات نفسها يتناولها مقال «نقطة النهاية ورؤوس الطلب في نظام الفوترة الوطني» ضمن مركز المطوّرين.

قبل البناء: ما يجب أن يكون ثابتًا في نظامك

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

وثانيها رقم الفاتورة cbc:ID ومعرّفها الفريد cbc:UUID. فالمفتاح الأساسي للفاتورة في النظام هو الاثنان معًا، والمعرّف الفريد يولّده نظام المكلف، والدليل يحذّر من أن توليد معرّف جديد عند إعادة المحاولة قد يؤدي إلى تكرار الفاتورة. وثالثها عداد الفاتورة (ICV) الذي يبدأ من 1 تسلسليًا ويُنشئه المكلف.

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

الخطوة الأولى: توليد ملف الفاتورة بصيغة UBL 2.1

يطلب الدليل (ص10) أن يبدأ الملف بسطر التعريف الذي يحدد الترميز UTF-8، ثم العنصر الجذري Invoice بفضاءات الأسماء الأربعة، ثم العنصر cbc:ProfileID بالقيمة reporting:1.0 في كل فاتورة.

بعد البداية تأتي كتل البائع والمشتري والبنود والمجاميع حسب نوع الفاتورة، والتاريخ بصيغة yyyy-mm-dd كما في جميع أمثلة XML في الدليل. ويطلب الإرشاد الثاني من إرشادات الدائرة التحقق قبل الإرسال من المجاميع والضرائب والرقم الضريبي ورقم المشتري والحقول الإلزامية. ولا تنسخ أمثلة الدليل كما هي، ففي بعضها عيوب موثقة.

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

الخطوة الثانية: الوسم الجذري على سطر واحد

يشترط الدليل (ص102) أن يكون وسم البداية للعنصر Invoice مكتوبًا على سطر واحد، بين أجزائه مسافات. فإن توزّع على أكثر من سطر يرد الخطأ Invalid Invoice Minification.

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

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

الخطوة الثالثة: ترميز الحروف UTF-8

سطر التعريف يعلن encoding="UTF-8"، والدليل يطلبه كما هو. ونصيحتنا، وهي ملاحظة عامة منا لا قاعدة من الدائرة، أن يُحفظ الملف فعلًا بترميز UTF-8 قبل الانتقال إلى الخطوة التالية. فإذا أعلن الملف UTF-8 وحفظه برنامجك بترميز حروف آخر، صار ما يعلنه الملف عن ترميزه يخالف الترميز الذي حُفظ به فعلًا. والدليل لا يذكر هذه الحالة ولا رسالة خطأ خاصة بها.

ما تسجّله. احفظ النسخة النهائية من الملف كما هي قبل ترميزها. هذا ما ترجع إليه حين تسأل عمّا أُرسل فعلًا في فاتورة بعينها.

الخطوة الرابعة: ترميز الملف بترميز Base64

يلخص الدليل هذه الخطوة في جملة واحدة (ص96). بعد تجهيز الفاتورة بصيغة XML يُرمَّز الملف بترميز Base64 ويُدرج في ملف JSON، مع رقم المستخدم والمفتاح السري.

تستعمل الجملة في الصورة لفظًا آخر لهذه الخطوة، والمقصود بها ترميز يغيّر طريقة كتابة الملف ولا يجعله سريًا. والترميز يقع على ملف XML كاملًا من سطر التعريف حتى وسم الإغلاق، ولا يقع على نص JSON.

ما تسجّله. أن الترميز تم من النسخة النهائية المحفوظة في الخطوة السابقة، لا من نسخة أقدم. شرح الخطوة وأخطاؤها في مقال ترميز Base64 في نظام الفوترة الوطني.

الخطوة الخامسة: جسم JSON وترويسات الطلب

يحمل جسم الطلب مفتاحًا واحدًا، فيكون على شكل {"invoice": "…"}، وتحل محل النقاط سلسلة Base64 كاملة. ويذكر الدليل (ص10) أن ملف JSON له ثلاثة مكونات، هي رقم المستخدم والمفتاح السري والفاتورة، لكن مثال الإرسال (ص96) يضع القيمتين الأوليين في ترويسة الطلب، والفاتورة وحدها في الجسم.

الترويسات في مثال الدليل ثلاث، هي Client-Id وSecret-Key وContent-Type: application/json. ويكتب الدليل الاسمين في نصوص أخرى بشرطة سفلية، Client_ID وSecret_Key. ويضيف المثال ترويسة رابعة تحمل قيمة جلسة التُقطت من جلسة الدائرة نفسها، فلا ترسلها ولا تنسخ المثال كما هو.

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

الخطوة السادسة: الإرسال وقراءة الاستجابة

يُرسل الطلب بطريقة POST إلى العنوان الذي يذكره الدليل https://backend.jofotara.gov.jo/core/invoices/. ثم يُقرأ الرد على مستويين، رمز الحالة الفني ثم قيمة EINV_STATUS، وهي الحالة الحاسمة للفاتورة بحسب الإرشاد الرابع. فالرمز 200 يعني أن الطلب استُلم وعولج تقنيًا، والقيمة تقول هل قُبلت الفاتورة (SUBMITTED) أو سبق قبولها (ALREADY_SUBMITTED) أو رُفضت (NOT_SUBMITTED).

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

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

ما تسجّله في كل خطوة: جدول واحد للسجل

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

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

إذا رُفض الطلب: من أي خطوة يبدأ الإصلاح

فائدة الترتيب السابق أنه يحوّل رسالة الخطأ إلى خطوة بعينها. والربط الآتي مأخوذ من شرح الدليل لرموز الأخطاء (ص101 و102).

• الرسالة Invalid Invoice Minification ترجعك إلى الخطوة الثانية، أي وسم البداية للعنصر Invoice.
• الرمز 400 يدل على أخطاء في قيم ملف XML، وتفصيلها في EINV_MESSAGE، فيرجعك إلى الخطوة الأولى.
• الرمز 403 يدل على خطأ في رقم المستخدم أو المفتاح السري، فيرجعك إلى ترويسات الخطوة الخامسة.
• الرمز 500 يربطه الدليل بخطأ في الرقم الضريبي أو تسلسل مصدر الدخل، وبدرجة أقل في رقم المستخدم أو المفتاح السري، أو بنسبة ضريبة ليست ضمن النسب المعتمدة لدى الدائرة. فيرجعك إلى الخطوة الأولى أو الخامسة.
• الرمز 504 يدل على تعذّر الوصول إلى النظام، بسبب جدار الحماية لدى المكلف أو موقع النظام نفسه، فيبقيك في الخطوة السادسة.

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

ما لا يحدده الدليل التقني في هذا المسار

• البيئة التجريبية. لا يذكر الدليل (الإصدار 1.5) بيئة تجريبية مفتوحة للمكلفين أو لمزودي البرامج، والعنوان الوحيد للإرسال فيه هو العنوان السابق.
• توقيع المكلف. لا يطلب الدليل توقيعًا ولا شهادة رقمية من المكلف، والفاتورة الموقعة تعود من الدائرة في الحقل EINV_SINGED_INVOICE [كذا في الدليل].
• بنية رمز الاستجابة والفاتورة الموقعة. لا يشرح الدليل بنيتهما بعد فك الترميز، فاحفظهما كما وصلتا ولا تبنِ عليهما منطقًا في برنامجك.
• مهلة الإرسال بعد البيع. لا يحدد الدليل عددًا من الساعات أو الأيام بين واقعة البيع والإرسال.

بناء طلب الإرسال حين تصدر فواتيرك من قيود

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

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

وللصورة الأشمل عن النظام ومن يلتزم به، راجع مقال نظام الفوترة الوطني الإلكتروني.

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

ما ترتيب بناء طلب إرسال الفاتورة إلى نظام الفوترة الوطني؟

يبدأ الترتيب بتوليد ملف UBL 2.1 XML، ثم كتابة الوسم الجذري على سطر واحد، ثم حفظ الملف بترميز UTF-8، ثم ترميزه بترميز Base64، ثم وضعه في جسم JSON تحت المفتاح invoice، ثم إرساله بطريقة POST وقراءة قيمة EINV_STATUS.

هل أرسل رقم المستخدم والمفتاح السري داخل جسم JSON؟

يضعهما مثال الدليل في ص96 في ترويسة الطلب باسمي Client-Id وSecret-Key، ويترك الجسم للفاتورة المرمّزة وحدها، مع أن ص10 يعدّهما بين مكونات ملف JSON الثلاثة.

ماذا أحفظ لكل فاتورة بعد الإرسال؟

يطلب الإرشاد الخامس حفظ رقم الفاتورة ومعرّفها الفريد ورمز الاستجابة السريع وقيمة EINV_STATUS، ويطلب الإرشاد العاشر سجلًا كاملًا لكل إرسال ورد وإعادة إرسال.

هل أعيد بناء الطلب من البداية بعد رفض الفاتورة؟

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

هل يكفي الرمز 200 للحكم بقبول الفاتورة؟

يدل الرمز 200 على أن الطلب استُلم وعولج تقنيًا فقط. والحالة الحاسمة هي قيمة EINV_STATUS، ولا تُعدّ الفاتورة مقبولة إلا إذا عاد معها رمز الاستجابة السريع.

هل يمكن تجربة الطلب في بيئة اختبار قبل الإرسال الفعلي؟

لا يذكر الدليل التقني (الإصدار 1.5) بيئة تجريبية مفتوحة للمكلفين أو لمزودي البرامج، والعنوان الوحيد الذي يورده للإرسال هو https://backend.jofotara.gov.jo/core/invoices/.

المراجع

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