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

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

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

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

ما يقوله الدليل التقني 1.5 عن اختبار إرسال الفواتير إلى نظام الفوترة الوطني

يحدد الدليل التقني للإرسال عنوانًا واحدًا، هو POST https://backend.jofotara.gov.jo/core/invoices/. والعناوين الأخرى الواردة في الدليل هي موقع الدائرة نفسه. ولا يرد في الدليل عنوان ثانٍ للإرسال التجريبي، ولا بيانات ربط مخصصة للتجربة.

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

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

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

لماذا تُعدّ كل فاتورة ترسلها فاتورة حقيقية

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

يترتب على ذلك ثلاثة أمور تحكم أي تجربة.

1. الفاتورة المقبولة لا تُعدَّل. لا تُعدَّل الفاتورة بعد إصدارها، والتصحيح يكون بفاتورة إرجاع (إشعار دائن) على الكميات فقط، دون تجاوز الكمية المباعة.
2. هوية الفاتورة لا تُستعمل مرتين. المفتاح الأساسي للفاتورة هو رقمها في cbc:ID ومعرّفها الفريد في cbc:UUID معًا. فإذا أعدت إرسال الزوج نفسه بعد قبوله، عادت الحالة ALREADY_SUBMITTED مع رمز QR الأصلي، ولا تُنشأ فاتورة جديدة.
3. الإرسال يحمل بيانات ربط حقيقية. يحمل كل طلب رقم المستخدم والمفتاح السري في ترويسته، وهما مرتبطان بتسلسل مصدر دخل واحد للمنشأة.

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

ما تستطيع فحصه قبل الإرسال وما لا يظهر إلا بالإرسال

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

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

الاختبار المحلي على قواعد الدليل

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

اختبار البنية

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

• أن يبدأ الملف بالمقدمة التي يحددها الدليل، وأن يأتي وسم الفتح <Invoice> بكامل خصائصه في سطر واحد.
• أن يحمل الحقل cbc:ProfileID القيمة reporting:1.0 في كل فاتورة.
• أن يكون التاريخ بصيغة yyyy-mm-dd، كما في جميع أمثلة XML في الدليل.
• أن يُرمَّز الملف بترميز Base64 ويوضع في ملف JSON تحت المفتاح invoice.
• أن تحمل ترويسة الطلب Client-Id وSecret-Key وContent-Type: application/json، دون أي ترويسة أخرى منقولة من المثال البرمجي في الدليل.

والبند الأخير مهم. فالمثال البرمجي في الدليل يرسل ملف تعريف ارتباط (Cookie) خاصًا بجلسة لدى الدائرة، فلا تنقله إلى نظامك. ويشرح مقال معيار UBL 2.1 في نظام الفوترة الوطني البنية بتفصيل أكبر.

اختبار الحساب بأرقام الدليل

نقترح، وهو اقتراح من قيود، أن تستعمل الأرقام التي يحسبها الدليل في أمثلة الفواتير الجديدة نتائجَ متوقعة لمحرك الحساب في نظامك، فتدخل البنود نفسها، ثم تقارن ما يخرجه نظامك بما في الدليل. وهذه الأمثلة الثلاثة كما وردت.

• فاتورة دخل (ص19 إلى ص21). بندان، الأول 33 × 2 − 2 = 64، والثاني 10 × 5 − 5 = 45. المجموع قبل الخصم 116.000، والخصم 7.000، والمبلغ المستحق 109.000.
• فاتورة ضريبة مبيعات عامة (ص40 وص43 وص44). بند 33 × 2 − 2 = 64 بنسبة 7%، ضريبته 4.48 ومجموعه 68.48. وبند معفى 10 × 5 بتصنيف Z ونسبة 0%، مجموعه 50.00. المجموع قبل الخصم 116.000، والخصم 2.000، والضريبة 4.480، والمستحق 118.480.
• فاتورة ضريبة خاصة (ص69 إلى ص71). بند 10 × 50 − 5 = 495، وضريبة خاصة 10.00، وضريبة عامة (495 + 10) × 10% = 50.500، ومجموع البند 555.500.

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

استعمل الأرقام وحدها، لا ملفات XML المنشورة في الدليل. فأمثلة الدليل توضيحية، وفي بعضها عيوب نذكر منها ثلاثة. منها معرّفات فريدة غير سليمة الصيغة في ص14 وص98، وعلامات تنصيص مكررة في أمثلة الضريبة الخاصة. ومنها أن أمثلة فواتير الإرجاع لا تطابق فواتيرها الأصلية (ص24 وص25 وص47 وص74)، فلا تتخذها نتائج متوقعة لاختبار الإرجاع.

اختبار المعرّف الفريد وإعادة الإرسال

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

