معالجة أخطاء فواتير ZATCA في WooCommerce

تسجل رصيدو حالة الفواتير وردود ZATCA داخل لوحة تحكم WooCommerce. إذا فشل إصدار فاتورة أو ظلت معلقة، فابدأ بفتح WooCommerce > الفوترة الإلكترونية (ZATCA) > الفواتير الإلكترونية.

يغطي هذا الدليل مشكلات ربط المتجر والإبلاغ عن الفواتير والشهادات وصفحات الفواتير الخاصة بالعملاء. تحقق من حالة المستند ورد ZATCA عليه قبل تغيير الإعدادات.

فشل ربط المتجر بسبب رمز التحقق

ما الذي تراه

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

السبب

قد تكون صلاحية رمز التحقق (OTP) المكون من 6 أرقام قد انتهت. تكون رموز ZATCA صالحة لمدة ساعة واحدة، وقد يفشل الربط أيضًا إذا سبق استخدام الرمز.

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

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

المعالجة

تحقق من البيئة المحددة في WooCommerce > الفوترة الإلكترونية (ZATCA) > بيانات البائع. إذا كنت تستخدم بيئة الاختبار، فاستخدم رمز التحقق التجريبي الذي توفره رصيدو.

إذا كنت تستخدم بيئة المحاكاة أو بيئة الإنتاج، فسجّل الدخول إلى بوابة فاتورة. أنشئ رمز تحقق (OTP) جديدًا مكونًا من 6 أرقام لربط وحدة جديدة من نظام الفوترة الإلكترونية.

ارجع إلى تبويب «الربط»، وأدخل الرمز الجديد خلال ساعة من إصداره. ثم اضغط على اربط هذا المتجر مرة أخرى.

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

رفض ZATCA للفاتورة

ما الذي تراه

تظهر الفاتورة بحالة مرفوضة في علامة تبويب الفواتير الإلكترونية. ويحتوي طلب WooCommerce المرتبط بها على ملاحظة تتضمن معلومات الرفض الواردة من ZATCA.

لم تجتز الفاتورة فحوصات التحقق لدى ZATCA في عملية الإرسال تلك.

السبب

قد ينتج الرفض عن معلومات غير صحيحة للبائع أو رقم ضريبي غير صالح أو بيانات عنوان لا تستوفي المتطلبات. ويتحدد السبب الفعلي بحسب رد ZATCA على المستند.

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

المعالجة

افتح WooCommerce > الفوترة الإلكترونية (ZATCA) > الفواتير الإلكترونية، وابحث عن المستند المرفوض. اقرأ سبب الرفض الذي أرسلته ZATCA وحدد الحقل أو بيانات المستند التي تحتاج إلى تصحيح.

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

بعد التصحيح، يجب إصدار مستند مصحح. لا تفترض أن إعادة إرسال ملف XML المرفوض نفسه ستعالج خطأ موجودًا في محتواه.

احتفظ بمعلومات الرفض الأصلية ضمن سجلاتك. وإذا لم يكن سبب الرفض واضحًا، فأرفق رد ZATCA عند التواصل مع الدعم.

بقاء الفواتير في حالة معلقة

ما الذي تراه

يحتوي طلب WooCommerce المدفوع على فاتورة، لكن عملية إرسالها ما زالت معلقة. ولا تعرض علامة تبويب الفواتير الإلكترونية ردًا مكتملًا من ZATCA على المستند.

قد يظهر أيضًا تنبيه في صحة الموقع (Site Health) بشأن مستندات تأخر إرسالها.

السبب

تنشئ رصيدو الفواتير الضريبية المبسطة وتتولى الإبلاغ عنها في الخلفية باستخدام Action Scheduler الخاص بـ WooCommerce. وتعتمد عملية الإرسال على تشغيل المهام المجدولة.

إذا كان WP-Cron أو Action Scheduler لا يعمل، فقد تبقى عمليات الإرسال في قائمة الانتظار. وقد تؤدي مشكلات الشبكة أو انقطاع خدمات ZATCA إلى تأخير الإبلاغ أيضًا.

تعيد رصيدو محاولة الإرسال لعدة ساعات عند حدوث هذه المشكلات، ضمن مهلة الإبلاغ البالغة 24 ساعة.

المعالجة

افتح WooCommerce > الحالة > الإجراءات المجدولة (Scheduled Actions). تحقق من تنفيذ المهام المجدولة، وابحث عن المهام الفاشلة أو التي تجاوزت موعد تنفيذها.

إذا كانت المهام لا تُنفذ، فافحص مشكلة WP-Cron أو Action Scheduler على موقع WordPress. ثم افتح علامة تبويب الفواتير الإلكترونية وراجع المستندات المتأثرة.

تحقق مما إذا كانت رصيدو قد سجلت رفضًا من ZATCA أو كانت عملية الإرسال ما زالت معلقة. تجنب إنشاء فواتير بديلة بصورة متكررة قبل معرفة نتيجة إرسال المستند الأصلي.

يجب الإبلاغ عن الفواتير الضريبية المبسطة إلى ZATCA خلال 24 ساعة. إذا اقترب المستند من هذه المهلة، فافحص قائمة المهام المجدولة وتواصل مع الدعم، مع إرسال حالة المستند والرد المتوفر.

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

