الربط مع نظام الفوترة الوطني (JoFotara)

كيف يجري الربط عملياً

نظام الفوترة الوطني يستقبل الفاتورة لحظة إصدارها ويعتمدها، ويعيد رقماً مرجعياً ومعرّفاً فريداً (UUID) ورمز QR. الفاتورة ليست ملف PDF ولا صورة — بل ملف XML منظَّم وفق معيار UBL 2.1. ما تطبعه للعميل مجرد تمثيل بصري لذلك الملف.

التفاصيل الكاملة لتدفّق الربط كما يصفه دليل المستخدم الرسمي لمنصة الـPortal منشورة في صفحة الربط الوطني وتكامل ERP، ومرجع الحقول والأخطاء في توثيق الـAPI.

مفاتيح Client-Id و Secret-Key

الربط البرمجي يتم بمفتاحين تُصدرهما الدائرة لمنشأتك ويُرسلان في ترويسات كل طلب. قبل أي شيء يجب أن تحمل المنشأة رقماً ضريبياً فعّالاً وأن تكون مسجّلة على بوابة الضريبة الإلكترونية، ثم يُنشأ حساب نظام الفوترة الإلكتروني من داخلها.

المفتاح	الترويسة	الدور
Client Id	Client-Id	يعرّف منشأتك لدى النظام.
Secret Key	Secret-Key	يثبت أن الطلب صادر عنك فعلاً. سرّي تماماً.

الحقول الإلزامية في الفاتورة

نقص أي حقل من هذه يرفض الفاتورة — بغضّ النظر عن صحة المبالغ.

الحقل	موقعه في UBL	ملاحظة عملية
رقم الفاتورة	cbc:ID	فريد لدى منشأتك، ولا يُعاد استخدامه.
المعرّف الفريد	cbc:UUID	يُولَّد لكل فاتورة (UUID v4).
تاريخ الإصدار	cbc:IssueDate	بصيغة YYYY-MM-DD حصراً.
نوع الفاتورة وطريقة الدفع	cbc:InvoiceTypeCode	يجب أن يتوافقا معاً — القسم التالي.
الرقم الضريبي للبائع	cac:PartyTaxScheme	مطابق للمسجّل لدى الدائرة.
تسلسل مصدر الدخل	cac:SellerSupplierParty	أكثر حقل يُنسى، وسبب رفض متكرر.
بيانات المشتري	cac:AccountingCustomerParty	الاسم مطلوب دائماً؛ الرقم الضريبي حسب نوع العملية.
بنود الفاتورة	cac:InvoiceLine	بند واحد على الأقل بكميّة أكبر من صفر.
المجاميع	cac:LegalMonetaryTotal	بثلاث خانات عشرية — لا خانتين.

رموز نوع الفاتورة وطريقة الدفع

هنا يقع أكثر خطأ شيوعاً على الإطلاق. الرمزان ليسا مستقلّين: طريقة الدفع المسموحة تتبع نوع المستند.

نوع المستند	الرمز	طرق الدفع المسموحة
فاتورة ضريبية	388	011 نقدي · 021 ذمم (آجل)
إشعار دائن / مرتجع	381	013 مرتجع نقدي · 023 مرتجع ذمم

معيار UBL 2.1 و XML عملياً

UBL (Universal Business Language) معيار دولي لتمثيل مستندات الأعمال في XML، والإصدار 2.1 هو المعتمد لدى النظام الأردني. لن تحتاج لحفظه، لكن فهم بنيته يساعدك على قراءة رسائل الخطأ. الفاتورة أربع كتل: رأس المستند، الأطراف، البنود، والمجاميع.

<Invoice>
  <cbc:ID>INV-2026-0418</cbc:ID>
  <cbc:UUID>8f3c1e42-…</cbc:UUID>
  <cbc:IssueDate>2026-04-18</cbc:IssueDate>
  <cbc:InvoiceTypeCode name="011">388</cbc:InvoiceTypeCode>
  <cac:AccountingSupplierParty>   <!-- البائع -->
  <cac:AccountingCustomerParty>   <!-- المشتري -->
  <cac:SellerSupplierParty>       <!-- تسلسل مصدر الدخل -->
  <cac:InvoiceLine>               <!-- بند لكل صنف -->
  <cac:LegalMonetaryTotal>        <!-- المجاميع -->
</Invoice>

احتساب الضريبة يجري على مستوى البند، لا الفاتورة

النسبة العامة لضريبة المبيعات في الأردن 16%، وتوجد نسب مخفّضة وأصناف معفاة أو خاضعة لنسبة صفرية بحسب طبيعة السلعة أو الخدمة.

