لكل فاتورة ترسلها إلى نظام الفوترة الوطني رقم تعرفه، وهو رقم الفاتورة في الحقل cbc:ID. لكن النظام لا يعرّف الفاتورة بهذا الرقم وحده. فإلى جانبه يحمل الملف المعرّف الفريد UUID في نظام الفوترة الوطني، في الحقل cbc:UUID، والقيمتان معًا هما ما يميّز فاتورتك عن أي فاتورة أخرى على النظام.
الجواب المباشر عن سؤال هذا المقال أن الدليل التقني الصادر عن دائرة ضريبة الدخل والمبيعات يجعل رقم الفاتورة والمعرّف الفريد معًا مفتاحًا أساسيًا للفاتورة، ويجعل توليد المعرّف مسؤولية نظام المكلف، ويطلب إعادة استعماله في كل إعادة إرسال. ومن هنا تأتي القاعدة العملية التي يدور حولها كل ما بعدها، وهي أن تولّد المعرّف مرة واحدة، وتحفظه، ولا تستبدله.
يشرح هذا المقال موقع المعرّف الفريد في ملف الفاتورة وفي رد النظام، ولماذا يتكرر الإرسال حين يضيع، وما الذي تحفظه لكل فاتورة، وما الذي لا تنسخه من أمثلة الدليل.
ID وUUID معًا: المفتاح الأساسي للفاتورة
يصف الدليل التقني (الإصدار 1.5، ص12) الحقلين في جدول رأس الفاتورة. الحقل cbc:ID هو رقم الفاتورة. أما الحقل cbc:UUID فوصفه في الدليل بالنص الآتي.
«رقم مميز UUID (Universal Unique Identifier) يتم إنشاؤه من قبل نظام المكلف بحيث يشكل ID و UUID معًا مفتاحًا رئيسيًا (Primary Key) لعدم تكرار الفاتورة المرسلة على النظام».
في هذا النص ثلاث معلومات تستحق أن تقف عندها.
- المفتاح مركّب من قيمتين. رقم الفاتورة وحده لا يكفي ليعرف النظام الفاتورة، والمعرّف الفريد وحده لا يكفي كذلك. الهوية هي الزوج.
- المعرّف يولّده نظام المكلف. لا ينتظر برنامجك من نظام الفوترة الوطني أن يعطيه معرّفًا. برنامجك هو من ينشئه ويضعه في الملف قبل الإرسال.
- الغاية منع التكرار. يذكر الدليل صراحة أن وظيفة المفتاح هي «عدم تكرار الفاتورة المرسلة على النظام».
ويعيد الدليل القاعدة نفسها في ملاحظاته التشغيلية (ص104)، فيقول إن رقم الفاتورة في نظام الفوترة «لا يقتصر على رقم الـ ID فقط، وإنما يتكوّن من الـ ID والـ UUID معًا كمفتاح رئيسي (Primary Key)».
النتيجة العملية أن أي حديث عن «الفاتورة نفسها» في نظام الفوترة الوطني هو حديث عن الزوج نفسه. فإذا أرسلت رقم الفاتورة نفسه مع معرّف فريد آخر، فأنت في نظر المفتاح ترسل زوجًا مختلفًا.
أين يظهر المعرّف الفريد UUID في نظام الفوترة الوطني داخل الملف والرد
المعرّف الفريد ليس حقلًا تكتبه مرة ثم تنساه. فهو يظهر في رأس فاتورة البيع، ويعود إليك في رد النظام، ثم تحتاجه مرة أخرى إذا أصدرت فاتورة إرجاع على الفاتورة نفسها. وفي الملف حقول أخرى تحمل أسماء متشابهة لكنها لا تخص المفتاح، فمن المفيد أن تراها كلها في مكان واحد.
مرِّر الجدول أفقيًا لعرض بقية الأعمدة
سطران في هذا الجدول يسببان الالتباس أكثر من غيرهما. الأول رقم البند، فهو يحمل اسم العنصر cbc:ID نفسه لكنه يعيش داخل سطر البند ويخص ترتيب البنود داخل الفاتورة، وشرحه في مقال رسالة The ID number must be unique في نظام الفوترة الوطني. والثاني كتلة عدّاد الفاتورة، فهي تحتوي عنصرًا اسمه UUID لكن قيمته عدّاد الفاتورة الذي يبدأ من 1 ويتصاعد، لا المعرّف الفريد للفاتورة. والعدّاد لا يدخل في المفتاح الأساسي للفاتورة.
من يولّد المعرّف الفريد ولماذا يجب أن تخزّنه
بما أن نظام المكلف هو من يولّد المعرّف، فالمسؤولية عن ثباته تقع على نظام المكلف كذلك. ويحذّر الدليل التقني من خطأ محدد في هذا الموضع، وهذا نصه في ملاحظاته التشغيلية (ص104).
«تعتمد الكثير من الأنظمة على توليد الـ UUID تلقائيًا (Auto Generation)، وعند عدم تخزينه قد يؤدي ذلك إلى تكرار الفواتير عند إعادة الإرسال، لذلك يجب تخزينه وإعادة استخدامه».
المشكلة إذن ليست في التوليد التلقائي ذاته، بل في توليد معرّف لا يُحفظ. تخيّل برنامجًا يولّد معرّفًا جديدًا في كل مرة يبني فيها ملف الفاتورة. تُرسل الفاتورة، ويضيع الرد لأي سبب، فيبني البرنامج الملف من جديد ويرسله. في المحاولة الثانية يحمل الملف رقم الفاتورة نفسه لكن بمعرّف آخر، فلا يعود الزوج هو الزوج الأول. وهذا هو المسار الذي يصفه الدليل حين يقول إن عدم التخزين قد يؤدي إلى تكرار الفواتير.
والترتيب الصحيح لهذه الخطوة بسيط.
- ولّد المعرّف عند إنشاء الفاتورة، لا عند بناء ملف الإرسال.
- احفظه مع سجل الفاتورة في قاعدة بيانات برنامجك قبل أول محاولة إرسال.
- اقرأه من السجل في كل بناء لاحق للملف، فلا يُولَّد مرة ثانية للفاتورة نفسها مهما تكرر البناء.
هذا الترتيب استنتاج عملي من نص الدليل، فالدليل يطلب التخزين وإعادة الاستخدام ولا يحدد لحظة التوليد. لكن حفظ المعرّف قبل أول إرسال هو ما يضمن أن تجده حين تحتاج إليه.
إعادة الإرسال بالمعرّف نفسه: القاعدة في كل حالة فشل
من الإرشادات العشر التي يوردها الدليل التقني (ص104) إرشادان يخصان هذا الموضوع مباشرة.
- الإرشاد الثالث، إدارة إعادة الإرسال. عند فشل الإرسال يطلب الدليل إعادة الإرسال برقم الفاتورة ID والمعرّف الفريد UUID ذاتهما، لتجنب إنشاء فاتورة جديدة أو تكرار البيانات.
- الإرشاد الثامن، معالجة الانقطاع. نصه «عند حدوث Timeout أو فشل اتصال يجب إعادة المحاولة دون توليد UUID جديد».
الإرشادان يغطيان حالتين مختلفتين، والقاعدة فيهما واحدة.
الحالة الأولى، رفض الفاتورة بسبب خطأ في بياناتها. هنا تعرف أن الفاتورة لم تُقبل، وتعرف السبب من رد النظام. تصلح السبب ثم تعيد الإرسال برقم الفاتورة نفسه ومعرّفها الفريد نفسه. ويختلف موضع الإصلاح باختلاف الرمز. فخطأ رقم المستخدم والمفتاح السري شرحه في مقال خطأ 403 في نظام الفوترة الوطني، وأسباب رمز 500 وترتيب فحصها في مقال خطأ 500 في نظام الفوترة الوطني. وفي كل الأحوال لا يدخل تغيير المعرّف ضمن الإصلاح.
الحالة الثانية، انقطاع الاتصال قبل وصول الرد. هذه الحالة أخطر، لأنك لا تعرف مصير المحاولة الأولى. ربما لم تصل الفاتورة، وربما وصلت وقُبلت وضاع الرد في الطريق. وتعذّر الوصول إلى النظام أصلًا له رمزه وأسبابه في مقال خطأ 504 في نظام الفوترة الوطني. وفي الحالتين يطلب الدليل إعادة المحاولة دون توليد معرّف جديد.
ولا يحدد الدليل عدد مرات إعادة المحاولة ولا الفاصل الزمني بينها، فهذا قرار يعود إلى تصميم نظامك. الثابت الوحيد في النص أن المعرّف لا يتغير بين محاولة وأخرى.
وإذا كانت المحاولة الأولى قد قُبلت فعلًا، فالفاتورة صادرة ولا يتيح الدليل التقني تعديلها. وأي تصحيح بعد القبول يتم بفاتورة إرجاع تشير إلى رقم الفاتورة الأصلية ومعرّفها الفريد وإجماليها، لا بإعادة إرسال الفاتورة بمحتوى جديد.
حالة ALREADY_SUBMITTED: حين يتعرف النظام على فاتورة سبق قبولها
هنا تظهر فائدة المفتاح المركّب بوضوح. إذا أعدت إرسال فاتورة سبق أن قُبلت، برقمها نفسه ومعرّفها الفريد نفسه، يعيد النظام في الحقل EINV_STATUS الحالة ALREADY_SUBMITTED ومعها رمز الاستجابة السريع الأصلي، دون أن تتكرر الفاتورة. ولهذا تُعد هذه الحالة الطريقة الموثقة لاستعادة رمز لم تتمكن من حفظه بعد المحاولة الأولى. أما إن تغيّر المعرّف بين المحاولتين، فهذا هو المسار الذي يحذّر الدليل من أنه قد يؤدي إلى تكرار الفواتير. وشرح حالات EINV_STATUS الثلاث مع بقية رموز الرد في مقال أخطاء نظام الفوترة الوطني.
ما الذي تحفظه لكل فاتورة بعد الإرسال
ينص الإرشاد الخامس في الدليل التقني، وعنوانه «تخزين البيانات الأساسية»، على أنه «يجب حفظ ID و UUID و QR Code و EINV_STATUS لضمان التتبع وإعادة الاسترجاع عند الحاجة». هذه أربع قيم لكل فاتورة، ولكل منها دور.
- رقم الفاتورة
cbc:ID. النصف الأول من المفتاح، وهو ما تبحث به عن الفاتورة في سجلاتك. - المعرّف الفريد
cbc:UUID. النصف الثاني من المفتاح، ومن دونه لا تستطيع أن تعيد إرسال الفاتورة بهويتها نفسها. ومن الأغراض الستة التي يذكرها الدليل لرد النظام (ص97) «استرجاع الرقم الفريد للفاتورة (UUID)»، ويصل في الرد في الحقلEINV_INV_UUID. - رمز الاستجابة السريع. يعود في الحقل
EINV_QRبعد قبول الفاتورة، ولا تُعد الفاتورة مستلمة ومقبولة إلا بوجوده. ويطلب الدليل إظهار هذا الرمز على فاتورة البائع. - حالة الفاتورة
EINV_STATUS. وهي المرجع في الحكم على الفاتورة. فالإرشاد الرابع ينص على أنه «لا يُعتمد على Status Code فقط، وإنما يجب الاعتماد على قيمة EINV_STATUS لتحديد حالة الفاتورة النهائية».
ويضيف الدليل إلى هذه القيم الأربع أمرين. الأول سجل كامل لعمليات الإرسال والردود وإعادات الإرسال، وهو الإرشاد العاشر «تتبع العمليات (Audit Trail)». والثاني الاحتفاظ برقم البند لكل سلعة في فاتورة البيع، لأن فاتورة الإرجاع تُطابَق على أرقام البنود في الفاتورة الأصلية.
وحين يصل الأمر إلى الإرجاع، تجتمع هذه القيم في مكان واحد. فكتلة المرجع في فاتورة الإرجاع تحمل رقم الفاتورة الأصلية ومعرّفها الفريد وإجماليها. ومن لم يحفظ المعرّف الفريد للفاتورة الأصلية لن يجد ما يضعه في هذه الكتلة.
لا تنسخ أمثلة المعرّف الفريد من الدليل التقني
أمثلة الدليل التقني توضيحية، وبعضها فيه عيوب لا تصلح للنسخ. ويخص المعرّف الفريد منها عيبان.
- معرّفان مكتوبان بشكل غير سليم في صفحتي 14 و98. المجموعة الأخيرة في المثال الأول ناقصة، إذ لا تضم إلا إحدى عشرة خانة، والمثال الثاني يحتوي أحرفًا لا تنتمي إلى النظام الست عشري. لذلك لا نعيد طباعتهما هنا، ولا تستعمل أيًا منهما في ملف اختبار أو في إعدادات برنامجك.
- مثال فاتورة الإرجاع لا يطابق فاتورته الأصلية. في مثال إرجاع فاتورة ضريبة المبيعات العامة يشير المرجع إلى معرّف فريد يختلف عن معرّف الفاتورة الأصلية في المثال نفسه. وفي التطبيق الفعلي يجب أن يحمل المرجع المعرّف الأصلي كما حفظته.
والقاعدة التي تخرج بها من ذلك أن يولّد نظامك المعرّف الفريد بنفسه لكل فاتورة، وألا يُنسخ أي معرّف من مثال، لا من الدليل ولا من فاتورة سابقة. فالمعرّف المنسوخ يعيد استعمال قيمة لا تخص فاتورتك.
كيف يتعامل قيود مع المعرّف الفريد
كل ما سبق عمل يقع على نظام المكلف، وهو ما يتولاه برنامجك المحاسبي إذا كان مربوطًا بالنظام. ويعمل تكامل قيود مع نظام الفوترة الوطني على هذه الطبقة كما يلي.
- بناء الملف والمعرّف. يبني قيود ملف الفاتورة بصيغة UBL 2.1 مع المعرّف الفريد، ويرسله إلى نظام الفوترة الوطني دون أي تدخل يدوي.
- حالة كل فاتورة أمامك. تعيد الدائرة حالة الفاتورة ورسالة الخطأ، ويعرضها قيود في لوحة الحالة، ومنها «مرسلة» و«مرسلة مسبقًا» و«لم تُرسل» مع رسالة الخطأ.
- قائمة بما يحتاج إعادة إرسال. تعرض لوحة الحالة الفواتير التي لم تُرسل وتحتاج إلى إعادة إرسال.
- إعادة إرسال بالمعرّف نفسه. حين تعيد إرسال الفاتورة من لوحة الحالة، تُرسل بالمعرّف UUID نفسه.
وإعادة الإرسال هنا خطوة تقوم بها أنت من لوحة الحالة. أما رمز الاستجابة السريع فتصدره الدائرة بعد قبول الفاتورة، ويظهر على الفاتورة التي يصدرها قيود. ولصورة أوسع عن النظام وطريقة ربط منشأتك به، اقرأ مقال نظام الفوترة الوطني الالكتروني، أو تعرّف على ما يقدمه قيود في نظام الفوترة الوطني.
فوترة إلكترونية ومحاسبة متكاملة في نظام واحد
قيود متكامل مع نظام الفوترة الوطني (JoFotara). تُصدر فاتورتك بالدينار الأردني من قيود فتُقيَّد في دفاترك تلقائيًا وتُرسل إلى النظام، وبعد قبولها يعود عليها رمز QR من دائرة ضريبة الدخل والمبيعات.
الأسئلة الشائعة
ما المعرّف الفريد UUID في نظام الفوترة الوطني؟
هو رقم مميز يولّده نظام المكلف ويضعه في الحقل cbc:UUID في رأس الفاتورة. ويشكّل مع رقم الفاتورة في الحقل cbc:ID مفتاحًا أساسيًا يمنع تكرار الفاتورة المرسلة على النظام، بحسب الدليل التقني لدائرة ضريبة الدخل والمبيعات.
هل يولّد نظام الفوترة الوطني المعرّف الفريد للفاتورة؟
لا يولّده النظام. ينص الدليل التقني على أن المعرّف ينشئه نظام المكلف، ثم يعيده النظام في الرد في الحقل EINV_INV_UUID.
هل أولّد معرّفًا فريدًا جديدًا عند إعادة إرسال فاتورة فشل إرسالها؟
لا تولّد معرّفًا جديدًا. يطلب الدليل التقني إعادة الإرسال برقم الفاتورة نفسه ومعرّفها الفريد نفسه، وإعادة المحاولة عند انقطاع الاتصال دون توليد معرّف جديد، لأن عدم تخزين المعرّف قد يؤدي إلى تكرار الفواتير.
ماذا تعني حالة ALREADY_SUBMITTED؟
تعني أن الفاتورة أُرسلت من قبل برقمها نفسه ومعرّفها الفريد نفسه وقُبلت. يعيد النظام معها رمز الاستجابة السريع الأصلي، وهي الطريقة الموثقة لاستعادة رمز لم تحفظه.
ما القيم التي يجب حفظها لكل فاتورة؟
يوصي الدليل التقني بحفظ أربع قيم هي رقم الفاتورة والمعرّف الفريد ورمز الاستجابة السريع وحالة الفاتورة EINV_STATUS، مع سجل كامل لعمليات الإرسال والردود، وأرقام البنود التي تُطابَق عليها فواتير الإرجاع.
هل يمكنني استعمال أمثلة المعرّف الفريد الواردة في الدليل التقني؟
لا تستعملها. فالمعرّفان الواردان في صفحتي 14 و98 مكتوبان بشكل غير سليم، وأمثلة الدليل توضيحية لا تصلح للنسخ في ملف فعلي. ولّد معرّفًا جديدًا لكل فاتورة واحفظه.
المراجع
- دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026، ص12 وص97 وص104.
