تسجيل فاتورة زاتكا: خطوة بخطوة للمنشآت الصغيرة (2026)

إذا قررت التكامل مع فاتورة زاتكا مباشرة (بدلاً من المرور عبر مزود SaaS)، فهذه الصفحة هي دليل التشغيل. تمشي تدفق التسجيل الفعلي كما هو موثق في المواصفات الفنية لزاتكا، مع المزالق التي واجهها فريقنا في الإنتاج. للصورة الكبيرة لما هي المرحلة الثانية ولماذا، راجع دليل المرحلة الثانية الكامل.

الوقت المقدر: 8 إلى 20 ساعة من وقت المطور المركز، حسب نظام ERP الخاص بك ومقدار ما هو مؤتمت بالفعل. لا تحتاج أن تكون خبيراً في زاتكا لإكمال التسجيل — تحتاج إلى مطور يمكنه توليد CSR، وتشغيل عميل HTTPS، وقراءة رسائل الخطأ.

قبل البدء: المتطلبات الأربعة

لا يمكنك التسجيل حتى يكون لديك كل من هذه:

1. تسجيل ضريبة قيمة مضافة نشط على بوابة زاتكا. إذا كنت مسجلاً في الضريبة فلديك هذا بالفعل؛ سجل الدخول في login.gazt.gov.sa بالرقم الضريبي وكلمة المرور. إذا لم تكن مسجلاً في الضريبة، فلا يمكنك استخدام فاتورة والمرحلة الثانية لا تنطبق عليك بعد.
2. حساب بوابة فاتورة، منفصل عن بوابة الضريبة. سجل في fatoorah.zatca.gov.sa باستخدام رقمك الضريبي. عند تسجيل الدخول لأول مرة، تأخذك زاتكا عبر إعداد TOTP — احفظ رموز الاسترداد في مدير كلمات المرور.
3. بيئة تطوير يمكنها توقيع OpenSSL CSRs. ستولّد مفتاحاً خاصاً + CSR، وتحتفظ بالمفتاح الخاص آمناً، وترفع CSR. المفتاح الخاص لا يترك بنيتك التحتية أبداً.
4. نظام ERP أو POS staging / sandbox. ستتكامل أولاً ضد sandbox فاتورة (https://sandbox-fatoorah.zatca.gov.sa)، وتثبت أن التدفق يعمل، ثم تتحول إلى الإنتاج. لا تتكامل ضد الإنتاج في اليوم الأول.

الخطوة 1: توليد CSR (طلب توقيع شهادة)

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

الطريقة الأكثر شيوعاً تستخدم OpenSSL. من جهاز التطوير الخاص بك، باستخدام طرفية Linux أو macOS:

# 1. ولّد مفتاح خاص RSA 2048-بت (احتفظ بهذا سراً!)\nopenssl genrsa -out private.key 2048\n\n# 2. أنشئ ملف تكوين للـ CSR\ncat > csr.conf << EOF\n[req]\ndistinguished_name = dn\nreq_extensions = v3_req\nprompt = no\n[dn]\nC=SA\nOU=اسم-منشأتك-بالإنجليزية\nO=اسم-منشأتك\nCN=رقمك-الضريبي-15-رقم\n[v3_req]\nsubjectAltName = DNS:fatoorah.zatca.gov.sa\nEOF\n\n# 3. ولّد CSR\nopenssl req -new -key private.key -out request.csr -config csr.conf\n\n# 4. Base64 للـ CSR — ستلصق هذا في بوابة فاتورة\ncat request.csr | base64 | tr -d "\n"

زاتكا تقبل أيضاً مفاتيح ECDSA P-256 (أصغر، أسرع)، لكن RSA-2048 هو الافتراضي وما تدعمه معظم أنظمة ERP خارج الصندوق. مهما اخترت، ثبّت الخوارزمية في وثائق التطوير الخاصة بك — المواصفات تتغير بمرور الوقت.

الخطوة 2: ارفع CSR إلى فاتورة واحصل على CSID الامتثال

سجل الدخول إلى فاتورة. مسار القائمة: التسجيل → CSID الامتثال → طلب CSID الامتثال. الصق CSR base64. توقّعه زاتكا وأرجع CSID امتثال، وهو JSON Web Token (JWT) تستخدمه لاستدعاءات sandbox فقط.

CSID الامتثال غير إنتاجي. يعمل فقط ضد نقطة نهاية sandbox. لديك 90 يوماً من الإصدار لاستخدامه. بعد 90 يوماً يجب أن تطلب CSID امتثال جديد. هذا عن قصد — يجبرك على التكامل، وليس مجرد جمع الشهادات.

الخطوة 3: التكامل ضد sandbox

نقطة نهاية sandbox: https://sandbox-fatoorah.zatca.gov.sa. تدفق التكامل مطابق للإنتاج، لكن مع حد معدل معدل وقاعدة بيانات sandbox تُعاد يومياً. قبل أن تكتب أي كود، ثبّت أداة اختبار sandbox — تنشر زاتكا Swagger UI ومجموعة Postman في بوابة فاتورة.

الحد الأدنى من تكامل sandbox يبدو هكذا:

1. ابنِ فاتورة UBL 2.1 XML (المخطط في دليل هيكل XML).
2. وقّع الـ XML المعياري بمفتاحك الخاص باستخدام خوارزمية ECDSA أو RSA التي تتوقعها زاتكا.
3. احسب تجزئة SHA-256 للفاتورة السابقة في سلسلتك (تجزئة السلسلة — موضحة في دليل التشفير).
4. أرسل POST إلى /e-invoicing/clearance/single (B2B) أو /e-invoicing/reporting/single (B2C).
5. التقط تجزئة التخليص + العداد من الاستجابة. اختم PDF بتلك التجزئة.

اختبر 5-10 حالات حافة في sandbox: فاتورة ببند واحد، فاتورة بـ 20 بنداً، استرداد (إشعار دائن)، توجيه B2B مقابل B2C، بنود العملة الأجنبية (USD مسموح لكن الضريبة يجب أن تكون بالريال)، ووضع فشل "تجزئة الفاتورة السابقة مفقودة".

الخطوة 4: احصل على CSID الإنتاج

بمجرد أن يكون تكامل sandbox مستقراً لمدة 30+ يوماً وقمت بمعالجة 100 فاتورة اختبار على الأقل بدون أخطاء، ارجع إلى بوابة فاتورة: التسجيل → CSID الإنتاج → طلب CSID الإنتاج. ستسمح لك البوابة برفع نفس CSR (أو جديد إذا كنت قد دوّرت). تتحقق زاتكا من حالة الضريبة الخاصة بك وأنك في موجة مرحلة ثانية نشطة، ثم تصدر CSID الإنتاج.

CSID الإنتاج هو JWT الذي يستخدمه ERP / POS / الخدمة الإنتاجية الخاصة بك لتوقيع الفواتير الحية. صلاحيته سنة واحدة، بعدها يجب تدويره. سترسل لك زاتكا بريداً إلكترونياً قبل 30 يوماً من انتهاء الصلاحية. معظم الفرق تضع تذكيراً في التقويم للتجديد.

الخطوة 5: التحول إلى الإنتاج

التحول هو اللحظة الأكثر خطورة في التسجيل. النمط الذي يعمل:

1. انشر كودك للإنتاج لكن وجّهه إلى نقطة نهاية sandbox. عالج فاتورة حقيقية من عملية بيع حقيقية. تحقق من أن PDF يحمل تجزئة تخليص sandbox.
2. اقلب ثابت نقطة النهاية إلى الإنتاج. عالج فاتورة حقيقية أخرى. تحقق من ظهور تجزئة الإنتاج في PDF.
3. شغّل كلتا نقطتي النهاية بالتوازي لمدة 7 أيام. مهمة تسوية يومية: قارن تجزئات الإنتاج ضد دفتر الأستاذ الداخلي. أي انحراف هو خطأ.
4. بعد 7 أيام نظيفة، عطّل مسار sandbox.

وثّق التحول في سجل إدارة التغييرات. احتفظ بـ PDFs المرحلة الأولى السابقة لمدة 90 يوماً على الأقل بعد التحول — قد يطلب المدققون مقارنة جنباً إلى جنب.

العمليات: العدادات، إعادة المحاولة، وقاعدة 24 ساعة

ثلاثة أشياء تعض الناس في الإنتاج:

العدادات يجب أن تكون رتيبة لكل جهاز. تتوقع زاتكا أن يكون عداد الفاتورة (حقل PIH / UUID) في تزايد صارم لكل جهاز. إذا فقد نظام ERP رقماً — قل،الفاتورة #47 تم إلغاؤها وتنتقل إلى #48 — الاستدعاء التالي يفشل. الحل: استخدم UUID، وليس عدداً صحيحاً. UUIDs مضمونة الفريدة وزاتكا تقبلها.

أعد المحاولة بـ exponential backoff. يمكن لفاتورة إرجاع 503 / 504 في أول 90 يوماً من موجة جديدة عندما يكون الحمل مرتفعاً. يجب على عميلك إعادة المحاولة بـ exponential backoff (ابدأ بـ 1 ثانية، ضاعف، cap عند 60 ثانية) و idempotency — إذا نجح POST الأصلي لكنك لم تحصل على الاستجابة، فإن إعادة محاولة نفس تجزئة الفاتورة يجب ألا تكرر الفوترة.

قاعدة الإبلاغ 24 ساعة (B2C). فواتير B2C مبلغ عنها، وليست مخلصة. لديك 24 ساعة من الإصدار للإبلاغ عنها إلى فاتورة. إذا فاتتك النافذة، تضع زاتكا علامة "متأخر" على الفاتورة وتحصل على إشعار. الإصلاح هو إما الإبلاغ المجمّع ليلاً أو الإبلاغ في الوقت الفعلي — اختيارك.

متى تستعن بمزود حلول بدلاً من ذلك

التكامل المباشر هو القرار الصحيح إذا (أ) كان لديك فريق تطوير، (ب) كنت تصدر أكثر من ~5,000 فاتورة شهرياً (اشتراك SaaS يبدأ في الإطفاء تحت ذلك)، و(ج) كان لديك شخص واحد على الأقل بدوام كامل يمكنه الحفاظ على التكامل على المدى الطويل. إذا كان أي من هذه خاطئاً، فإن رياضيات تكلفة الملكية تفضل SaaS معتمد من زاتكا. قائمة مزودي الحلول المعتمدين بها 30+ بائع في 2026. اختر واحداً يدعم ERP الخاص بك بشكل أصلي (Odoo، ERPNext، Microsoft Dynamics، SAP، Oracle) قبل أن تختار واحداً لا يدعمه. للتحليل الكامل للتكلفة عبر مسارات التكامل الثلاثة والمواعيد النهائية لكل موجة، راجع دليل الموجات والمواعيد النهائية.

الأسئلة الشائعة

كم من الوقت تستغرق زاتكا لإصدار CSID؟
CSID الامتثال: فوري بعد رفع CSR. CSID الإنتاج: 1-5 أيام عمل، أحياناً أسرع. الـ 1-5 أيام هي قائمة مراجعة، وليست عملية تشفير.

ماذا يحدث إذا تم اختراق مفتاحي الخاص؟
يجب أن تدوره فوراً. يجب إلغاء CSID القديم من خلال بوابة فاتورة، وأي فواتير موقّعة بالمفتاح القديم بعد الاختراق غير مقبولة في النزاعات الضريبية. هذا حدث "عار ولوم"؛ عامل إدارة المفاتيح بالجدية التي تستحقها.

هل يمكنني استخدام نفس CSID عبر أنظمة متعددة (ERP + POS + التجارة الإلكترونية)؟
CSID واحد لكل جهاز. لمنشأة متعددة القنوات، سجّل كل نظام كجهاز منفصل. CSID مرتبط بالاسم الشائع (CN) في CSR، والذي يمكنك تعيينه لكل نظام.

هل لا زلت أحتاج المرحلة الأولى إذا كانت لدي المرحلة الثانية؟
نعم. المرحلة الثانية إضافية. رمز QR TLV على PDF، والتنسيق ثنائي اللغة، والاحتفاظ 5 سنوات — كلها لا تزال تنطبق. مولّد المرحلة الأولى المجاني يظل مفيداً لـ PDF الذي يواجه العميل حتى عندما يكون السجل الأساسي تخليص المرحلة الثانية.

ماذا عن مولدات "المرحلة الأولى فقط" القديمة التي باعها البائعون بـ 5,000 ريال؟
لا تزال قانونية. لم تعد كافية فحسب للمنشآت في موجة المرحلة الثانية. إذا اشتريت واحدة، فلا تحتاج إلى رميها — احتفظ بها للملء التلقائي أو للشركات التابعة تحت العتبة.