اقتراب انتهاء صلاحية الشهادة أو انتهاؤها

ما الذي تراه

تعرض صحة الموقع (Site Health) في WordPress تنبيهًا بشأن اقتراب انتهاء صلاحية شهادة الفوترة الإلكترونية. تبدأ رصيدو بعرض هذا التنبيه قبل انتهاء الصلاحية بـ 30 يومًا.

وقد تكتشف أيضًا أن الشهادة قد انتهت صلاحيتها بالفعل.

السبب

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

لا يمكن التعامل مع الشهادة المنتهية على أنها شهادة توقيع سارية.

المعالجة

افتح WooCommerce > الفوترة الإلكترونية (ZATCA)، وتأكد من البيئة المرتبطة بمتجرك. ثم سجّل الدخول إلى بوابة فاتورة وأنشئ رمز تحقق (OTP) جديدًا للبيئة المناسبة.

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

تحقق من اكتمال ربط المتجر، ثم راجع علامة تبويب الفواتير الإلكترونية. وإذا كانت الشهادة قد انتهت بالفعل، فافحص المستندات المتأثرة قبل اعتبارها صادرة أو تم الإبلاغ عنها بنجاح.

فقدان بيانات الربط بعد نقل الموقع

ما الذي تراه

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

السبب

تشفّر رصيدو الشهادات والمفاتيح الخاصة باستخدام قيمتي AUTH_KEY وSECURE_AUTH_KEY في WordPress. وإذا تغيرت هاتان القيمتان أثناء نقل الموقع، فلن تتمكن الإضافة من فك تشفير بيانات الربط التي شُفّرت باستخدام القيم القديمة.

المعالجة

تحقق مما إذا تغيرت قيمة AUTH_KEY أو SECURE_AUTH_KEY أثناء نقل الموقع. إذا تغيرت المفاتيح، فأكمل ربط المتجر مرة أخرى باستخدام رمز تحقق (OTP) جديد للبيئة المحددة.

لا تحتاج إلى إعادة إنشاء الفواتير السابقة بسبب تغيير مفاتيح الأمان. تبقى ملفات XML الموقعة وردود ZATCA المحفوظة دون تأثر.

بعد إكمال الربط، افتح علامة تبويب الفواتير الإلكترونية وتحقق من معالجة المستندات الجديدة. ولا ترسل مفاتيح أمان WordPress أو مفاتيح التوقيع الخاصة أو كلمات المرور إلى الدعم.

تعذر فتح صفحة الفاتورة للعميل

ما الذي تراه

يبلغك أحد العملاء بأن رابط الفاتورة لا يفتح الصفحة المطلوبة. وقد يكون الطلب مكتملًا والفاتورة صادرة، لكن العميل لا يستطيع الوصول إليها باستخدام الرابط المتوفر لديه.

السبب

توفر رصيدو صفحة فاتورة للعميل بالعربية والإنجليزية، وتتضمن رمز QR. وتُفتح هذه الصفحة باستخدام مفتاح طلب WooCommerce.

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

المعالجة

افتح طلب WooCommerce المتأثر، وتحقق من إصدار فاتورته. استخدم رابط الفاتورة المرتبط بالطلب بدلًا من إنشاء رابط يدويًا.

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

إذا استمر تعذر فتح الرابط الأصلي، فتواصل مع الدعم وأرسل معلومات الطلب ووصف المشكلة. لا تنشر مفتاح طلب العميل في مكان عام.

عدم قبول رمز QR بواسطة تطبيق الفحص

ما الذي تراه

لا يقبل تطبيق الفحص رمز QR، أو يظهر أن الرمز يحتوي على حقول أقل من المتوقعة لمستندات المرحلة الثانية (الربط والتكامل). وقد يكون العميل يفحص رمز QR صادرًا من إضافة أخرى للفوترة.

السبب

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

المعالجة

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

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

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

التواصل مع الدعم وإرسال بيانات المستند

راسل info@raseedo.com للمساعدة في مشكلات التثبيت أو ربط المتجر أو المستندات المرفوضة أو صفحات فواتير العملاء. تشمل برو دعمًا ذا أولوية عبر البريد الإلكتروني، دون التزام بوقت استجابة محدد.

أرفق المعلومات التالية:

1. إصدار WordPress وإصدار WooCommerce وإصدار إضافة رصيدو المستخدم في متجرك.
2. البيئة التي تستخدمها، سواء بيئة الاختبار أو بيئة المحاكاة أو بيئة الإنتاج.
3. مرجع الطلب أو الفاتورة المتأثرة، والحالة المعروضة في علامة تبويب الفواتير الإلكترونية.
4. رد ZATCA على المستند، بما فيه سبب الرفض إن كان متوفرًا.
5. وصفًا مختصرًا لما حدث والخطوات التي جربتها لمعالجة المشكلة.

لا ترسل المفاتيح الخاصة أو رموز التحقق (OTP) أو كلمات المرور أو مفاتيح أمان WordPress بالبريد الإلكتروني. واحذف بيانات الدخول والاعتماد الحساسة من أي معلومات ترسلها.

لتعليمات التثبيت وربط المتجر، راجع دليل الإعداد.