دليل تكامل الفوترة الإلكترونية للمرحلة الثانية من ZATCA: قائمة مراجعة المطور موجة بموجة

1. الفوترة الإلكترونية في ZATCA: المرحلة الأولى مقابل المرحلة الثانية

نظام الفوترة الإلكترونية الإلزامي في المملكة العربية السعودية، الذي تحكمه هيئة الزكاة والضريبة والجمارك (ZATCA)، يُنشر في مرحلتين متميزتين.

المرحلة الأولى (مرحلة التوليد)، السارية من 4 ديسمبر 2021، تطلبت من جميع المكلفين المسجلين في ضريبة القيمة المضافة توليد فواتير إلكترونية وإشعارات إلكترونية بصيغة رقمية منظمة عبر حل فوترة إلكترونية متوافق (EGS). المرحلة الأولى كانت أساسًا عن الصيغة: توقف عن إصدار فواتير يدوية أو غير منظمة، وابدأ إنتاج مستندات قابلة للقراءة آليًا بحقول إلزامية ورموز QR ومعرفات UUID. لم يكن مطلوبًا اتصال API بـ ZATCA. الفواتير كانت تُولد وتُخزن محليًا.

المرحلة الثانية (مرحلة التكامل)، التي تُنشر على موجات منذ 1 يناير 2023، مختلفة جوهريًا. تتطلب تكاملًا فوريًا أو شبه فوري مع منصة فاتورة التابعة لـ ZATCA عبر API. حسب نوع الفاتورة، يجب إما الإبلاغ عن المستندات (إرسالها لـ ZATCA خلال 24 ساعة) أو اعتمادها (التحقق منها وختمها من ZATCA قبل مشاركتها مع المشتري). المرحلة الثانية تقدم أيضًا متطلبات التوقيع التشفيري وتحقق أكثر صرامة من مخطط XML وعملية تسجيل رسمية تتضمن طلبات توقيع الشهادات (CSR) ومعرفات الختم التشفيري (CSID).

إذا كنت تبني أو تصون نظام فوترة للسوق السعودي، المرحلة الثانية هي حيث يكمن التعقيد الهندسي. بقية هذا الدليل تركز على ما تحتاج تنفيذه.

2. جدول الموجات: من يتأثر ومتى

تنشر ZATCA المرحلة الثانية على موجات، كل منها تستهدف مكلفين بناءً على حجم مبيعاتهم الخاضعة للضريبة خلال سنوات تقويمية محددة. يُخطر المكلفون ستة أشهر على الأقل قبل موعدهم النهائي. إليك الجدول للموجات الأحدث:

الموجة	نافذة الانطلاق	عتبة الإيرادات	فترة المرجع
الموجة 1	1 يناير 2023	3 مليارات ريال+	2021
الموجة 2	1 يوليو 2023	500 مليون ريال+	2021
الموجة 3	1 أكتوبر 2023	250 مليون ريال+	2021 أو 2022
الموجات 4-10	نوفمبر 2023 - ديسمبر 2024	150 مليون إلى 5 ملايين ريال	متنوعة
الموجات 11-22	يناير 2025 - ديسمبر 2025	4 ملايين إلى مليون ريال	2022 أو 2023 أو 2024
الموجة 23	1 يناير - 31 مارس 2026	750,000 ريال+	2022 أو 2023 أو 2024
الموجة 24	1 أبريل - 30 يونيو 2026	375,000 ريال+	2022 أو 2023 أو 2024

ملاحظة: تواصل ZATCA الإعلان عن موجات جديدة بشكل دوري. تحقق من موجتك المحددة على صفحة ZATCA الرسمية للنشر.

الاتجاه واضح: العتبة تنخفض مع كل موجة. عمليًا جميع الأعمال المسجلة في ضريبة القيمة المضافة في المملكة ستحتاج في النهاية تكامل المرحلة الثانية.

3. المتطلبات التقنية: هيكل UBL 2.1 XML

3.1 الصيغة

جميع فواتير المرحلة الثانية الإلكترونية يجب توليدها بصيغة UBL 2.1 XML، متوافقة مع معيار التنفيذ XML لـ ZATCA (نفسه ملف شخصي مقيد من ISO EN 16931). بديلًا، يُقبل PDF/A-3 مع حمولة UBL 2.1 XML مضمنة، لكن XML هو البيانات المرجعية.

3.2 أنواع الفواتير

