سلسلة السلطة التقنية

الدليل غير الرسمي لـ
بوابة فاتورة

الركيزة الأساسية للاقتصاد الرقمي في المملكة. جسر الفجوة بين المراسيم التنظيمية والحقائق التقنية الدقيقة لعملية الربط مع زاتكا. [1]

اتقن عملية التهيئة البوابة الرسمية ↗
1

التشريح المعماري

يتطلب التنقل في مشهد "زاتكا" فهم البيئات الثلاث المتميزة. الخلط بينها هو السبب الرئيسي لفشل عملية الربط. [11]

البيئة التجريبية

sandbox.zatca.gov.sa

للتطوير الأولي. اختبار توافق هيكل XML مع معايير UBL 2.1. الشهادات الصادرة هنا لا تعمل في البيئة الواقعية. [8]

بيئة المحاكاة

fatoora.zatca.gov.sa (UAT)

نسخة طبق الأصل من بيئة الإنتاج. تفرض قواعد العمل الحقيقية. ضرورية لاختبارات ما قبل "يوم الانطلاق". [13]

بيئة الإنتاج

fatoora.zatca.gov.sa

البيئة الحية. كل فاتورة يتم اعتمادها هنا هي مسؤولية قانونية ضريبية. تتطلب بيانات "إيراد" والتحقق الثنائي. [12]

2

نموذج التشغيل الهجين

نموذج الاعتماد

B2B & B2G

تدفق متزامن. يرسل النظام ملف XML إلى بوابة فاتورة. تقوم البوابة بالتحقق، الختم، وإعادة الفاتورة الموقعة.

⚠️ فقط ملف XML المعتمد هذا هو المستند الضريبي القانوني. [6]

نموذج الإرسال

B2C (Retail)

الأولوية للسرعة. يقوم النظام بتوقيع الفاتورة محلياً باستخدام شهادة CSID مخزنة. يحصل العميل على الفاتورة فوراً.

⚡ لدى النظام 24 ساعة للإبلاغ عنها للبوابة. [7]
3

الأسس التشفيرية

  • ٠١
    منحنى secp256k1

    على عكس RSA، تفرض زاتكا تشفير المنحنى الإهليلجي. استخدام المنحنى الخاطئ يؤدي لرفض طلب الشهادة فوراً. [8]

  • ٠٢
    طلب توقيع الشهادة (CSR)

    يجب أن يحتوي على معرفات كائنات (OIDs) مخصصة تربط الجهاز بالرقم الضريبي للمنشأة وأنواع الفواتير. [18]

  • ٠٣
    سلسلة الهاش (Hash Chain)

    لمنع حذف الفواتير، يجب أن تحتوي كل فاتورة على هاش SHA-256 للفاتورة السابقة (PIH). الفاتورة الأولى تبدأ بهاش "٠".

4

الخطوات التقنية للتهيئة

الخطوة ١

توليد رمز OTP

يتم توليده من بوابة فاتورة من قبل المكلف. صالح لمدة ساعة واحدة فقط. يبني جسر الثقة بين البوابة ونظامك. [5]

الخطوة ٢

شهادة الامتثال (CCSID)

يستدعي النظام واجهة برمجة تطبيقات الامتثال مع الرمز وطلب التوقيع المحلي. تعيد الهيئة شهادة مقيدة للاختبار. [21]

الخطوة ٣

دورة فحص الامتثال

يجب على النظام تقديم فواتير عينة لإثبات قدرته على توليد XML صحيح وفقاً لجميع قواعد العمل. [30]

الخطوة ٤

شهادة الإنتاج (PCSID)

بعد النجاح، يطلب النظام ترقية الشهادة. تصدر الهيئة شهادة PCSID—"المفتاح الذهبي" للعمليات الحية. [29]

5

فك رموز الأخطاء الشائعة

🔍 تبحث عن رموز أخطاء محددة؟ راجع دليلنا الشامل مع 15 خطأ تفصيلي من زاتكا.

تصفح مرجع رموز أخطاء زاتكا ←
كود الخطأ المعنى الأثر
BR-S-09 عدم تطابق حساب ضريبة القيمة المضافة. عادة بسبب فروق التقريب. رفض
BR-KSA-31 رقم المبنى يجب أن يتكون من ٤ أرقام. شائع في البيانات غير المنظمة. [34] تحذير
Hash Mismatch هاش الفاتورة السابقة لا يتطابق مع السلسلة المسجلة لدى الهيئة. رفض

قائمة التحقق التشغيلية

٦أ
استلام إشعار الهيئة ومراجعة جاهزية برنامجك للمرحلة الثانية. [4]
٤أ
الدخول لبيئة المحاكاة وبدء اختبارات "التشغيل التجريبي". [13]
١أ
توليد رموز OTP للإنتاج وتهيئة جميع الأجهزة. [17]

