رسالة The ID number must be unique في نظام الفوترة الوطني: تكرار رقم البند

تظهر رسالة The ID number must be unique حين يرسل برنامجك المحاسبي فاتورة إلى نظام الفوترة الوطني وفيها بندان أو أكثر يحملان رقم البند نفسه. فالحقل cbc:ID داخل كل بند من بنود الفاتورة (cac:InvoiceLine) رقم تسلسلي لا يتكرر على مستوى الفاتورة الواحدة، وإذا تكرر لم تُصدر الفاتورة.

والإصلاح تعديل في ملف XML، يعيد ترقيم البنود ترقيمًا تسلسليًا لا يتكرر فيه رقم. لكن لهذا الرقم وظيفة تتجاوز قبول الفاتورة، فهو المرجع الذي تُبنى عليه فاتورة الإرجاع لاحقًا، ولذلك يستحق أن يُضبط ويُحفظ من البداية.

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

ما معنى رسالة The ID number must be unique

يضع الدليل التقني هذه الرسالة بين رسائل رمز 400 (Bad Request)، وهو الرمز الذي يدل على خطأ في القيم المرسلة داخل ملف XML، ويأتي تفصيله في الحقل EINV_MESSAGE من ملف الاستجابة. ويشرح الدليل الرسالة بهذا النص:

«يدل على تكرار رقم ال ID الخاص بالسلعة او الخدمة لاكثر من سلعة (على سبيل المثال السلعة الأولى رقم ال ID هو 1 والسلعة الثانية رقم ال ID هو 1) وبالتالي لن يتم اصدار الفاتورة حيث ان رقم ال ID الخاص بالسلعة هو فريد على مستوى الفاتورة ويجب عدم تكراره».

يحمل هذا النص ثلاث معلومات تحدد طريقة التعامل مع الخطأ:

• الرقم المقصود هو رقم السلعة أو الخدمة داخل الفاتورة، أي رقم البند، لا رقم الفاتورة نفسها.
• نطاق عدم التكرار هو الفاتورة الواحدة. فالنص يقول «فريد على مستوى الفاتورة»، ولا يتحدث عن تكرار الرقم بين فاتورة وأخرى.
• النتيجة أن الفاتورة لا تُصدر. فلا يعود عليها رمز الاستجابة السريع (QR)، وتبقى غير مقبولة حتى تُصحح وتُرسل من جديد.

أين تجد الرسالة في ملف الاستجابة

يعيد نظام الفوترة الوطني مع كل إرسال ملف استجابة بصيغة JSON. وحالة الفاتورة النهائية في الحقل EINV_STATUS، فإذا رُفضت حمل القيمة NOT_SUBMITTED، وعادت حقول رمز الاستجابة السريع ورقم الفاتورة ومعرّفها والفاتورة الموقّعة فارغة. أما سبب الرفض فيأتي داخل المصفوفة ERRORS، وكل عنصر فيها يحمل الحقول type وstatus وEINV_CODE وEINV_CATEGORY وEINV_MESSAGE، والرسالة التي يشرحها هذا المقال تظهر في الحقل الأخير.

ولا يذكر الدليل قيمة EINV_CODE أو EINV_CATEGORY التي ترافق هذه الرسالة تحديدًا، فاعتمد على نص EINV_MESSAGE في التعرف عليها. وطريقة قراءة عنصر الخطأ بحقوله كلها هي موضوع مقال قراءة رسائل خطأ 400 في السلسلة نفسها.

الحقل المقصود: cbc:ID داخل بند الفاتورة

كل سلعة أو خدمة في الفاتورة تُرسل في عنصر مستقل اسمه cac:InvoiceLine، وأول حقل فيه هو cbc:ID. ويصفه الدليل في جدول قالب البند بأنه:

«هو رقم تسلسلي خاص لكل (سلعة أو خدمة) لا يتكرر على مستوى الفاتورة الواحدة».

يتبع الحقل في القالب نفسه الكمية (cbc:InvoicedQuantity)، ثم قيمة البند بعد الخصم (cbc:LineExtensionAmount)، ثم وصف السلعة أو الخدمة (cbc:Name)، ثم سعر الوحدة والخصم. فرقم البند هو ما يميّز كل بند من غيره داخل الملف، أما بقية الحقول فتصف محتواه.

