نقطة النهاية ورؤوس الطلب في نظام الفوترة الوطني هي العنوان الذي يرسل إليه برنامجك الفاتورة، والترويسات التي ترافق كل طلب إليه. يحددها الدليل التقني الصادر عن دائرة ضريبة الدخل والمبيعات (الإصدار 1.5) في مثال واحد، ص96. العنوان واحد، والطريقة POST، والترويسات ثلاث، وجسم الطلب يحمل مفتاحًا واحدًا اسمه invoice.
هذا المقال مرجع سريع لمن يطوّر برنامجًا محاسبيًا أو نظام تخطيط موارد يرسل فواتيره إلى نظام الفوترة الوطني. يجمع ما يقوله الدليل عن عنوان الإرسال وعن كل ترويسة، ويشرح الفرق في كتابة اسمي الترويستين بين صفحة وأخرى، ويربط كل رمز خطأ بالجزء الذي يخصه من الطلب. ويذكر في آخره ما لا يحدده الدليل أصلًا. والمقال يصف بنية الطلب ولا يقدم شيفرة جاهزة، لأننا لم نرسل أي طلب تجريبي إلى النظام، ولا يذكر الدليل بيئة تجريبية مفتوحة للمكلفين.
نقطة النهاية ورؤوس الطلب في نظام الفوترة الوطني بنظرة واحدة
يجمع الجدول الآتي كل ما يحدده الدليل التقني لطلب إرسال الفاتورة. وكل قيمة فيه منقولة من مثال الإرسال في ص96 أو من وصف المسار في ص9 وص10.
مرِّر الجدول أفقيًا لعرض بقية الأعمدة
وترتيب هذه العناصر في بنية واحدة يكون على الشكل الآتي. هذا رسم توضيحي للبنية لا شيفرة للتنفيذ، والقيم بين القوسين الزاويين أماكن تضع فيها قيمك.
POST https://backend.jofotara.gov.jo/core/invoices/
Client-Id: <client-id>
Secret-Key: <secret-key>
Content-Type: application/json
{"invoice": "<base64-of-ubl-xml>"}
السطر الأول هو الطريقة والعنوان. والأسطر الثلاثة بعده هي رؤوس الطلب. وما بعد السطر الفارغ هو جسم الطلب، وفيه الفاتورة وحدها.
نقطة النهاية: العنوان الوحيد للإرسال في الدليل
يرسل مثال الدليل الفاتورة إلى العنوان https://backend.jofotara.gov.jo/core/invoices/ بطريقة POST. والعنوان يبدأ بالبروتوكول الآمن HTTPS، ومساره /core/invoices/ بشرطة مائلة في آخره كما هو مكتوب في المثال. وننصح، من جهتنا، بنسخه بالحرف كما ورد، لأن الدليل لا يذكر صيغة بديلة له.
وفي الدليل كله ثلاثة عناوين فقط. الأول موقع الدائرة الذي يحيل إليه لدليل الانضمام (ص6). والثاني عنوان الإرسال هذا (ص96). والثالث رابط لجنة الدعم الفني لشؤون الفوترة (ص104). فلا يوجد في الدليل عنوان ثانٍ للإرسال، ولا عنوان لبيئة تجريبية، ولا مسار لاستعلام عن فاتورة بعد إرسالها.
ويظهر في لقطات الدليل حساب اختبار داخلي لدى الدائرة. وهذا يدل على أن الدائرة تختبر النظام داخليًا، لكنه لا يوثق بيئة مفتوحة للمكلفين أو لمزودي البرامج. ولا يصف الدليل طريقة لإرسال طلب تجريبي إلى هذا العنوان.
رؤوس الطلب الثلاثة وما يحمله كل منها
يرسل مثال الدليل مع كل طلب ثلاث ترويسات، ولكل منها وظيفة واحدة.
Client-Idويحمل رقم المستخدم. يولّده النظام حين ينشئ المكلف ربطًا جديدًا من خيار «ربط الأجهزة»، ويظهر في قائمة الأجهزة المربوطة مع زر للنسخ.Secret-Keyويحمل المفتاح السري. يولّده النظام في الخطوة نفسها، ويظهر في الصف نفسه من القائمة.Content-Typeبالقيمةapplication/json. يعلن أن جسم الطلب بصيغة JSON، وقيمته ثابتة في المثال.
والقيمتان الأوليان مرتبطتان بتسلسل مصدر دخل واحد، هو التسلسل الذي يختاره المكلف عند إنشاء الربط. فكل زوج من رقم المستخدم والمفتاح السري يخص تسلسلًا واحدًا. أما طريقة إنشائهما خطوة بخطوة فمشروحة في مقال رقم المستخدم والمفتاح السري في نظام الفوترة الوطني، فلا نعيدها هنا.
ولا يذكر مثال الدليل ترويسة رابعة مطلوبة. والترويسة الإضافية الظاهرة في المثال ليست من متطلبات الطلب، ونعود إليها في قسم مستقل أدناه.
كتابة اسمي الترويستين: Client-Id أم Client_ID
يكتب الدليل اسمي الترويستين بصيغتين في مواضع مختلفة، ويحسن أن يعرف المطوّر ذلك قبل أن يحتار.
- في مثال الإرسال (ص96) يكتب الاسمين بشرطة وسطى، أي
Client-IdوSecret-Key. وهذا هو الموضع الوحيد في الدليل الذي يضعهما في طلب فعلي. - في جدول رموز الخطأ (ص101) وفي الإرشاد السابع (ص104) يكتبهما بشرطة سفلية، أي
Client_IDوSecret_Key، في سياق الشرح لا في سياق الطلب.
لذلك نكتب في هذا المقال الاسمين كما في مثال الإرسال، لأنه الموضع الذي يصف الطلب نفسه. ولا نقول إن النظام يقبل الصيغة الأخرى أو يرفضها، لأن الدليل لا يذكر ذلك، ولم نجرّب أيًا من الصيغتين على النظام.
«ثلاثة مكونات» في ص10 وأين يضعها مثال ص96
يقول الدليل في ص10 إن الفاتورة المجهّزة للإرسال بصيغة JSON تحتوي على ثلاثة مكونات، هي رقم المستخدم والمفتاح السري والفاتورة بصيغة XML. ويضيف أن القيمتين الأوليين تؤخذان من شاشة «ربط الأجهزة».
لكن مثال ص96 يوزع هذه المكونات على موضعين. فرقم المستخدم والمفتاح السري يذهبان في رؤوس الطلب، والفاتورة وحدها تذهب في جسمه. ومخطط مسار الإرسال في ص9 يوافق المثال، إذ يضع القيمتين تحت كلمة Header ويضع ملف XML تحت كلمة Body.
فالصحيح أن تقرأ «المكونات الثلاثة» على أنها ما يحمله الطلب كله، لا ما يحمله نص JSON وحده. ووضع رقم المستخدم والمفتاح السري داخل الجسم يخالف المثال الوحيد للطلب في الدليل.
جسم الطلب: مفتاح واحد اسمه invoice
جسم الطلب في مثال الدليل نص JSON فيه مفتاح واحد هو invoice، وقيمته ملف الفاتورة بصيغة UBL 2.1 XML بعد ترميزه بترميز Base64. ويضع المثال مكان القيمة نصًا مؤقتًا، ولا يضيف إلى الجسم أي مفتاح آخر.
وثلاث قواعد من الدليل تمس ما يدخل في هذه القيمة.
- يبدأ ملف XML بسطر التعريف بترميز UTF-8، ثم العنصر الجذر
Invoiceبفضاءات الأسماء، ثمcbc:ProfileIDبالقيمةreporting:1.0(ص10). - يُكتب وسم البداية للعنصر
Invoiceعلى سطر واحد، وإلا ورد الخطأInvalid Invoice Minification(ص102). - يقع الترميز على ملف XML وحده، ويبقى نص JSON نفسه مقروءًا.
والترميز يغيّر طريقة كتابة الملف لينتقل نصًا واحدًا، ولا يجعل محتواه سريًا. وخطوات تجهيز القيمة بالترتيب، وما تتجنبه أثناءها، مشروحة في مقال ترميز Base64 في نظام الفوترة الوطني.
ما لا تنسخه من مثال الإرسال في الدليل
مثال الدليل مكتوب بلغة C# بمكتبة RestSharp، والدليل يكتب اسمها «ResetSharp». وهو يبيّن شكل الطلب، لكنه ليس شيفرة جاهزة للنسخ، لثلاثة أسباب.
- ترويسة جلسة إضافية. يضيف المثال سطرًا يرسل ترويسة Cookie تحمل قيمة جلسة التُقطت من جلسة الدائرة نفسها. لا ترسل هذه الترويسة، فالطلب الذي يصفه الدليل يقوم على الترويسات الثلاث وحدها. وقد طمسنا هذا السطر في الصورة أعلاه.
- قيمة لمهلة الاتصال لا يشرحها الدليل. يضبط المثال مهلة الاتصال بقيمة دون أن يشرحها، والدليل لا يحدد مهلة موصى بها. فلا تنقل هذه القيمة إلى برنامجك على أنها توصية من الدائرة.
- قيمة مؤقتة في الجسم. النص الموضوع قيمةً للمفتاح
invoiceفي المثال مجرد علامة مكان، وليس ملف فاتورة.
وفي أمثلة XML الأخرى في الدليل عيوب معروفة، منها معرّفات فريدة (UUID) بصيغة غير سليمة في ص14 وص98. فالأمثلة توضيحية، وليست ملفات مجرّبة على النظام.
أي رمز خطأ يخص أي جزء من الطلب
يذكر الدليل في ص101 أكثر رموز الحالة ظهورًا ومعنى كل منها. ونرتبها هنا بحسب الجزء من الطلب الذي يشير إليه كل رمز. هذا الترتيب قراءة منا لنص الدليل، وليس تصنيفًا تضعه الدائرة.
وتفصيل كل رمز في مقاله. فالخطأ الذي يخص الترويستين مباشرة مشروح في مقال خطأ 403 في نظام الفوترة الوطني. وتعذّر الوصول إلى العنوان مشروح في مقال خطأ 504 في نظام الفوترة الوطني. وأسباب الرمز 500 مفصّلة في مقال خطأ 500 في نظام الفوترة الوطني. وقراءة رسائل الرمز 400 في مقال خطأ 400 في نظام الفوترة الوطني.
وتبقى ملاحظتان تخصان الترويستين. الأولى أن صحة رقم المستخدم والمفتاح السري لا تكفي وحدها، لأنهما مرتبطان بتسلسل مصدر دخل واحد. فإن أرسل البرنامج نوع فاتورة لا يتناسب مع الرقم الضريبي أو مع تسلسل مصدر الدخل، فالدليل يذكر لذلك رسالة الرمز 400 This user is not authorized to submit this type of invoice. والثانية أن الرمز 200 يعني أن الطلب استُلم وعولج تقنيًا فقط. فالحكم على الفاتورة يكون بقيمة EINV_STATUS في الرد، لا برمز الحالة وحده.
حماية قيم الترويستين في برنامجك
عنوان الإرشاد السابع من إرشادات الدائرة العشرة هو «الأمان». ويطلب حماية بيانات الربط، أي رقم المستخدم والمفتاح السري، وألا تُخزَّن مكشوفة داخل الشيفرة البرمجية. ويحمّل الدليل المكلف وحده مسؤولية سرية القيمتين، فهو «يتحمّل كامل المسؤولية عن أي استخدام غير مصرح به».
ومن هذا الإرشاد تنتج ممارسات عملية، نذكرها اقتراحًا من قيود لا نصًا من الدائرة.
- احفظ القيمتين في إعدادات محمية خارج الشيفرة، لا في ملف ضمن مستودع الشيفرة.
- لا تكتب قيمة المفتاح السري في سجلات الطلبات التي يحفظها برنامجك، واكتفِ بما يدل على التسلسل المستخدم.
- لا ترسل المفتاح السري في أي مراسلة، ولا في طلب دعم فني.
- إن كان لمنشأتك أكثر من تسلسل مصدر دخل، فاربط كل زوج من القيمتين بتسلسله في إعدادات البرنامج، حتى لا يُرسل طلب بزوج يخص تسلسلًا آخر.
وشرح الإرشادات العشرة كلها، وما يعنيه كل منها للأنظمة المرتبطة، في مقال الإرشادات العشر لنظام الفوترة الوطني.
ما لا يحدده الدليل التقني عن نقطة النهاية
يصف الدليل التقني (الإصدار 1.5) عنوانًا واحدًا وترويسات ثلاثًا وجسمًا بمفتاح واحد، ثم يسكت عن أمور يسأل عنها المطوّرون عادة. ولا نملأ هذا السكوت بافتراض.
- رقم إصدار في العنوان أو في ترويسة. لا يحمل العنوان رقم إصدار، ولا يذكر الدليل ترويسة تحدد إصدار الواجهة.
- حد لعدد الطلبات. لا يذكر الدليل حدًا لعدد الطلبات في الدقيقة أو في اليوم، ولا رسالة خاصة بتجاوز حد.
- بيئة تجريبية. لا يذكر الدليل عنوانًا تجريبيًا مفتوحًا للمكلفين أو لمزودي البرامج.
- مهلة الانتظار. لا يحدد الدليل مدة يُنتظر فيها الرد، ولا عدد مرات إعادة المحاولة ولا الفاصل بينها. وما يحدده هو أن إعادة المحاولة بعد انقطاع الاتصال تكون دون توليد معرّف فريد جديد.
- إرسال أكثر من فاتورة في طلب واحد. يحمل الجسم في المثال فاتورة واحدة تحت مفتاح واحد، ولا يصف الدليل طلبًا يجمع عدة فواتير.
فإن احتجت إلى جواب عن أي من هذه الأمور، فالمرجع هو الدائرة نفسها. ويحيل الدليل (ص104) إلى لجنة الدعم الفني لشؤون الفوترة في دائرة ضريبة الدخل والمبيعات عبر الرابط istd.gov.jo.
وللصورة الأشمل، فهذا المقال جزء من مسار أطول يبدأ بتسجيل المنشأة وينتهي بقراءة الرد. ويجمع مقال خطوات الربط التقني خطوة بخطوة هذا المسار كله. أما من يلتزم بالنظام ولماذا، ففي مقال نظام الفوترة الوطني الإلكتروني.
حين يرسل قيود فواتيرك إلى نظام الفوترة الوطني
إن كنت تستخدم تكامل قيود مع نظام الفوترة الوطني، فلا تحتاج إلى بناء الطلب بنفسك. يبني قيود ملف الفاتورة بصيغة UBL 2.1 مع معرّفها الفريد، ويرسله إلى نظام الفوترة الوطني دون تدخل يدوي، ولا يلزمك توقيع أو شهادة رقمية خاصة بك.
ويفحص قيود كل فاتورة على مستوى الحقول لحظة إنشائها، وهي الرقم الضريبي، ونوع المستند وطريقة الدفع، ونسبة ضريبة المبيعات العامة، واكتمال البنود، وينبهك بأي خطأ قبل إرسالها لتقليل حالات الرفض. وإن رُفضت فاتورة، تعيد الدائرة حالة الفاتورة ورسالة الخطأ، ويعرضها قيود في لوحة الحالة، فتعيد إرسالها بالمعرّف الفريد (UUID) نفسه بعد تصحيح السبب.
فوترة إلكترونية ومحاسبة متكاملة في نظام واحد
قيود متكامل مع نظام الفوترة الوطني (JoFotara). تُصدر فاتورتك بالدينار الأردني من قيود فتُقيَّد في دفاترك تلقائيًا وتُرسل إلى النظام، وبعد قبولها يعود عليها رمز QR من دائرة ضريبة الدخل والمبيعات.
الأسئلة الشائعة
ما عنوان نقطة النهاية في نظام الفوترة الوطني؟
يرسل مثال الدليل التقني الفاتورة بطريقة POST إلى العنوان https://backend.jofotara.gov.jo/core/invoices/، وهو العنوان الوحيد للإرسال في الدليل (الإصدار 1.5).
ما رؤوس الطلب التي يرسلها البرنامج مع كل فاتورة؟
يرسل البرنامج ثلاث ترويسات، هي Client-Id بقيمة رقم المستخدم، وSecret-Key بقيمة المفتاح السري، وContent-Type بالقيمة application/json.
هل أكتب Client-Id أم Client_ID؟
يكتب مثال الإرسال في ص96 الاسمين بشرطة وسطى، ويكتبهما جدول الأخطاء والإرشاد السابع بشرطة سفلية. نتبع المثال لأنه يصف الطلب نفسه، والدليل لا يذكر هل يقبل النظام الصيغة الأخرى.
هل يوضع رقم المستخدم والمفتاح السري داخل جسم JSON؟
يذكرهما الدليل ضمن مكونات الإرسال الثلاثة في ص10، لكن مثاله في ص96 يرسلهما في رؤوس الطلب، ويترك الجسم للفاتورة وحدها تحت المفتاح invoice.
هل توجد نقطة نهاية تجريبية لاختبار الطلب؟
لا يذكر الدليل التقني (الإصدار 1.5) عنوانًا تجريبيًا مفتوحًا للمكلفين أو لمزودي البرامج، ولا يصف طريقة لإرسال طلب تجريبي إلى عنوان الإرسال.
هل يكفي الرمز 200 لأعرف أن الفاتورة قُبلت؟
لا يكفي، فالرمز 200 يعني أن الطلب استُلم وعولج تقنيًا. والحكم على الفاتورة يكون بقيمة EINV_STATUS في الرد، كما يطلب الإرشاد الرابع.
المراجع
- دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026.
