BR-KSA-03 — معرّف الفاتورة (UUID) غير موجود أو غير صالح

نص الرسالة كما ترسلها الهيئة بالإنجليزية، بلا تعديل

The invoice must contain a unique identifier ("UUID") (KSA-1) given by the unit that issued the document (unique message identifier for interchange process). This value must contain only letters, digits, and dashes.

ماذا يعني هذا؟

كل مستند يحمل معرّفين يسهل الخلط بينهما. رقم الفاتورة (BT-1) هو التسلسل الذي تطبعه على الورقة ويذكره العميل. أما الـ UUID (الحقل KSA-1) فمعرّف تقني للمستند نفسه في التبادل مع الهيئة: لا يقرؤه أحد، ووجوده ليُشار إلى مستند بعينه بلا لبس.

والقاعدة تفحص أمرين معًا: أن يكون الحقل موجودًا، وألا تحتوي قيمته إلا حروفًا وأرقامًا وشرطات. والصيغة المتعارف عليها للـ UUID تحقّق الشرطين: 36 خانة على هيئة 8-4-4-4-12 من الأرقام الستّ عشرية تفصل بينها شرطات، مثل f6e1c7b4-3a0d-4a3e-9f2b-1d8c5e4a7b90.

مستند واحد، معرّف واحد. الفاتورة والإشعار الدائن والإشعار المدين ثلاثة مستندات لها ثلاث قيم؛ ويبقى المستند على القيمة التي أُنشئ بها.

لماذا يحدث؟

مرتّبة من الأشيع إلى الأقل شيوعًا — الأرجح أن سببك في الأول أو الثاني.

XML مبني على ملف مثال بقي فيه UUID المثال كما هو — فتخرج المستندات كلها بالقيمة نفسها.
توليد المعرّف مرة واحدة عند إقلاع النظام أو في ملف الإعدادات، ثم إعادة استخدام المتغيّر طوال التشغيل.
كتابة رقم الفاتورة في الحقل: INV-2026/0042 يسقط بسبب الشرطة المائلة، وINV_42 يسقط بسبب الشرطة السفلية لأنها ليست شرطة.
تغليف القيمة: بادئة urn:uuid:، أو الأقواس المعقوفة التي تنتجها Guid.ToString("B") في .NET — النقطتان والأقواس خارج المسموح.
قيمة مؤقتة نُسيت من الاختبار مثل 00000000-0000-0000-0000-000000000000: تمرّ من شرط الحروف ولا تعرّف شيئًا، وهي أخفى هذه الأسباب.

كيف تصلحه

3 خطوات، ثم أعد إرسال الفاتورة.

1

ولّد معرّفًا لكل مستند لحظة إنشائه

ولّد UUID من النوع الرابع (v4) عند إنشاء سجل المستند، واحفظه في السجل، وأرسل القيمة المحفوظة. أما التوليد لحظة الإرسال فيعني أن كل إعادة محاولة تعطي المستند نفسه معرّفًا مختلفًا.
2

أرسله مجرّدًا

36 خانة بحروف صغيرة وشرطات: بلا بادئة urn:uuid:، وبلا أقواس، وبلا مسافات حوله. وصيغة N في .NET (32 خانة بلا شرطات) تمرّ من شرط الحروف لكنها ليست الصيغة المتعارف عليها؛ المطلوب صيغة D.
3

أبقِ رقم الفاتورة في حقله

الحقل BT-1 هو مكان INV-2026-0042، وعدّاد الفاتورة (KSA-16) حقل ثالث لا يقبل غير الأرقام — راجع BR-KSA-34. ثلاثة حقول، ثلاث وظائف، ولا قيمة مشتركة بينها.

بعد التصحيح أعد إرسال الفاتورة. الفاتورة المرفوضة لم تُسجَّل عند الهيئة، فلا تحتاج إشعارًا دائنًا — أرسل الفاتورة الصحيحة نفسها.

هل يمنعه ZATCA Tools؟

نعم، ولا سبيل للوصول إليه من عندنا: ZATCA Tools يولّد UUID من النوع الرابع عند إنشاء سجل المستند — فاتورةً كان أو إشعارًا دائنًا أو مدينًا — ويحفظه ويرسل القيمة المحفوظة. ولا تقبل شاشة ولا حقل في الـ API معرّفًا من الخارج، فلا يتكرر ولا تنكسر صيغته. وهذه الصفحة لمن يبني الربط بنفسه أو يستخدم حلًّا آخر يولّد الـ XML.

أكواد لها علاقة

BR-KSA-33 يرفض الفاتورة

عدّاد الفاتورة (ICV) غير موجود أو غير صحيح

BR-KSA-34 يرفض الفاتورة

عدّاد الفاتورة (ICV) يحمل غير الأرقام

BR-KSA-26 تحذير

بصمة الفاتورة السابقة (PIH) بصيغة غير صحيحة

أسئلة شائعة

هل الـ UUID هو رقم الفاتورة؟ +

لا، ولا يقوم أحدهما مقام الآخر. الحقل BT-1 رقم يقرؤه الإنسان وتُنظَّم به دفاترك، والحقل KSA-1 معرّف تقني في التبادل مع الهيئة. كلاهما على المستند، ووضع أحدهما مكان الآخر أشيع طريق إلى هذا الكود.

هل أستطيع استخدام رقم متسلسل من عندي بدل UUID؟ +

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

رُفضت فاتورتي — أعيد الإرسال بالمعرّف نفسه أم بجديد؟ +

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

أصلحت هذه — ولا تريد التالية

ZATCA Tools يبني التوقيع والبصمة والعدّاد والترميز عنك، ويتحقق من البيانات قبل الإرسال. مجاني بالكامل حاليًا، وبدون بطاقة ائتمانية.

ابدأ مجانًا

← كل أكواد أخطاء ZATCA