الفوترة الإلكترونية المرحلة الثانية (زاتكا): دليل المطوّر 2026

إذا كنت تبني نظاماً جديداً أو تحدّث نظاماً قائماً (ERP أو POS أو متجراً إلكترونياً) لتاجر سعودي في عام 2026، فأنت تتكامل مع المرحلة الثانية من فاتورة — مرحلة الربط والتكامل التي بدأت الدفعات منها في يناير 2023 وما زالت تتوسّع. المرحلة الأولى (PDF مع رمز QR فقط) لم تعد كافية.

هذه هي القائمة الفعلية التي أستخدمها قبل كل إطلاق للمرحلة الثانية. لا نظريات — فقط الخطوات، ونقاط الـ API، والمواضع التي تتعثّر عندها الفرق فعلاً.

ماذا تتطلّب المرحلة الثانية فعلياً

المرحلة الثانية ليست مجرّد تنسيق فاتورة جديد — بل هي سلسلة التزام فورية. تتوقّع زاتكا أن تُوقَّع كل عملية خاضعة للضريبة رقمياً، وتُربط بسلسلة هاش (Hash) مع الفاتورة السابقة، ثم تُرسَل للإفصاح أو الإبلاغ قبل أن تصل للعميل أو بعده بوقت قصير.

يوجد مساران يجب على نظامك دعمهما:

• فاتورة ضريبية (B2B). يجب أن تحصل على الإفصاح من زاتكا قبل إصدارها للمشتري. استدعاء API متزامن. بدون استجابة إفصاح، لا فاتورة.
• فاتورة ضريبية مبسّطة (B2C). تُصدَر للعميل مباشرة، ثم يُبلَّغ بها زاتكا خلال 24 ساعة. غير متزامن لكن غير اختياري.

إذا كان نظامك لا يدعم كلا المسارين، فأنت لست مُمتثلاً لمتطلبات المرحلة الثانية.

قائمة التكامل في 8 خطوات

1. تأكّد من أنّ التاجر ضمن النطاق

تُدخِل زاتكا التجّار إلى المرحلة الثانية على شكل دفعات (Waves)، بحسب الإيرادات الخاضعة للضريبة السنوية. الدفعات بدأت من يناير 2023 ولا تزال جارية في 2026. قبل كتابة أي كود، ادخل على بوابة فاتورة لحساب ضريبة القيمة المضافة الخاصّ بالتاجر وتأكّد من الدفعة وتاريخ الربط. لا تفترض أنّه خارج النطاق — الشبكة تتّسع باستمرار.

2. إصدار الـ CSID (هوية الختم المشفّر)

كل جهاز فوترة (جهاز كاشير أو نسخة ERP أو تطبيق نقطة بيع) يحتاج إلى CSID خاصّ به. التسلسل:

1. التاجر يدخل على بوابة فاتورة ويطلب كلمة مرور لمرّة واحدة (OTP) للجهاز.
2. الكود الخاصّ بك يولّد CSR (طلب توقيع شهادة) باستخدام ECDSA مع منحنى secp256k1 — نفس المنحنى المستخدم في بيتكوين. ليس RSA، وليس secp256r1. أيّ خطأ هنا وكلّ استدعاء لاحق سيُرفَض بخطأ INVALID_CERTIFICATE مبهم.
3. أرسل CSR + OTP إلى /compliance على Sandbox، لتستلم CSID مؤقّت للامتثال.
4. شغّل فواتير الامتثال الثلاث (واحدة ضريبية، واثنتان مبسّطتان) لإثبات أنّ التوقيع يعمل.
5. استبدل CSID المؤقّت بـ CSID إنتاج عبر /production/csids.

كل CSID مرتبط بجهاز، ليس بشركة. إذا كان لدى التاجر 12 فرعاً، فأنت تحتاج 12 CSID، وكلّ تجديد هو نشر جديد.

3. بناء XML حسب UBL 2.1 + ملفّ زاتكا

تستخدم زاتكا صيغة UBL 2.1 مع ملفّ (profile) خاصّ بالسعودية. الأجزاء السهلة هي cbc:InvoiceTypeCode وبنود الفاتورة. أمّا الأجزاء التي تُعثِر الفِرق:

