شارع المشتري (BT-50) بلا قيمة، أو أطول من الحد

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

ما تعيده واجهة الهيئة المباشرة نصًّا: [BR-KSA-F-06-C23] - Field character limits for the Buyer Address - Street field (BT-50) have not been met. The minimum limit is 1 character and the maximum limit is 127 characters.

والنص المطبوع أعلى هذه الصفحة مأخوذ من مستخرج SDK الذي نفهرسه، وفيه الحدّ الأعلى لهذا الحقل 1000 لا 127. الفرق في الحدّ الأعلى وحده — والحدّ الأدنى، محرف واحد، هو نفسه في الاثنين وهو الذي يُخفق عمليًا. ولم نعدّل المستخرج ليطابق ما رأيناه: هو نصّ الهيئة كما شُحن في أدواتها، والفرق بين النصّين معلومة تخصّك، لا خطأ يُصحَّح بالكتابة فوقه. فإن كتبت شارعًا طويلًا فاحسب على 127 لا على 1000.

الحقل هو BT-50، أي cbc:StreetName داخل cac:AccountingCustomerParty/cac:Party/cac:PostalAddress. والقاعدة لا تسأل «هل للمشتري شارع؟» — ذلك سؤال قواعد الوجود — بل تقيس عدد المحارف: أقلّ من واحد يُخفق، وأكثر من الحدّ الأعلى يُخفق.

وصفر محرف هو ما يقدّمه شيئان لا شيء واحد: عنصر كُتب فارغًا مثل <cbc:StreetName/> من عمود خالٍ في قاعدة البيانات، وعنصر لم يُكتب أصلًا. فاتورتان قياسيتان مرّتا على واجهة الهيئة المباشرة في يوم واحد أوضحتا ذلك: المستند الذي يولّده ZATCA Tools لا يكتب عنصر عنوان فارغًا في أي مسار — الجزء الذي لا قيمة له يُحذف قبل بناء الملف، وهذا مُثبت باختبار في المستودع — ومع ذلك عاد هذا التحذير على الفاتورة التي خلا عنوان مشتريها من كل شيء. فلا تبنِ على أن حذف العنصر يُسكت قاعدة الطول؛ الذي رأيناه أن الغياب يخفق في الحدّ الأدنى كما يخفق الفراغ.

وتجاورها قاعدتا وجود يعودان معها في الرد نفسه: BR-KSA-10 تطلب الشارع والمدينة ورمز الدولة في الفاتورة الضريبية وإشعاراتها، وBR-KSA-63 تطلب ستة عناصر متى كان رمز دولة المشتري SA. الثلاثة تحذيرات، وثلاثتها تتكلم عن الشارع من ثلاث جهات: واحدة تقول إنه غير موجود، وهذه تقول إن طوله صفر، والثالثة تحصي العناصر الستة. وتصحيح واحد — شارع حقيقي في خانته — يُسكتها جميعًا.

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

لماذا يحدث؟

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

• عمود شارع فارغ يُكتب عنصرًا على أي حال: القالب يطبع <cbc:StreetName> في كل فاتورة، فيخرج <cbc:StreetName/> حين لا يكون في العمود شيء. هذا أشيع سبب في الأنظمة التي تبني XML من قالب نصّي بدل أن تبنيه عنصرًا عنصرًا.
• قيمة من مسافات أو سطر جديد: الحقل «غير فارغ» في قاعدة بياناتك، وطوله بعد تسوية المسافات صفر.
• العنوان كله في حقل واحد — «العنوان» أو «الوصف» — بينما عمود الشارع القائم بذاته بقي فارغًا، فيخرج ممتلئًا في غير موضعه وفارغًا في موضعه.
• الحدّ الأعلى من الجهة الأخرى: عنوان كامل لُصق في خانة الشارع. الواجهة المباشرة أعادت 127 محرفًا حدًّا أعلى، وسطر عنوان عربي كامل يتجاوزها بسهولة.
• استيراد عملاء من جدول بيانات فيه عمود للشارع وخلاياه خالية، فتُكتب سلسلة فارغة بدل قيمة غائبة.
• ربط يكتب null سلسلةً فارغة عند التحويل إلى XML — سلوك افتراضي في كثير من مكتبات التسلسل، ولا يظهر إلا في رد الهيئة.

كيف تصلحه

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

1. 1
   اكتب شارعًا حقيقيًا — فهو وحده ما يُسكت القاعدة

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

2. 2
   وإن لم تكن عندك قيمة، فالحذف أفضل من الفراغ

   العنصر الفارغ يخسر مرتين: يخفق في القاعدة، ويترك في مستند موقَّع عنصرًا لا يعني شيئًا — وهو ما يقرؤه مدقّق أو نظام محاسبة المشتري لاحقًا. والعنصر الغائب يخفق في القاعدة وحدها، والمستند يبقى صادقًا في وصف ما تعرفه. فاجعل مُولِّد XML يكتب العنصر حين تكون له قيمة لا قبل ذلك، ولا تملأه بشرطة ولا بنقطة ولا بكلمة «لا يوجد»: تلك قيم تستوفي محرفًا واحدًا وتقول على المشتري ما ليس صحيحًا، والتحذير كان أصدق منها.

3. 3
   الفائض مكانه الشارع الإضافي لا الشارع

   إن كان سطر العنوان أطول من الحدّ فقسّمه كما قسّمه المعيار: الشارع في BT-50، وما زاد عليه — رقم وحدة، علامة مميزة، اسم مجمّع — في الشارع الإضافي BT-51، أي cbc:AdditionalStreetName، وحدّه الأعلى 127 محرفًا بنصّ BR-KSA-F-06-C11. والقصّ الأعمى عند الحدّ ليس حلًّا: يُنتج عنوانًا مبتورًا على مستند ضريبي.

4. 4
   صحّح سجل العميل — والمستند الصادر لا يُعاد

   الفاتورة التي حملت التحذير مُجازة ولا تحتاج إعادة إصدار لتُقبل. صحّح الشارع في سجل العميل فتخرج فواتيره التالية نظيفة. وما دمت في العنوان فأكمل بقيته: المدينة بنصّ BR-KSA-F-06-C25، والحي بنصّ BR-KSA-F-06-C28، والرمز البريدي خمسة أرقام بنصّ BR-KSA-67.

هذا الكود لا يمنع القبول، فالفاتورة الحالية نظامية. صحّح البيانات لتختفي التحذيرات من الفواتير القادمة.

أسئلة شائعة