الأساس الخاضع = (الكمية × سعر الوحدة) − الخصم
الضريبة       = الأساس الخاضع × (النسبة ÷ 100)
الإجمالي      = الأساس الخاضع + الضريبة

// مثال: 2 × 120 بخصم 20 وضريبة 16%
// الأساس = 220 ، الضريبة = 35.200 ، الإجمالي = 255.200

البنود صفرية النسبة أو المعفاة تُرسل بفئة ضريبية مختلفة (Z بدل S) مع سبب الإعفاء. يمكن أن تجتمع بنود خاضعة ومعفاة في الفاتورة نفسها، ويجب أن تعكس المجاميع ذلك بدقة.

أسباب رفض الفواتير وعلاجها

السبب	كيف يظهر	العلاج
تعارض نوع الفاتورة مع طريقة الدفع	رفض فوري عند الإرسال	التزم بجدول الرموز أعلاه.
تسلسل مصدر الدخل ناقص	خطأ يشير إلى SellerSupplierParty	أضف التسلسل لبيانات البائع الثابتة.
تقريب لخانتين عشريتين	عدم تطابق المجاميع	احسب وأرسل بثلاث خانات.
XML غير مُصغَّر	خطأ في صيغة المستند	طبّق Minify قبل ترميز Base64.
رقم فاتورة مكرر	رفض للتكرار	استخدم تسلسلاً فريداً ولا تُعد استخدام الأرقام.

أربعة من هذه الخمسة تُكتشف بتحقّق مسبق فلا تصل إلى الدائرة أصلاً. جدول الأخطاء الكامل مع رموز الدائرة وترجمتها منشور في دليل نظام الفوترة الوطني.

رمز QR والتحقّق من الفاتورة

بعد القبول يعيد النظام رمز QR تضعه على النسخة المطبوعة أو الـPDF، ويستطيع أي شخص مسحه للتحقّق من أن الفاتورة مُسجَّلة فعلاً وأن مبالغها لم تُعدَّل. عملياً هذا يعني أمرين: لا تطبع الفاتورة قبل استلام رد القبول لأن الرمز لا يوجد قبله، واحتفظ بالرمز مع سجل الفاتورة فهو جزء من مستندك لا زينة عليه.

الأنظمة التي نربطها

أنماط ربط مجرَّبة. وإن لم يكن نظامك في القائمة، فنقطة النهاية نفسها تكفي.

أسماء المنتجات أعلاه علامات تجارية لأصحابها، ونذكرها للدلالة على التوافق التقني فقط.

أسئلة شائعة

كيف أربط نظامي المحاسبي مع نظام الفوترة الوطني (JoFotara) عبر API؟

الربط البرمجي يحتاج ثلاثة أشياء: حساب منشأة على بوابة النظام، مفتاحَي ربط (Client-Id و Secret-Key) يُصدرهما حساب المستخدم الرئيسي من شاشة «ربط الأجهزة»، ثم طبقة تبني ملف XML وفق معيار UBL 2.1 وتُصغّره وتُرمّزه بـ Base64 قبل إرساله. لا تحتاج إلى استبدال نظامك المحاسبي: الطبقة تجلس بين نظامك وبين الدائرة، ويبقى نظامك مصدر الحقيقة لبيانات المبيعات.

ما هي الحقول الإلزامية في فاتورة JoFotara؟

رقم الفاتورة (cbc:ID) ويجب أن يكون فريداً، والمعرّف الفريد UUID، وتاريخ الإصدار بصيغة YYYY-MM-DD، ورمز نوع الفاتورة مع طريقة الدفع المتوافقة معه، والرقم الضريبي للبائع، وتسلسل مصدر الدخل، وبيانات المشتري، وبند واحد على الأقل بكمية أكبر من صفر، والمجاميع بثلاث خانات عشرية. نقص أي حقل من هذه يرفض الفاتورة بغضّ النظر عن صحة المبالغ.

ما هو تسلسل مصدر الدخل ولماذا تُرفض فواتيري بسببه؟

تسلسل مصدر الدخل حقل يعرّف النشاط الذي صدرت عنه الفاتورة، ويقع في UBL داخل cac:SellerSupplierParty. هو أكثر حقل يُنسى عند بناء أول تكامل، وغيابه سبب رفض متكرر. العلاج أن تضيفه إلى بيانات البائع الثابتة مرة واحدة، فيتكرر تلقائياً في كل فاتورة بدل إدخاله يدوياً.

ما رموز نوع الفاتورة وطريقة الدفع في JoFotara؟