• كل مبلغ مالي يحتاج currencyID="SAR" على العنصر نفسه — ليس فقط على بيان عملة المستند.
• الطوابع الزمنية بتوقيت آسيا/الرياض بصيغة ISO 8601. التوقيت العالمي UTC يُقبَل، لكنّ التسويات تصبح مؤلمة.
• cac:AdditionalDocumentReference مع ICV (Invoice Counter Value) يجب أن يزيد بمقدار 1 لكل فاتورة تصدر من ذلك الـ CSID، عالمياً، بلا تصفير. أيّ خطأ هنا ويلزمك إعادة التسجيل من الصفر.
• cbc:UUID على كل فاتورة، حتى وإن كان لدى زاتكا هوية فاتورة معتمدة مسبقاً.

4. وقّع بـ ECDSA وأدرج QR TLV

بعد بناء XML، وقّع هاش المستند الكانوني بالمفتاح الخاصّ المقرون بـ CSID. ثمّ أدرج TLV مُرمَّز Base64 داخل QR على الفاتورة. الترميز موقعي:

Tag 1 — اسم البائع
Tag 2 — الرقم الضريبي
Tag 3 — التاريخ والوقت (ISO 8601 بتوقيت الرياض)
Tag 4 — إجمالي الفاتورة شامل الضريبة
Tag 5 — إجمالي ضريبة القيمة المضافة
Tag 6 — هاش XML الموقَّع
Tag 7 — توقيع ECDSA
Tag 8 — المفتاح العام ECDSA
Tag 9 — توقيع الختم (للفواتير الضريبية فقط)

أطوال الـ Tag محسوبة بـ البايت، لا بالحروف. أسماء البائعين بالعربية ذات الحروف متعدّدة البايتات تُسقِط الفِرق كلّها تقريباً في المحاولة الأولى. استخدم Buffer.byteLength(name, 'utf8') وليس name.length.

5. حافظ على سلسلة هاش الفواتير

كل فاتورة تحتوي على هاش الفاتورة السابقة من نفس CSID. إذا تخطّيت واحدة أو أصدرت اثنتين خارج الترتيب، تنكسر السلسلة وترفض زاتكا كلّ ما يليها. اعتبر عمود previous_invoice_hash بنية تحتية حرجة — احفظه، انسخه، ولا تسمح لخيطَين على نفس CSID بالتسابق.

6. استدعِ نقطة الإفصاح أو الإبلاغ

• فاتورة ضريبية (B2B): POST /invoices/clearance/single — متزامن. توقّع أن تستلم XML معتمد بختم زاتكا. الفاتورة التي تُسلّمها للمشتري هي هذه، لا التي أرسلتها أنت.
• فاتورة مبسّطة (B2C): POST /invoices/reporting/single — غير متزامن. أعطيت العميل فاتورته بالفعل، أنت فقط تُبلِّغ زاتكا خلال 24 ساعة.

كلاهما idempotent عبر UUID. إعادة إرسال نفس الحمولة بنفس UUID تُرجِع الاستجابة الأصلية. استخدم ذلك — فشل الشبكة هو القاعدة لا الاستثناء.

7. احفظ XML الموقَّع من زاتكا لمدّة 6 سنوات

تشترط زاتكا الاحتفاظ بـ XML المعتمد (بتوقيع الختم) لمدّة لا تقلّ عن 6 سنوات. ليس الـ XML الذي أرسلتَه — بل الذي أعادوه. التخزين بنظام object storage مع versioning (S3 أو R2 أو MinIO) هو المعيار. لا تحفظ في قاعدة البيانات فقط.

8. راقِب، نبّه، وأجرِ تسوية يومية

شغّل مهمّة تسوية ليلية: اسحب كل الفواتير المُبلَّغ عنها خلال آخر 24 ساعة من بوابة زاتكا، قارِن الأعداد بما يظنّ نظامك أنّه أرسله. أيّ فارق = تنبيه للـ on-call. تدقيقات زاتكا تبدأ من هذه الأرقام.

مقارنة خيارات التكامل

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

