فهرس الدراسات
قطاع التجارة الإلكترونية، نقاط البيع، وتطبيقات المؤسسات في المملكة العربية السعودية (KSA)18 دقيقة قراءة معمارية2026-11-09

معمارية الربط والتكامل مع منظومة الفوترة الإلكترونية السعودية (ZATCA Phase 2 FATOORA)

التوقيع الرقمي ECDSA secp256k1، وتشفير XML C14N، وسلسلة الكتل السابقة PIH، ورمز الاستجابة 9-Tag QR

حزمة التقنيات المستخدمة:ECDSA secp256k1UBL 2.1 XMLXML-C14N 1.1SHA-256 HashingXAdES-BESBase64 TLV 9-Tag QRZATCA REST APIPostgreSQL / SQLite WALBullMQ Redis

مؤشرات الأداء الفعلية وبنود كفاءة الخدمة (ZATCA KPIs)

زمن التشفير والتوقيع وتوليد QR محلياً
< 160ms

إتمام المعايرة C14N وتوقيع ECDSA وتوليد 9-Tag TLV دون اتصال خارجي

الأساس المعياري:3,200ms في الحلول السحابية غير المهيأة
خوارزمية المنحنى الإهليلجي المعتمدة
secp256k1

مفتاح 256 بت مطابق لمعايير FIPS 186-4 واشتراطات هيئة الزكاة

الأساس المعياري:حظر تام لخوارزميات التجزئة المتقادمة
سلامة تسلسل سلسلة الفواتير (PIH Chaining)ضمان SLA
100.00%

قفل تسلسلي يمنع تداخل الهاش السابق ويحمي الدفاتر من التلاعب

الأساس المعياري:أخطاء PIH Mismatch تسبب رفض حزم الفواتير
نسبة الامتثال لنافذة الإبلاغ (B2C Reporting)ضمان SLA
100%

تفريغ طابور الفواتير المبسطة خلال أقل من 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)

المستوى 01

تنشئ كائن الفاتورة المالي وتسجله في قاعدة البيانات المحلية في أقل من 50 ملي ثانية.

واجهة الكاشير / سلة الشراءقاعدة البيانات المحلية SQLite / PostgreSQLمحدد نوع الفاتورة (Standard vs Simplified)

2. طبقة المعايرة وتجزئة الهاش (C14N Cleansing & SHA-256 Hashing)

المستوى 02

تستبعد وسوم التوقيع والـ QR وتولد الهاش المعياري الفريد الذي يمثل هوية الفاتورة الرقمية.

مرشح استبعاد وسوم التوقيع XPathمحرك المعايرة XML-C14N 1.1حاسب بصمة الفاتورة SHA-256

3. طبقة التوقيع وسلسلة الكتل (ECDSA secp256k1 & PIH Chain Ledger)

المستوى 03

تربط الفاتورة بهاش الفاتورة السابقة PIH وتوقع المستند بمفتاح المنشأة المشفر وفق أعلى المعايير.

محرك التوقيع الرقمي XAdES-BESمدير الهاش السابق Previous Invoice Hashخزنة شهادة الإنتاج PCSID

4. طبقة تشفير الاستجابة السريعة (9-Tag Base64 TLV Generator)

المستوى 04

تدمج اسم المورد، الرقم الضريبي، التوقيت، الإجمالي، الضريبة، الهاش، التوقيع، المفتاح العام، وختم الهيئة.

محول الحقول الثنائية TLV Encoderمجمع الوسوم الـ 9 الرسميةمولد رمز الاستجابة 2D QR Code

5. طبقة بوابات الربط السحابي (ZATCA Clearance & Reporting Gateway)

المستوى 05

تتولى اعتماد فواتير الشركات B2B فورياً وإبلاغ فواتير التجزئة B2C خلال 24 ساعة بأمان تام.

بوابة الاعتماد المسبق اللحظي Clearance APIطابور الإبلاغ غير المتزامن Reporting APIنظام قواطع الدوائر وإعادة المحاولة

تسلسل مسار تدفق البيانات (Data Flow Lifecycle)

  1. 11. يقوم العميل بإتمام الطلب؛ يُنشأ مستند الفاتورة بصيغة UBL 2.1 XML مع جلب الهاش السابق PIH من السجل المحلي.
  2. 22. يستبعد محرك المعايرة وسوم التوقيع والـ QR، ويطبق C14N 1.1، ويحسب هاش SHA-256 الموحد للفاتورة.
  3. 33. يوقع محرك ECDSA secp256k1 الهاش، ويحقن بنية XAdES-BES والشهادة الرقمية PCSID داخل مستند الـ XML.
  4. 44. تُشفر مصفوفة الـ 9 وسوم TLV بصيغة Base64 وتُحقن في الفاتورة وتُطبع على إيصال العميل في أقل من 160ms.
  5. 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-256Canonical 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 ساعة.

RTO = 0 ثانية (لا تتوقف عمليات الكاشير أو المتجر إطلاقاً)
RPO = صفر فقد في بيانات الفواتير وأرقام التسلسل
!

سيناريو الفشل: تعارض في الهاش السابق (PIH Chain Mismatch) نتيجة محاولة إرسال فواتير متزامنة

استراتيجية المعالجة والتحويل: تطبيق قفل التزامن الموزع (Redis Redlock / Transactional Mutex) الذي يقصر حساب وتحديث الـ PIH على خيط معالجة واحد لكل وحدة EGS مسجلة، مع إعادة ترتيب العمليات تلقائياً قبل الإرسال لمنع أي رفض برمز INVALID_PIH.

RTO < 2 ثانية لتصحيح التسلسل
RPO = سلامة السلسلة التشفيرية بنسبة 100%
!

سيناريو الفشل: قرب انتهاء صلاحية شهادة الإنتاج PCSID السنوية وتوقف التوقيع الرقمي

استراتيجية المعالجة والتحويل: خدمة خلفية مجدولة ترصد تاريخ صلاحية الشهادة، وتصدر تلقائياً قبل 30 يوماً من انتهائها طلب تجديد عبر واجهة PATCH /production/csids دون أي انقطاع في سير العمل.

RTO = 0 ثانية (تجديد استباقي في الخلفية)
RPO = استمرارية التوقيع القانوني المعتمد بنسبة 100%
أدوات ونماذج الاستلام الهندسية المعتمدةملف CSV مفتوح قابل للتعديل المباشر في Excel

حمّل كراسة الشروط وقائمة فحص استلام الربط مع ZATCA Phase 2 (CSV)

وفرنا كراسة مواصفات الاستلام الخاصة بالربط مع منظومة الفوترة الإلكترونية السعودية في صورة ملف جدول بيانات منظم (CSV) يغطي بنود التشفير، معايير الأمان، سلامة تسلسل الهاش السابق PIH، واختبارات الضغط العالي لمساعدتك في فحص ومطابقة استلام مشروعك.

تطبيق عملي واستشارات هندسية مخصصة

هل تخطط لربط متجرك أو نظام نقطة البيع مع ZATCA Phase 2؟

فريقنا الهندسي يصمم وينفذ محركات الفوترة الإلكترونية المتوافقة مع متطلبات المرحلة الثانية مع تسليم الكود المصدري كاملاً وفق وثيقة نطاق عمل مكتوبة ومحضر استلام فني معتمد.