وضع الاختبار
ابنِ الربط على بيئة اختبار قبل أن تلمس بيانات التاجر الفعلية. مفتاح الاختبار يعمل تماماً مثل المفتاح الفعلي، على نفس الـ Host ونفس المسارات، لكن كل طلب يصل إلى بيئة الاختبار الخاصة بالتاجر: نسخة منفصلة من بياناته الأساسية، فواتيرها تُوقَّع بشهادات الاختبار من هيئة الزكاة والضريبة ولا تصل أبداً إلى سجلاته الفعلية في الهيئة.
الحصول على مفتاح اختبار
ينشئ التاجر بيئة الاختبار من لوحة التحكم في الإعدادات ← المطوّرون ← بيئة الاختبار، ثم يصدر مفتاح اختبار من الإعدادات ← المطوّرون ← مفاتيح الربط. يبدأ مفتاح الاختبار بـ ksr_test_:
Authorization: Bearer ksr_test_7c1e...
كل رد على طلب بمفتاح اختبار يحمل الـ Header Kosoor-Mode: test. تحقق منه في الكود عندك إذا أردت التأكد أن الطلب لم يصل إلى البيانات الفعلية.
ماذا تحتوي بيئة الاختبار
- فروع التاجر وأصنافه وطرق الدفع وشجرة الحسابات والمستودعات، منسوخة وقت بناء البيئة.
- لا شيء من عملائه أو فواتيره أو مدفوعاته. أنشئ ما تحتاجه بنفسك، أو استخدم البيانات الجاهزة في الأسفل.
- اسم التاجر وعنوانه، مع الرقم الضريبي التجريبي من الهيئة
399999999900003.
ملفات PDF من بيئة الاختبار تحمل علامة حمراء نسخة اختبار — ليست فاتورة ضريبية. ولا ترسل بيئة الاختبار أي رسائل SMS.
عندما تكون البيئة مشغولة
أثناء بناء بيئة الاختبار أو إعادة تعيينها، يرجع مفتاح الاختبار بالخطأ 503 sandbox_unavailable مع الـ Header Retry-After: 30. انتظر ثم أرسل نفس الطلب مرة أخرى.
إذا تعذّر بناء البيئة، يرجع مفتاح الاختبار بالخطأ 503 sandbox_failed بدون Retry-After، ولن تنجح إعادة المحاولة حتى يعيد التاجر تعيين البيئة. وأثناء حذف البيئة، ترجع مفاتيح الاختبار بالخطأ 401 invalid_api_key.
إعادة التعيين تبني البيئة من جديد من بيانات التاجر الأساسية الحالية. مفاتيح الاختبار تبقى تعمل، وتُمسح كل المستندات وسجل الطلبات. أما حذف البيئة فيوقف كل مفاتيح الاختبار.
البيانات الجاهزة
كل بيئة اختبار فيها هؤلاء العملاء وصنف واحد بمعرّفات ثابتة، ولكل منهم نتيجة معروفة. استخدمهم لاختبار التعامل مع الأخطاء عندك دون أن تجهّز البيانات بنفسك.
| المعرّف | الاسم | النتيجة |
|---|---|---|
5a4db0c5-0000-4000-8000-000000000001 | Sandbox Person | الفاتورة المبسطة تنجح |
5a4db0c5-0000-4000-8000-000000000002 | Sandbox Standard Co | الفاتورة الضريبية تُعتمد من الهيئة |
5a4db0c5-0000-4000-8000-000000000003 | Sandbox CRN Co | منشأة لها سجل تجاري وبلا رقم ضريبي، والفاتورة الضريبية تُعتمد |
5a4db0c5-0000-4000-8000-000000000004 | Sandbox No Street Co | الفاتورة الضريبية تُرفض: 422 customer_address_incomplete |
5a4db0c5-0000-4000-8000-000000000005 | Sandbox Gulf Trading | منشأة في الإمارات، والفاتورة الضريبية تُعتمد |
5a4db0c5-0000-4000-8000-000000000006 | Sandbox Inactive Person | أي فاتورة تُرفض: 422 customer_inactive |
5a4db0c5-0000-4000-8000-000000000007 | Sandbox Credit Limit Co | حد الائتمان 100، والفاتورة الآجلة فوقه ترجع 422 credit_limit_exceeded |
5a4db0c5-0000-4000-8000-000000000008 | Sandbox ZATCA Pending Co | الفاتورة الضريبية ترجع 201 وzatca.status قيمته pending، ثم تُعتمد بعدها بقليل |
5a4db0c5-0000-4000-8000-000000000009 | Sandbox ZATCA Rejected Co | الفاتورة الضريبية تُرفض: 422 zatca_rejected، مع مثال BR-KSA-63 في zatcaErrors |
5a4db0c5-0000-4000-8000-000000000101 | Test subscription (صنف) | أي سطر فيه هذا الصنف يُرفض: 422 item_not_sellable |
العميلان 8 و9 لا يصلان إلى الهيئة وقت إصدار الفاتورة: نتيجتهما تأتي من كسور نفسها، لذلك تتكرر بنفس الشكل في كل مرة.