متطلبات المطوّر قبل برمجة الربط بنظام الفوترة الوطني هي البيانات والقرارات التي يجمعها مبرمج النظام المحاسبي أو نظام تخطيط موارد المؤسسات من المكلف قبل أن يكتب سطرًا واحدًا من شيفرة الربط. فملف الفاتورة الذي يُرسل إلى دائرة ضريبة الدخل والمبيعات يحمل قيمًا لا يملكها المطوّر، مثل الرقم الضريبي وتسلسل مصدر الدخل ونوع التسجيل الضريبي، وبعضها يقرره تسجيل المكلف لدى الدائرة لا اختيار المطوّر.
يجمع هذا المقال تلك المتطلبات في سبعة بنود مرتبة، ولكل بند ما يذكره الدليل التقني للربط (الإصدار 1.5) وما يترتب عليه في تصميم نظامك. ويقف المقال عند مرحلة الجمع والتصميم، أما بناء الطلب نفسه وفحص الملف قبل إرساله فلكل منهما مقال مستقل نشير إليه في موضعه. ولا يتضمن المقال شيفرة قابلة للتشغيل، بل خطوات وبنية مقترحة للبيانات.
لماذا تبدأ متطلبات المطوّر قبل برمجة الربط بنظام الفوترة الوطني بالجمع لا بالبرمجة
يُبنى الربط على نموذج الاعتماد الفوري، فالفاتورة تُرسل إلى النظام ويعود ردّه بحالتها ورمز QR إن قُبلت. وبعض شروط القبول لا يظهر في ملف XML نفسه، بل في سجلات الدائرة عن المكلف. فالدليل التقني يذكر أن رمز 500 يعود عند خطأ في الرقم الضريبي أو تسلسل مصدر الدخل، ثم «بدرجة أقل» عند خطأ في رقم المستخدم أو المفتاح السري، أو عند نسبة ضريبة ليست ضمن النسب المعتمدة لدى الدائرة (ص101). ويذكر رسالة رفض تظهر حين يرسل المكلف نوع فاتورة لا يتناسب مع رقمه الضريبي أو تسلسل مصدر الدخل الخاص به.
هذه الأخطاء لا يكشفها اختبار الشيفرة وحده، لأن مصدرها قيمة إعداد خاطئة أو افتراض عن تسجيل المكلف. ولذلك تبدأ المتطلبات بسؤال المكلف وتوثيق إجاباته، ثم يأتي التصميم. والبنود السبعة التالية هي ما يحتاج المطوّر إلى معرفته قبل البدء.
- الرقم الضريبي واسم البائع كما هو مسجل.
- كل تسلسل مصدر دخل فعّال، وزوج بيانات ربط لكل تسلسل.
- عائلة الفاتورة التي يسمح بها تسجيل المكلف.
- أنواع التعامل التي يمارسها المكلف فعلًا، وطرق الدفع.
- صلاحية سعر المستهلك، هل مُنحت أم لا.
- أنواع هوية المشتري التي سيجمعها نظامك.
- تصميم التخزين لما يُرسل وما يعود.
البند الأول: الرقم الضريبي واسم البائع كما هو مسجل
يملأ نظامك في كل فاتورة بيانات البائع في العنصر cac:AccountingSupplierParty، وفيه رمز الدولة JO، والرقم الضريبي للبائع في cbc:CompanyID، واسم البائع في cbc:RegistrationName كما هو مسجل لدى الدائرة. لذلك اطلب من المكلف الرقم الضريبي والاسم المسجل كما يظهران في سجلاته لدى الدائرة، ولا تعتمد على الاسم التجاري المستخدم في التسويق.
والرقم الضريبي هو أيضًا أول حقل في شاشة الدخول إلى نظام الفوترة، مع اسم المستخدم وكلمة المرور. ومن خلال هذا الحساب يصل المكلف إلى خيار «ربط الأجهزة» الذي تُنشأ منه بيانات الربط في البند التالي.
البند الثاني: كل تسلسل مصدر دخل فعّال وبيانات ربطه
تسلسل مصدر الدخل قيمة إجبارية في كل فاتورة تُرسل عبر الواجهة البرمجية، ويضعها نظامك في العنصر cac:SellerSupplierParty/cbc:ID. وقد شرحنا معناه وأين يجده المكلف في مقال تسلسل مصدر الدخل في نظام الفوترة الوطني. أما هنا فالمطلوب أن تجمع من المكلف قائمة بكل تسلسل فعّال سيصدر منه فواتير، وأن تعرف أي فرع أو نشاط أو نقطة إصدار في نظامك يقابل كل تسلسل.
وتنشأ بيانات الربط من حساب المكلف لا من نظامك. فبحسب الدليل التقني يدخل المكلف إلى نظام الفوترة، ويختار «ربط الأجهزة»، ويُدخل اسم مستخدم ويختار تسلسل مصدر الدخل، فيولّد النظام رقم المستخدم والمفتاح السري. أي أن المكلف يختار التسلسل، والنظام يولّد بيانات الربط فقط. وخطوات إنشائهما من الشاشة مفصلة في مقال رقم المستخدم والمفتاح السري في نظام الفوترة الوطني.
ويترتب على ذلك ثلاثة أمور في تصميمك.
- زوج بيانات لكل تسلسل. ترتبط بيانات الربط بتسلسل مصدر دخل واحد، فإذا أصدر المكلف فواتير من تسلسلين احتاج نظامك إلى زوجين، وإلى قاعدة واضحة تحدد أي زوج يُرسل مع أي فاتورة.
- تطابق التسلسل مع بيانات الربط. رسالة الرفض الخاصة بنوع الفاتورة غير المصرح به قد تنتج عن عدم تناسب النوع مع تسلسل مصدر الدخل، لا مع الرقم الضريبي وحده. فاجعل التسلسل وبيانات ربطه إعدادًا واحدًا في نظامك لا حقلين منفصلين.
- حماية بيانات الربط. يطلب الإرشاد السابع حماية رقم المستخدم والمفتاح السري وعدم وضعهما مكشوفين في الشيفرة. ويضع الدليل مسؤولية سريتهما على المكلف، إذ ينص على أنه «يتحمّل كامل المسؤولية عن أي استخدام غير مصرح به». وفي دليل الانضمام تنبيه صريح للمكلف «تأكد من حفظ بيانات الربط في مكان آمن وعدم مشاركتها مع أحد.»
وإذا لم يجد المكلف تسلسل مصدر دخل فعّالًا أصلًا، فالحل الرسمي في دليل الأسئلة والأجوبة طلب خدمة داخلية من نوع «فتح مصدر دخل ومجموعة جديدة» من موقع الخدمات الإلكترونية للدائرة. وهذا إجراء على المكلف أن ينهيه قبل أن يبدأ الربط، لا شيء يحله المطوّر.
وقبل أن يضغط المكلف «ربط الأجهزة» اعرف منه هل يصدر فواتير من المنصة عبر مستخدمين فرعيين. فدليل الأسئلة والأجوبة يذكر أن عدم ظهور «تنظيم فاتورة» للمستخدم الفرعي سببه النقر على خيار ربط الأجهزة، وأن طلب فك الربط «فقط لمن ليس لديه نظام محاسبي ويكون قام بالربط عن طريق الخطأ». ويذكر الدليل نفسه أن المنصة تتيح إرجاع الفواتير المرسلة عبرها في جميع الحالات، سواء تم الربط أم لا.
البند الثالث: عائلة الفاتورة التي يسمح بها التسجيل
يعرض الدليل التقني نماذج ملف XML حسب نوع المكلف، وهي ثلاث عائلات لكل منها نموذج إنشاء ونموذج إرجاع، وهي فاتورة الدخل لغير المسجلين في ضريبة المبيعات، وفاتورة المبيعات للمسجلين فيها، وفاتورة المبيعات الخاصة للمسجلين في الضريبة الخاصة.
وتظهر العائلة في الرقم الثالث من الخاصية name في العنصر cbc:InvoiceTypeCode، فالرقم 1 للدخل و2 للمبيعات العامة و3 للمبيعات الخاصة. والملف يعلن العائلة لكنه لا يقررها، فالذي يقررها تسجيل المكلف لدى الدائرة. وإذا أعلن الملف عائلة لا تتناسب مع التسجيل عادت الرسالة This user is not authorized to submit this type of invoice.
اسأل المكلف إذن عن تسجيله، ودوّن الإجابة إعدادًا ثابتًا في نظامك بدل أن تستنتجها من نوع البنود. وتختلف بنية الملف بين العائلات اختلافًا يؤثر في التصميم.
- فاتورة الدخل لا تحمل كتلة ضريبة على البنود ولا مجموع ضريبة على مستوى الفاتورة، فالبند فيها كمية وسعر وخصم واسم.
- فاتورة المبيعات العامة تحمل الضريبة على كل بند بتصنيفها ونسبتها، ومجموع الضريبة العامة على مستوى الفاتورة. والقيم التي تقبلها الواجهة في حقل النسبة
cbc:Percentقائمة تحقق، أما النسبة الواجبة على السلعة فيحددها قانون الضريبة العامة على المبيعات. - فاتورة المبيعات الخاصة تضيف الضريبة الخاصة، وهي في نص الدليل «قيمة يتم إدخالها دون عمليات حسابية»، ثم تُحسب الضريبة العامة على قيمة البند مضافًا إليها الضريبة الخاصة.
البند الرابع: أنواع التعامل وطرق الدفع المستخدمة فعلًا
الرقم الأول في الخاصية name يحدد نوع التعامل، والرقم الثاني يحدد طريقة الدفع، فالرقم 1 للنقدي و2 للذمم. وهناك ستة أنواع للتعامل، ولا يحتاج كل مكلف إليها كلها. فاسأل المكلف عن الأنواع التي يمارسها فعلًا، وابنِ لكل نوع منها قواعده، بدل أن تبني الأنواع الستة دون حاجة.
وفي فواتير الضريبة العامة والخاصة من الأنواع الخمسة غير المحلية، ينص الدليل على أن تكون نسبة الضريبة 0% وأن تُعبأ القيمة O لجميع السلع (ص42 للضريبة العامة وص69 للخاصة). أما في الفاتورة المحلية فعند نسبة 0% لا يُستخدم التصنيف S، ويُستخدم Z للمعفى وO للخاضع لنسبة الصفر.
وفي فاتورة المناطق التنموية شرط لا يراه نظامك، وهو أن يكون المشتري مسجلًا فيها ومعه كتاب إعفاء سارٍ مُدخل على النظام المالي. يستطيع نظامك أن يتأكد من وجود الرقم الضريبي للمشتري، لكن صحة تسجيله تظهر في رد النظام. ولاحظ أيضًا أن الدليل لا يقدم مثالًا كاملًا لفاتورة ذمم ولا لأي نوع غير محلي، بل أمثلة من سطر واحد لرمز النوع. فإذا بنيت ملفًا لأحدها فاعتبره غير مجرّب حتى يُرسل ويُقبل.
وحدد مع المكلف كذلك عملة الفواتير. فالعملة الافتراضية في الدليل الدينار الأردني، ويمكن تغيير العملة على مستوى الفاتورة كاملة فقط، لا على مستوى البند.
البند الخامس: صلاحية سعر المستهلك
سعر المستهلك إضافة في الإصدار 1.5 من الدليل، وهو السعر النهائي للمستهلك حين يُتخذ أساسًا لحساب الضريبة، ويُرسل لكل بند في العنصر cac:ItemPriceExtension/cbc:Amount بعد العنصر cac:Price. وتفصيل طريقة الحساب في مقال سعر المستهلك في نظام الفوترة الوطني.
والسؤال الذي يطرحه المطوّر قبل البرمجة هو هل مُنح المكلف هذه الصلاحية، لأن الدليل يضع لها أربعة شروط تؤثر في التصميم.
- تُمنح عند الطلب فقط، بمعاملة إلكترونية يقدمها المكلف من الخدمات الداخلية إلى دعم فني نظام الفوترة.
- تتاح فقط للمسجلين في الضريبة العامة على المبيعات أو الضريبة الخاصة، فلا تخص فاتورة الدخل.
- تنطبق على جميع بنود الفاتورة، فلا تُستخدم لبعض السلع دون غيرها.
- يجب أن يكون سعر المستهلك مساويًا لسعر الوحدة أو أكبر منه.
وإذا كانت الصلاحية ممنوحة فصمّم الحساب بحيث لا يُنقص خصم البند أساس الضريبة حين يزيد سعر المستهلك على سعر الوحدة، لأن الضريبة عندئذ تُحسب على الكمية مضروبة في سعر المستهلك.
البند السادس: أنواع هوية المشتري التي يجمعها نظامك
يحدد الدليل ثلاثة أنواع لمعرّف المشتري في الخاصية schemeID: NIN للرقم الوطني، وPN للرقم الشخصي لغير الأردني، وTN للرقم الضريبي، والقيمة أرقام فقط. وتفصيل هذه الحقول في مقال بيانات المشتري في ملف فاتورة نظام الفوترة الوطني.
وما يهم في مرحلة المتطلبات أن نماذج العملاء في نظامك يجب أن تتسع لهذه البيانات قبل أن تبدأ الفوترة. فاسأل المكلف عن عملائه، هل بينهم أفراد أردنيون أو غير أردنيين أو منشآت مسجلة، وصمّم بطاقة العميل على هذه القواعد.
- نوع المعرّف
schemeIDإجباري حسب تظليل الحقول في الدليل، وقيمة المعرّف اختيارية. - اسم المشتري إجباري في فاتورة الذمم دائمًا، وفي الفاتورة النقدية إذا زادت قيمتها على 10,000 دينار أو ما يعادلها بالعملات الأجنبية.
- الرقم الضريبي للمشتري إجباري في فاتورة المناطق التنموية.
- رقم الهاتف أرقام فقط، بين 9 و14 رقمًا، والرمز البريدي 5 خانات على الأكثر، ورمز المحافظة من قائمة الدليل.
واحفظ بيانات المشتري كما أُرسلت في كل فاتورة، لا كما هي في بطاقة العميل لاحقًا. فالدليل ينص على أن بيانات المشتري في فاتورة الإرجاع يجب أن تتوافق مع بياناته في فاتورة البيع الأصلية، وتعديل بطاقة العميل بعد البيع لا يغير ما أُرسل.
البند السابع: تصميم التخزين قبل أول إرسال
الإرشاد الخامس من إرشادات الدليل عنوانه «تخزين البيانات الأساسية»، وهو يطلب حفظ ID وUUID ورمز QR وEINV_STATUS لضمان التتبع وإعادة الاسترجاع. ويطلب الإرشاد السادس تسجيل الأخطاء داخليًا بالتفصيل مع رسالة مبسطة للمستخدم.
ويضاف إلى ما يذكره الإرشاد ما تفرضه قواعد الإرجاع، لأن فاتورة الإرجاع تشير إلى الأصلية برقمها ومعرّفها الفريد وإجماليها. والجدول التالي بنية مقترحة لما يحفظه نظامك عن كل فاتورة، ومصدر كل قيمة، وسبب الحاجة إليها.
وأهم قرار هنا توقيت توليد المعرّف الفريد. فالدليل يحذر من أن توليد معرّف جديد عند إعادة المحاولة ينشئ فواتير مكررة، فيجب أن يُولّد المعرّف ويُحفظ قبل الإرسال الأول، ثم يُقرأ من التخزين في كل إعادة. وشرحنا ذلك في مقال المعرّف الفريد UUID في نظام الفوترة الوطني. وإذا ضاع رمز QR لفاتورة مقبولة، فإعادة إرسالها بالرقم والمعرّف نفسيهما تعيد الحالة ALREADY_SUBMITTED مع رمز QR الأصلي.
ووحّد كذلك صيغة التاريخ والوقت في نظامك. فالإرشاد التاسع يطلب تنسيقًا زمنيًا موحدًا لتجنب اختلافات المعالجة بين الأنظمة، وجميع أمثلة XML في الدليل تكتب تاريخ الإصدار بصيغة yyyy-mm-dd.
ما يأتي بعد جمع المتطلبات
بعد اكتمال البنود السبعة تنتقل إلى بناء الطلب. ويحدد الدليل نقطة إرسال واحدة POST https://backend.jofotara.gov.jo/core/invoices/، ورؤوسًا ثلاثة هي Client-Id وSecret-Key وContent-Type: application/json، والمرجع السريع لها في مقال نقطة النهاية ورؤوس الطلب في نظام الفوترة الوطني. ويُرسل ملف XML بعد ترميزه بصيغة Base64 داخل جسم JSON، وتفصيل ذلك في مقال بناء طلب إرسال الفاتورة إلى نظام الفوترة الوطني.
وثلاث ملاحظات تحسم توقعات المكلف قبل البدء.
- لا توقيع رقمي من جهة المكلف. لا يطلب الدليل من المكلف شهادة أو توقيعًا، والمستند الموقّع يعود من الدائرة في الرد.
- لا بيئة تجريبية في الدليل. لا يذكر الإصدار 1.5 بيئة اختبار مفتوحة للمكلفين، فخطط للاختبار على هذا الأساس، وقد تناولنا ذلك في مقال اختبار الإرسال دون بيئة رسمية.
- لا تنسخ أمثلة الدليل كما هي. في بعض أمثلة الدليل عيوب موثقة، ومثال الشيفرة فيه يرسل ملف تعريف ارتباط خاصًا بجلسة الدائرة، وهذا لا يُرسل في نظامك.
وقبل كل إرسال يفحص نظامك الملف بالقواعد الموثقة، وقد جمعناها في مقال التحقق قبل الإرسال إلى نظام الفوترة الوطني. وللصورة العامة للنظام اقرأ مقال نظام الفوترة الوطني الإلكتروني في الأردن، ولمسار الربط من جهة مستخدم قيود اقرأ مقال خطوات الربط التقني خطوة بخطوة.
ما لا يحسمه الدليل فلا تبنِ عليه افتراضًا
بعض الأسئلة التي يطرحها المطوّر في مرحلة المتطلبات لم نجد لها حكمًا في الدليل التقني الإصدار 1.5. والأسلم أن تسجلها أسئلة مفتوحة وأن ترجع فيها إلى لجنة الدعم الفني لشؤون الفوترة في الدائرة، بدل أن تبني عليها قاعدة.
- تحويل العملة. لا يحوي الدليل عنصرًا لسعر الصرف ولا قاعدة لتحويل الفاتورة الأجنبية إلى الدينار.
- قيمة رمز العملة على المبالغ. تستخدم أمثلة الدليل القيمة
currencyID="JO"، ولا يذكر هل تُقبل قيم أخرى. - وحدات القياس. لا تظهر في الأمثلة إلا الوحدة
PCEفي بنود الفاتورة الجديدة، ولا يذكر الدليل قائمة بالوحدات. - الفاتورة المسددة جزئيًا. لم نجد في الدليل حكمًا لاختيار نقدي أو ذمم لها.
كيف يساعدك قيود إن كان هو نظامك المحاسبي
إذا كانت المنشأة تصدر فواتيرها من قيود، فهو يبني ملف الفاتورة بصيغة UBL 2.1 مع المعرّف الفريد ويرسله إلى نظام الفوترة الوطني دون أي تدخل يدوي، ولا يحتاج المكلف إلى شهادة أو توقيع خاص به. ويفحص قيود كل فاتورة على مستوى الحقول لحظة إنشائها، فيفحص الرقم الضريبي ونوع المستند وطريقة الدفع ونسبة ضريبة المبيعات العامة واكتمال البنود، وينبهك بأي خطأ قبل إرسالها لتقليل حالات الرفض. وهذا تنبيه لا ضمان بالقبول، فالحكم النهائي لدائرة ضريبة الدخل والمبيعات.
وبعد الإرسال تعيد الدائرة حالة الفاتورة ورسالة الخطأ إن وُجد، ويعرضها قيود في لوحة الحالة. والفواتير التي لم تُرسل تظهر في اللوحة بحاجة إلى إعادة إرسال، وحين تعيد إرسالها يُستخدم المعرّف الفريد نفسه. وتبقى على المكلف متطلبات تخص تسجيله لدى الدائرة، مثل نوع تسجيله الضريبي وتسلسلات مصادر دخله وطلب صلاحية سعر المستهلك إن احتاجها. ولمعرفة التكامل كاملًا زر صفحة قيود ونظام الفوترة الوطني.
فوترة إلكترونية ومحاسبة متكاملة في نظام واحد
قيود متكامل مع نظام الفوترة الوطني (JoFotara). تُصدر فاتورتك بالدينار الأردني من قيود فتُقيَّد في دفاترك تلقائيًا وتُرسل إلى النظام، وبعد قبولها يعود عليها رمز QR من دائرة ضريبة الدخل والمبيعات.
الأسئلة الشائعة
ما أول ما يطلبه المطوّر من المكلف قبل برمجة الربط؟
يطلب المطوّر أولًا الرقم الضريبي واسم البائع كما هو مسجل لدى دائرة ضريبة الدخل والمبيعات، ثم قائمة تسلسلات مصادر الدخل الفعالة التي ستصدر منها الفواتير. فهذه القيم تدخل في كل ملف فاتورة، والخطأ في الرقم الضريبي أو في تسلسل مصدر الدخل هو أول ما يذكره الدليل التقني من أسباب رمز 500.
هل يحتاج كل تسلسل مصدر دخل إلى بيانات ربط مستقلة؟
يختار المكلف تسلسل مصدر الدخل عند إنشاء الربط من خيار «ربط الأجهزة»، فيولّد النظام رقم المستخدم والمفتاح السري، وترتبط بيانات الربط بتسلسل واحد. لذلك يحتاج المكلف الذي يصدر فواتير من أكثر من تسلسل إلى زوج بيانات لكل تسلسل، ويحتاج نظامه إلى ربط كل فاتورة بالتسلسل الصحيح وبياناته.
كيف يعرف المطوّر نوع الفاتورة المسموح للمكلف بإرسالها؟
يعرفه من تسجيل المكلف لدى الدائرة، ففاتورة الدخل لغير المسجلين في ضريبة المبيعات، وفاتورة المبيعات للمسجلين فيها، وفاتورة المبيعات الخاصة للمسجلين في الضريبة الخاصة. والملف يعلن النوع في رمز من ثلاثة أرقام، لكن إرسال نوع لا يتناسب مع الرقم الضريبي أو تسلسل مصدر الدخل يعيد رسالة رفض بأن المستخدم غير مخوّل بإرسال هذا النوع.
هل يستطيع أي مكلف استخدام سعر المستهلك في فواتيره؟
لا يستطيع ذلك إلا من مُنح الصلاحية بطلب منه، إذ يقدم المكلف معاملة إلكترونية من الخدمات الداخلية إلى دعم فني نظام الفوترة لتفعيلها. وهي متاحة فقط للمسجلين في الضريبة العامة على المبيعات أو الضريبة الخاصة، وتنطبق على جميع بنود الفاتورة.
ما البيانات التي يجب حفظها بعد كل إرسال؟
يذكر الإرشاد الخامس في الدليل التقني حفظ ID وUUID ورمز QR وEINV_STATUS لضمان التتبع وإعادة الاسترجاع. ويضاف إليها رقم كل بند وإجمالي الفاتورة وبيانات المشتري، لأن فاتورة الإرجاع تُبنى عليها.
المراجع
- دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026.
- دائرة ضريبة الدخل والمبيعات، دليل إجراءات الانضمام إلى نظام الفوترة الوطني الإلكتروني الأردني، إصدار 2026.
- دائرة ضريبة الدخل والمبيعات، دليل إجراءات تنظيم الفاتورة في نظام الفوترة الوطني الإلكتروني الأردني، إصدار 2026.
- دائرة ضريبة الدخل والمبيعات، دليل الأسئلة والأجوبة لنظام الفوترة الوطني، 2026.
