زاتكا Sandbox مقابل Production: دليل الربط الكامل خطوة بخطوة [2026]

خرافة شائعة: “إذا كان الأمر يعمل في Sandbox، يمكنني فقط تغيير الرابط إلى Production وانتهى الأمر.”

هذه أسرع طريقة لرفض عملية الربط الخاصة بك.

لدى هيئة الزكاة والضريبة والجمارك (ZATCA) ثلاث بيئات متميزة. الخلط بينها يؤدي إلى تواقيع غير صالحة، شهادات (CSID) محظورة، وفشل في الامتثال. يشرح هذا الدليل بالضبط كيفية الانتقال من “مرحلة الكود” إلى “فاتورة حية”.

البيئات الثلاث

1. بيئة المطورين (Sandbox)

• الرابط: sandbox.zatca.gov.sa
• الهدف: ساحة لعب وتجربة.
• المخاطرة: صفر.
• ما تفعله هنا: اختبار منطق الكود، هيكلية XML، واتصال API.
• تفصيل هام: الشهادة (CSID) التي تحصل عليها هنا وهمية. لن تعمل أبداً على فاتورة حقيقية.

2. بيئة المحاكاة (بوابة فاتورة)

• الرابط: fatoora.zatca.gov.sa (وضع المحاكاة)
• الهدف: ما قبل الإنتاج / اختبار قبول المستخدم (UAT).
• المخاطرة: منخفضة (لكنها مراقبة).
• ما تفعله هنا: محاكاة عملية تهيئة حقيقية. تسجل الدخول ببيانات الشركة الحقيقية ولكن تضع علامة على الشهادة بأنها “محاكاة”.
• إجبارية؟ نعم. غالباً ما تطلب الهيئة اجتياز الفحوصات هنا قبل الانتقال للإنتاج.

3. بيئة الإنتاج (الحية)

• الرابط: core.zatca.gov.sa (نقطة اتصال API)
• الهدف: الإبلاغ الضريبي الحقيقي.
• المخاطرة: عالية. كل فاتورة تُرسل هنا هي وثيقة ضريبية قانونية.
• ما تفعله هنا: إصدار فواتير حقيقية للعملاء.

خطوة بخطوة: من الكود إلى البث الحي

الخطوة 1: التهيئة “الوهمية” (Sandbox)

• الهدف: التحقق من كود إنشاء XML الخاص بك.
• الإجراء:
  1. اذهب إلى بوابة المطورين.
  2. اطلب رمز تحقق (OTP) مؤقت.
  3. شغّل السكريبت الخاص بك للحصول على BinarySecurityToken.
  4. أرسل فاتورة تجريبية.
• النجاح: تحصل على حالة REPORTED أو CLEARED.

الخطوة 2: فحص الامتثال (مرحلة CSID)

قبل أن تتمكن من إرسال أي فاتورة، يجب أن يثبت برنامجك (EGS) أنه يعمل بشكل صحيح.

• الإجراء:
  1. قم بإنشاء طلب توقيع شهادة (CSR) على خادمك.
  2. استدعِ نقطة الاتصال compliance.
  3. تطلب منك الهيئة إرسال 3 مستندات محددة:
     • فاتورة ضريبية (Standard Invoice)
     • إشعار دائن (Credit Note)
     • إشعار مدين (Debit Note)
  4. حاسم: يجب أن تجتاز هذه المستندات الفحص بشكل مثالي.

الخطوة 3: تهيئة الإنتاج

بمجرد اجتياز الامتثال، تطلب شهادة الإنتاج (PCSID).

• الإجراء:
  1. سجل الدخول لبوابة “فاتورة” ببيانات الرئيس التنفيذي/المالك.
  2. انتقل إلى “تهيئة حل جديد” (Onboard New Solution).
  3. أنشئ رمز تحقق (OTP) للإنتاج.
  4. استخدم هذا الرمز في برنامجك خلال 60 دقيقة.
  5. يستلم برنامجك “المفتاح الذهبي” (PCSID).

تحذير: احفظ هذا المفتاح بشكل آمن. إذا فقدته، لا يمكنك استعادته. يجب عليك إلغاؤه والبدء من جديد.

عقبات شائعة

1. كتابة المفتاح العام في الكود (Hardcoding)

غالباً ما يقوم المطورون بكتابة المفتاح العام لبيئة Sandbox داخل منطق التحقق. عند الانتقال للإنتاج، يفشل التحقق من التوقيع لأن شهادة الإنتاج مختلفة.

2. خدعة UUID “00000”

في Sandbox، قد تستخدم معرفات وهمية. في الإنتاج، يتم تطبيق القاعدة BR-KSA-03 بصرامة. كل مستند يحتاج إلى معرف UUID (الإصدار 4) حقيقي.

3. نسيان تغيير الروابط

إرسال فاتورة إنتاج (موقعة بمفتاح إنتاج) إلى رابط API الخاص بـ Sandbox سيعيد خطأ 401 Unauthorized أو Invalid Signature. يجب أن تتطابق البيئة، المفتاح، والرابط.

قائمة التحقق: هل أنت جاهز للإنتاج؟

• يحتوي ملف CSR الخاص بي على الرقم الضريبي الصحيح للإنتاج (يبدأ بـ 3 وينتهي بـ 3).
• لقد اجتزت فحص الامتثال للمستندات الثلاثة.
• لدي خزانة/قاعدة بيانات آمنة لتخزين مفتاح الإنتاج الخاص (لا تضعه في الكود أبداً!).
• لدي آلية لتجديد الشهادة (CSID) حيث أنها تنتهي الصلاحية!.

---

تجاوز وجع الرأس

إدارة ثلاث بيئات وتدوير المفاتيح هو عمل DevOps معقد.

قيمة (Qeemah) تدير دورة الحياة هذه نيابة عنك. نحن نوفر واجهة برمجة تطبيقات (API) واحدة. أنت ترسل لنا الفاتورة، ونحن نوجهها لبيئة الهيئة الصحيحة بناءً على إعداداتك.

تحدث مع خبير