مشاركة هامة لمن يقوم باستخدام الرقم الضريبي في بيئة التطوير (Sandbox)
مرحباً بالمطورين الأعزاء،
أود أن أشارككم تجربة قد توفر عليكم الكثير من الوقت والجهد أثناء العمل على بيئة التطوير (Sandbox) الخاصة بهيئة الزكاة والضريبة والجمارك (ZATCA).
عند استخدام واجهة برمجة التطبيقات (API) للحصول على شهادة (CSID) في بيئة التطوير، قد تلاحظون أن العملية تتم بنجاح حتى لو استخدمتم رقماً ضريبياً وهمياً في ملف CSR. هذا أمر طبيعي ومتوقع.
ولكن، النقطة الجوهرية التي تسببت في حيرتي وتأخيري هي أن الشهادة النهائية التي يتم إعادتها لكم من الـ API ستحتوي دائماً على الرقم الضريبي الثابت 399999999900003 بغض النظر عن الرقم الذي أدخلتموه في ملف الـ CSR.
هذا يعني أنه عند الانتقال إلى الخطوات اللاحقة مثل إرسال الفواتير، يجب عليكم استخدام الرقم الضريبي الثابت 399999999900003، وليس الرقم الذي استخدمتموه في البداية. إذا حاولتم إرسال الفاتورة بأي رقم آخر، سيتم رفضها.
من وجهة نظري، هذا الغموض غير ضروري وكان من الأفضل أن يتم توضيحه بشكل مباشر في التوثيق الرسمي. لأن المنطق السليم يدفع المطور للاعتقاد بأن الرقم الذي أدخله وتم قبول طلبه بناءً عليه هو الرقم الذي سيستخدمه في التجارب اللاحقة. وقد يستغرق الأمر يوماً كاملاً أو أكثر في محاولات فاشلة قبل اكتشاف هذا الأمر.
لقد قمت بالبحث في التوثيق المتوفر ولم أجد ما يشير صراحةً إلى أن الـ API ستعيد الشهادة برقم ضريبي ثابت دائماً.
إذا كان هناك أي توثيق رسمي يوضح هذه النقطة بالتحديد، فأرجو من أي شخص لديه علم به أن يشاركنا الرابط.
أتمنى أن يكون هذا التوضيح مفيداً لجميع من يواجهون نفس المشكلة.
شكراً جزيلاً.
**
Important note for developers: The Sandbox environment returns a fixed VAT number**
Hello everyone,
I want to share a crucial detail about the ZATCA Sandbox environment that can save you a lot of time.
After successfully completing the CSR process, the final certificate (CSID) you receive from the API will always contain the fixed VAT number 399999999900003, regardless of the number you used in your initial CSR file.
This means you must use this specific fixed VAT number for all subsequent API calls to test invoice submission. Using your own dummy VAT number will result in invoice rejection.
This behavior isn’t clearly documented and can lead to a lot of frustration. It would be helpful if ZATCA could add a clear note about this in the official documentation.