يظهر خطأ 500 في نظام الفوترة الوطني حين ترسل فاتورة من برنامجك المحاسبي فيعود الرد برمز 500 Internal Server Error بدل رمز الاستجابة السريع. الاسم يوحي بعطل في خادم الدائرة، لكن الدليل التقني الصادر عن دائرة ضريبة الدخل والمبيعات يردّه إلى بيانات يرسلها المكلف نفسه.
الجواب المباشر: ابدأ بالرقم الضريبي وتسلسل مصدر الدخل، ثم رقم المستخدم والمفتاح السري، ثم نسبة الضريبة في كل بند. هذا هو ترتيب الدائرة نفسه، والخطوة الأولى في مقدمة أسبابها.
يشرح هذا الدليل كل سبب من هذه الأسباب، وكيف تفحصه في ملف الفاتورة وفي حسابك، ثم كيف تعيد الإرسال دون أن تكرر الفاتورة، ومتى تتواصل مع الدعم الفني للدائرة. أما بقية الرموز (400 و403 و504) فلها شرح مستقل نحيلك إليه في موضعه.
ما الذي يعنيه خطأ 500 في نظام الفوترة الوطني
يمر كل إرسال بمسار واحد يرسمه الدليل التقني. يبني برنامجك ملف الفاتورة بصيغة XML، ثم يرمّزه بترميز Base64 داخل ملف JSON، ويرسله إلى النظام مع رقم المستخدم والمفتاح السري في ترويسة الطلب. فإما أن تُقبل الفاتورة ويعود عليها رمز الاستجابة السريع، وإما أن تعود قائمة أخطاء.
رمز 500 واحد من نتائج هذا المسار. ويصف الدليل التقني (الإصدار 1.5، ص101) أسبابه بهذا النص:
«خطأ في الرقم الضريبي أو تسلسل مصدر الدخل وبدرجة أقل يكون الخطأ في ال Client_ID أو ال Secret_Key ويمكن ان تكون نسبة الضريبة الموجودة في ملف ال XML ليست ضمن نسب الضريبة المعتمدة لدى الدائرة».
في النص ثلاث مجموعات من الأسباب، بترتيب يستحق أن تحترمه في الفحص:
- الرقم الضريبي أو تسلسل مصدر الدخل. السبب الأول في ترتيب الدائرة.
- رقم المستخدم (Client ID) أو المفتاح السري (Secret Key). سبب أقل حدوثًا، والدليل يربط خطأ هاتين القيمتين في العادة برمز 403.
- نسبة ضريبة خارج القائمة المقبولة. قيمة في حقل النسبة لا يقبلها النظام.
ولا يذكر الدليل سببًا خارج هذه المجموعات الثلاث، فلا تضيّع الوقت في البحث عن غيرها قبل أن تستنفدها.
وللتمييز السريع بين الرموز المجاورة، يكفيك سطر لكل منها. رمز 400 يعني خطأ في قيم ملف XML، ويصل سببه مكتوبًا في حقل EINV_MESSAGE. ورمز 403 يعني رقم مستخدم أو مفتاحًا سريًا غير صحيح. ورمز 504 يعني تعذّر الوصول إلى النظام من الأساس. والشرح الكامل لكل رمز منها في دليل أخطاء نظام الفوترة الوطني.
قبل الفحص: هل يتكرر الرفض في كل فاتورة أم في فاتورة واحدة؟
هذا السؤال يختصر نصف الطريق، وجوابه مستنتج من بنية الملف نفسه لا من نص الدائرة.
الرقم الضريبي للبائع وتسلسل مصدر الدخل لا يتغيران من فاتورة إلى أخرى، ويُرسلان في كل فاتورة. ورقم المستخدم والمفتاح السري يُرسلان مع كل طلب كذلك. فإذا كان الخطأ في أي منها، رُفضت كل فاتورة ترسلها بالرمز نفسه.
أما نسبة الضريبة فتتغير من بند إلى آخر ومن صنف إلى آخر. فإذا مرّت أغلب فواتيرك وتعثرت فاتورة بعينها، فابدأ بنسب البنود في تلك الفاتورة. وإذا رُفض كل شيء منذ لحظة معينة، فابحث عمّا تغيّر في إعدادات الربط أو بيانات المنشأة في تلك اللحظة.
الفحص الأول: الرقم الضريبي
يُرسل الرقم الضريبي للبائع في كل فاتورة ضمن بيانات البائع، في العنصر cac:AccountingSupplierParty، وتحديدًا في الحقل cbc:CompanyID. ولا يحدد نص الدليل أي رقم ضريبي يقصد، لذلك ابدأ برقم البائع لأنه يُرسل في كل فاتورة مقترنًا بتسلسل مصدر الدخل، ثم انتقل إلى رقم المشتري إن كانت فاتورتك تحمله.
قائمة الفحص:
- طابق الرقم المرسل مع رقمك لدى الدائرة. الرقم الضريبي أحد حقول الدخول إلى نظام الفوترة الوطني نفسه، فقارن الرقم الذي تدخل به إلى النظام بالرقم الذي يضعه برنامجك في ملف الفاتورة.
- افحص الرقم في ملف الفاتورة الفعلي لا في شاشة الإعدادات. ما يظهر في إعدادات البرنامج قد لا يكون ما وصل إلى الملف، خاصة بعد ترحيل بيانات أو تغيير في المنشأة.
- إن كنت تدير أكثر من منشأة، فتأكد أن الفاتورة خرجت برقم المنشأة التي تملك بيانات الاعتماد المستخدمة في الإرسال.
- راجع رقم المشتري إن أرسلته. يُرسل رقم المشتري بنوع معرّف
TN، ويقبل الأرقام فقط، ويصبح إلزاميًا في فاتورة المناطق التنموية.
الفحص الثاني: تسلسل مصدر الدخل
تسلسل مصدر الدخل حقل إلزامي في كل فاتورة تُرسل عبر الواجهة البرمجية، ويُرسل في العنصر cac:SellerSupplierParty داخل الحقل cbc:ID. ويختاره المكلف بنفسه عند إنشاء بيانات الربط في خيار «ربط الأجهزة»، ثم يولّد النظام رقم المستخدم والمفتاح السري مرتبطين به.
وهذه النقطة هي مفتاح التشخيص: كل زوج من بيانات الاعتماد مرتبط بتسلسل مصدر دخل واحد. لذلك فالمرجع الذي تقارن به التسلسل المرسل هو التسلسل الظاهر بجانب بيانات الاعتماد التي يستخدمها برنامجك.
قائمة الفحص:
- افتح قائمة الأجهزة المربوطة في خيار «ربط الأجهزة»، فبحسب لقطات الدليل التقني يظهر بجانب كل رقم مستخدم تسلسل مصدر الدخل المرتبط به.
- قارن ذلك التسلسل بالقيمة المرسلة في ملف الفاتورة، حرفًا بحرف.
- إن كان لمنشأتك أكثر من مصدر دخل، فتأكد أن كل فاتورة تخرج بتسلسل المصدر الذي ربطت به بيانات اعتمادها، لا بتسلسل مصدر آخر.
- تأكد أن للمنشأة تسلسل مصدر دخل فعالًا أصلًا. يذكر دليل الأسئلة والأجوبة غياب التسلسل الفعال سببًا لتعذّر التسجيل، والحل الذي يورده طلب خدمة داخلية من نوع «فتح مصدر دخل ومجموعة جديدة».
وانتبه إلى أن تعارض التسلسل مع نوع الفاتورة له رسالة أخرى برمز 400، هي This user is not authorized to submit this type of invoice. فإن وصلتك هذه الرسالة فأنت أمام رمز 400 لا 500، ومكان علاجه نوع الفاتورة المرسلة.
الفحص الثالث: رقم المستخدم والمفتاح السري
يضع الدليل هذا السبب «بدرجة أقل»، والسبب واضح: الخطأ في هاتين القيمتين يظهر في العادة برمز 403. لذلك لا تبدأ به، لكن لا تتجاوزه إن انتهى الفحصان الأولان دون نتيجة.
يرسل برنامجك القيمتين في ترويسة الطلب لا داخل ملف الفاتورة، تحت الاسمين Client-Id وSecret-Key. وقائمة الفحص هنا قصيرة:
- طابق القيمتين مع قائمة الأجهزة المربوطة، فلكل قيمة منهما زر نسخ بجانبها في تلك القائمة.
- تأكد أن الرقم والمفتاح من السطر نفسه. الخلط بين رقم مستخدم من ربط ومفتاح سري من ربط آخر يعطي زوجًا غير صحيح وإن كانت كل قيمة منهما صحيحة وحدها.
- تأكد أن التسلسل المرتبط بهذا الزوج هو التسلسل المرسل في الفاتورة، وهي النقطة نفسها من الفحص الثاني من الجهة المقابلة.
- احفظ القيمتين في مكان محمي. يوصي الدليل بعدم تضمينهما مكشوفتين في الشيفرة، ويحمّل المكلف وحده مسؤولية أي استعمال غير مصرح به.
أما طريقة الحصول على هاتين القيمتين من خيار «ربط الأجهزة» فمشروحة في دليل رقم المستخدم والمفتاح السري في نظام الفوترة الوطني، وطريقة إدخالهما في برنامجك في دليل خطوات الربط التقني خطوة بخطوة.
الفحص الرابع: نسبة ضريبة خارج القائمة المقبولة
هذا السبب الوحيد الذي يسكن داخل بنود الفاتورة. فكل بند في فاتورة ضريبة المبيعات العامة يحمل نسبة الضريبة في الحقل cbc:Percent، ولهذا الحقل قائمة قيم مغلقة.
القيم التي تقبلها الواجهة البرمجية في هذا الحقل، كما يوردها الدليل التقني لفواتير البيع الجديدة (ص42)، هي: 0 و1 و2 و3 و4 و5 و7 و8 و10 و16.
هذه قائمة تحقق تقنية تقبلها الواجهة عند الإرسال، وليست جدول نسب ضريبة المبيعات العامة في الأردن. فالسؤال عن النسبة التي تنطبق على سلعتك يجيب عنه قانون الضريبة العامة على المبيعات، لا هذه القائمة. ووجود قيمة فيها لا يعني أن نسبة بهذا المقدار مفروضة على سلعة ما.
قائمة الفحص:
- افحص نسبة كل بند في الفاتورة المرفوضة، لا نسبة البند الأول وحده. بند واحد خارج القائمة يكفي لرفض الفاتورة كلها.
- تأكد أن النسبة مأخوذة من إعداد الصنف لا محسوبة. إن كان برنامجك يستخرج النسبة بقسمة مبلغ الضريبة على المبلغ الخاضع لها، فقد يُنتج التقريب قيمة كسرية لا تطابق أي قيمة في القائمة.
- لا تضع الضريبة الخاصة في حقل النسبة. الضريبة الخاصة في الدليل «قيمة يتم إدخالها دون عمليات حسابية»، وتُرسل مبلغًا في كتلة مستقلة بلا حقل نسبة، قبل كتلة الضريبة العامة.
- راجع فواتير الإرجاع بعناية. تورد صفحات فاتورة الإرجاع في الدليل القائمة دون الصفر (1 و2 و3 و4 و5 و7 و8 و10 و16)، ولا يشرح الدليل هذا الفرق.
وإن كنت تصدر فاتورة دخل لأن منشأتك غير مسجلة في ضريبة المبيعات، فهذا السبب لا يخصك أصلًا. فبنود فاتورة الدخل لا تحمل كتلة ضريبة ولا حقل نسبة، فيبقى أمامك الرقم الضريبي وتسلسل مصدر الدخل وبيانات الاعتماد.
كيف تقرأ رد النظام بعد خطأ 500
رمز الاستجابة في بروتوكول HTTP يخبرك بما جرى للطلب تقنيًا، أما حكم الفاتورة نفسها فيحمله الحقل EINV_STATUS. ولا تُعد الفاتورة مقبولة إلا إذا عاد عليها رمز الاستجابة السريع في الحقل EINV_QR، وهذا الرمز يجب أن يُطبع على فاتورة البائع.
فالقاعدة العملية بعد خطأ 500 بسيطة: الفاتورة لم تُقبل، ولا تسجّلها في دفاترك على أنها صادرة عبر النظام قبل أن يعود عليها رمز. وشرح حالات EINV_STATUS الثلاث وبقية حقول الرد موجود في مقال قيود عن أخطاء نظام الفوترة الوطني ورموزها.
ويوصي الدليل كذلك بأن تسجل الأخطاء بالتفصيل داخل نظامك، وأن تعرض على المستخدم رسالة مبسطة. سجل الخطأ المفصل هو ما ستحتاجه إن وصلت إلى مرحلة التواصل مع الدعم الفني.
إعادة الإرسال بعد الإصلاح: الرقم نفسه والمعرّف نفسه
بعد أن تصلح السبب، أعد إرسال الفاتورة برقمها نفسه ومعرّفها الفريد (UUID) نفسه. هذه إحدى الإرشادات العشر التي يوردها الدليل التقني: عند فشل الإرسال أعد الإرسال بالقيمتين ذاتهما، ولا تولّد معرّفًا جديدًا.
والسبب أن النظام يعرّف الفاتورة بالرقم والمعرّف معًا لا بالرقم وحده. والمعرّف الفريد يولّده برنامج المكلف لا النظام، والدائرة تنبّه إلى أن عدم الاحتفاظ بالمعرّف وتوليد غيره قد يؤدي إلى تكرار الفواتير عند إعادة الإرسال.
وتحميك هذه القاعدة أيضًا حين لا تعرف مصير المحاولة الأولى. فإن كانت الفاتورة قد قُبلت فعلًا ثم أعدت إرسالها بالرقم والمعرّف نفسيهما، يعيد النظام الحالة ALREADY_SUBMITTED ومعها رمز الاستجابة السريع الأصلي، ولا يُنشئ فاتورة ثانية.
ولكي تتمكن من ذلك، احفظ لكل فاتورة أربع قيم يوصي الدليل بتخزينها: الرقم، والمعرّف الفريد، ورمز الاستجابة السريع، والحالة. ويضيف إليها الاحتفاظ بسجل كامل للإرسالات والردود وإعادات الإرسال.
متى تتواصل مع الدعم الفني للدائرة
تواصل مع الدعم الفني حين تنهي الفحوص الأربعة كلها دون أن تجد خللًا، ويستمر الرمز نفسه. ويحدد الدليل التقني جهة التواصل بنصه: «لمزيد من الاستفسارات يمكن التواصل مع لجنة الدعم الفني لشؤون الفوترة في دائرة ضريبة الدخل والمبيعات على الرابط التالي: https://istd.gov.jo».
قبل أن تتواصل، جهّز ما يختصر المراسلة:
- رقم الفاتورة ومعرّفها الفريد ووقت الإرسال.
- رمز الرد وأي رسالة عادت معه، من سجل الأخطاء المفصل.
- الرقم الضريبي وتسلسل مصدر الدخل المرسلين في الملف.
- ما فحصته فعلًا من الفحوص الأربعة، حتى لا تبدأ المراسلة من الصفر.
ولا ترسل المفتاح السري في أي مراسلة. فالدليل يجعل سريته مسؤوليتك وحدك.
كيف يساعدك قيود في تجنب خطأ 500
أغلب أسباب خطأ 500 بيانات تُضبط مرة واحدة ثم تتكرر في كل فاتورة. وهنا يفيد أن يتولى برنامجك المحاسبي بناء الملف بدلًا منك. يعمل تكامل قيود مع نظام الفوترة الوطني على هذه الطبقة كما يلي:
- فحص قبل الإرسال. يفحص قيود كل فاتورة على مستوى الحقول لحظة إنشائها: الرقم الضريبي، ونوع المستند وطريقة الدفع، ونسبة ضريبة المبيعات العامة، واكتمال البنود، وينبهك بأي خطأ قبل إرسالها لتقليل حالات الرفض.
- حالة كل فاتورة أمامك. تعيد الدائرة حالة الفاتورة ورسالة الخطأ، ويعرضها قيود في لوحة الحالة.
- قائمة بما يحتاج إعادة إرسال. تعرض لوحة الحالة الفواتير التي لم تُرسل وتحتاج إلى إعادة إرسال.
- إعادة إرسال بالمعرّف نفسه. تعيد إرسال الفاتورة بمعرّف UUID نفسه، فلا تتكرر في سجلك.
والفحص المسبق تنبيه لا ضمان. فهو يغطي الحقول الأربعة المذكورة، ويبقى قبول الفاتورة لنظام الفوترة الوطني وحده.
أين تذهب بعد هذا الدليل
- بقية رموز الرفض: 400 و403 و504 ورسائل التحقق، في أخطاء نظام الفوترة الوطني: لماذا تُرفض فاتورتك وكيف تصلحها.
- الصورة الكاملة للنظام: كيف يعمل وكيف تربط منشأتك به، في نظام الفوترة الوطني الإلكتروني في الأردن.
- بعد قبول الفاتورة: لماذا لا تُعدَّل وما البديل، في تعديل فاتورة صادرة في نظام الفوترة الوطني.
- كل أدلة النظام في مكان واحد: مركز نظام الفوترة الوطني في الأردن.
فوترة إلكترونية ومحاسبة متكاملة في نظام واحد
قيود متكامل مع نظام الفوترة الوطني (JoFotara). تُصدر فاتورتك بالدينار الأردني من قيود فتُقيَّد في دفاترك تلقائيًا وتُرسل إلى النظام، وبعد قبولها يعود عليها رمز QR من دائرة ضريبة الدخل والمبيعات.
الأسئلة الشائعة
ما سبب خطأ 500 في نظام الفوترة الوطني؟
يذكر الدليل التقني للدائرة ثلاثة أسباب: خطأ في الرقم الضريبي أو تسلسل مصدر الدخل أولًا، ثم بدرجة أقل خطأ في رقم المستخدم أو المفتاح السري، أو نسبة ضريبة في ملف XML ليست ضمن القيم التي يقبلها النظام.
هل يعني خطأ 500 أن خادم الدائرة معطّل؟
اسم الرمز يوحي بذلك، لكن الدليل التقني يردّه إلى بيانات في الطلب المرسل، ولا يذكر عطلًا في الخادم بين أسبابه. أما تعذّر الوصول إلى النظام نفسه فيظهر برمز 504.
ما الفرق بين خطأ 500 وخطأ 403؟
رمز 403 يخص رقم المستخدم والمفتاح السري. ورمز 500 يبدأ في العادة من الرقم الضريبي أو تسلسل مصدر الدخل، وقد يعود بدرجة أقل إلى بيانات الاعتماد، أو إلى نسبة ضريبة خارج القائمة.
هل قائمة النسب المقبولة هي نسب ضريبة المبيعات العامة في الأردن؟
لا. القائمة (0 و1 و2 و3 و4 و5 و7 و8 و10 و16) هي القيم التي تقبلها الواجهة البرمجية في حقل النسبة. أما النسبة التي تنطبق على سلعتك فيحددها قانون الضريبة العامة على المبيعات.
هل أولّد معرّفًا فريدًا جديدًا عند إعادة الإرسال؟
لا. توصي الدائرة بإعادة الإرسال بالرقم نفسه والمعرّف الفريد نفسه. فتوليد معرّف جديد عند إعادة الإرسال قد يؤدي إلى تكرار الفاتورة.
متى أتواصل مع الدعم الفني للدائرة؟
حين تفحص الأسباب كلها دون نتيجة ويستمر الرمز. يحيل الدليل التقني إلى لجنة الدعم الفني لشؤون الفوترة في دائرة ضريبة الدخل والمبيعات عبر موقعها istd.gov.jo.
المراجع
- دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026.
- دائرة ضريبة الدخل والمبيعات، دليل الأسئلة والأجوبة لنظام الفوترة الوطني، 2026.
