fbpx

دليل الأسئلة التقنية الشائعة حول حلول إصدار الفواتير الإلكترونية السعودية | 25 سؤالًا

8 دقائق للقراءة
دليل الأسئلة التقنية الشائعة حول حلول إصدار الفواتير الإلكترونية السعودية | 25 سؤالًا

ما بين السين والجيم احتار الكثير من المستخدمين في معرفة تفاصيل حلول إصدار الفواتير الإلكترونية السعودية، وزادت التساؤلات أيضًا عن البيئة التجريبية وكيفية الاستفادة منها.

في هذا المقال سنجيب بالتفصيل عن تلك التساؤلات لتتمكن من الانضمام إلى المنظومة بسهولة.

1- ما هي حزمة أدوات تطوير البرمجيات SDK؟

تعد حزمة أدوات تطوير البرمجيات SDK أداة فعالة للتحقق من الامتثال، ويمكن تنزيلها دون الحاجة إلى إنترنت، واستخدامها للتحقق من صحة ملفات XML وفقًا لمتطلبات وحلول إصدار الفواتير الإلكترونية السعودية.

بالإضافة إلى ذلك تسمح حزمة أدوات تطوير البرمجيات SDK بالتحقق من صحة رموز الاستجابة السريعة (QR code) وفقًا للهيكل المحدد.

2- كيف يمكن الحصول على حزمة أدوات تطوير البرمجيات SDK؟

كيف يمكن الحصول على SDK؟
تستطيع الحصول على حزمة أدوات تطوير البرمجيات SDK باتباع عدد من الخطوات كما يلي:

  1. الدخول على موقع هيئة الزكاة والضريبة والجمارك.
  2. الانتقال إلى صفحة “مطوري الأنظمة”.
  3. الدخول على صفحة “مجموعة أدوات التحقق من الامتثال”.

ومن ثم الموافقة على شرط إخلاء المسؤولية، وبهذا تبدأ عملية تنزيل الأدوات بكل سهولة وتضمن الامتثال لمتطلبات وحلول إصدار الفواتير الإلكترونية السعودية.

3- هل استخدام أدوات تطوير البرمجيات SDK إلزاميًا؟

لا يعد استخدام SDK أمرًا إلزاميًا، ولكن تحث هيئة الزكاة والضريبة والجمارك المستخدمين على استخدامها لضمان الالتزام بحلول إصدار الفواتير الإلكترونية السعودية.

كما يجب على المطوّرين استخدام حزمة أدوات تطوير البرمجيات من أجل اختبار وضعية عدم الاتصال بالإنترنت، وذلك لتقليل الحمل على البيئة التجريبية لطلبات التكامل والربط (Sandbox).

4- ما هي صيغة XML؟

عند ذكر رمز XML يجب أن يأتي في أذهاننا النظام والدقة، فهي صيغة إلكترونية لعرض البيانات بشكل منظم وقابل للقراءة آليًا، ولذلك تعتمد الهيئة على صيغة XML في حلول إصدار الفواتير الإلكترونية السعودية.

ويمكن للمطورين بكل سهولة التحقق من مطابقة ملفات XML ورمز الاستجابة السريع QR Code للمواصفات الخاصة بالفوترة الإلكترونية باستخدام أدوات أدوات تطوير البرمجيات SDK كما ذكرنا، ولكن التحقق لا يعني الحصول على موافقة هيئة الزكاة والضريبة والجمارك على مستند الفاتورة.

5- ماذا يحدث في حالة وجود خطأ في ملف XML؟

الأمر بسيط جدًا، ففي حالة حدوث أي خطأ في ملفات XML ستظهر رسائل أو ردود الأخطاء الواردة، وعند تحديدها يصبح المستخدم قادرًا على حل تلك المشاكل والتي في الأغلب تكون بسبب عدم إدخال البيانات المطلوبة في إحدى الحقول بشكل صحيح، وهنا يجوز للمستخدم طلب الحصول على مساعدة خبير تقني لتسوية ذلك الخطأ.

6- ما الحقول الخاصة برمز الاستجابة السريع QR Code في المرحلة الأولى؟