المصادر والمراجع التقنية
  1. كومبلاينس (Complyance.io)، "تهيئة أجهزة EGS — المرحلة الثانية من زاتكا".
  2. هيئة الزكاة والضريبة والجمارك، "دليل كيف تستعد للمرحلة الثانية؟".
  3. هيئة الزكاة والضريبة والجمارك، "المبادئ التوجيهية التفصيلية للفوترة الإلكترونية - الإصدار الثاني".
  4. سيدين تكنولوجيز (Sedin Technologies)، "دليل الامتثال والموجات للفوترة الإلكترونية في السعودية".
  5. مجتمع مطوري فاتورة، "وثائق التهيئة وتجديد الشهادات".
  6. كلير تاكس (ClearTax)، "شرح حلول EGS والربط مع زاتكا".
  7. وافق (Wafeq)، "دليل سريع: الإبلاغ عن فاتورة مبسطة لهيئة الزكاة".
  8. هيئة الزكاة والضريبة والجمارك، "دليل مستخدم بوابة المطورين (الإصدار 2)".
  9. هيئة الزكاة والضريبة والجمارك، "دليل مستخدم بوابة المطورين (الإصدار 3)".
  10. هيئة الزكاة والضريبة والجمارك، "أدوات الامتثال والتمكين (SDK) - الوثائق التقنية".
  11. مدونة EINV، "أنواع واجهات برمجة التطبيقات (APIs) وبيئات زاتكا".
  12. هيئة الزكاة والضريبة والجمارك، "دليل مستخدم بوابة فاتورة (النسخة الرسمية)".
  13. منتدى مطوري زاتكا، "الفرق بين بوابة فاتورة وبيئة المحاكاة".
  14. Tax2Gov، "شرح الوصول لمنصة فاتورة للمكلفين".
  15. برايس ووترهاوس كوبرز (PwC)، "دليل مستخدم بوابة فاتورة الصادر عن هيئة الزكاة".
  16. كلير تاكس (ClearTax)، "كيفية تجديد شهادات CSID الحالية".
  17. VATUpdate، "دليل مستخدم بوابة فاتورة".
  18. منتدى مطوري زاتكا، "عملية توليد طلب توقيع الشهادة (CSR) والمتطلبات".
  19. كلير تاكس (ClearTax)، "كيفية إلغاء (Revocation) شهادات CSID".
  20. QuickDice ERP، "ماذا يعني طلب توقيع الشهادة (CSR)؟".
  21. مايكروسوفت دايناميكس 365، "تهيئة الفوترة الإلكترونية في المملكة العربية السعودية".
  22. منتدى مطوري زاتكا، "هل هناك فرق بين بيئة المحاكاة والإنتاج عند إنشاء CSR؟".
  23. Medium، "دليل تكامل زاتكا مع Laravel".
  24. أبي زاتكا (ApiZatca)، "حل أخطاء شهادات الإنتاج في منظومة فاتورة".
  25. Stack Overflow، "خطأ شهادة الإنتاج لا تغطي المستندات المبسطة".
  26. كلير تاكس (ClearTax)، "كيفية التحقق من فاتورة زاتكا باستخدام رمز QR".
  27. تالية (Tally Solutions)، "دليل بوابة فاتورة في المملكة العربية السعودية".
  28. منتدى مطوري زاتكا، "استرجاع OTP تلقائياً عبر SAML SSO".
  29. منتدى مطوري زاتكا، "كيفية الحصول على شهادة الإنتاج (CSID)".
  30. منتدى مطوري زاتكا، "مشكلة الحصول على شهادة الإنتاج بعد إكمال الامتثال".
  31. QuickDice ERP، "تجديد شهادات CSID في نظام الفوترة الإلكترونية".
  32. Claudion، "التحقق من صحة فواتير زاتكا".
  33. كلير تاكس (ClearTax)، "كيفية حل أخطاء الفواتير الإلكترونية".
  34. منتدى مطوري زاتكا، "خطأ عند محاولة اعتماد الفاتورة".
  35. أبي زاتكا (ApiZatca)، "الأسئلة الشائعة حول المرحلة الثانية".
  36. منتدى Manager.io، "مشكلة في التكامل مع زاتكا".
  37. Cygnet.One، "بوابة فاتورة السعودية: الدليل الكامل".
  38. Vita-xpro.com، "قائمة رموز الأخطاء الإلزامية من زاتكا".
  39. منتدى مطوري زاتكا، "توضيح حول تحذيرات وأخطاء التحقق".
  40. هيئة الزكاة والضريبة والجمارك، "مراحل الإطلاق".
  41. إي واي (EY)، "المملكة العربية السعودية تعلن عن الموجة ٢٢".
  42. تومسون رويترز (Thomson Reuters)، "تأثير إرشادات زاتكا على المنشآت".

تخلص من الديون التقنية

لا تضيع شهوراً في فك رموز مخططات UBL 2.1 ومنحنيات التشفير. قيمة يتولى عملية الربط مع بوابة فاتورة بالكامل.

ابدأ الربط مع زاتكا عرض دليل المطورين
Chat with us on WhatsApp