رمز الخطأ 1011: رمز QR ناقص الحقول

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

نتعمّد هنا ألّا نخلط هذا الخطأ بأخطاء رمز QR الأخرى. تلف ترميز TLV، أو تشفير Base64 الخاطئ، أو فشل المسح البصري، كلها أعطال منفصلة لها أدلتها الخاصة. الخطأ 1011 تحديدًا يقول إن بنية الرمز سليمة بما يكفي لقراءتها، لكن عدد الوسوم أقل من المطلوب. بعبارة أخرى: الرمز قابل للفك، لكنه ناقص. هذا التمييز هو مفتاح التشخيص الصحيح، ويوفّر عليك ساعات من البحث في الطبقة الخطأ.

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

ماذا يعني رمز الخطأ 1011 بالضبط؟

رمز QR في الفاتورة الإلكترونية ليس صورة، بل سلسلة بيانات مرمّزة تتكوّن من حقول متتابعة، كل حقل بصيغة وسم وطول وقيمة. تفرض مواصفة المرحلة الثانية أن يحمل الرمز تسعة وسوم بالترتيب من 1 إلى 9. حين يفكّ تطبيق «منصة فاتورة» الرمز ويجد أن أحد هذه الوسوم غائب، يطلق الخطأ 1011: رمز QR ناقص الحقول.

الوسوم التسعة تنقسم إلى مجموعتين واضحتين. الوسوم من 1 إلى 5 بيانات أساسية كانت موجودة منذ المرحلة الأولى: اسم البائع، والرقم الضريبي، والطابع الزمني، وإجمالي الفاتورة شامل الضريبة، وقيمة ضريبة القيمة المضافة. أما الوسوم من 6 إلى 9 فأضافتها المرحلة الثانية، وهي وسوم تقنية تتعلّق بالتوقيع الرقمي: قيمة تجزئة الفاتورة، والتوقيع الرقمي، والمفتاح العام، وختم الهيئة المشفّر. غياب أي واحد من التسعة يطلق الخطأ، لكن الغياب الأشيع بفارق كبير يقع في المجموعة الثانية، أي الوسوم 6 و7 و8 و9.

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

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

الوسوم التسعة وأيّها يسبّب الخطأ 1011

لتشخيص الخطأ بدقة، عليك أن تعرف ما الذي يمثّله كل وسم ومن يولّده. هذه قائمة الوسوم التسعة بالترتيب الملزم:

• الوسم 1: اسم البائع، نص يطابق الاسم المسجّل في الشهادة الضريبية.
• الوسم 2: الرقم الضريبي للبائع، خمسة عشر رقمًا يبدأ وينتهي بالرقم 3.
• الوسم 3: الطابع الزمني للفاتورة بصيغة التاريخ والوقت الدولية.
• الوسم 4: إجمالي الفاتورة شاملًا ضريبة القيمة المضافة.
• الوسم 5: قيمة ضريبة القيمة المضافة وحدها.
• الوسم 6: قيمة تجزئة الفاتورة بصيغة Base64، تربط الفاتورة بسلسلة الفواتير السابقة لمنع التلاعب.
• الوسم 7: التوقيع الرقمي للفاتورة المولّد بالمفتاح الخاص.
• الوسم 8: المفتاح العام المقابل، يستخدمه القارئ للتحقق من التوقيع.
• الوسم 9: ختم الهيئة المشفّر، وهو توقيع الهيئة على المفتاح العام لإثبات أنه صادر عن شهادة معتمدة.

الوسوم من 1 إلى 5 تكتبها أنت من بيانات الفاتورة مباشرة، فغيابها نادر ويشير عادة إلى خلل في بناء الحقول. أما الوسوم من 6 إلى 9 فلا تكتبها، بل يولّدها محرّك التوقيع بعد ربط الفاتورة بشهادة معرّف الختم المشفّر (CSID) المسجّلة لدى الهيئة. لذلك حين يطلق المدقّق الخطأ 1011، فالاحتمال الأكبر أن الناقص أحد الوسوم 6 إلى 9، وأن الجذر في طبقة التوقيع لا في كتابة البيانات.

هذا التمييز يوجّه تشخيصك مباشرة. لو كان الناقص أحد الوسوم 1 إلى 5، فابحث في كود بناء الحقول وحساب الطول. ولو كان الناقص أحد الوسوم 6 إلى 9، وهو الأشيع، فتوقّف عن فحص بناء الحقول وانتقل فورًا إلى حالة الشهادة ومحرّك التوقيع. هذا وحده يوفّر جهدًا كبيرًا، لأن كثيرًا من الفرق تضيّع وقتها في مراجعة كود الحقول بينما المشكلة لم تكن هناك أصلًا.

كيف تكشف الوسم الناقص بدقة؟

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

ابدأ باستخراج النص المرمّز بـ Base64 من الرمز، لا بالنظر إلى الصورة. النص هو ما يمكن تحليله. فكّ Base64 للحصول على السلسلة الثنائية، ثم فكّك بنية TLV بايتًا ببايت: اقرأ أول بايت كوسم، والتالي كطول، ثم اقفز عددًا من البايتات يساوي الطول لتقرأ القيمة، ثم عُد للوسم التالي. سجّل أرقام الوسوم التي ظهرت بالترتيب. إن رأيت 1، 2، 3، 4، 5 ثم توقّفت السلسلة، فالناقص هو الوسوم 6 إلى 9، وهذا يؤكّد أن المشكلة في طبقة التوقيع.

المقطع التالي يبيّن مخرج فك رمز سليم يحمل وسومه التسعة، مقابل مخرج رمز ناقص يطلق الخطأ 1011:

