يظهر خطأ 403 في نظام الفوترة الوطني حين يرسل برنامجك المحاسبي فاتورة فيعود الرد برمز 403 Forbidden بدل رمز الاستجابة السريع. ولهذا الرمز في الدليل التقني الصادر عن دائرة ضريبة الدخل والمبيعات سبب واحد مكتوب، هو خطأ في رقم المستخدم (Client ID) أو المفتاح السري (Secret Key).
فالإصلاح لا يبدأ من بنود الفاتورة ولا من مبالغها، بل من القيمتين اللتين يرسلهما برنامجك مع كل طلب. يشرح هذا المقال أين تُرسل القيمتان، وكيف تطابقهما مع قائمة «ربط الأجهزة»، وكيف تميّز الرمز 403 من الرمزين 500 و504، وكيف تحمي القيمتين، ومتى تتواصل مع الدعم الفني للدائرة.
ما الذي يعنيه خطأ 403 في نظام الفوترة الوطني
يورد الدليل التقني للربط (الإصدار 1.5، ص101) الرموز الأكثر ظهورًا في حقل Response Status Code، ويصف الرمز 403 بالجملة الآتية.
«وهذا الخطأ يدل على خطأ في ال Client_ID أو ال Secret_Key».
هذا كل ما يقوله الدليل عن الرمز. فلا يذكر له سببًا ثانيًا، ولا يربطه ببنود الفاتورة أو مبالغها أو نوعها. لذلك فمكان البحث محدد من البداية، وهو القيمتان اللتان يتعرّف بهما النظام على برنامجك.
تتولد القيمتان في حساب المكلف على نظام الفوترة الوطني، من خيار «ربط الأجهزة» في الشاشة الرئيسية للمستخدم الرئيسي. وخطوات إنشائهما مشروحة في مقال رقم المستخدم والمفتاح السري في نظام الفوترة الوطني، فلا نكررها هنا.
أين يرسل برنامجك رقم المستخدم والمفتاح السري
يذكر الدليل التقني (ص10) ثلاثة مكونات لملف الطلب، هي رقم المستخدم والمفتاح السري والفاتورة بصيغة XML. لكن مثال الشيفرة في الدليل نفسه (ص96) يضع القيمتين الأوليين خارج ملف JSON، في ترويسة الطلب (Header)، ومعهما ترويسة ثالثة لنوع المحتوى.
Client-Idوقيمتها رقم المستخدم.Secret-Keyوقيمتها المفتاح السري.Content-Type: application/jsonوتحدد نوع المحتوى.
أما جسم الطلب فيحمل الفاتورة وحدها، بصيغة XML مرمّزة بترميز Base64 تحت الاسم invoice. ويذهب الطلب إلى العنوان https://backend.jofotara.gov.jo/core/invoices/، والمسار الكامل من بناء الفاتورة إلى عودة الرد مشروح في مقال نظام الفوترة الوطني الإلكتروني في الأردن.
لذلك لن تجد القيمتين إن فتحت ملف XML للفاتورة. ابحث عنهما في إعدادات الربط في برنامجك، أو في سجل الطلبات المرسلة إن كان برنامجك يحتفظ به.
ولاحظ أن نص الخطأ في الدليل يكتب الاسمين Client_ID وSecret_Key بشرطة سفلية، بينما يسميهما مثال الشيفرة في الترويسة Client-Id وSecret-Key. والمثال هو ما يمثل شكل الطلب نفسه. وهو مع ذلك مثال توضيحي، فلا تنسخه كما هو في برنامجك، وقد طمسنا منه سطرًا لا ننصح بنسخه.
كيف تطابق القيمتين مع قائمة «ربط الأجهزة»
المرجع الذي تقارن به ما يرسله برنامجك هو قائمة الأجهزة المربوطة في خيار «ربط الأجهزة». تعرض القائمة كل ربط في صف مستقل، بأعمدة هي المستخدم، وحالة المستخدم، ورقم المستخدم، والمفتاح السري، وتسلسل مصدر الدخل. وبجانب كل من القيمتين زر نسخ.
تجري المطابقة في أربع خطوات.
- حدّد الصف الذي يعتمد عليه برنامجك. كل زوج من القيمتين مرتبط بتسلسل مصدر دخل واحد، فإن كان لمنشأتك أكثر من ربط، فابدأ بالصف الذي يطابق تسلسله التسلسل المرسل في فواتيرك.
- قارن رقم المستخدم المخزن في برنامجك بالرقم الظاهر في ذلك الصف، حرفًا بحرف.
- قارن المفتاح السري بالطريقة نفسها، ومن الصف نفسه. فالقيمتان تتولدان معًا لكل ربط، لذلك خذهما من صف واحد ولا تجمع رقم مستخدم من صف ومفتاحًا سريًا من صف آخر.
- إن وجدت فرقًا، فانسخ القيمة من القائمة بزر النسخ وضعها في إعدادات برنامجك مكان القيمة القديمة، ثم أعد إرسال الفاتورة. فالنسخ بالزر يجنّبك أخطاء الكتابة اليدوية.
وفي القائمة عمود «حالة المستخدم» فيه مفتاح تشغيل وإيقاف، لكن الدليل التقني لا يشرح أثره، ولا يذكره بين أسباب الرمز 403. فلا تبنِ عليه استنتاجًا، ولا تغيّره على ربط يعمل قبل أن تسأل الدائرة.
الفرق بين خطأ 403 وخطأ 500 وخطأ 504
الرموز الثلاثة متجاورة في الصفحة نفسها من الدليل التقني (ص101)، ويختلف مكان البحث في كل منها.
في الجدول ملاحظة تستحق الانتباه. فخطأ رقم المستخدم أو المفتاح السري لا يظهر برمز 403 وحده، إذ يذكره الدليل كذلك بين أسباب الرمز 500 «بدرجة أقل». فإن وصلك الرمز 500 فابدأ بالرقم الضريبي وتسلسل مصدر الدخل كما يرتبها الدليل، والتفاصيل في مقال خطأ 500 في نظام الفوترة الوطني. وإن وصلك الرمز 403 فالدليل يحصر السبب في القيمتين.
أما الرمز 504 فيصفه الدليل بتعذّر الاتصال بالنظام، لا بخطأ في بيانات الطلب، فمكان البحث فيه الاتصال نفسه لا القيمتان. والشرح الموسّع لرموز الرفض ورسائل التحقق في مقال أخطاء نظام الفوترة الوطني.
ما مصير الفاتورة بعد خطأ 403
الرمز في بروتوكول HTTP يخبرك بما جرى للطلب تقنيًا، أما حكم الفاتورة فيحمله الحقل EINV_STATUS بحسب إرشادات الدليل. ولا تُعد الفاتورة مقبولة إلا إذا عاد عليها رمز الاستجابة السريع في الحقل EINV_QR، فإن عاد الرد برمز 403 دون رمز استجابة سريع، فالفاتورة لم تُقبل.
بعد تصحيح القيمتين، أعد إرسال الفاتورة برقمها نفسه ومعرّفها الفريد (UUID) نفسه، ولا تولّد معرّفًا جديدًا. هذه إحدى الإرشادات العشر في الدليل التقني (ص104)، والدائرة تنبّه إلى أن توليد معرّف جديد عند إعادة الإرسال قد يؤدي إلى تكرار الفواتير.
ويوصي الدليل كذلك بتسجيل الأخطاء بالتفصيل داخل نظامك، وعرض رسالة مبسطة على المستخدم. فاحتفظ بالرد الذي حمل الرمز 403 كما وصل، لأنك ستحتاجه إن تواصلت مع الدعم الفني.
حماية رقم المستخدم والمفتاح السري
يجعل الدليل التقني سرية القيمتين مسؤولية المكلف وحده، فهو «يتحمّل كامل المسؤولية عن أي استخدام غير مصرح به» (ص8). ومن الإرشادات العشر في الدليل (ص104) إرشاد بعنوان «الأمان»، مضمونه حماية رقم المستخدم والمفتاح السري وعدم تخزينهما مكشوفين داخل الشيفرة البرمجية.
وتزداد أهمية هذه القاعدة أثناء معالجة الخطأ 403، لأن التشخيص يغري بتداول القيمتين. ومن هنا ثلاث ممارسات عملية.
- لا ترسل المفتاح السري في رسالة أو بريد. يكفي أن تذكر اسم المستخدم الظاهر في عمود «المستخدم» ليُعرف الصف المقصود.
- اطمس القيمتين في أي لقطة شاشة تشاركها لطلب المساعدة، كما في الصور أعلاه.
- راجع ما يحفظه سجل برنامجك. إن كان برنامجك يسجّل الطلبات المرسلة، فتأكد أن السجل لا يحفظ المفتاح السري مكشوفًا.
إذا تطابقت القيمتان واستمر الخطأ
لا يصف الدليل التقني في إصداره 1.5 إجراءً لإعادة توليد رقم المستخدم أو المفتاح السري، ولا إجراءً لإعادة ضبطهما. فإن طابقت القيمتين مع القائمة وصححتهما وأعدت الإرسال، ثم استمر الرمز 403، فالمرجع الدعم الفني للدائرة. ويحدد الدليل (ص104) جهة التواصل بهذا النص.
«لمزيد من الاستفسارات يمكن التواصل مع لجنة الدعم الفني لشؤون الفوترة في دائرة ضريبة الدخل والمبيعات على الرابط التالي: https://istd.gov.jo».
جهّز قبل التواصل ما يختصر المراسلة.
- رقم الفاتورة ومعرّفها الفريد ووقت الإرسال.
- نص الرد كاملًا كما سجله برنامجك.
- اسم المستخدم في صف الربط الذي يعتمد عليه برنامجك، دون المفتاح السري.
- ما فحصته فعلًا من خطوات المطابقة الأربع.
خطأ 403 حين يرسل قيود فواتيرك
إن كنت تستخدم تكامل قيود مع نظام الفوترة الوطني، فرقم المستخدم والمفتاح السري هما ما يحتاجه منك برنامج قيود المحاسبي من شاشة «ربط الأجهزة». بعدها يبني قيود ملف الفاتورة ويرسله دون تدخل يدوي.
وإن رُفضت فاتورة، تعيد الدائرة حالة الفاتورة ورسالة الخطأ، ويعرضها قيود في لوحة الحالة. وتظهر الفاتورة هناك ضمن الفواتير التي لم تُرسل وتحتاج إلى إعادة إرسال، فتعيد إرسالها بمعرّفها الفريد (UUID) نفسه بعد تصحيح السبب.
للدقة، يفحص قيود كل فاتورة قبل إرسالها على مستوى الحقول، وهي الرقم الضريبي، ونوع المستند وطريقة الدفع، ونسبة ضريبة المبيعات العامة، واكتمال البنود، وينبهك بأي خطأ فيها لتقليل حالات الرفض. ورقم المستخدم والمفتاح السري ليسا من هذه الحقول، فتصحيحهما يبقى بمطابقتهما مع قائمة «ربط الأجهزة» كما سبق.
فوترة إلكترونية ومحاسبة متكاملة في نظام واحد
قيود متكامل مع نظام الفوترة الوطني (JoFotara). تُصدر فاتورتك بالدينار الأردني من قيود فتُقيَّد في دفاترك تلقائيًا وتُرسل إلى النظام، وبعد قبولها يعود عليها رمز QR من دائرة ضريبة الدخل والمبيعات.
الأسئلة الشائعة
ما سبب خطأ 403 في نظام الفوترة الوطني؟
يربطه الدليل التقني لدائرة ضريبة الدخل والمبيعات بخطأ في رقم المستخدم (Client_ID) أو المفتاح السري (Secret_Key)، ولا يذكر له سببًا آخر.
أين أجد القيمتين الصحيحتين لأطابق بهما؟
تجدهما في قائمة الأجهزة المربوطة ضمن خيار «ربط الأجهزة» في حساب المستخدم الرئيسي، وبجانب كل قيمة منهما زر نسخ.
هل يظهر خطأ المفتاح السري برمز غير 403؟
يذكر الدليل التقني خطأ رقم المستخدم أو المفتاح السري كذلك بين أسباب الرمز 500، لكن بدرجة أقل من الرقم الضريبي وتسلسل مصدر الدخل.
هل أعيد توليد المفتاح السري عند ظهور الخطأ؟
لا يصف الدليل التقني إجراءً لإعادة توليد القيمتين. طابق القيمتين المخزنتين مع القائمة أولًا، فإن استمر الخطأ فتواصل مع لجنة الدعم الفني لشؤون الفوترة في الدائرة.
ما الفرق بين خطأ 403 وخطأ 504؟
يشير الرمز 403 إلى خطأ في رقم المستخدم أو المفتاح السري، ويشير الرمز 504 إلى تعذّر الاتصال بنظام الفوترة الوطني بسبب جدار الحماية لدى المكلف أو موقع النظام نفسه.
هل أولّد معرّفًا فريدًا جديدًا عند إعادة الإرسال؟
توصي الدائرة بإعادة الإرسال بالرقم نفسه والمعرّف الفريد نفسه، لأن توليد معرّف جديد قد يؤدي إلى تكرار الفاتورة.
المراجع
- دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026.
