يظهر خطأ 504 في نظام الفوترة الوطني حين يرسل برنامجك المحاسبي فاتورة فيعود الطلب برمز 504 Gateway Timeout بدل رد يحمل حالة الفاتورة. ويعني هذا الرمز، بحسب الدليل التقني الصادر عن دائرة ضريبة الدخل والمبيعات، تعذّر الاتصال بموقع الفوترة الوطني، فالمشكلة في الطريق إلى النظام لا في محتوى الفاتورة.
والخطوة العملية باختصار أن تفحص الجدار الناري في شبكتك، ثم تعيد إرسال الفاتورة برقمها نفسه ومعرّفها الفريد (UUID) نفسه، دون توليد معرّف جديد. وإن كانت المحاولة الأولى قد وصلت فعلًا، فإعادة الإرسال بالقيمتين نفسيهما تعيد لك رمز الاستجابة السريع الأصلي ولا تُنشئ فاتورة ثانية.
يشرح هذا المقال ما يقوله الدليل عن هذا الرمز، ولماذا لا يعني رفض الفاتورة، وكيف تعيد الإرسال بأمان، وما الذي تحفظه في سجلاتك، ومتى تتواصل مع الدعم الفني للدائرة.
ما الذي يعنيه خطأ 504 في نظام الفوترة الوطني
يورد الدليل التقني (الإصدار 1.5، ص101) هذا الرمز ضمن قيم رمز الاستجابة الأكثر شيوعًا، ويكتب اسمه بصيغة «504 : Timout Getway» كما هي في الدليل، ثم يشرحه بهذا النص:
«وهذا الخطأ يدل على عدم القدرة على الاتصال في موقع الفوترة الوطني وتكون المشكلة إما في ال FireWall الخاص بالمكلف او من موقع الفوترة الرئيسي».
في النص موضعان للمشكلة لا ثالث لهما:
- الجدار الناري (FireWall) لدى المكلف. أي في شبكة المنشأة التي يخرج منها طلب الإرسال.
- موقع الفوترة الرئيسي. أي في جهة نظام الفوترة الوطني نفسه.
ولا يذكر الدليل سببًا ثالثًا، ولا يحدد طريقة للتمييز بين الموضعين. لذلك يبدأ الفحص من الموضع الذي تملك الوصول إليه، وهو شبكتك.
خطأ 504 لا يعني أن الفاتورة رُفضت
هذه أهم نقطة في الموضوع. فحكم الفاتورة في نظام الفوترة الوطني يحمله الحقل EINV_STATUS في رد النظام، وتوصي الدائرة بأن تحدد الحالة النهائية للفاتورة من هذا الحقل لا من رمز الاستجابة وحده. ولا تُعد الفاتورة مقبولة إلا إذا عاد عليها رمز الاستجابة السريع في الحقل EINV_QR.
أما رمز 504 فيعني أن الرد لم يصل أصلًا. فلا تملك حالة تقرؤها، ولا رمزًا تطبعه، ولا رسالة خطأ في EINV_MESSAGE تدلك على حقل بعينه. والنتيجة العملية أن مصير الفاتورة غير معروف حتى تقرأ ردًا فعليًا من النظام:
- لا تعاملها على أنها مقبولة، فلا رمز استجابة سريعًا عليها.
- ولا تعاملها على أنها مرفوضة، فلا حالة
NOT_SUBMITTEDولا قائمة أخطاء. - ولا تعدّل محتواها بحثًا عن خطأ، فالدليل لا يربط هذا الرمز بأي قيمة في ملف XML.
أين تبحث: الجدار الناري لديك أم موقع النظام
يرسل برنامجك الفاتورة بطلب إلى عنوان الواجهة البرمجية الذي يحدده الدليل التقني، وهو https://backend.jofotara.gov.jo/core/invoices/. فإذا منع الجدار الناري في شبكتك الاتصال بهذا العنوان، لم يصل الطلب إلى النظام.
ابدأ من جهتك بهذه الخطوات:
- اسأل مسؤول الشبكة عن قواعد الجدار الناري، وهل تسمح للجهاز الذي يعمل عليه برنامجك بالاتصال بعنوان الواجهة البرمجية أعلاه.
- اربط الخطأ بأي تغيير قريب في الشبكة، مثل تحديث إعدادات الجدار الناري أو نقل البرنامج إلى خادم آخر. وهذا استنتاج عملي من طبيعة السبب، لا خطوة يذكرها الدليل.
- دوّن وقت كل محاولة ونتيجتها في سجل الأخطاء، فهو ما ستحتاجه إن انتقلت المشكلة إلى الدعم الفني.
وإن لم تجد في شبكتك ما يمنع الاتصال، فالموضع الثاني الذي يذكره الدليل هو موقع الفوترة الرئيسي، وهذا خارج يدك. وفي الحالتين لا يتغير ما تفعله بالفاتورة نفسها، وهو موضوع القسم التالي.
الفرق بين خطأ 504 وخطأ 500 وخطأ 403
يضع الدليل التقني الرموز الثلاثة في صفحة واحدة، والفرق بينها يحدد أين تبحث. فأسباب رمزي 500 و403 في الدليل كلها بيانات في الطلب نفسه، أما رمز 504 فيدل على تعذّر الاتصال بالنظام، فلا تعرف منه إن كان الطلب قد وصل أم لا.
ولكل رمز من الرمزين الآخرين مقال مستقل. فإن وصلك رمز 500 فابدأ من مقال خطأ 500 في نظام الفوترة الوطني، وإن وصلك رمز 403 فمن مقال خطأ 403 في نظام الفوترة الوطني. أما رمز 400 ورسائل التحقق المرافقة له، مثل رسالة Total General Amount is Not Correct، فتعني أن النظام قرأ الفاتورة ووجد في قيمها خطأ.
إعادة الإرسال بعد خطأ 504: المعرّف نفسه لا معرّف جديد
يورد الدليل التقني عشر إرشادات تشغيلية، منها إرشاد بعنوان «معالجة الانقطاع» مضمونه أن تعيد المحاولة عند انتهاء المهلة أو فشل الاتصال دون توليد معرّف فريد جديد. ويؤكده إرشاد «إدارة إعادة الإرسال» الذي يوصي عند فشل الإرسال بإعادته برقم الفاتورة نفسه ومعرّفها الفريد نفسه، ويعلّل ذلك بتجنب إنشاء فاتورة جديدة أو تكرار البيانات.
والسبب في بنية النظام نفسها. فالنظام يعرّف الفاتورة بالرقم (cbc:ID) والمعرّف الفريد (cbc:UUID) معًا بوصفهما مفتاحًا رئيسيًا (Primary Key)، لا بالرقم وحده، والمعرّف يولّده برنامج المكلف لا النظام. وتنبّه الدائرة إلى أن توليد معرّف جديد عند إعادة الإرسال قد يؤدي إلى تكرار الفواتير.
وهنا تظهر قيمة القاعدة بعد خطأ 504 تحديدًا، لأنك لا تعرف مصير المحاولة الأولى. فإعادة الإرسال بالرقم والمعرّف نفسيهما تعطيك أحد ردين واضحين:
- إن كانت المحاولة الأولى قد وصلت وقُبلت، يعيد النظام الحالة
ALREADY_SUBMITTEDومعها رمز الاستجابة السريع الأصلي، ولا يُنشئ فاتورة ثانية. - وإن لم تكن قد وصلت، فهذه المحاولة هي التي تصل، ويعود عليها رد يحمل حالتها في
EINV_STATUS.
ولا يحدد الدليل عدد المحاولات ولا المدة بين محاولة وأخرى، فلا تبنِ على رقم لم تنشره الدائرة.
ماذا تحفظ وتسجّل أثناء الانقطاع
إعادة الإرسال بالمعرّف نفسه تفترض أنك حفظته قبل المحاولة الأولى. ولذلك يوصي الدليل التقني بحفظ أربع قيم لكل فاتورة لأغراض التتبع وإعادة الاسترجاع: الرقم، والمعرّف الفريد، ورمز الاستجابة السريع، والحالة.
وتتصل بهذه السجلات ثلاثة إرشادات أخرى:
- إدارة الأخطاء. سجّل الأخطاء بالتفصيل داخل نظامك، واعرض على المستخدم رسالة مبسطة.
- تتبع العمليات (Audit Trail). احتفظ بسجل كامل لعمليات الإرسال والردود وإعادات الإرسال.
- التوقيت الزمني. يوصي الدليل باستخدام «تنسيق زمني موحد (Standard Time Format) لتجنب اختلافات المعالجة بين الأنظمة»، فدوّن أوقات المحاولات في سجلك بهذا التنسيق الموحد.
وفي حالة رمز 504 يعني ذلك أن يظهر في سجلك أن الفاتورة أُرسلت في وقت معين ولم يعد عليها رد، ثم أُعيد إرسالها بالمعرّف نفسه، ثم الرد الذي عاد بعد ذلك.
وحين يعود الرد بعد إعادة الإرسال، حدّث القيم الأربع في سجلك من الرد نفسه. فإن عادت الحالة ALREADY_SUBMITTED فهي تأكيد أن المحاولة الأولى وصلت إلى النظام وقُبلت رغم انقطاع ردها، والرمز الذي يعود معها هو رمز الاستجابة السريع الأصلي. وهذه هي الطريقة الموثقة لاسترجاع رمز لم تحفظه، فاحفظه هذه المرة، ثم أظهره على الفاتورة، فالدليل يوجب إظهار رمز الاستجابة السريع على فاتورة البائع.
أما إن عادت الحالة NOT_SUBMITTED فقد وصلت الفاتورة هذه المرة ورُفضت، ويعود الرد برمز غير 200، ويأتي فيه رمز الاستجابة السريع والمعرّف الفريد فارغين، ويظهر سبب الرفض في EINV_MESSAGE. وعندها لم تعد المشكلة في الاتصال، بل في قيمة تذكرها الرسالة وتحتاج إلى تصحيح.
متى تتواصل مع الدعم الفني للدائرة
تواصل مع الدعم الفني حين تتأكد أن شبكتك لا تمنع الاتصال ويستمر الرمز نفسه. ويحدد الدليل التقني جهة التواصل بنصه: «لمزيد من الاستفسارات يمكن التواصل مع لجنة الدعم الفني لشؤون الفوترة في دائرة ضريبة الدخل والمبيعات على الرابط التالي: https://istd.gov.jo».
جهّز قبل التواصل:
- رقم الفاتورة ومعرّفها الفريد، ووقت كل محاولة إرسال.
- رمز الرد كما ظهر في سجل الأخطاء المفصل.
- ما فحصته في شبكتك ومع مسؤولها.
ولا ترسل المفتاح السري في أي مراسلة، فالدليل يوصي بحمايته وعدم تخزينه مكشوفًا داخل الشيفرة البرمجية. وينص الدليل كذلك على أن مسؤولية الحفاظ على سرية رقم المستخدم (Client ID) والمفتاح السري وعدم مشاركتهما تقع على عاتق المكلف، وأنه يتحمّل كامل المسؤولية عن أي استخدام غير مصرّح به.
كيف يتعامل قيود مع الفاتورة التي لم تُرسل
يبني تكامل قيود مع نظام الفوترة الوطني ملف الفاتورة ومعرّفها الفريد ويرسلهما دون تدخل يدوي، ويعرض نتيجة الإرسال أمامك:
- حالة كل فاتورة في لوحة الحالة. تعيد الدائرة حالة الفاتورة ورسالة الخطأ، ويعرضها قيود في لوحة الحالة.
- قائمة بما يحتاج إعادة إرسال. تعرض لوحة الحالة الفواتير التي لم تُرسل وتحتاج إلى إعادة إرسال.
- إعادة إرسال بالمعرّف نفسه. تعيد إرسال الفاتورة بمعرّف UUID نفسه.
وإعادة الإرسال في قيود خطوة تقوم بها أنت من لوحة الحالة. أما الاتصال بين شبكتك والنظام فيبقى خارج البرنامج، فإن كان الجدار الناري يمنعه فعلاجه في الشبكة.
أين تذهب بعد هذا المقال
- كل رموز الأخطاء في صورة واحدة: في مقال أخطاء نظام الفوترة الوطني.
- الصورة الكاملة للنظام وطريقة الربط: في مقال نظام الفوترة الوطني الإلكتروني في الأردن.
- الربط مع برنامج محاسبي متكامل: في صفحة قيود ونظام الفوترة الوطني.
فوترة إلكترونية ومحاسبة متكاملة في نظام واحد
قيود متكامل مع نظام الفوترة الوطني (JoFotara). تُصدر فاتورتك بالدينار الأردني من قيود فتُقيَّد في دفاترك تلقائيًا وتُرسل إلى النظام، وبعد قبولها يعود عليها رمز QR من دائرة ضريبة الدخل والمبيعات.
الأسئلة الشائعة
ما سبب خطأ 504 في نظام الفوترة الوطني؟
يردّه الدليل التقني للدائرة إلى عدم القدرة على الاتصال بالنظام، والمشكلة إما في الجدار الناري لدى المكلف وإما في موقع الفوترة الرئيسي.
هل يعني خطأ 504 أن فاتورتي رُفضت؟
لا يعني ذلك. يدل الرمز على أن الرد لم يصل، فتبقى حالة الفاتورة غير معروفة حتى تقرأ ردًا من النظام في الحقل EINV_STATUS.
هل أولّد معرّفًا فريدًا جديدًا عند إعادة الإرسال بعد خطأ 504؟
لا تولّد معرّفًا جديدًا. توصي الدائرة بإعادة المحاولة عند فشل الاتصال بالرقم نفسه والمعرّف الفريد نفسه، لأن توليد معرّف جديد قد يؤدي إلى تكرار الفاتورة.
ماذا لو كانت الفاتورة قد وصلت في المحاولة الأولى؟
يعيد النظام في هذه الحالة الحالة ALREADY_SUBMITTED ومعها رمز الاستجابة السريع الأصلي، بشرط أن تعيد الإرسال بالرقم والمعرّف الفريد نفسيهما.
هل أعدّل محتوى الفاتورة بعد خطأ 504؟
لا يربط الدليل التقني هذا الرمز بأي قيمة في ملف الفاتورة. فالخلل في الاتصال، ويبدأ علاجه من الشبكة لا من حقول الفاتورة.
متى أتواصل مع الدعم الفني للدائرة؟
تواصل معه حين تتأكد أن شبكتك لا تمنع الاتصال ويستمر الرمز. يحيل الدليل التقني إلى لجنة الدعم الفني لشؤون الفوترة في دائرة ضريبة الدخل والمبيعات عبر موقعها istd.gov.jo.
المراجع
- دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5.