ومثال الدليل في نص الرسالة يعطي السلعة الأولى الرقم 1. ونقرأ من وصف «رقم تسلسلي» أن يأخذ البند الثاني 2 والثالث 3 وهكذا، وهذه قراءتنا للوصف لا نص في الدليل. والشرط الذي ينص عليه الدليل صراحة هو عدم التكرار داخل الفاتورة.

لا تخلط بينه وبين رقم الفاتورة ومعرّفها الفريد

في رأس الفاتورة حقل آخر اسمه cbc:ID أيضًا، لكنه رقم الفاتورة نفسها، ويرافقه المعرّف الفريد cbc:UUID الذي يولّده نظام المكلف، ويكوّن الاثنان معًا المفتاح الذي يميّز الفاتورة. وقواعدهما مختلفة عن رقم البند. فإذا أعدت إرسال فاتورة بالرقم والمعرّف نفسيهما بعد قبولها، أعاد النظام الحالة ALREADY_SUBMITTED مع رمز الاستجابة الأصلي. وتفصيل هذا الجانب في مقال أخطاء نظام الفوترة الوطني. ويحمل رأس الفاتورة كذلك عدادًا ثالثًا (ICV)، وهو عداد للفواتير لا للبنود.

لماذا يتكرر رقم البند في ملفك

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

• رقم ثابت لكل البنود. كأن يكتب الكود القيمة 1 في كل بند بدل أن يزيدها، وهي الصورة نفسها التي يضربها الدليل مثالًا.
• رمز الصنف بدل رقم البند. إذا أخذ البرنامج قيمة cbc:ID من رمز السلعة في المخزون، فظهور السلعة نفسها في بندين يكرر الرقم.
• إعادة الترقيم من البداية. كأن تُجمع بنود من مصدرين داخل فاتورة واحدة ويبدأ كل مصدر ترقيمه من 1.
• نسخ بند موجود. كأن يُنسخ بند لإضافة سطر جديد، فيُنسخ رقمه معه ولا يُحدَّث.
• حذف بند ثم إضافة غيره. إذا حسب البرنامج الرقم الجديد من عدد البنود بعد الحذف، فقد يأخذ رقمًا مستخدمًا في بند آخر.

والفحص المباشر أسرع من التخمين. افتح ملف XML الذي أُرسل فعلًا، واستخرج قيم cbc:ID داخل عناصر cac:InvoiceLine وحدها، ثم ابحث فيها عن القيم المكررة. ولا تُدخل في هذا الفحص cbc:ID الموجود في رأس الفاتورة أو في عناصر أخرى.

كيف تصلح رسالة The ID number must be unique وتعيد الإرسال

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

1. حدد البنود المتكررة. من ملف XML المرسل، كما في الفحص السابق.
2. أعد ترقيم البنود. أعط كل بند رقمًا تسلسليًا خاصًا به لا يتكرر داخل الفاتورة.
3. لا تغيّر محتوى البنود. الكمية والسعر والخصم والوصف تبقى كما هي، فالخطأ في رقم البند وحده.
4. أعد الإرسال برقم الفاتورة ومعرّفها نفسيهما. يوصي الدليل عند فشل الإرسال بإعادة المحاولة برقم الفاتورة ومعرّفها الفريد (UUID) نفسيهما، دون توليد معرّف جديد.
5. احكم على النتيجة من حالة الفاتورة. اقرأ EINV_STATUS لا رمز HTTP وحده، ولا تعدّ الفاتورة مقبولة إلا إذا عاد عليها رمز الاستجابة السريع.
6. احفظ أرقام البنود مع الفاتورة. الأرقام التي قُبلت بها الفاتورة هي التي ستحتاجها عند أي إرجاع لاحق.

إعادة الترقيم وحدها لا تغيّر أي مبلغ في الفاتورة. أما إذا عالجت التكرار بدمج بندين في بند واحد، فقد تغيّرت قيم البنود، فراجع مجاميع الفاتورة بالمعادلات المشروحة في مقال رسالة Total General Amount is Not Correct قبل الإرسال، حتى لا يتحول خطأ الترقيم إلى خطأ في المجاميع.

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