تميز ZATCA نوعين من الفواتير، كل منهما بتدفق معالجة مختلف:

• فاتورة ضريبية قياسية (B2B): تُصدر للمعاملات بين الأعمال. خاضعة لـ الإبلاغ (إرسال غير متزامن لـ ZATCA خلال 24 ساعة).
• فاتورة ضريبية مبسطة (B2C): تُصدر للمعاملات بين الأعمال والمستهلكين. خاضعة لـ الاعتماد (تحقق متزامن من ZATCA قبل مشاركة الفاتورة مع المشتري).

3.3 حقول XML الإلزامية

الحقول التالية إلزامية في كل فاتورة XML للمرحلة الثانية. هذا ليس شاملاً؛ راجع قاموس بيانات ZATCA للمواصفات الكاملة.

1<?xml version="1.0" encoding="UTF-8"?>
2<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
3         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
4         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
5         xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2">
6
7  <!-- UBL Extensions: contains the digital signature -->
8  <ext:UBLExtensions>
9    <ext:UBLExtension>
10      <ext:ExtensionContent>
11        <!-- XMLDSig Signature block inserted here -->
12      </ext:ExtensionContent>
13    </ext:UBLExtension>
14  </ext:UBLExtensions>
15
16  <cbc:ProfileID>reporting:1.0</cbc:ProfileID>
17  <cbc:ID>INV-2026-00042</cbc:ID>
18  <cbc:UUID>6f4d20e0-6bfe-4a80-9389-7dabe6620f12</cbc:UUID>
19  <cbc:IssueDate>2026-04-15</cbc:IssueDate>
20  <cbc:IssueTime>14:30:00</cbc:IssueTime>
21  <cbc:InvoiceTypeCode name="0100000">388</cbc:InvoiceTypeCode>
22  <cbc:DocumentCurrencyCode>SAR</cbc:DocumentCurrencyCode>
23  <cbc:TaxCurrencyCode>SAR</cbc:TaxCurrencyCode>
24  <!-- ... -->
25</Invoice>

نقاط رئيسية:

• UUID يجب أن يكون v4 UUID صالحًا وفريدًا لكل فاتورة. بعد الرفض، يجب توليد UUID جديد.
• InvoiceTypeCode يستخدم خاصية name تشفر علم ثنائي من 7 أرقام (مثل 0100000 لفاتورة ضريبية قياسية).
• تجزئة الفاتورة السابقة (PIH) تسلسل كل فاتورة بالسابقة، مما يخلق سلسلة مقاومة للتلاعب.
• قيمة عداد الفواتير (ICV) يجب أن يكون عددًا صحيحًا تسلسليًا لا ينقص ولا يتكرر أبدًا ضمن وحدة EGS.

3.4 رمز QR بترميز TLV

رمز QR المضمن في فواتير المرحلة الثانية يستخدم ترميز Tag-Length-Value (TLV)، ثم يُشفر بـ Base64.

العلامة	الحقل	النوع
1	اسم البائع	سلسلة UTF-8
2	رقم التسجيل الضريبي (TRN)	سلسلة UTF-8
3	طابع زمني للفاتورة (ISO 8601)	سلسلة UTF-8
4	إجمالي الفاتورة (مع الضريبة)	سلسلة UTF-8
5	إجمالي الضريبة	سلسلة UTF-8
6	تجزئة SHA-256 لـ XML	مصفوفة بايت
7	توقيع ECDSA	مصفوفة بايت
8	المفتاح العام	مصفوفة بايت
9	توقيع الشهادة (ختم CSID)	مصفوفة بايت

العلامات 1-5 كانت مطلوبة في المرحلة الأولى. العلامات 6-9 إضافات المرحلة الثانية وهي ما يجعل رمز QR قابلاً للتحقق تشفيريًا.

4. التوقيع التشفيري: ECDSA وCSR وCSID

4.1 توليد المفتاح

تفرض ZATCA استخدام ECDSA مع المنحنى البيضاوي secp256k1 لتوقيع الفواتير. أنشئ مفتاحك الخاص باستخدام OpenSSL:

