بيئة اختبار زاتكا (Sandbox): كيف تختبر الربط والتكامل قبل الإطلاق الفعلي

مقدمة حول بيئة اختبار زاتكا (Sandbox)

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

في هذا الدليل، سنأخذك في جولة تقنية وإجرائية حول خطوات اختبار بيئة الـ Sandbox لضمان جاهزية منشأتك لمتطلبات الفوترة الإلكترونية.

ما هي بيئة اختبار زاتكا (Sandbox)؟

بيئة الـ Sandbox هي بيئة محاكاة توفرها هيئة الزكاة والضريبة والجمارك (ZATCA) تتيح للمنشآت:

• التحقق من فواتير XML: التأكد من أن هيكل فاتورة UBL 2.1 يتوافق مع المعايير السعودية.
• اختبار واجهات البرمجية (APIs): التحقق من الاتصال بواجهات الاعتماد (Clearance) للفواتير الضريبية (B2B) وواجهات الإبلاغ (Reporting) للفواتير المبسطة (B2C).
• التأكد من الأمان الرقمي: اختبار توليد شهادات التشفير (CSIDs).
• معالجة الأخطاء: تحديد وإصلاح أخطاء التحقق قبل أن تؤثر على السجلات الضريبية الحقيقية.

المتطلبات الأساسية للبدء في الاختبار

قبل البدء، يجب أن تتوفر لديك المكونات التقنية التالية:

1. ملف CSR: طلب توقيع الشهادة للحصول على الهوية الرقمية من الهيئة.
2. المفتاح الخاص (Private Key): مفتاح يتم توليده بشكل آمن لتوقيع الفواتير رقمياً.
3. الرقم الضريبي: رقم ضريبي صالح للمنشأة التي يتم اختبارها.
4. المعرفة بهيكل UBL 2.1 XML: فهم طريقة بناء الفواتير الإلكترونية السعودية.

💡 نصيحة: استخدم أداة فحص الجاهزية من قيمة لمعرفة مدى استعداد بياناتك للربط.

خطوات سير عمل الاختبار (Step-by-Step)

1. مرحلة التهيئة وتوليد شهادة الامتثال (CCSID)

الخطوة الأولى هي الحصول على رمز أمان ثنائي (Binary Security Token) من خلال واجهة برمجة تطبيقات الامتثال (Compliance API). يتم إرسال ملف CSR إلى الهيئة لاستلام شهادة امتثال (CCSID)، والتي تسمح لك بإجراء فحص الامتثال لعينات الفواتير.

2. اختبار واجهة الامتثال

يجب إرسال أنواع مختلفة من الفواتير لواجهة الامتثال لإثبات قدرة النظام على التعامل مع الحالات المختلفة، وتشمل:

• الفواتير الضريبية القياسية (B2B).
• الفواتير الضريبية المبسطة (B2C).
• الإشعارات الدائنة والمدينة.
• فواتير بنسب ضريبية مختلفة (15%، 5%، صفرية، معفاة).

3. فهم الرموز التقنية الإلزامية

أثناء الاختبار، يجب التأكد من تنفيذ الحقول التالية بدقة:

الحقل	الوصف	الأهمية
UUID	المعرف الفريد عالمياً	يمنع تكرار إرسال الفاتورة نفسها.
ICV	عداد الفواتير	رقم تسلسلي يجب أن يكون تراكمياً ولا يقبل التكرار.
PIH	هاش الفاتورة السابقة	يربط الفاتورة الحالية بالسابقة لمنع التلاعب بالسجلات.
QR Code	ترميز TLV	يجب أن يحتوي على التوقيع الرقمي والمفتاح العام.

أخطاء شائعة في بيئة الـ Sandbox وكيفية حلها

غالباً ما تظهر أخطاء أثناء الاختبار، إليك أبرزها:

• 401 Unauthorized: يعني عادةً أن شهادة (CSID) قد انتهت صلاحيتها أو أن التوقيع غير صحيح.
• 400 Bad Request: ناتج عن فشل في التحقق من هيكل ملف XML.
• BR-KSA-31: يشير إلى أن هاش الفاتورة السابقة (PIH) لا يتطابق مع السجل.
• KSA-2: وجود مشكلة في كود فئة الضريبة أو منطق الحساب.

الانتقال من بيئة الاختبار إلى البيئة الفعلية

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

⚠️ تحذير: لا تستخدم أبداً شهادات الاختبار (Sandbox CSIDs) في المعاملات الحقيقية، لأن ذلك سيؤدي إلى إصدار فواتير غير نظامية وتعريض منشأتك للغرامات.

كيف يساعدك نظام “قيمة” في الربط مع زاتكا؟

إن التعامل مع تعقيدات ملفات CSR، وترميز TLV، والربط مع APIs قد يكون مرهقاً للمنشآت الصغيرة والمتوسطة. نظام قيمة مصمم ليتولى كل هذه المهام التقنية نيابة عنك:

• تهيئة آلية: نقوم بإدارة عملية الحصول على شهادات التشفير والربط مباشرة مع الهيئة.
• تحقق فوري: يقوم نظامنا بفحص الفاتورة والتأكد من سلامتها قبل إرسالها إلى منصة فاتورة.
• التزام كامل بالمرحلة الثانية: من توليد الـ UUID إلى ربط الـ PIH، يقوم قيمة بأتمتة التسلسل بالكامل.
• تكامل الوحدات: سواء كنت تستخدم وحدة المبيعات أو المخازن، فإن كل حركة مالية جاهزة للربط مع زاتكا تلقائياً.

لا تترك امتثالك الضريبي للصدفة. انضم إلى آلاف المنشآت السعودية التي تثق في “قيمة” لإدارة فواتيرها الإلكترونية.

استكشف مميزات قيمة | تعرف على باقات الأسعار | تواصل مع خبرائنا