الفاتورة الضريبية رمزها 388 وطرق الدفع المسموحة لها 011 نقدي و021 ذمم (آجل). إشعار الدائن أو المرتجع رمزه 381 وطرق الدفع المسموحة له 013 مرتجع نقدي و023 مرتجع ذمم. الرمزان ليسا مستقلّين: 388 لا تأتي أبداً مع 013 أو 023، و381 لا تأتي أبداً مع 011 أو 021. عدم توافق الرمزين هو أكثر خطأ شيوعاً على الإطلاق.

لماذا تُرفض الفواتير المرفوضة في JoFotara وكيف أعالجها؟

أكثر الأسباب تكراراً خمسة: تعارض رمز نوع الفاتورة مع طريقة الدفع، غياب تسلسل مصدر الدخل، تقريب المبالغ إلى خانتين عشريتين بدل ثلاث، إرسال XML غير مُصغَّر، وتكرار رقم فاتورة مستخدم سابقاً. أربعة من هذه الخمسة تُكتشف قبل الإرسال بتحقّق مسبق، فلا تصل إلى الدائرة أصلاً.

لماذا يجب أن تكون المبالغ بثلاث خانات عشرية؟

الدينار الأردني يُكسر إلى ألف فلس، فالنظام يتوقع المبالغ بثلاث خانات عشرية — 255.200 لا 255.20. التقريب إلى خانتين سبب رفض متكرر عند الفرق القادمة من أنظمة مبنية على الدولار أو اليورو، لأن المجاميع لا تتطابق مع مجموع البنود.

هل يمكن ربط WooCommerce أو Shopify أو نظام نقاط البيع مع JoFotara؟

نعم. أي نظام يستطيع إرسال طلب HTTPS يستطيع الربط. الأنماط المجرَّبة تشمل Odoo و SAP و Microsoft Dynamics و WooCommerce و Shopify وأنظمة نقاط البيع، إضافة إلى الأنظمة المخصّصة. في متجر إلكتروني تُصدر الفاتورة تلقائياً عند اكتمال الطلب، وفي نقطة بيع تُرسل لحظة إتمام البيع ويُطبع رمز QR على الإيصال مباشرة.

من أين أحصل على Client Id و Secret Key؟

من شاشة «ربط الأجهزة» داخل حسابك على بوابة النظام، وهي متاحة لحساب المستخدم الرئيسي (Admin) وحده — المستخدم الفرعي ينظّم الفواتير من الواجهة ولا يُصدر مفاتيح ربط. المفتاحان يُرسلان في ترويسات كل طلب، ويعادلان توقيع منشأتك الضريبي: من يملكهما يستطيع إصدار فواتير على ذمّتك، فلا تُرسلهما في بريد أو واتساب ولا تضعهما في كود تطبيق أو موقع.

هل تظهر الفاتورة برمز QR وكيف يتحقّق العميل منها؟

بعد قبول الفاتورة يُعيد النظام رقماً مرجعياً ومعرّفاً فريداً (UUID) ورمز QR. الرمز يتيح لأي شخص — عميلك أو مدقّق من الدائرة — التحقّق من أن الفاتورة مُسجَّلة فعلاً وأن مبالغها لم تُعدَّل. عملياً: لا تطبع الفاتورة قبل استلام رد القبول، لأن الرمز لا يوجد قبله.

هل منشأتي مُلزَمة بالفوترة الإلكترونية، ومتى؟

الإلزام في الأردن يتوسّع تدريجياً على شرائح، والشريحة التي تقع فيها منشأتك تحدّدها دائرة ضريبة الدخل والمبيعات بناءً على عوامل مثل حجم المبيعات السنوي وطبيعة النشاط والتسجيل في ضريبة المبيعات. مواعيد الإلزام والغرامات المترتبة على التأخير تُعدَّل أكثر من مرة، فلا تعتمد على تواريخ من مصادر غير رسمية: راجع إعلانات الدائرة أو مستشارك الضريبي عن شريحتك بالتحديد.

كم يستغرق مشروع الربط؟

مشروع ربط نموذجي يستغرق من يوم إلى أسبوع بحسب تعقيد نظامك. المسار أربع محطات: مفتاح اختبار (Sandbox) تحصل عليه خلال دقائق، ثم مطابقة الحقول لتحديد موقع كل حقل مطلوب داخل نظامك، ثم تكامل واختبار على حالات حقيقية (فاتورة عادية، آجلة، بخصم، ببنود معفاة، وإشعار دائن)، ثم التحويل إلى البيئة الحية بمفاتيح منشأتك.