1# Generate EC private key
2openssl ecparam -name secp256k1 -genkey -noout -out ec-secp256k1-priv-key.pem
3
4# Generate a Certificate Signing Request (CSR)
5openssl req -new -sha256 \
6  -key ec-secp256k1-priv-key.pem \
7  -out taxpayer.csr \
8  -subj "/CN=EGS-Unit-01/OU=MyBranch/O=MyCompany/C=SA" \
9  -addext "subjectAltName=DNS:egs1.mycompany.com,dirName:cn=TST-886431145-399999999900003,serialNumber=1-TST|2-TST|3-ed22f1d8-e6a2-1118-9b58-d9a8f11e445f" \
10  -addext "certificateTemplateName=ZATCA-Code-Signing" \
11  -addext "1.3.6.1.4.1.311.20.2=ASN1:UTF8String:TSTZATCA-Code-Signing"

4.2 التسجيل: من CSID الامتثال إلى CSID الإنتاج

عملية التسجيل لها ثلاث مراحل:

المرحلة 1: الحصول على CSID الامتثال (CCSID)

أرسل CSR إلى نقطة نهاية الامتثال لـ ZATCA. تتلقى CSID امتثال (شهادة) ومعرف طلب.

المرحلة 2: اجتياز فحوصات الامتثال

باستخدام بيانات اعتماد CCSID، أرسل فواتير عينة لتحقق الامتثال. يجب اجتياز فحوصات الامتثال لجميع الأنواع الفرعية للفواتير التي سيتعامل معها EGS الخاص بك.

المرحلة 3: الحصول على CSID الإنتاج (PCSID)

بمجرد اجتياز فحوصات الامتثال، استبدل CCSID بـ CSID إنتاج. CSID الإنتاج هو ما يستخدمه EGS لتقديم الفواتير الحية. له تاريخ انتهاء؛ خطط للتجديد قبل انتهائه.

5. تكامل API: الإبلاغ مقابل الاعتماد

5.1 الإبلاغ (فواتير B2B القياسية)

الفواتير الضريبية القياسية يُبلغ عنها بشكل غير متزامن. ترسل الفاتورة الموقعة إلى ZATCA، وتعيد ZATCA نتيجة التحقق.

5.2 الاعتماد (فواتير B2C المبسطة)

الفواتير المبسطة تتطلب اعتمادًا: ZATCA تتحقق من الفاتورة وتختمها وترجع نسخة معتمدة. يجب استخدام XML المرجع من ZATCA (وليس الأصلي) كمستند صالح ضريبيًا.

5.3 معالجة الاستجابات

ترجع API الخاصة بـ ZATCA كائن validationResults يحتوي:

• status: PASS أو WARNING أو ERROR
• infoMessages وwarningMessages وerrorMessages: مصفوفات بحقول type وcode وcategory وmessage وstatus

حالة WARNING تعني أن الفاتورة قُبلت لكن بها مشاكل يجب إصلاحها. حالة ERROR تعني أن الفاتورة رُفضت. عند الرفض، يجب إصلاح المشكلة وتوليد UUID جديد وإعادة التقديم.

6. أخطاء التحقق الشائعة وكيفية إصلاحها

الخطأ	السبب	الإصلاح
Invalid Invoice Hash	التجزئة محسوبة على XML غير قياسي، أو عدم تطابق نسخة XML	التجزئة يجب أن تُحسب على XML الفاتورة قبل إدراج كتلة UBLExtensions/Signature
Invalid CSR	CSR مفقود امتدادات ZATCA المطلوبة	أعد توليد CSR بجميع الامتدادات الإلزامية
UUID already exists	إعادة استخدام UUID من فاتورة مقدمة أو مرفوضة سابقًا	ولّد v4 UUID جديد لكل محاولة تقديم
ICV sequence broken	قيمة عداد الفواتير ليست تسلسلية بدقة أو بها فجوات	تأكد أن ICV عداد يتزايد ذريًا لكل وحدة EGS
PIH mismatch	تجزئة الفاتورة السابقة لا تتطابق مع تجزئة ZATCA المسجلة	يجب أن يخزن نظامك تجزئة كل فاتورة مقدمة بنجاح
Invalid signature	التوقيع محسوب بالمفتاح الخاطئ	تحقق أنك توقع بالمفتاح الخاص المقابل لشهادة CSID
Missing mandatory field	عنصر XML مطلوب غائب أو فارغ	راجع كل حقل مقابل قاموس بيانات ZATCA
Certificate expired	CSID الإنتاج تجاوز تاريخ انتهائه	نفّذ تجديد CSID قبل الانتهاء

7. الاختبار مع بيئة ZATCA sandbox

