شرح رمز QR في ZATCA: حقول TLV التسعة، والفرق بين المرحلتين الأولى والثانية، وطريقة فحصه

ما هو رمز QR فعلًا

رمز QR على الفاتورة الإلكترونية السعودية ليس رابطًا وليس صورة للفاتورة. إنه كتلة قصيرة من البيانات، مرمَّزة بـ Base64، يستطيع الهاتف قراءتها دون اتصال بالإنترنت.

تستخدم البيانات بداخله صيغة تُسمى TLV: الوسم (Tag)، والطول (Length)، والقيمة (Value). يُكتب كل حقل في ثلاثة أجزاء متتالية:

• الوسم: بايت واحد يحدد أي حقل هذا (1 لاسم البائع، و2 للرقم الضريبي، وهكذا).
• الطول: بايت واحد يحدد عدد البايتات التي تشغلها القيمة.
• القيمة: الحقل نفسه، مرمَّزًا بـ UTF-8.

تُضم الحقول كلها دون مسافات أو فواصل، ثم تُرمَّز سلسلة البايتات كاملة بـ Base64. ويضع الدليل الفني لـ ZATCA حدًا أقصى قدره 700 حرف لنص Base64 النهائي.

حقول TLV التسعة

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

تجزئة الفاتورة في الوسم 6 هي تجزئة SHA-256 لفاتورة XML. ويوضح معيار الأمان لدى ZATCA أن التجزئة تستثني امتدادات UBL وكتلة التوقيع وعنصر QR نفسه، وهذا منطقي: لا يمكن أن يحتوي رمز QR على تجزئة لنفسه.

المرحلة الأولى مقابل المرحلة الثانية

طبّقت ZATCA الفوترة الإلكترونية على مرحلتين، وتغيّر رمز QR معهما.

المرحلة الأولى (الإصدار) بدأت في 4 ديسمبر 2021. كان يجب إصدار الفواتير من نظام متوافق، وكان يجب أن تحمل الفواتير الضريبية المبسطة (B2C) رمز QR بالحقول الخمسة الأساسية. ويذكر الدليل التفصيلي لـ ZATCA بوضوح أن رمز QR لم يكن إلزاميًا على الفواتير الضريبية (B2B) في هذه المرحلة.

المرحلة الثانية (الربط والتكامل) بدأت في 1 يناير 2023 وتُطبَّق على موجات، إذ يُدخَل المكلّفون حسب حد الإيرادات. إذا كانت شركتك في أحدث مجموعة، فاطّلع على ملاحظتنا حول الموجة 25 لـ SAP Business One. في المرحلة الثانية يكتسب رمز QR الوسوم من 6 إلى 9، وتعتمد القواعد على نوع الفاتورة:

الخلاصة العملية لفواتير B2B: يجب أن تستخدم فاتورتك المطبوعة أو بصيغة PDF رمز QR العائد من ZATCA بعد الاعتماد، لا رمزًا أنشأه نظامك قبل الإرسال. أما في B2C فينشئ نظامك رمز QR الكامل بنفسه لحظة البيع.

مثال تطبيقي

هذا نص QR بأسلوب المرحلة الأولى لفاتورة بقيمة 1,000 ريال زائد ضريبة القيمة المضافة 15%، مبني من القيم المثال في الجدول أعلاه:

AQ9BbCBOb29yIFRyYWRpbmcCDzMwMDAwMDAwMDAwMDAwMwMUMjAyNi0xMC0xNlQxMDoxNTowMFoEBzExNTAuMDAFBjE1MC4wMA==

إذا فككت ترميز البايتات الأولى سترى 01 0F يليهما اسم البائع. 01 هو الوسم 1. و0F يساوي 15 بالنظام الست عشري، وهو عدد البايتات في “Al Noor Trading”. ثم يأتي 02 0F والرقم الضريبي المكوّن من 15 رقمًا، وهكذا حتى الوسم 5.

