تخطَّ إلى المحتوى
الفوترة الإلكترونية في السعودية (فاتورة)

رمز الاستجابة السريعة في الفاتورة الإلكترونية

رمز مربع مطبوع على الفاتورة يحمل بياناتها الأساسية وختمها بصيغة TLV مرمّزة بـ base64، فيتحقق منه المشتري بهاتفه.

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

كل وسم يُكتب ثلاثة أجزاء متلاصقة: بايت لرقم الوسم، وبايت لطول القيمة، ثم القيمة بترميز UTF-8. تُجمع الأوسمة في سلسلة بايتات واحدة ثم تُرمّز بـ base64، ومن هذا النص تُرسم الصورة. ويحدد معيار الأمان أن النص لا يتجاوز 700 حرف.

في المبسطة يبني جهاز البائع الرمز كاملاً لأنه هو من يختمها. أما الضريبية فتضيف منصة فاتورة رمزها أو تحدّثه عند الاعتماد. وكتلة الرمز في الـ XML مستثناة من الـ hash لأنها تحمله.

بين الوثائق الرسمية اختلاف يستحق الانتباه: معيار الأمان يصف الوسم 6 بأنه 32 بايتاً (hash ثنائي)، بينما يضع المثال المحلول في الإرشادات الفنية للوسمين 6 و7 نص base64 (44 حرفاً للـ hash). والطابع الزمني في أمثلة الهيئة ينتهي بـ Z، مع أن المعيار يسمح بالوقت المحلي دونها.

في جوداكس

مبني

نقطة البيع تطبع على كل مستند مبسط رمزاً بتسعة أوسمة، والوسمان 6 و7 نص base64 كما في مثال الإرشادات الفنية. فواتير A4 في برنامج الحسابات تطبع رمز المرحلة الأولى بخمسة أوسمة دون ختم. البرنامج يرفض أي وسم فوق 255 بايتاً لكنه لا يفحص حد الـ 700 حرف.

crates/jdx-einvoice-sa/src/xml.rs

الخطوات

  1. اجمع القيم: الاسم، الرقم الضريبي، الطابع الزمني، الإجمالي، الضريبة، ثم في المرحلة الثانية الـ hash والتوقيع والمفتاح العام وتوقيع الهيئة.
  2. لكل قيمة اكتب بايت الوسم، ثم بايت الطول (عدد بايتات القيمة بترميز UTF-8)، ثم القيمة.
  3. ألصق الأوسمة بلا فواصل، ورمّز السلسلة كلها بـ base64.
  4. ضع النص في عنصر QR داخل الـ XML، وارسم منه الصورة على النسخة المطبوعة.

أوسمة رمز QR

الوسمالاسمالمرحلةالمعنى
1اسم المورد1الاسم المسجل للبائع بترميز UTF-8، كما في حقل اسم البائع (BT-27).
2رقم تسجيل ضريبة القيمة المضافة للمورد1الرقم الضريبي للبائع من 15 رقماً (BT-31).
3الطابع الزمني للفاتورة أو للإشعار (التاريخ والوقت)1تاريخ الإصدار ووقته بصيغة ISO 8601؛ مثال معيار الأمان 2022-02-21T12:13:57Z. البرنامج يكتب في المرحلة الثانية الوقت المحلي بلا Z مطابقاً لحقلي التاريخ والوقت، وفي رمز المرحلة الأولى الوقت العالمي مع Z.
4إجمالي الفاتورة أو الإشعار (مع ضريبة القيمة المضافة)1الإجمالي شاملاً الضريبة (BT-112) كنص رقمي.
5إجمالي ضريبة القيمة المضافة1إجمالي الضريبة؛ أوضح الإصدار 1.2 من معيار الأمان أنه القيمة في الحقل BT-110.
6دالة تشفير (Hash) لفاتورة أو إشعار XML2hash المستند. معيار الأمان يذكر أن طوله 32 بايتاً، بينما يضع المثال المحلول في الإرشادات الفنية نص base64 من 44 حرفاً، وهو ما يفعله البرنامج.
7ختم التشفير2توقيع ECDSA على hash المستند. في المبسطة يولّده جهاز البائع، وفي الضريبية منصة الهيئة. البرنامج يكتبه نص base64 كما في مثال الإرشادات الفنية.
8المفتاح العام المستعمل لإنشاء ختم التشفير2المفتاح العام المقابل لمفتاح التوقيع. البرنامج يكتب بنية SubjectPublicKeyInfo كاملة بصيغة DER (88 بايتاً لمنحنى secp256k1)، كما في مثال الإرشادات الفنية.
9ختم التشفير الخاص للمنصة المستخدمة من قبل الهيئة للمفتاح العام للحل التقني2للمبسطة وإشعاراتها فقط: توقيع جهة إصدار الشهادات في الهيئة على شهادة الجهاز، يُنسخ من الشهادة نفسها. في وضع الاختبار المحلي يكون توقيعاً ذاتياً لا توقيع الهيئة.

أسئلة وأجوبة

لماذا يقرأ تطبيق الهيئة الاسم العربي مشوهاً؟

غالباً لأن الاسم رُمّز بغير UTF-8، أو لأن الطول كُتب بعدد الحروف لا بعدد البايتات؛ الحرف العربي بايتان.

هل يكفي رمز المرحلة الأولى بعد الانضمام إلى المرحلة الثانية؟

لا. بعد الربط يجب أن يحمل المستند أوسمة المرحلة الثانية، والوسم التاسع للمبسطة وإشعاراتها فقط.

صفحات ذات صلة

مفاهيم ذات صلة

الفوترة الإلكترونية في السعودية (فاتورة)

المصادر

  1. Security Features Implementation Standards to the E-Invoicing resolution dated 2023-05-19 (v1.2) — ZATCA
  2. E-invoicing Detailed Technical Guidelines (vVersion 2) — ZATCA
  3. الضوابط والمتطلبات والمواصفات الفنية والقواعد الإجرائية اللازمة لتنفيذ أحكام لائحة الفوترة الإلكترونية (قرار المحافظ رقم 62738 وتاريخ 1443/11/23هـ) (vfile dated 20230519 (decision 62738)) — ZATCA
  4. Electronic Invoice XML Implementation Standard to the E-Invoicing resolution dated 2023-05-19 (v1.2) — ZATCA

تاريخ المراجعة: 4 نوفمبر 2026. ما يخص جوداكس مأخوذ من شيفرة البرامج نفسها.