معمارية الربط والتكامل مع منظومة الفوترة الإلكترونية السعودية (ZATCA Phase 2 FATOORA)
التوقيع الرقمي ECDSA secp256k1، وتشفير XML C14N، وسلسلة الكتل السابقة PIH، ورمز الاستجابة 9-Tag QR
مؤشرات الأداء الفعلية وبنود كفاءة الخدمة (ZATCA KPIs)
إتمام المعايرة C14N وتوقيع ECDSA وتوليد 9-Tag TLV دون اتصال خارجي
مفتاح 256 بت مطابق لمعايير FIPS 186-4 واشتراطات هيئة الزكاة
قفل تسلسلي يمنع تداخل الهاش السابق ويحمي الدفاتر من التلاعب
تفريغ طابور الفواتير المبسطة خلال أقل من 24 ساعة من الإصدار
الملخص التنفيذي (Executive Summary)
توثيق معماري وهندسي شامل لبناء وتشغيل محرك الفوترة الإلكترونية المتوافق مع متطلبات المرحلة الثانية (مرحلة الربط والتكامل FATOORA) لهيئة الزكاة والضريبة والجمارك (ZATCA) في المملكة العربية السعودية، مع تحقيق زمن تشفير دون 160 ملي ثانية للفواتير المبسطة، وتأمين سلاسل الكتل غير القابلة للتلاعب عبر تجزئة SHA-256 السابقة PIH، وتوليد الأختام المشفرة 9-Tag TLV QR، وإدارة طوابير الاعتماد اللحظي B2B والإبلاغ خلال 24 ساعة B2C دون التأثير على سرعة نقطة البيع أو المتجر الإلكتروني.
التحدي الهندسي وظروف التشغيل الواقعية (Problem Statement)
تفرض هيئة الزكاة والضريبة والجمارك بالمملكة معايير تشفير صارمة للمرحلة الثانية من الفوترة؛ حيث يؤدي أي خطأ في معايرة XML C14N أو تسلسل الهاش السابق (PIH) أو عدم تطابق توقيع ECDSA secp256k1 مع شهادة الإنتاج PCSID إلى رفض فوري للفاتورة بغرامات مالية وتعطيل إتمام صفقات الشركات B2B. علاوة على ذلك، فإن الاعتماد على الاستدعاء المباشر لخوادم الهيئة في فواتير التجزئة B2C يعرض الكاشير والمتجر للتوقف التام عند انقطاع الإنترنت أو بطء الشبكة.
المعمارية العامة للنظام وتدفق العمليات (Architectural Overview)
تصميم منظومة فوترة هجينة تعتمد على الفصل بين التوقيع الرقمي اللحظي وإرسال الفواتير السحابي. يتم توليد زوج المفاتيح التشفيرية ECDSA secp256k1 محلياً واستخراج شهادة الإنتاج PCSID عبر دورة الاعتماد الرسمية. تقوم النواة المحلية بتنظيف مستند UBL 2.1 XML ومعايرته وفق C14N 1.1، وحساب هاش SHA-256، وربطه بسلسلة الفواتير السابقة عبر PIH المخزن محلياً، ثم توقيع المستند بمعيار XAdES-BES وتوليد رمز الاستجابة السريعة ذي الـ 9 وسوم المشفرة بـ Base64 TLV في أقل من 160ms. يتولى طابور خلفي ذو أقفال موزعة (FIFO Queue per EGS) إرسال الفواتير الأساسية فورياً عبر Clearance API، بينما يفرغ فواتير التجزئة المبسطة عبر Reporting API خلال مهلة الـ 24 ساعة مع خوارزمية Exponential Backoff لضمان عدم فقد أي معاملة.
معمارية النظام: معمارية الربط والتكامل مع منظومة الفوترة الإلكترونية السعودية (ZATCA Phase 2 FATOORA)
معمارية متكاملة لربط الفوترة الإلكترونية ZATCA Phase 2 تفصل التوقيع المحلي عن النقل السحابي
1. طبقة نقطة البيع والمتجر الإلكتروني (EGS Storefront & POS Tier)
تنشئ كائن الفاتورة المالي وتسجله في قاعدة البيانات المحلية في أقل من 50 ملي ثانية.
2. طبقة المعايرة وتجزئة الهاش (C14N Cleansing & SHA-256 Hashing)
تستبعد وسوم التوقيع والـ QR وتولد الهاش المعياري الفريد الذي يمثل هوية الفاتورة الرقمية.
3. طبقة التوقيع وسلسلة الكتل (ECDSA secp256k1 & PIH Chain Ledger)
تربط الفاتورة بهاش الفاتورة السابقة PIH وتوقع المستند بمفتاح المنشأة المشفر وفق أعلى المعايير.
4. طبقة تشفير الاستجابة السريعة (9-Tag Base64 TLV Generator)
تدمج اسم المورد، الرقم الضريبي، التوقيت، الإجمالي، الضريبة، الهاش، التوقيع، المفتاح العام، وختم الهيئة.
5. طبقة بوابات الربط السحابي (ZATCA Clearance & Reporting Gateway)
تتولى اعتماد فواتير الشركات B2B فورياً وإبلاغ فواتير التجزئة B2C خلال 24 ساعة بأمان تام.
تسلسل مسار تدفق البيانات (Data Flow Lifecycle)
- 11. يقوم العميل بإتمام الطلب؛ يُنشأ مستند الفاتورة بصيغة UBL 2.1 XML مع جلب الهاش السابق PIH من السجل المحلي.
- 22. يستبعد محرك المعايرة وسوم التوقيع والـ QR، ويطبق C14N 1.1، ويحسب هاش SHA-256 الموحد للفاتورة.
- 33. يوقع محرك ECDSA secp256k1 الهاش، ويحقن بنية XAdES-BES والشهادة الرقمية PCSID داخل مستند الـ XML.
- 44. تُشفر مصفوفة الـ 9 وسوم TLV بصيغة Base64 وتُحقن في الفاتورة وتُطبع على إيصال العميل في أقل من 160ms.
- 55. إذا كانت الفاتورة B2B تُرسل فورياً إلى Clearance API للاعتماد، وإن كانت B2C تُدرج في طابور Reporting للإرسال خلال 24 ساعة.
مكونات النظام البرمجية وآليات المتانة (System Components & Resilience)
جدول يوضح دور كل مكون برمجي، تقنيات بنائه، وآلية الاستمرارية المقاومة للأعطال في منظومة ZATCA Phase 2:
| المكون البرمجي | الدور الوظيفي في المعمارية | التقنيات المستخدمة | آلية مقاومة الفشل (Resilience) |
|---|---|---|---|
| خزنة المفاتيح ومحرك التشفير (ECDSA Cryptographic Vault) | توليد وإدارة زوج المفاتيح secp256k1 وإنشاء طلب الشهادة CSR وتخزين المفتاح الخاص بأمان تام | Node.js Crypto / OpenSSL 3.0 مع تشفير AES-256 للبيئة المعزولة | عزل المفتاح الخاص في خادم محلي أو Cloud HSM مع منع تصديره برمجياً |
| معاير XML ومولد الهاش (UBL 2.1 C14N & Hash Core) | تنظيف مستند الفاتورة واستبعاد وسوم التوقيع وتطبيق معيار C14N 1.1 وحساب هاش SHA-256 | Canonical XML 1.1 Parser مع XPath Filter ومعيار OASIS UBL 2.1 | مطابقة صارمة لمخططات Schematron وقواعد العمل ZATCA Business Rules محلياً |
| محرك التوقيع الرقمي ومولد الـ QR (XAdES-BES & 9-Tag TLV Engine) | حقن توقيع XAdES-BES داخل مستند XML وتوليد مصفوفة TLV الثنائية المشفرة Base64 بـ 9 حقول | XMLDSig Enveloped Signature مع ترميز TLV الثنائي المخصص | فحص ذاتي للتوقيع ومطابقته بالمفتاح العام قبل إخراج الفاتورة للكاشير |
| طابور الإرسال وضابط التسلسل (ZATCA Sequential Outbox Broker) | إدارة استدعاءات Clearance API اللحظية للفواتير الضريبية وReporting API للفواتير المبسطة | PostgreSQL Outbox Table مع Redis Distributed Lock (Redlock) وBullMQ | معالجة FIFO أحادية الخيط لكل وحدة EGS تمنع كسر سلسلة الـ PIH مع Exponential Backoff |
بروتوكولات التبديل الآلي وأهداف التعافي (Failover Protocols: RTO & RPO)
كيف يتعامل النظام مع سيناريوهات الفشل وانقطاع الشبكات أو تعارض السلاسل دون التأثير على عمليات نقطة البيع:
سيناريو الفشل: انقطاع كامل في شبكة الإنترنت أو بطء استجابة خوادم منصة فاتورة ZATCA
استراتيجية المعالجة والتحويل: استمرار إصدار الفواتير المبسطة B2C للعملاء محلياً بتوقيعها الرقمي ورمز 9-Tag QR المكتمل دون توقف، مع حفظها في طابور الإبلاغ الآمن وتفريغها تلقائياً بجدولة Exponential Backoff فور عودة الشبكة ضمن مهلة الـ 24 ساعة.
سيناريو الفشل: تعارض في الهاش السابق (PIH Chain Mismatch) نتيجة محاولة إرسال فواتير متزامنة
استراتيجية المعالجة والتحويل: تطبيق قفل التزامن الموزع (Redis Redlock / Transactional Mutex) الذي يقصر حساب وتحديث الـ PIH على خيط معالجة واحد لكل وحدة EGS مسجلة، مع إعادة ترتيب العمليات تلقائياً قبل الإرسال لمنع أي رفض برمز INVALID_PIH.
سيناريو الفشل: قرب انتهاء صلاحية شهادة الإنتاج PCSID السنوية وتوقف التوقيع الرقمي
استراتيجية المعالجة والتحويل: خدمة خلفية مجدولة ترصد تاريخ صلاحية الشهادة، وتصدر تلقائياً قبل 30 يوماً من انتهائها طلب تجديد عبر واجهة PATCH /production/csids دون أي انقطاع في سير العمل.
حمّل كراسة الشروط وقائمة فحص استلام الربط مع ZATCA Phase 2 (CSV)
وفرنا كراسة مواصفات الاستلام الخاصة بالربط مع منظومة الفوترة الإلكترونية السعودية في صورة ملف جدول بيانات منظم (CSV) يغطي بنود التشفير، معايير الأمان، سلامة تسلسل الهاش السابق PIH، واختبارات الضغط العالي لمساعدتك في فحص ومطابقة استلام مشروعك.
هل تخطط لربط متجرك أو نظام نقطة البيع مع ZATCA Phase 2؟
فريقنا الهندسي يصمم وينفذ محركات الفوترة الإلكترونية المتوافقة مع متطلبات المرحلة الثانية مع تسليم الكود المصدري كاملاً وفق وثيقة نطاق عمل مكتوبة ومحضر استلام فني معتمد.