// sahih: al-ramz yahmil al-wusum al-tisaa kamila
{
  "tags_found": [1, 2, 3, 4, 5, 6, 7, 8, 9],
  "phase": 2,
  "valid": true
}

// khata 1011: nuqsan al-wusum 6-9 (tabaqat al-tawqee)
{
  "tags_found": [1, 2, 3, 4, 5],
  "phase": 1,
  "valid": false,
  "error_code": "1011",
  "missing": [6, 7, 8, 9]
}

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

إن لم تكن لديك أداة فك جاهزة، فابنِ مجموعة اختبار صغيرة تفكّ الرمز وتطبع قائمة الوسوم. هذه الأداة استثمار بسيط يحوّل التشخيص من تخمين بصري إلى فحص بياناتي دقيق، ويصبح بإمكانك تحديد الوسم الناقص في ثوانٍ بدل ساعات.

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

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

متى يكون الناقص من المجموعة الأولى؟

رغم أن الغياب الأشيع في الوسوم 6 إلى 9، يحدث أحيانًا أن يغيب أحد الوسوم 1 إلى 5. هذا يقع غالبًا حين يبني النظام الحقول يدويًا ويتخطّى حقلًا لأن قيمته فارغة. مثلًا، فاتورة بقيمة ضريبة صفرية قد يتخطّى فيها الكود الوسم 5 ظنًّا أن الصفر لا يحتاج إلى حقل، وهذا خطأ: الوسم إلزامي حتى لو كانت قيمته صفرًا. النتيجة رمز بثمانية وسوم بدل تسعة، فيطلق المدقّق الخطأ 1011.

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

الأسباب الجذرية للخطأ 1011

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

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

السبب الثاني: الشهادة غير مربوطة أو منتهية الصلاحية. الوسوم 6 إلى 9 تعتمد على شهادة معرّف الختم المشفّر (CSID) المسجّلة لدى الهيئة. إن لم تُربط الشهادة، أو رُبطت ثم انتهت صلاحيتها، فلا يملك محرّك التوقيع ما يولّد به التوقيع والمفتاح العام وختم الهيئة، فتغيب الوسوم. كل جهاز أو فرع يحتاج إلى شهادته الخاصة، وإغفال ربط أحدها مصدر متكرّر للخطأ.

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

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

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

الإصلاح خطوة بخطوة

الإصلاح يتبع السبب الجذري الذي حدّدته. نعرض هنا المسارين الرئيسيين بالترتيب العملي.

المسار الأول: الناقص من الوسوم 6 إلى 9 (طبقة التوقيع)

هذا المسار يعالج الحالة الأشيع، حين تظهر الوسوم 1 إلى 5 وتغيب 6 إلى 9. اتبع الخطوات بالترتيب:

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

المسار الثاني: الناقص من الوسوم 1 إلى 5 (بناء الحقول)

هذا المسار يعالج الحالة الأقل شيوعًا، حين يغيب أحد الوسوم الخمسة الأولى:

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

في كلا المسارين، القاعدة الختامية واحدة: أعد فك الرمز بعد الإصلاح وتأكّد أن الوسوم تظهر بالترتيب 1 إلى 9 دون فجوات قبل أن تعتبر المشكلة محلولة. لا تكتفِ بأن الخطأ اختفى من رسالة المدقّق، بل أثبت اكتمال الوسوم بالفك المباشر.

كيف تمنع تكرار الخطأ 1011؟

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

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

راقب صلاحية الشهادة. ضع تنبيهًا قبل انتهاء صلاحية شهادة معرّف الختم المشفّر بوقت كافٍ، لأن انتهاءها يحوّل كل الفواتير اللاحقة إلى ناقصة دفعة واحدة. تتبّع تاريخ انتهاء كل شهادة لكل جهاز وفرع.

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

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

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

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

كيف يساعدك قيود في تفادي الخطأ 1011

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

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

أسئلة شائعة

ماذا يعني رمز الخطأ 1011 بالضبط؟

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

أي الوسوم يغيب عادة في الخطأ 1011؟

الأشيع غياب الوسوم 6 و7 و8 و9: قيمة التجزئة، والتوقيع، والمفتاح العام، وختم الهيئة. هذه وسوم يولّدها محرّك التوقيع، فغيابها يشير إلى مشكلة في طبقة التوقيع أو الشهادة لا في بناء الحقول.

كيف أعرف أي وسم بالضبط هو الناقص؟

افكّ الرمز محليًا بدل النظر إلى الصورة: فكّ Base64 ثم فكّك بنية TLV وعدّ الوسوم بالترتيب. إن ظهرت 1 إلى 5 وغابت 6 إلى 9، فالمشكلة في طبقة التوقيع. وإن غاب وسم متفرّق من 1 إلى 5، فالمشكلة في بناء الحقول.

لماذا يُمسح الرمز بصريًا رغم أنه ناقص الحقول؟

لأن المسح البصري يقرأ الصورة فقط، والصورة سليمة. النقص يقع في طبقة البيانات لا في الصورة، فيُمسح الرمز بنجاح بينما يفشل التحقق عند عدّ الوسوم. سلامة الصورة لا تعني اكتمال البيانات.

هل يكفي إصلاح النظام لمعالجة الفواتير الناقصة السابقة؟

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

هل أحتاج إلى بناء رمز QR يدويًا في قيود؟

لا. يُصدر قيود الرمز تلقائيًا بوسومه التسعة كاملة على كل فاتورة ضريبية مبسّطة، بعد ربط شهادة معرّف الختم المشفّر (CSID) مرة واحدة، فلا يظهر الخطأ 1011 أصلًا.