رمز الاستجابة السريعة في الفاتورة الإلكترونية
رمز مربع مطبوع على الفاتورة يحمل بياناتها الأساسية وختمها بصيغة 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
الخطوات
- اجمع القيم: الاسم، الرقم الضريبي، الطابع الزمني، الإجمالي، الضريبة، ثم في المرحلة الثانية الـ hash والتوقيع والمفتاح العام وتوقيع الهيئة.
- لكل قيمة اكتب بايت الوسم، ثم بايت الطول (عدد بايتات القيمة بترميز UTF-8)، ثم القيمة.
- ألصق الأوسمة بلا فواصل، ورمّز السلسلة كلها بـ base64.
- ضع النص في عنصر 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) لفاتورة أو إشعار XML | 2 | hash المستند. معيار الأمان يذكر أن طوله 32 بايتاً، بينما يضع المثال المحلول في الإرشادات الفنية نص base64 من 44 حرفاً، وهو ما يفعله البرنامج. |
| 7 | ختم التشفير | 2 | توقيع ECDSA على hash المستند. في المبسطة يولّده جهاز البائع، وفي الضريبية منصة الهيئة. البرنامج يكتبه نص base64 كما في مثال الإرشادات الفنية. |
| 8 | المفتاح العام المستعمل لإنشاء ختم التشفير | 2 | المفتاح العام المقابل لمفتاح التوقيع. البرنامج يكتب بنية SubjectPublicKeyInfo كاملة بصيغة DER (88 بايتاً لمنحنى secp256k1)، كما في مثال الإرشادات الفنية. |
| 9 | ختم التشفير الخاص للمنصة المستخدمة من قبل الهيئة للمفتاح العام للحل التقني | 2 | للمبسطة وإشعاراتها فقط: توقيع جهة إصدار الشهادات في الهيئة على شهادة الجهاز، يُنسخ من الشهادة نفسها. في وضع الاختبار المحلي يكون توقيعاً ذاتياً لا توقيع الهيئة. |
أسئلة وأجوبة
لماذا يقرأ تطبيق الهيئة الاسم العربي مشوهاً؟
غالباً لأن الاسم رُمّز بغير UTF-8، أو لأن الطول كُتب بعدد الحروف لا بعدد البايتات؛ الحرف العربي بايتان.
هل يكفي رمز المرحلة الأولى بعد الانضمام إلى المرحلة الثانية؟
لا. بعد الربط يجب أن يحمل المستند أوسمة المرحلة الثانية، والوسم التاسع للمبسطة وإشعاراتها فقط.
صفحات ذات صلة
- KSA-14 رمز الاستجابة السريعة (QR Code)
- BT-27 اسم المورد
- BT-31 رقم تسجيل ضريبة القيمة المضافة
- BT-112 إجمالي قيمة الفاتورة (شامل ضريبة القيمة المضافة)
- BT-110 إجمالي ضريبة القيمة المضافة
- BR-KSA-27 · يجب أن يحمل المستند رمز استجابة سريعة بترميز base64.
مفاهيم ذات صلة
- ختم التشفير (التوقيع الرقمي) في الفاتورةتوقيع ECDSA بصيغة XAdES على hash المستند وخصائص التوقيع، بمفتاح جهاز مسجل وشهادة من الهيئة.
- hash الفاتورة: كيف يُحسببصمة SHA-256 للمستند بعد حذف كتل الختم والرمز وتوحيد صيغته، تُكتب بـ base64، وعليها يقوم الختم والسلسلة.
- المرحلة الأولى (الإصدار) والمرحلة الثانية (الربط والتكامل)المرحلة الأولى منذ 4 ديسمبر 2021 تشترط إصدار الفواتير وحفظها إلكترونياً، والثانية منذ 1 يناير 2023 على موجات تضيف صيغة XML والختم والربط مع منصة فاتورة.
الفوترة الإلكترونية في السعودية (فاتورة)
المصادر
- Security Features Implementation Standards to the E-Invoicing resolution dated 2023-05-19 (v1.2) — ZATCA
- E-invoicing Detailed Technical Guidelines (vVersion 2) — ZATCA
- الضوابط والمتطلبات والمواصفات الفنية والقواعد الإجرائية اللازمة لتنفيذ أحكام لائحة الفوترة الإلكترونية (قرار المحافظ رقم 62738 وتاريخ 1443/11/23هـ) (vfile dated 20230519 (decision 62738)) — ZATCA
- Electronic Invoice XML Implementation Standard to the E-Invoicing resolution dated 2023-05-19 (v1.2) — ZATCA
تاريخ المراجعة: 4 نوفمبر 2026. ما يخص جوداكس مأخوذ من شيفرة البرامج نفسها.