الحقول الخاصة برمز الاستجابة السريع QR Code في المرحلة الأولى
هناك حقول أساسية لا يمكن الاستغناء عنها عند إنشاء رمز الاستجابة السريع QR Code، ولا بد من التحقق من صحتها، وهي:

  • اسم المورد.
  • رقم تسجيل ضريبة القيمة المضافة للمورد.
  • التاريخ والوقت للفاتورة الإلكترونية.
  • إجمالي الفاتورة الإلكترونية بما يشمل ضريبة القيمة المضافة.
  • إجمالي ضريبة القيمة المضافة.

يجوز تضمين حقول إضافية فيما يتعلق بالمواصفات، لكن هيئة الزكاة والضريبة والجمارك لن تأخذها في الاعتبار.

تعرف أيضًا على متطلبات الفوترة الإلكترونية ومراحل تنفيذها.

7- ما الحقول الخاصة برمز الاستجابة السريع QR Code في المرحلة الثانية؟

لا تختلف الحقول الخاصة برمز الاستجابة السريع QR Code في المرحلة الثانية من إصدار الفاتورة الإلكترونية السعودية عما تم ذكره في المرحلة الأولى، ولكن هناك عدة حقول إضافية يجب التحقق من تواجدها، وتتمثل في:

  • اسم المورد.
  • رقم تسجيل ضريبة القيمة المضافة للمورد.
  • التاريخ والوقت للفاتورة الإلكترونية.
  • إجمالي الفاتورة الإلكترونية بما يشمل ضريبة القيمة المضافة.
  • إجمالي ضريبة القيمة المضافة.
  • دالة التشفير للفاتورة الإلكترونية أو الإشعار الدائن/المدين بصيغة XML.
  • خوارزمية ختم التشفير ECDSA.
  • المفتاح العام لخوارزمية ختم التشفير ECDSA.

8- ما واجهة الأوامر النصية CLI؟

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

