جدول المحتويات
دعنا نوضح مفهومًا خاطئًا كبيرًا على الفور: لا يمكنك إنشاء فاتورة إلكترونية سعودية رسمية بمجرد كتابة البيانات في مولد رموز QR عبر الإنترنت.
بناء نظام ERP أو نقطة بيع (POS) يتوافق مع هيئة الزكاة والضريبة والجمارك (ZATCA) هو مسعى هندسي برمجي معقد. بصفتي مهندس نظم مقيم في الرياض صمم مؤخراً حلولاً تقنية لأنظمة نقاط البيع غير المتصلة بالإنترنت والتي تربط المرحلة الأولى بالمرحلة الثانية، يمكنني أن أخبرك أن التحدي الحقيقي ليس رسم رسم QR البياني — بل هو المنطق التشفيري الصارم المطلوب لإنشاء السلسلة الأساسية.
حقيقة الامتثال لهيئة الزكاة
إذا قام العميل بمسح إيصالك المطبوع باستخدام تطبيق ZATCA الرسمي وأظهر خطأ "رمز QR غير صالح"، فالمشكلة ليست في الطابعة. المشكلة في قاعدة التعليمات البرمجية الخاصة بك.
تتطلب هيئة الزكاة من نظام ERP الخاص بك أخذ بيانات الفاتورة المحددة (اسم الشركة، الرقم الضريبي، الطابع الزمني، الإجمالي، وقيمة الضريبة)، وتشفيرها في مصفوفة بايتات دقيقة باستخدام طريقة (TLV) Tag-Length-Value، وتجزئتها، وتوقيعها، ثم تحويل تلك المصفوفة بأكملها إلى سلسلة Base64. عندها فقط يتم تحويل سلسلة Base64 هذه إلى رمز QR.
تشريح تشفير TLV
في المرحلة الأولى، كان المتطلب بسيطًا نسبيًا. كان عليك بناء مصفوفة بايتات تعين 5 علامات أساسية. يعمل TLV تمامًا كما يبدو:
- العلامة (Tag) (1 بايت): المعرف (مثل
01لاسم البائع). - الطول (Length) (1 بايت): طول القيمة بالبايت (مثل
0Fلـ 15 بايت). - القيمة (Value) (متغير): البيانات الفعلية المشفرة بـ UTF-8 (مثل
Mahwar KSA).
def get_tlv_hex(tag: int, value: str) -> str:
val_bytes = value.encode('utf-8')
tag_hex = f"{tag:02x}"
length_hex = f"{len(val_bytes):02x}"
val_hex = val_bytes.hex()
return tag_hex + length_hex + val_hex
التحول التشفيري في المرحلة الثانية (مرحلة الربط والتكامل)
المرحلة الثانية تربط نظام ERP الخاص بك مباشرة بمنصة فاتورة. أصبحت قواعد إنشاء رموز QR أكثر صعوبة بشكل كبير. تتطلب ZATCA الآن علامات إضافية (العلامات 6-9) لضمان موثوقية وتسلسل الفاتورة:
- العلامة 6 (تجزئة XML للفاتورة): تجزئة SHA-256 لفاتورة XML التي تم إنشاؤها.
- العلامة 7 (توقيع ECDSA): توقيع تشفيري تم إنشاؤه باستخدام المفتاح الخاص للمكلف.
- العلامة 8 (المفتاح العام لـ ECDSA): المفتاح العام المطابق للمفتاح الخاص المستخدم لتوقيع الفاتورة.
- العلامة 9 (توقيع الختم التشفيري): تقدمه هيئة الزكاة نفسها عند التخليص الناجح عبر واجهة برمجة التطبيقات (API).
إذا كانت مصفوفة البايتات الخاصة بك خاطئة بحرف واحد، أو إذا حاولت تشفير السلسلة باستخدام ASCII بدلاً من تحويلات UTF-8 السداسية العشرية الصارمة، فسيتم رفض سلسلة Base64 الناتجة من قبل تطبيق ماسح ZATCA.
معضلة اختبار الجودة (QA) للمطورين
عندما تكتب منطق الواجهة الخلفية في Odoo أو سلة أو غلاف Python مخصص، ستقوم بإنشاء مئات من سلاسل Base64 الاختبارية. لضمان صحة التشفير، يجب عليك مسح رموز QR الناتجة فعليًا باستخدام تطبيق ZATCA المحمول الرسمي. ولكن كيف تختبر 500 سلسلة Base64 بسرعة دون بناء أداة عرض واجهة أمامية خاصة بك من الصفر؟
اختبار سلاسل Base64 دفعة واحدة محلياً
هنا بالضبط يعمل BulkBarcode Generator كبيئة اختبار (Sandbox) حاسمة للمطورين السعوديين.
لم نقم ببناء هذه الأداة لإنشاء الفواتير. بل بنيناها حتى يتمكن مهندسو البرمجيات من اختبار مخرجات أنظمة ERP الخاصة بهم بسرعة. باستخدام مساحة العمل الخاصة بنا من جانب العميل، يمكن لفريق التطوير الخاص بك تجاوز متاعب كتابة نصوص العرض المحلية والتركيز فقط على إصلاح التشفير الخاص بهم.
سير عمل الاختبار الآمن:
- استخراج التجزئة: استعلم عن قاعدة بيانات ERP الخاصة بك واسحب قائمة بـ 500 سلسلة Base64 اختبارية تم إنشاؤها بواسطة الواجهة الخلفية.
- اللصق والعرض: الصق هذه القائمة مباشرة في مساحة عمل "لصق SKU". نظرًا لأن محركنا يعمل بالكامل على WebAssembly داخل متصفحك، فإن تجزئاتك وبيانات TLV الاختبارية لا تترك جهاز الكمبيوتر الخاص بك أبدًا.
- المسح والتحقق: تعرض مساحة العمل على الفور 500 رمز QR عالي الدقة على شاشتك. يمكنك أخذ هاتفك المحمول، وفتح تطبيق ZATCA الرسمي، ومسحها مباشرة من الشاشة للتحقق من أن تشفير TLV عبر Python أو JS يعمل بلا عيوب.
بمجرد اجتياز برنامجك لاختبار الجودة، سيتولى نظام ERP الخاص بك الفوترة الإلكترونية لهيئة الزكاة تلقائيًا في محطة نقاط البيع (POS). يمكنك بعد ذلك حجز مساحة عمل BulkBarcode لما تفعله بشكل أفضل: تنسيق ملصقات أرفف المستودعات المادية، وعلامات تتبع GS1، وتوجيه لوجستيات سلسلة التبريد.
اختبر جودة (QA) تجزئات Base64 الخاصة بك
الصق مخرجات Base64 لنظام ERP الخاص بك في محرك العرض الآمن من جانب العميل لإنشاء رموز QR قابلة للمسح فوراً لاختبار منصة فاتورة.