أخطاء شائعة ما زلنا نراها في 2026

أمور واجهناها في كل مشروع راجعناه هذا العام تقريباً:

• طول اسم البائع بالبايتات. أطوال TLV محسوبة بالبايت. اسم مثل "مؤسسة الرياض التجارية" طوله 40 بايت، لا 22 حرفاً. تقريباً كل فريق يُخطئ هنا أوّل مرّة.
• خلط SAR بدقّة كسرية أكثر من خانتين عشريتين. تتحقّق زاتكا من المجاميع بخانتَين عشريتَين بالضبط. التدوير-قبل-الجمع مقابل الجمع-قبل-التدوير يسبّب فوارق 0.01 ريال تبدو تافهة لكنّها ترفض المستند بأكمله.
• انحراف الساعة. إذا كان خادمك يختلف عن الوقت الحقيقي بأكثر من 3 دقائق، ترفض زاتكا الطوابع الزمنية كمستقبلية أو منتهية الصلاحية. NTP ليس اختيارياً.
• مدّة صلاحية CSID. CSIDs الإنتاج صالحة لـ 12 شهراً. ضع الانتهاء في تقويم الفريق يوم الإصدار. الانتهاء الصامت يعني فشل فواتير صامت بعد سنة.
• الفواتير الدائنة والمدينة. إشعارات دائنة (388) ومدينة (383) تُرجِع لـ UUID + هاش الفاتورة الأصلية. إذا أشار إشعار الدائن إلى فاتورة اختبار في الإنتاج، يفشل الإفصاح. احتفظ بسلاسل ICV منفصلة لكل بيئة.

استراتيجية الاختبار

قبل الإطلاق، عليك اجتياز فحص امتثال Sandbox زاتكا — ثلاث فواتير (واحدة ضريبية، اثنتان مبسّطتان) تُثبت تدفّق التوقيع والإفصاح من البداية للنهاية. واجهة الامتثال على gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal، والـ Sandbox على gw-fatoora.zatca.gov.sa/e-invoicing/simulation.

مصفوفة اختبار قبل الإنتاج موصى بها:

1. كل فواتير الامتثال الثلاث تجتاز Sandbox.
2. إشعار دائن ضريبي مقابل فاتورة ضريبية معتمدة — لأنّ إشعارات الدائن هي حيث تنكسر سلسلة الهاش أوّل مرّة.
3. فاتورة متعدّدة البنود بالريال السعودي بنسب ضريبية مختلطة (15% + 0% معفى).
4. فاتورة مبسّطة عند 00:00 بتوقيت الرياض — أخطاء تحوّل التاريخ شائعة.
5. فاتورة بمبلغ مرتفع فوق 1,000,000 ريال — لزاتكا تحقّق إضافي عند هذا الحدّ.

الإطلاق وإشعار زاتكا

عندما تصبح جاهزاً، اطلب CSIDs إنتاج من بوابة فاتورة، استبدلها عبر /production/csids، وبدّل عنوان القاعدة من simulation إلى core. لا يوجد إشارة "بدء إطلاق" واضحة خارج ذلك — أوّل فاتورة إنتاج معتمدة هي تأكيدك.

أبلِغ مسؤول الضريبة لدى التاجر (لا قسم المالية فقط) يوم الإطلاق. تدقيقات زاتكا تبدأ عادة بسحب فواتير الأسبوع الأوّل المعتمدة مباشرة من البوابة، فاجعل لوحة التسوية جاهزة.

الخلاصة

المرحلة الثانية ليست صعبة بمعزل. الصعوبة في اجتماع التوقيع المشفّر، وسلسلة الهاش، وواجهات API فورية، وحفظ متعدّد السنوات تحت ضغط الإطلاق. خطّط لـ 8 أسابيع هندسة لا أسبوعَين. اختر مسار تكامل يُبقي منطق XML في كود تملكه. شغّل التسوية الليلية من اليوم الأوّل.

إذا كنت تحتاج فريقاً شحن المرحلة الثانية في كلّ الدفعات حتى الآن ويريد تسليمك الكود في النهاية، نحن نقوم بهذا كعمل أساسي.