زاتكا المرحلة الثانية: دليل التطبيق خطوة بخطوة 2026

دليل بصري كامل لمرحلة الربط والتكامل مع هيئة الزكاة والضريبة والجمارك — من إنشاء CSR إلى Clearance والأرشفة. كل ما تحتاج معرفته في سبع خطوات.

جزء من مجموعة: زاتكا والضريبة

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

المسار في سطر

CSR → CSID → UBL 2.1 XML → XAdES Signature → Clearance / Reporting → Archive

الخطوات السبع

  1. تحقّق من موجة الالتزام الخاصّة بك

    هيئة الزكاة والضريبة والجمارك (ZATCA) تُبلّغ المنشآت قبل ستة أشهر على الأقل من تاريخ الربط. التزم بالتاريخ المُعلَن في خطاب الموجة المُرسَل إليك عبر البريد الإلكتروني الرسمي وبوابة فاتورة.

    • افتح بوابة Fatoora واطّلع على لوحة الموجات.
    • احفظ خطاب الإبلاغ — يُطلب أحياناً عند التدقيق.
    • إذا لم يصلك إشعار وتجاوز إيرادك السنوي حدّ الموجة الحاليّة، تواصل مع الهيئة فوراً.
    تنبيه: غرامة التأخّر في الالتزام تبدأ من 5,000 ريال وتتصاعد مع التكرار.

  2. أعدّ بيئة الإصدار في نظامك المحاسبي

    المرحلة الثانية تفرض ربط نظامك مع API الهيئة. تأكّد من أنّ نظامك (ERP أو POS أو مولّد الفواتير) يدعم UBL 2.1 و XAdES B-B للتوقيع، ويستطيع تخزين CSID بأمان.

    • حدّث نظامك إلى أحدث إصدار معتمد من المورّد.
    • تحقّق من توافق ساعة الخادم مع UTC — انحراف دقيقة واحدة يُسقط التوقيع.
    • أنشئ مستخدم خدمة (Service Account) خاص بالإرسال إلى ZATCA.

  3. أنشئ طلب توقيع شهادة (CSR)

    كل وحدة إصدار (Solution Unit) تحتاج زوج مفاتيح ECDSA secp256k1 و CSR موقّع. تُولّد المفاتيح داخل نظامك ولا تُرسل أبداً المفتاح الخاص.

    • املأ حقول CSR: الاسم القانوني، الرقم الضريبي، نوع الفاتورة (B2B / B2C)، الموقع الجغرافي.
    • احفظ المفتاح الخاص في خزنة آمنة (Vault / HSM).
    • ابعث CSR إلى الـ Sandbox أوّلاً للاختبار قبل الإنتاج.
    تنبيه: خطأ متكرّر: استخدام نفس CSR لأكثر من جهاز — كل وحدة إصدار تحتاج CSR مستقلّاً.

  4. احصل على CSID من بوابة فاتورة

    بعد رفع CSR ستحصل على Compliance CSID (للاختبار) ثم Production CSID (للإصدار الفعلي). كلاهما يُستخدم في التوقيع وفي المصادقة على طلبات API.

    • OTP يُرسل إلى البريد المسجّل في الهيئة — صلاحيّته ساعة واحدة فقط.
    • احفظ CSID وكلمة السر (Secret) في متغيّرات بيئة مشفّرة.
    • ادخل بيانات Production CSID فقط بعد اجتياز اختبارات الـ Compliance.

  5. ولّد الفاتورة بصيغة UBL 2.1 XML

    صيغة الفاتورة موحّدة: ملف XML يتبع معيار UBL 2.1 مع امتدادات ZATCA. يجب أن يحتوي على PIH (Previous Invoice Hash) لربط الفواتير بسلسلة غير قابلة للتلاعب.مولّد فاتورة ZATCA أو محوّل XML.

    • كل فاتورة تحمل UUID فريد و ICV (عدّاد تسلسلي) و PIH (هاش الفاتورة السابقة).
    • اكتب الحقول العربية بالعربيّة الفصحى — الأرقام الضريبية بالأرقام اللاتينيّة.
    • تأكّد من تطابق إجمالي الضريبة في XML مع الإجمالي المعروض على الفاتورة المرئيّة.
    تنبيه: تستطيع توليد UBL 2.1 صحيح فوراً عبر أداة

  6. وقّع الفاتورة وأرسلها (Clearance / Reporting)

    فواتير B2B (ضريبية) تمرّ بـ Clearance: تُرسل لحظيّاً للهيئة وتعود معتمدة قبل تسليمها للعميل. فواتير B2C (مبسّطة) تمرّ بـ Reporting: تُرسل خلال 24 ساعة من الإصدار.

    • التوقيع: XAdES B-B باستخدام CSID والمفتاح الخاص.
    • أدخل توقيع الهيئة (Cryptographic Stamp) في XML قبل الطباعة.
    • QR Code من Base64 من نموذج TLV — إلزامي على كلّ فاتورة مطبوعة أو PDF.
    تنبيه: إذا رفضت الهيئة الفاتورة، عالج الخطأ خلال نفس اليوم — لا يُسمح بإعادة الإرسال بنفس الـ ICV.

  7. أرشف وراقب الأداء

    يجب الاحتفاظ بكل فاتورة XML الموقّعة + رد الهيئة لمدّة 6 سنوات على الأقل. ابنِ لوحة مراقبة لمعدّل القبول من الهيئة — أيّ هبوط مفاجئ يشير إلى عطل في التوقيع أو الاتصال.

    • خزّن XML الأصلي + Cleared Invoice من الهيئة.
    • سجّل كل محاولة فاشلة مع رمز الخطأ ووقت الإرسال.
    • أنشئ تنبيه إذا تجاوز الفشل 1% من الفواتير اليوميّة.

أخطاء شائعة في التطبيق

  • إرسال فواتير B2B بعد التسليم للعميل بدل قبله — يُعدّ مخالفة لـ Clearance.
  • نسيان حقل PIH في أوّل فاتورة بعد إعادة تهيئة النظام — كسر في السلسلة.
  • QR Code يحوي بيانات قبل التوقيع بدل البيانات الموقّعة.
  • استخدام Compliance CSID في الإنتاج — كل الفواتير تُرفض.
  • عدم تخزين الـ XML الأصلي قبل التوقيع — استرجاع مستحيل عند الخطأ.

جرّب الأدوات

مولّد فاتورة ZATCA

أنشئ فاتورة مبسّطة أو ضريبية مع QR Code جاهز للطباعة.

محوّل ZATCA XML

حوّل بيانات الفاتورة إلى UBL 2.1 XML متوافق مع الهيئة.

مراجع رسميّة

هذا الدليل لأغراض إرشاديّة. للحالات الخاصّة راجع الهيئة أو مستشاراً ضريبيّاً مرخّصاً.