رقم البند بعد قبول الفاتورة: مرجع فاتورة الإرجاع

لا تنتهي وظيفة رقم البند عند قبول الفاتورة. فالإرجاع في نظام الفوترة الوطني يتم بفاتورة إرجاع مستقلة، تشير في عنصر cac:BillingReference إلى رقم الفاتورة الأصلية ومعرّفها الفريد وإجماليها. وتحدد البنود المرجعة برقم البند نفسه، إذ ينص الدليل على أنه:

«يجب ان يكون رقم الID للسلعة او الخدمة المراد ارجاعها كما هو في الفاتورة الاصلية».

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

ويلخص الجدول التالي ما يحمله رقم البند في كل موضع:

ومن هذا الجدول تتضح نتيجة عملية. إذا أعاد برنامجك ترقيم بنود فاتورة مقبولة لأي سبب، كتعديل داخلي في السجلات، فستفقد فاتورة الإرجاع مرجعها الصحيح. فثبّت أرقام البنود عند القبول، ولا تعدّلها بعد ذلك.

قائمة فحص قبل الإرسال

يوصي الدليل في إرشاداته بالتحقق من الحقول قبل الإرسال لتقليل أخطاء 400. وهذه بنود الفحص الخاصة برقم البند:

1. كل عنصر cac:InvoiceLine يحمل حقل cbc:ID بقيمة.
2. لا تتكرر أي قيمة cbc:ID بين بنود الفاتورة الواحدة.
3. الترقيم تسلسلي، ولا يُؤخذ من رمز الصنف أو من أي قيمة قد تتكرر.
4. الفحص يقتصر على cbc:ID داخل البنود، ولا يختلط برقم الفاتورة في رأسها.
5. في فاتورة الإرجاع، رقم كل بند مرجع مطابق لرقمه في الفاتورة الأصلية.
6. أرقام البنود محفوظة في نظامك مع رقم الفاتورة ومعرّفها ورمز الاستجابة السريع وحالتها.

كيف يساعدك قيود

حين تصدر فاتورتك من برنامج محاسبي، لا تكتب ملف XML بيدك. يبني تكامل قيود مع نظام الفوترة الوطني ملف الفاتورة بصيغة UBL 2.1 ومعرّفها الفريد، ويرسله دون أي تدخل يدوي. ويعمل كذلك على هذه الطبقة:

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

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

أين تذهب بعد هذا المقال

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

الأسئلة الشائعة

ما معنى رسالة The ID number must be unique؟

تعني أن رقم البند (cbc:ID داخل cac:InvoiceLine) تكرر لأكثر من سلعة أو خدمة في الفاتورة نفسها. ويصنفها الدليل التقني ضمن رسائل رمز 400، وينص على أن الفاتورة لا تُصدر في هذه الحالة.

هل تتعلق الرسالة برقم الفاتورة أم برقم البند؟

تتعلق برقم البند. فالدليل يتحدث عن «رقم ال ID الخاص بالسلعة او الخدمة»، ويجعله فريدًا على مستوى الفاتورة. أما رقم الفاتورة ومعرّفها الفريد في رأسها فلهما قواعد أخرى.

هل يجوز أن يتكرر رقم البند نفسه في فاتورتين مختلفتين؟

يحدد الدليل نطاق عدم التكرار بالفاتورة الواحدة، ولا يتحدث عن تكرار رقم البند بين فاتورة وأخرى.

هل أولّد معرّفًا فريدًا جديدًا للفاتورة بعد تصحيح الترقيم؟

يوصي الدليل بإعادة الإرسال برقم الفاتورة ومعرّفها الفريد (UUID) نفسيهما، دون توليد معرّف جديد. فصحّح أرقام البنود وحدها، ثم أعد إرسال الفاتورة بالرقم والمعرّف اللذين أُرسلت بهما أول مرة.

لماذا أحتفظ بأرقام البنود بعد قبول الفاتورة؟

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

المراجع

• دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026.