الصق هذا النص في أداة فك ترميز رمز QR لـ ZATCA المجانية وسترى الحقول الخمسة معروضة واحدًا تلو الآخر.

كيف تفحص رمز QR على فاتورتك

استخدم هذه الخطوات عندما يشتكي عميل من أن ماسحه يعرض «رمز QR غير صالح»، أو عندما تختبر تصميم فاتورة جديدًا.

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

يؤكد فك الترميز البنية والحقول المقروءة، لكنه لا يثبت أن التوقيع في الوسمين 7 و9 أصلي. فهذا الفحص يحتاج ملف XML الموقّع والتحقق الخاص بـ ZATCA، الذي يتم عبر SDK أو بواسطة المنصة أثناء الاعتماد والإبلاغ.

أخطاء شائعة في رمز QR

يسرد الدليل الفني لـ ZATCA بعض الأخطاء التي تتكرر مرارًا. ونرى الأخطاء نفسها عند مراجعة تصاميم الفواتير:

• اسم البائع العربي غير مرمَّز بـ UTF-8. يظهر الاسم عند المسح علامات استفهام أو أحرفًا مشوّهة.
• حساب الطول بالأحرف لا بالبايتات. الاسم العربي المكوّن من 10 أحرف يساوي نحو 20 بايت. إذا قال بايت الطول 10، فكل وسم بعده يُقرأ خطأً.
• فواصل بين الحقول. الفواصل أو المسافات أو الحشو بين مجموعات TLV تُفسد فك الترميز. يجب ألا يوجد أي منها.
• مبالغ لا تطابق الفاتورة. غالبًا يُبنى رمز QR من المجموع الفرعي، أو من أرقام قبل خصم على مستوى المستند.
• طباعة رمز QR الخطأ على فواتير B2B. في المرحلة الثانية يجب أن يكون رمز QR المعتمد من ZATCA هو الموجود على المستند.

في SAP Business One تُخزَّن قيمة QR عادةً على فاتورة المبيعات (في حقل معرّف من قِبل المستخدم أو في بيانات المستند الإلكتروني) وتُطبع عبر Crystal Reports أو مصمم تخطيط الطباعة (PLD) كباركود أو صورة. عندما يفشل الرمز المطبوع، تحقق أولًا من القيمة المخزنة باستخدام أداة فك ترميز TLV. إذا كانت القيمة المخزنة صحيحة، فالمشكلة في التصميم لا في التكامل.

موقع رمز QR في المرحلة الثانية

رمز QR هو النهاية المرئية لعملية أطول: ملف UBL 2.1 XML، والتجزئة، والتوقيع بشهادة CSID الخاصة بك، والاعتماد أو الإبلاغ عبر واجهات ZATCA البرمجية. إذا كانت أي خطوة من هذه خاطئة، فغالبًا يكون رمز QR خاطئًا أيضًا. يغطي دليل الفوترة الإلكترونية لـ ZATCA المسار الكامل، وتساعدك حاسبة ضريبة القيمة المضافة السعودية عندما تحتاج إلى التحقق يدويًا من الوسمين 4 و5.

إذا كانت فواتير SAP Business One لديك تطبع رمز QR يرفضه العملاء أو ZATCA، فأرسل لنا عيّنة وسنخبرك بالجزء الذي يفشل.

المصادر

• ZATCA: الدليل الفني التفصيلي للفوترة الإلكترونية، الإصدار 2 (نوفمبر 2022)
• ZATCA: الدليل التفصيلي للفوترة الإلكترونية، الإصدار 2 (مايو 2023)
• ZATCA: معايير تطبيق ميزات أمان الفاتورة الإلكترونية (19 مايو 2023)
• مجتمع مطوري ZATCA: بنية رمز QR للفواتير الضريبية الإلكترونية
• ZATCA: صفحة أدلة الفوترة الإلكترونية

خدمات ذات صلة

• تكامل الفوترة الإلكترونية
• تطوير SAP Business One