توفر ZATCA بيئة sandbox تحاكي API الإنتاج. عنوان sandbox الأساسي:

https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal

تدعم sandbox كامل تدفق التسجيل (تقديم CSR، إصدار CCSID، فحوصات الامتثال، إصدار PCSID) وكل من تقديم الإبلاغ والاعتماد. استخدم قيمة OTP 123456 لتسجيل sandbox.

8. Factur-X وPeppol والسياق العابر للحدود

إذا كان عملك أو عملاؤك يفوترون في كل من المملكة العربية السعودية والاتحاد الأوروبي، نظامك يحتاج التعامل مع:

• توليد UBL 2.1 XML (مشترك بين ZATCA وPeppol، رغم اختلاف الملفات الشخصية)
• توليد CII XML (لأسواق Factur-X/ZUGFeRD)
• التوقيع والتقديم الخاص بـ ZATCA عبر API
• اتصال نقاط الوصول الخاصة بـ Peppol
• مجموعات قواعد تحقق مختلفة لكل ولاية قضائية

القرار المعماري الجيد هو فصل المخاوف: ابنِ نموذج بيانات فاتورة أساسي متوافق مع دلالات EN 16931، ثم نفّذ مسلسلات ومحولات تقديم خاصة بكل ولاية قضائية.

9. قائمة مراجعة الانطلاق في الإنتاج

قبل انطلاق EGS لمكلف محدد، تحقق من كل بند:

• تأكيد تسجيل ZATCA. المكلف أُخطر بموجته وموعده النهائي.
• وحدة EGS مسجلة. كل وحدة فوترة فعلية أو افتراضية لها CSR وCSID وعداد ICV تسلسلي خاص بها.
• CSID إنتاج محصول. استبدلت CSID الامتثال بـ CSID إنتاج عبر API الإنتاج.
• تجديد CSID مجدول. أتمتت أو جدولت التجديد قبل تاريخ notAfter في الشهادة.
• سلسلة الفواتير مهيأة. PIH الفاتورة الأولى مضبوط على Base64 لـ SHA-256(0).
• جميع أنواع الفواتير مختبرة. الفواتير القياسية والمبسطة وإشعارات الخصم والائتمان اجتازت فحوصات الامتثال.
• توليد رمز QR محقق. رموز QR بترميز TLV قابلة للقراءة وتحتوي جميع العلامات الـ 9.
• معالجة الأخطاء منفذة. نظامك يتعامل بشكل صحيح مع استجابات WARNING وERROR.
• تدفق الاعتماد مختبر. للفواتير المبسطة، نظامك يخزن ويستخدم XML clearedInvoice المرجع من ZATCA.
• منطق إعادة المحاولة موضوع. فشل الشبكة والمهلات واستجابات 5xx من API ZATCA تُعالج بتراجع أسي.
• مسار التدقيق محفوظ. كل محاولة تقديم واستجابة وUUID وICV وتجزئة وCSID مستخدم مسجل.
• تحقق مخطط XML. مخرجات XML تجتاز التحقق مقابل مخططات XSD المنشورة من ZATCA.

10. هل تحتاج مساعدة في التكامل؟

إذا كنت تبني امتثال المرحلة الثانية من ZATCA في برمجياتك، أو إذا كان عملك يحتاج أن يصبح متوافقًا دون استبدال نظام الفوترة الحالي، يمكنني المساعدة.

بنيت وأرسلت تكامل المرحلة الثانية من ZATCA لأنظمة إنتاج، بما في ذلك خط الأنابيب الكامل من استخراج المستندات إلى التوقيع التشفيري إلى تقديم API والاعتماد. أعمل مع الحالات الحدية المحددة التي تفوتها الحلول العامة: فوترة تقدم الإنشاءات، وتوحيد الكيانات المتعددة، وأغلفة الأنظمة القديمة، وتكاملات ERP المخصصة.

أغطي أيضًا امتثال Factur-X وPeppol وXRechnung للأعمال العاملة عبر الأسواق السعودية والأوروبية.

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

---

يعكس هذا الدليل لوائح ZATCA وجداول الموجات حتى أبريل 2026. تحدث ZATCA متطلباتها بشكل دوري. تحقق دائمًا من تخصيصات الموجات الحالية والمواصفات التقنية مقابل بوابة ZATCA الرسمية للفوترة الإلكترونية ومجتمع مطوري فاتورة.