1. تأكد أن نظامك يحفظ رقم الفاتورة ومعرّفها الفريد قبل أول محاولة إرسال.
2. حاكِ داخل نظامك فشل الاتصال، ثم تأكد أن المحاولة التالية تحمل الرقم والمعرّف نفسيهما.
3. تأكد أن المعرّف بصيغة صحيحة، ولا تنسخ معرّفات أمثلة الدليل.

وتفصيل هذا الزوج في مقال المعرّف الفريد UUID في نظام الفوترة الوطني.

اختبار قراءة الرد

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

• EINV_STATUS هي الحالة الرسمية للفاتورة، وقيمها SUBMITTED وALREADY_SUBMITTED وNOT_SUBMITTED.
• EINV_RESULTS تضم حالة عامة (PASS أو ERROR) وثلاث مجموعات هي INFO وWARNINGS وERRORS. وكل عنصر فيها يحمل النوع والحالة وEINV_CODE وEINV_CATEGORY وEINV_MESSAGE.
• EINV_QR يحمل رمز QR للفاتورة المقبولة، ويأتي فارغًا مع الفاتورة المرفوضة.

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

أول إرسال حقيقي بأقل قدر من المخاطر

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

1. تأكد من بيانات الربط قبل الإرسال. راجع أن رقم المستخدم والمفتاح السري أُنشئا من «ربط الأجهزة» على تسلسل مصدر الدخل الذي ستصدر عليه الفواتير. وطريقة إنشائهما في مقال خطوات الربط التقني خطوة بخطوة.
2. اختر عملية بيع فعلية بسيطة. فاتورة جديدة محلية، ببند واحد أو بندين، ونوع يتفق مع تسجيل المنشأة لدى الدائرة. وأجّل الأنواع ذات الشروط الإضافية، كفواتير المناطق التنموية التي تشترط الرقم الضريبي للمشتري.
3. احفظ هوية الفاتورة قبل الإرسال. سجّل رقم الفاتورة ومعرّفها الفريد قبل أن يغادر الطلب نظامك.
4. اقرأ الرد كاملًا. انظر إلى EINV_STATUS وإلى وجود رمز QR، ولا تكتفِ برمز الحالة.
5. تحقق من الرمز. يتيح الدليل للمكلف التحقق من رمز QR بمسحه في تطبيق سند فقط، من خيار «التحقق من المستندات الرقمية». فإذا ظهرت عبارة «الوثيقة صحيحة» عرض التطبيق بيانات الفاتورة الأساسية المحمولة داخل الرمز.
6. وسّع بالتدريج. بعد قبول الفاتورة الأولى، أضف نوعًا جديدًا في كل مرة، كفاتورة الذمم أو فاتورة الإرجاع، حين تقع عملية من هذا النوع فعلًا، حتى تغطي الأنواع التي تصدرها منشأتك.

وفي كل خطوة تبقى القاعدة نفسها. الفاتورة التي تُقبل فاتورة صادرة فعلًا، فلا ترسل بيعًا لم يقع.

إذا رُفضت الفاتورة الأولى أو انقطع الاتصال

الأخطاء التي لا يكشفها الاختبار المحلي تظهر هنا، ولكل منها رمز يدل عليه. وهذه أبرز الحالات كما يصفها الدليل.

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

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

واقتراح من قيود أن تسجل كل محاولة في هذه المرحلة، بما فيها الطلب والرد ووقت كل منهما. فالإرشاد العاشر يطلب «تسجيل جميع العمليات (إرسال، استجابة، إعادة إرسال)»، وهذا السجل هو ما تعود إليه حين تسأل لماذا رُفضت فاتورة بعينها.

متى تتواصل مع دائرة ضريبة الدخل والمبيعات

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

ونقترح، وهو اقتراح من قيود، أن ترفق بسؤالك رقم الفاتورة ومعرّفها الفريد، ورمز الحالة، ونص EINV_MESSAGE كما وصل. ولا ترسل رقم المستخدم أو المفتاح السري في المراسلة، فالدليل يحمّل المكلف مسؤولية سريتهما، ويقول إنه «يتحمّل كامل المسؤولية عن أي استخدام غير مصرح به».

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

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

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

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

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

هل يوفّر نظام الفوترة الوطني بيئة اختبار للمطورين؟

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

هل أرسل فاتورة تجريبية إلى النظام لأتأكد من عمل الربط؟

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

ما الذي أستطيع اختباره قبل أول إرسال؟

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

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

اقرأ الحالة من الحقل EINV_STATUS لا من رمز الحالة وحده، وتأكد من وجود رمز QR في الحقل EINV_QR. وتستطيع التحقق من الرمز بمسحه في تطبيق سند من خيار «التحقق من المستندات الرقمية».

هل أستعمل ملفات XML المنشورة في الدليل التقني للاختبار؟

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

المراجع

• دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026، ص7 إلى ص10، وص19 إلى ص21، وص40 إلى ص44، وص69 إلى ص71، وص97 إلى ص107.
• الأدلة الإرشادية لنظام الفوترة الوطني على موقع دائرة ضريبة الدخل والمبيعات