يظهر خطأ 400 في نظام الفوترة الوطني حين يرسل برنامجك المحاسبي فاتورة فيعود الرد برمز 400 Bad Request بدل رمز الاستجابة السريع. وما يميز هذا الرمز أن دائرة ضريبة الدخل والمبيعات تنص على أن توضيح الخطأ يصل مكتوبًا في حقل EINV_MESSAGE داخل ملف الاستجابة.
الجواب المباشر هو أن خطأ 400 يعني قيمة غير صحيحة في ملف XML للفاتورة، وأن مكان السبب هو عنصر الخطأ داخل EINV_RESULTS. اقرأ حقل EINV_MESSAGE فيه حرفيًا، وطابقه مع الرسائل التي يوثقها الدليل التقني، ثم أصلح القيمة وأعد الإرسال بالرقم والمعرّف الفريد نفسيهما.
يشرح هذا المقال كيف تقرأ ملف الاستجابة عنصرًا عنصرًا، وما يحمله كل حقل في عنصر الخطأ، ثم يضع أمامك فهرسًا بالرسائل التي يوثقها الدليل لرمز 400 مع سطر واحد لكل رسالة. أما شرح كل رسالة بالتفصيل فله مقال مستقل في مركز الأخطاء، والصورة العامة لرموز الرفض كلها في مقال أخطاء نظام الفوترة الوطني.
ما الذي يعنيه خطأ 400 في نظام الفوترة الوطني
يصف الدليل التقني للربط مع نظام الفوترة الوطني (الإصدار 1.5، ص101) هذا الرمز بنص قصير.
«هذا يدل على وجود خطأ في القيم المبعوثة من خلال ملف ال XML ويتم توضيح الخطأ في ال EINV_MESSAGE في ملف ال Response».
في هذا النص معلومتان تبنيان طريقة العمل كلها.
- الخطأ في قيم الملف. رمز 400 يخص ما كتبه برنامجك داخل ملف الفاتورة، من مجاميع وأنواع ونسب وحقول، لا الوصول إلى النظام ولا بيانات الاعتماد.
- السبب مكتوب في الرد. الدليل يحيلك إلى حقل
EINV_MESSAGEفي ملف الاستجابة، فلا تحتاج إلى التخمين قبل أن تقرأه.
ويوثق الدليل بعد هذا التعريف مجموعة من الرسائل يقدمها بعبارة «ومن أهمها»، أي أنها الأهم لا أنها القائمة الكاملة. لذلك إن وصلتك رسالة ليست في الفهرس أدناه، فاقرأ نصها كما هو واعرضه على الدعم الفني للدائرة بدل أن تقيسه على رسالة تشبهه.
أين يقع سبب الرفض في ملف الاستجابة
يعيد النظام بعد كل إرسال ملف استجابة بصيغة JSON. ويحدد الدليل التقني ستة أغراض لهذا الملف، منها أن تعرف هل قُبلت الفاتورة أم رُفضت، وأن تطّلع على أسباب الخطأ، وأن يعالج نظامك النتيجة آليًا. والجدول التالي يجمع العناصر التي تهمك عند قراءة خطأ 400.
القاعدة التي يكررها الدليل في إرشاداته واضحة، وهي أن تقرّر حالة الفاتورة من EINV_STATUS لا من رمز الاستجابة. ولا تُعد الفاتورة مستلمة ومقبولة إلا إذا عاد رمز الاستجابة السريع في EINV_QR، وهذا الرمز يجب أن يُطبع على فاتورة البائع. أما شرح حالات EINV_STATUS نفسها فخارج هذا المقال، ومكانه مقالات مركز الأخطاء الخاصة بها.
تشريح عنصر واحد داخل EINV_RESULTS
يحمل EINV_RESULTS حقلًا عامًا اسمه status قيمته PASS أو ERROR، ثم ثلاث قوائم. وكل عنصر في أي قائمة منها، سواء كان معلومة أو تحذيرًا أو خطأ، يتكون من خمسة حقول ثابتة. وفهم هذه الحقول الخمسة هو كل ما تحتاجه لقراءة أي رد.
الصورة أعلاه مثال الدليل لرد في حالة ALREADY_SUBMITTED، وفيه عنصر واحد في قائمة INFO وقائمتان فارغتان. وقيم الفاتورة الموقعة ورمز الاستجابة فيه توضيحية، والمعرّف الفريد الظاهر فيه غير صالح الصياغة، فلا تنسخ أيًا منها إلى نظامك. والجدول التالي يضع حقول العنصر الخمسة بجانب قيمها في عنصر النجاح الذي يورده الدليل.
ويورد الدليل كذلك مثالًا لعنصر خطأ في فاتورة مرفوضة، يحمل فيه EINV_CODE القيمة totalGeneralTaxesAmount، وEINV_CATEGORY القيمة invoice، وEINV_MESSAGE النص Total General Amount is Not Correct.
ومن هذا الجدول تخرج ثلاث ملاحظات عملية.
EINV_MESSAGEهو النص الذي تطابقه. الدليل يوثق الرسائل بنصها، فهو المرجع الذي تبحث به في الفهرس وفي الدليل وفي مراسلة الدعم الفني.- احفظ
EINV_CODEوEINV_CATEGORYمع الرسالة. سجل الأخطاء الكامل يختصر على المبرمج وعلى الدعم الفني تحديد موضع الخلل، والدليل يوصي بتسجيل الأخطاء بالتفصيل. - الحكم على الفاتورة لا يؤخذ من عنصر واحد. مهما كانت العناصر في القوائم الثلاث، يبقى الحكم لحقل
EINV_STATUS.
INFO وWARNINGS وERRORS: أي قائمة تقرأ أولًا
عند خطأ 400 ابدأ بقائمة ERRORS، فهي التي تحمل سبب الرفض. ولأن ERRORS قائمة لا حقل واحد، فاقرأ عناصرها كلها قبل أن تعدّل شيئًا، وأصلح ما فيها دفعة واحدة.
أما قائمة INFO ففي أمثلة الدليل تحمل نتيجة فحص التوافق مع معيار UBL 2.1. وأما قائمة WARNINGS فتظهر فارغة في أمثلة الدليل، ولم نجد فيه ما يشرح أثر التحذير على قبول الفاتورة. لذلك لا تبنِ في نظامك منطقًا يفترض معنى معينًا للتحذير، واكتفِ بتسجيل ما يصل فيها كما هو.
فهرس رسائل خطأ 400 الموثقة في الدليل التقني
هذه الرسائل التي يوردها الدليل التقني تحت رمز 400 (ص101 وص102)، بنصها كما يكتبها الدليل. وبعض الرسائل مكتوب في المصدر بإملاء غير دقيق، مثل Bayer بدل Buyer وarear بدل area، وقد أبقيناها كما وردت في الدليل، وابحث دائمًا بالنص الذي يصلك في الرد كما هو.
مرِّر الجدول أفقيًا لعرض بقية الأعمدة
وفي رسالة General tax percentage must be zero تحديدًا تنبيه، فنص الدليل يقول إن الفئة عند 0% «يجب ان يكون … قيمته O وليس S». لكن جدول الفئات في الدليل نفسه (ص42) يعطي للنسبة الصفرية فئتين صحيحتين، Z للمعفى وO للخاضع لنسبة الصفر. فالخطأ الذي تعالجه هذه الرسالة هو استخدام S مع نسبة 0%، لا استخدام Z لسلعة معفاة.
ويتناول مركز الأخطاء كل رسالة من هذه الرسائل في مقال مستقل يشرح أسبابها وطريقة فحصها، منها مقال رسالة Total General Amount is Not Correct، ومقالات رسائل This user is not authorized وBayer name is missing وThe ID number must be unique وGeneral tax percentage must be zero ورسالة الرقم الضريبي للمشتري في المناطق التنموية. وإن كان الرفض يعود إلى حقل إلزامي ناقص، فراجع مقال الحقول الإجبارية والاختيارية في نظام الفوترة الوطني.
من الرسالة إلى الإصلاح: خمس خطوات منظمة
هذه الخطوات مبنية على الإرشادات العشر التي يختم بها الدليل التقني، مرتبة على مسار قراءة خطأ 400 من وصول الرد إلى إعادة الإرسال.
- اقرأ
EINV_STATUSقبل أي شيء. هو الذي يحسم أن الفاتورة لم تُقبل، ويؤكد ذلك غياب رمز الاستجابة السريع منEINV_QR. - افتح قائمة ERRORS واجمع عناصرها كلها. انسخ من كل عنصر الحقول الخمسة كما هي، دون ترجمة أو تلخيص.
- طابق نص
EINV_MESSAGEمع الفهرس. حدد الحقل أو الحساب الذي تشير إليه الرسالة، وافحص قيمته في ملف XML الفعلي الذي أُرسل، لا في شاشة الإعدادات. - سجّل الخطأ بالتفصيل واعرض على المستخدم رسالة مبسطة. هذه إحدى إرشادات الدليل، وسجل الأخطاء المفصل هو ما يحتاجه المبرمج والدعم الفني لاحقًا. واحتفظ كذلك برقم الفاتورة ومعرّفها الفريد وحالتها لأغراض التتبع.
- أعد الإرسال بالرقم نفسه والمعرّف الفريد (UUID) نفسه. يوصي الدليل عند فشل الإرسال بإعادته بالقيمتين ذاتهما، ويحذر من أن توليد معرّف جديد عند الإعادة قد يؤدي إلى تكرار الفواتير.
وتوصي إرشادات الدليل كذلك بالتحقق من المجاميع والضرائب والرقم الضريبي ورقم المشتري والحقول الإلزامية قبل الإرسال، وهي القيم نفسها التي تدور حولها عدة رسائل في الفهرس أعلاه. وإن استمر الرفض بعد الإصلاح، فالدليل يحيل إلى لجنة الدعم الفني لشؤون الفوترة في دائرة ضريبة الدخل والمبيعات عبر موقعها istd.gov.jo، ومعك الحقول الخمسة لعنصر الخطأ ورقم الفاتورة ومعرّفها الفريد.
ما الفرق بين خطأ 400 والرموز المجاورة
يكفيك سطر لكل رمز كي لا تبحث في المكان الخطأ. رمز 400 خطأ في قيم ملف XML وسببه مكتوب في EINV_MESSAGE. ورمز خطأ 403 في نظام الفوترة الوطني يعني رقم مستخدم أو مفتاحًا سريًا غير صحيح. ورمز خطأ 500 في نظام الفوترة الوطني يردّه الدليل أولًا إلى الرقم الضريبي أو تسلسل مصدر الدخل، وبدرجة أقل إلى رقم المستخدم والمفتاح السري، أو إلى نسبة ضريبة ليست ضمن نسب الضريبة المعتمدة لدى الدائرة. ورمز 504 يعني تعذّر الوصول إلى النظام من جهة جدار الحماية لدى المكلف أو من جهة موقع الدائرة، وله مقال مستقل في مركز الأخطاء.
وانتبه إلى تقاطع واحد بين 400 و500. فتسلسل مصدر الدخل يظهر في أسباب خطأ 500، ويظهر كذلك في شرح رسالة This user is not authorized to submit this type of invoice برمز 400. والفيصل هو الرمز ونص الرسالة معًا، فإن وصلتك هذه الرسالة برمز 400 فمكان العلاج تناسب نوع الفاتورة مع رقمك الضريبي وتسلسل مصدر الدخل.
كيف يساعدك قيود في التعامل مع خطأ 400
رسائل رمز 400 تخص قيمًا داخل ملف الفاتورة، وهنا يفيد أن يتولى برنامجك المحاسبي بناء الملف بدلًا منك. يعمل تكامل قيود مع نظام الفوترة الوطني على هذه الطبقة على النحو الآتي.
- فحص قبل الإرسال. يفحص قيود كل فاتورة على مستوى الحقول لحظة إنشائها، أي الرقم الضريبي ونوع المستند وطريقة الدفع ونسبة ضريبة المبيعات العامة واكتمال البنود، وينبهك بأي خطأ قبل إرسالها إلى نظام الفوترة الوطني لتقليل حالات الرفض.
- حالة كل فاتورة ورسالة خطئها أمامك. تعيد الدائرة حالة الفاتورة ورسالة الخطأ، ويعرضها قيود في لوحة الحالة.
- قائمة بما يحتاج إعادة إرسال. تعرض لوحة الحالة الفواتير التي لم تُرسل وتحتاج إلى إعادة إرسال.
- إعادة إرسال بالمعرّف نفسه. تعيد إرسال الفاتورة بمعرّف UUID نفسه، كما توصي إرشادات الدليل.
والفحص المسبق تنبيه لا ضمان. فهو يغطي الحقول المذكورة، ويبقى قبول الفاتورة لنظام الفوترة الوطني وحده.
أين تذهب بعد هذا المقال
- الصورة العامة لرموز الرفض: في مقال أخطاء نظام الفوترة الوطني: لماذا تُرفض فاتورتك وكيف تصلحها.
- أول رسائل رمز 400 تفصيلًا: في مقال رسالة Total General Amount is Not Correct.
- كيف يعمل النظام وكيف تربط منشأتك به: في مقال نظام الفوترة الوطني الإلكتروني في الأردن.
- تكامل قيود مع النظام: في صفحة قيود ونظام الفوترة الوطني.
فوترة إلكترونية ومحاسبة متكاملة في نظام واحد
قيود متكامل مع نظام الفوترة الوطني (JoFotara). تُصدر فاتورتك بالدينار الأردني من قيود فتُقيَّد في دفاترك تلقائيًا وتُرسل إلى النظام، وبعد قبولها يعود عليها رمز QR من دائرة ضريبة الدخل والمبيعات.
الأسئلة الشائعة
ما معنى خطأ 400 في نظام الفوترة الوطني؟
يعني الرمز بحسب الدليل التقني لدائرة ضريبة الدخل والمبيعات وجود خطأ في القيم المرسلة في ملف XML للفاتورة، ويصل توضيح الخطأ في حقل EINV_MESSAGE داخل ملف الاستجابة.
أين أجد سبب رفض الفاتورة برمز 400؟
تجده في قائمة ERRORS داخل EINV_RESULTS. فكل عنصر فيها يحمل الحقول type وstatus وEINV_CODE وEINV_CATEGORY وEINV_MESSAGE، والأخير هو النص المقروء لسبب الرفض.
هل أحكم على الفاتورة من رمز 400 وحده؟
لا تحكم عليها من الرمز وحده، فالدليل يوصي بتقرير حالة الفاتورة من EINV_STATUS. ولا تُعد الفاتورة مقبولة إلا إذا عاد عليها رمز الاستجابة السريع في EINV_QR.
هل رسائل خطأ 400 في الدليل هي كل الرسائل الممكنة؟
يقدم الدليل رسائله بعبارة «ومن أهمها»، فهي الأهم لا القائمة الكاملة. وإن وصلتك رسالة غير موثقة فاحتفظ بنصها كما هو وتواصل مع الدعم الفني للدائرة.
هل أولّد معرّفًا فريدًا جديدًا بعد إصلاح خطأ 400؟
لا تولّد معرّفًا جديدًا. يوصي الدليل بإعادة الإرسال بالرقم نفسه والمعرّف الفريد نفسه، لأن توليد معرّف جديد عند الإعادة قد يؤدي إلى تكرار الفواتير.
لماذا تبدو بعض الرسائل مكتوبة بإملاء خاطئ؟
كُتبت بعض الرسائل في الدليل التقني نفسه بإملاء غير دقيق، مثل Bayer name is missing. وقد أبقيناها في الفهرس كما وردت في الدليل، وابحث دائمًا بالنص الذي يصلك في الرد كما هو.
المراجع
- دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026.
