زاتكا المرحلة الثانية: التكامل مع منصة فاتورة — الخطوات والمتطلبات

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

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

نظرة عامة على المرحلة الثانية

تقوم المرحلة الثانية على مبدأ بسيط: كل فاتورة تُصدرها منشأتك يجب أن تصل إلى زاتكا إما قبل مشاركتها مع العميل (Clearance) أو خلال 24 ساعة من إصدارها (Reporting). الآليتان تختلفان حسب نوع الفاتورة:

شهادة CSID: البوابة إلى منصة فاتورة

CSID هي اختصار Cryptographic Stamp Identifier، وهي الشهادة الرقمية التي تُصدرها زاتكا لكل نظام فوترة (وليس لكل منشأة بالضرورة، بل لكل حل برمجي مستخدَم). تمر عملية الحصول عليها بثلاث مراحل:

1. توليد مفتاح خاص وطلب CSR

يُولِّد نظام الفوترة مفتاحاً خاصاً (Private Key) بخوارزمية ECDSA P-256، ثم يُنشئ طلب توقيع شهادة (CSR) يتضمن رقم التسجيل الضريبي للمنشأة ومعلومات النظام.

2. تقديم CSR إلى زاتكا (Onboarding)

يُرسَل CSR إلى نقطة نهاية /compliance في API زاتكا. تُعيد زاتكا شهادة CSID صالحة لمدة 3 سنوات، مع رقم تعريفي فريد (RequestID) لكل جهاز أو حل.

3. تجديد الشهادة (Renewal)

قبل انتهاء صلاحية الشهادة بـ 30 يوماً يُطلَب من المنشأة تجديدها عبر نقطة نهاية /renewal. التأخر في التجديد يُعطِّل عملية Clearance.

متطلبات التكامل مع API زاتكا

تُوفِّر زاتكا واجهة برمجية (API) RESTful يجب على نظام الفوترة الاندماج معها. النقاط الرئيسية:

• Compliance Check API: للتحقق من صحة XML قبل الإرسال الفعلي.
• Clearance API: لإرسال فواتير B2B واستلام الختم الرقمي.
• Reporting API: لإرسال فواتير B2C خلال 24 ساعة.
• بيئة الاختبار (Sandbox): متاحة على fatoora.zatca.gov.sa/zatca/services لاختبار الربط قبل الإنتاج.

كل طلب API يجب أن يتضمن في الرأس (Header):

• شهادة CSID مشفَّرة بـ Base64.
• توقيع الطلب بالمفتاح الخاص.
• UUID الفريد للفاتورة.
• رقم الفاتورة التسلسلي.
• هاش SHA-256 لملف XML.

جدول موجات المرحلة الثانية

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

تُبلِّغ زاتكا كل منشأة قبل 6 أشهر من موعد دخولها في المرحلة الثانية لإتاحة الوقت الكافي للتجهيز. إذا لم تستلم إشعاراً رسمياً، راجع بريد منشأتك المسجَّل في بوابة زاتكا.

المتطلبات التقنية التفصيلية

يجب أن يُوفِّر نظام الفوترة المستخدَم في المرحلة الثانية ما يلي:

• توليد XML وفق مخطط KSA UBL 2.1 الإصدار 2.0 على الأقل.
• دعم التوقيع الرقمي بخوارزمية XAdES-BES مع شهادة CSID.
• توليد رمز QR بترميز TLV مع الحقول الستة (يُضاف في المرحلة الثانية الحقل 6: توقيع الختم).
• إدارة طوابير الإرسال مع معالجة حالات الخطأ وإعادة المحاولة.
• تخزين استجابات زاتكا (الختم + XML المُعاد) مع كل فاتورة.
• وضع عمل بدون اتصال (Offline) مع رفع تلقائي عند استعادة الاتصال.

قائمة التجهيز قبل الربط

1. تأكَّد من موعد موجتك عبر بوابة زاتكا.
2. اختر نظام فوترة يدعم المرحلة الثانية تقنياً.
3. اختبر الربط في بيئة Sandbox لمدة لا تقل عن شهر.
4. أصدر شهادة CSID الإنتاجية من زاتكا.
5. درِّب الفريق المالي والتقني على إجراءات الطوارئ.
6. وثِّق إجراءات التعامل مع فواتير المرفوضة (4xx/5xx).
7. تحقق من سياسة النسخ الاحتياطي وحفظ استجابات زاتكا.

أسئلة شائعة عن المرحلة الثانية