مثال: (fatoora validatexml -f (invoicename.xml

تشير تلك الصيغة إلى تطبيق “فاتورة”؛ إذ تستخدم خاصية validatexml مع أمر a-f command، أما الجزء الثاني الذي نضيفه فهو (invoicename.xml) أي مسار صيغة XML واسم الملف الواجب التحقّق من صحته.

9- ما هي لغة “Java” وصيغة “جار”؟

لغة “Java” هي لغة برمجة تتوافق مع مختلف أنظمة التشغيل مثل “Windows” ولينكس، أما بالنسبة لـ”جار” فهي حزمة تنسيق ملفات تستخدم بشكل عام في تجميع العديد من ملفات “Java” والبيانات الوصفية “metadata” والموارد المرتبطة بها من نصوص وصور في ملف واحد للتوزيع.

يتم استخدام نسخة Java الخاصة بحزمة أدوات تطوير البرمجيات SDK ما بين 11 و15 ضمن حلول إصدار الفواتير الإلكترونية السعودية، ويجب تثبيتها قبل استخدام الحزمة، ولكن ماذا لو حدث خطأ في لغة Java؟

فور ثبوت حدوث خطأ من قبل المستخدم في لغة Java يتوجب عليه تثبيت لغة Java (النسخ ما بين 11 و15) قبل تشغيل حزمة أدوات تطوير البرمجيات SDK والبدء في استخدامها.

10- ما هي البيئة التجريبية لطلبات التكامل والربط Sandbox؟

المحاكاة والبيئة الافتراضية تزيد من التجارب الايجابية لأي منظومة جديدة، ولذلك حرصت هيئة الزكاة والضريبة والجمارك على تطوير بيئة تجريبية لمحاكاة بعض الخصائص الوظيفية لمنصة الفوترة الإلكترونية وستكون متاحة ضمن نظام الإنتاج.

الهدف الأساسي من إنشاء تلك المنصة هو السماح لمطوري حلول إصدار الفواتير الإلكترونية السعودية بتطوير حلول تقنية مماثلة لمتطلبات حلول إصدار الفواتير الإلكترونية السعودية، كما يمكن من خلالها إرسال طلبات إلى البيئة التجريبية لطلبات التكامل والربط Sandbox والحصول على ردود متعلقة بمدى نجاحها أو وجود أي أخطاء بها.

11- ما الفرق بين أدوات التحقق من الامتثال والبيئة التجريبية لطلبات التكامل والربط Sandbox؟

يعد الفارق الجوهري بين كلٍ من أدوات التحقق من الامتثال والبيئة التجريبية لطلبات التكامل والربط Sandbox أن الأولى تتكون من:

  • حزمة أدوات تطوير البرمجيات SDK غير متصلة بالإنترنت، وذلك للتحقق من صحة QR Code وملفات XML.
  • برنامج التحقق من الامتثال عبر المنصة Portal-based من أجل تمكين المستخدمين غير التقنيين من التحقق من ملفات XML.

أما الثانية تتمحور وظيفتها حول السماح باختبار ربط حلول إصدار الفواتير الإلكترونية السعودية مع البيئة التجريبية باستخدام واجهات برمجة تطبيقات تجريبية بطريقة مماثلة للطريقة الخاصة بمنصة الفوترة الإلكترونية.

باستخدام البيئة التجريبية سيكون بإمكانك إجراء عمليات التحقق التي تعد جزءًا من مجموعة حزمة أدوات تطوير البرمجيات SDK، بالإضافة إلى بعض عمليات المراجعة والتحقق الإضافية التي لا يمكن إجراؤها خارج خدمة الاتصال بالإنترنت.

12- هل يشترط عند التأكد من تماثل الفواتير باستخدام SDK أن تحققه أيضًا في Sandbox؟

من المتوقع أن تحقق ملفات XML المستخدمة ضمن حلول إصدار الفواتير الإلكترونية استجابة ناجحة من البيئة التجريبية ما لم تكن هناك مشكلة في طلب واجهة برمجة التطبيقات API، ومع ذلك يمكن أيضًا للبيئة التجريبية إجراء بعض عمليات التحقق الإضافية.

13- هل البيئة التجريبية لطلبات التكامل والربط Sandbox متاحة للمكلفين فقط؟

لا يقتصر استخدام البيئة التجريبية لطلبات التكامل والربط Sandbox على المكلفين بالتسجيل الضريبي فقط، إذ يمكن للمطورين أيضًا التسجيل من خلال تقديم المعلومات المطلوبة والاطلاع على وثائق واجهة برمجة التطبيقات API المتاحة على المنصة.

14- هل يمكن إرسال فواتير متعددة إلى البيئة التجريبية Sandbox؟

بالفعل يمكن إرسال فواتير متعددة إلى البيئة التجريبية لطلبات الربط والتكامل Sandbox، ولا يشترط تقديمها بشكل متسلسل، ولكن من الضروري أن تكون كل فاتورة أو إشعار دائن/ مدين جزءًا من طلب منفصل لواجهة برمجة التطبيقات API.

15- هل تُحفظ الفواتير المقدمة إلى البيئة التجريبية من قبل هيئة الزكاة والضريبة والجمارك؟

لا، فإن هيئة الزكاة والضريبة والجمارك لا تحتفظ بأية فواتير مقدمة إلى البيئة التجريبية لطلبات التكامل والربط Sandbox باعتبارها مكان للمحاكاة فقط.

16- هل تتطلب البيئة التجريبية وجود تفاصيل المكلفين الفعلية في ملفات XML؟

لا يتطلب الأمر وجود تفاصيل فعلية للمكلفين عند استخدام البيئة التجريبية لطلبات التكامل والربط Sandbox، ويمكن تقديم معلومات وهمية بهدف الاختبار فقط طالما أنها تستوفي جميع المتطلبات والمحتوى ومعايير تنفيذ XML وقواعد العمل.

17- هل يمكن استخدام نفس اسم المستخدم وكلمة المرور الخاصة بـ SDK في تسجيل الدخول إلى Sandbox؟

بالطبع؛ فعملية تسجيل الدخول هي ذاتها لكل من SDK والبيئة التجريبية لطلبات التكامل والربط (Sandbox).

18- ما هو ختم التشفير والمُعرف الخاص به (CSID)؟

ختم التشفير -Cryptographic stamp- هو ختم إلكتروني يتم استخدامه ضمن حلول إصدار الفواتير الإلكترونية السعودية لضمان صحة الفاتورة، وهو بمثابة بيانات اعتماد تسمح بالتصديق على عمليتي التوقيع وتشفير عملية الاتصال فيما يعرف أيضًا باسم شهادة المفتاح العام أو شهادة الهوية.

أما عن معرف الختم فهو رمز فريد يستخدم في تحديد وتمييز كل وحدة من وحدات الحل التقني المستخدم في إصدار الفواتير من قبل المكلف، وذلك من أجل ختم الفواتير المُبسطة، إلى جانب الوصول إلى واجهات برمجة التطبيقات لمشاركة الفواتير واعتمادها عن طريق بروتوكول أمان طبقة النقل TLS.

يمكن استخدام نفس رمز التعريف لختم التشفير CSID في تقديم أي فاتورة طالما أن رقم التسجيل الضريبي في الرمز التعريفي هو نفس الرقم الموجود بالمستندات، علمًا بأنه يمكن استخدام رقم وهمي يستوفي المواصفات ويتكون من 15 رقم تبدأ بـ 3 وتنتهي بـ 3.

19- ما هي واجهة برمجة التطبيقات لمشاركة الفواتير Reporting API؟

واجهة تتم من خلالها مشاركة فاتورة مُبسطة أو إشعار دائن/ مدين واحد، وتستخدم طريقة الترميز base64 لقبول تلك المستندات والتحقق من صحتها لضمان الامتثال إلى ما يلي:

  • معايير لغة UBL2 XSD.
  • مجموعة قواعد EN 16931.
  • مجموعة القواعد الخاصة بالمملكة العربية السعودية.
  • صحة رمز الاستجابة السريعة (QR code).
  • صحة ختم التشفير.

وكي يتمكن المستخدم من الدخول إلى Reporting API يحتاج إلى إجراء طريقة POST (رفع البيانات) على نقطة نهاية الاتصال/ الفواتير/المشاركة/طلب واحد وتمريرها بهدف المصادقة وتحديد اللغة المفضلة كأحد المعايير الواردة في العنوان.

والجدير بذكره أنه يجب على المستخدم إرسال نص طلب يحتوي على القيمتين التاليتين: الأولى “invoiceHash” والثانية “invoice”.

وفي حالة نجاح Reporting API يتوقع أن يصل للمستخدم الرد كما يلي: 200 HTTP Ok مع نص يتضمن 4 قيم:

  • InvoiceHash
  • Status
  • Warnings
  • Errors

20- ما هي واجهة برمجة التطبيقات لاعتماد الفواتير Clearance API؟

الوظيفة الأساسية لـ Clearance API هي اعتماد فاتورة ضريبية أو إشعار دائن/مدين واحد باستخدام طريقة الترميز base64 والتحقق من صحته الامتثال إلى:

  • معايير لغة UBL2 XSD.
  • مجموعة قواعد EN 16931.
  • مجموعة القواعد الخاصّة بالمملكة العربية السعودية، على أن تلغي مجموعة قواعد المملكة العربية
  • السعودية قواعد EN 16931 في حال وجود نفس القاعدة في كلتا المجموعتين.

يمكن للمستخدم الدخول إلى واجهة برمجة التطبيقات Clearance API بنفس طريقة الدخول إلى Reporting API، ومع إتمام عملية التحقق بنجاح، تقوم واجهة برمجة التطبيقات API بتضمين ختم التشفير وإنشاء رمز استجابة سريع مع مشاركة ملفات XML مرة أخرى.

21- ما هو نص الطلب الذي يجب إرساله عند استخدام Clearance API؟

تتمثل النصوص التي يجب توافرها في الطلب الذي يجب إرساله عند استخدام واجهة برمجة التطبيقات لاعتماد الفواتير Clearance API في قيمتين: InvoiceHash و Invoice.

أما عن الرد فيحتوي على 200 HTTP Ok مع نص يحتوى على نفس القيم التي يتم استلامها عند نجاح Reporting API.

22- إلام ترمز الأرقام التي يمكن أن تظهر أثناء تقديم طلب Reporting API وطلب Clearance API؟

هناك عدد من الأرقام التي من المحتمل أن تظهر للمستخدم أثناء تقديم طلب واجهة برمجة التطبيقات لمشاركة الفواتير Reporting API وواجهة برمجة التطبيقات لاعتماد الفواتير Clearance API، وهي:

  • 200 : يشير ذلك إلى أن HTTP صحيح.
  • 202: هذا يدل على قبول الفاتورة الضريبية المبسطة مع وجود بعض الأخطاء.
  • 303: يرمز ذلك إلى “HTTP see other”، ويعني إعادة الفاتورة عندما تكون فاتورة ضريبية أثناء تفعيل الاعتماد.
  • 400: يشير ذلك إلى “HTTP Bad Request”، بمعنى إعادة الفاتورة في حالة أن الطلب المقدم غير صحيح.
  • 500: يرمز إلى “HTTP Internal Server Error” وهذا يدل على إعادة الفاتورة عندما تواجه الخدمة أخطاء داخلية.

23- ما هو برنامج التحقق القائم على المنصة الخاصة بمجموعة أدوات التحقق من الامتثال “Portal-based Validator”؟

الدور الأساسي لبرنامج التحقق Portal-based Validator هو مساعدة المستخدمين غير التقنيين (الفريق المعني بالضرائب – الحسابات) في اختبار ملفات XML الخاصة بهم والتحقق من صحتها كي تتماشى مع متطلبات وحلول إصدار الفواتير الإلكترونية السعودية؛ إذ يمكن لأي شخص الدخول إلى برنامج التحقق من الامتثال عبر المنصة Postal-based من خلال بوابة المطورين.

24- هل من الضروري استخدام حزمة أدوات تطوير البرمجيات SDK أو برنامج التحقق من الامتثال عبر المنصة Portal-based؟

إنه ليس بالأمر الإلزامي، ولكن لضمان الامتثال لمتطلبات وحلول إصدار الفواتير الإلكترونية السعودية تحث هيئة الزكاة والضريبة والجمارك المستخدمين التقنيين وغير التقنيين على استخدام حزمة أدوات تطوير البرمجيات SDK وبرنامج التحقق من الامتثال عبر المنصة Portal-based.

25- ما هو رمز الاستجابة السريع QR Code؟

رمز الاستجابة السريع QR Code هو تمثيل مشفر لنص مقروء، ويتم إدراجه في حلول إصدار الفواتير الإلكترونية السعودية كبيان أساسي داخل الفاتورة يحتوي على جميع البيانات الخاصة بها بصيغة محددة.

لكي يستطيع المستخدم معرفة البيانات الكامنة داخل رمز الاستجابة السريع QR Code يجب مسح الرمز الموجود على ضمن الفاتورة الإلكترونية باستخدام تطبيق الهيئة الخاص بضريبة القيمة المضافة، ويمكن الحصول على ذلك التطبيق بشكل مجاني من على المتاجر الإلكترونية (Google Play Store – iOS App Store).

وبعد أن تناولنا معظم التساؤلات التي تدور في أذهان المستخدمين حول حلول إصدار الفواتير الإلكترونية السعودية والبيئة التجريبية الخاصة بها، أصبحت الآن على استعداد تام لخوض تلك الرحلة.

تعرف على تفاصيل أكثر من خلال هيئة الزكاة والضريبة والجمارك.

مقالات ذات صلة

5 دقائق للقراءة

أهم 6 معلومات عن منظومة الإيصال الإلكتروني 2022

بدأت رحلة التحول الرقمي بشكل تدريجي في الانتشار مع جميع المعاملات التجارية والاقتصادية، واستكمالًا لمنظومة الفاتورة الإلكترونية تم البدء في التعامل مع منظومة الإيصال الإلكتروني والحرص على إصدار المؤسسات جميع…

5 دقائق للقراءة

أهم 21 سؤالًا حول تطبيق منظومة الإيصال الإلكتروني

تعددت التساؤلات حول تطبيق منظومة الإيصال الإلكتروني؛ فهناك من يريد معرفة كيفية التعامل مع جميع الأمور الخاصة بها، ومن يريد تسجيل نقاط البيع POS ولكن يستصعب الأمر، لذلك نوفر لك…

6 دقائق للقراءة

كيف تتم عملية التسجيل في منظومة الإيصال الإلكتروني 2022؟

بالتزامن من تطبيق نظام الإيصال الإلكتروني ظهرت العديد من التساؤلات حول كيفية القيام بعملية التسجيل، هل توجد بيانات محددة يجب أخذها بعين الاعتبار؟ وهل تتم عملية التسجيل من مكان محدد؟…