محرك التحقق الخاص بهيئة الزكاة والضريبة والجمارك (ZATCA) دقيق للغاية ولا يتهاون. مسافة إضافية واحدة في ملف XML أو اختلاف في التقريب بمقدار 0.01 ريال سعودي قد يتسبب في حالة Rejected (مرفوض) أو Failed (فشل).

في قيمة (Qeemah)، قمنا بمعالجة وتصحيح آلاف طلبات الاعتماد. إليك أهم 15 خطأ رفض نراه وكيفية إصلاحها بالضبط.

الأخطاء “الحرجة” (توقف النظام)

1. عدم تطابق الختم الرقمي (Cryptographic Stamp Mismatch)

الخطأ: The cryptographic stamp is invalid. السبب: قمت بتعديل ملف XML بعد توقيعه، أو أن منطق التوحيد القياسي (Canonicalization - C14N) لديك غير صحيح. الحل: تأكد من أنك تقوم بتشفير النسخة الموحدة (Canonicalized) من الفاتورة، وليس النص الخام.

<!-- خطأ: التشفير بوجود مسافات -->
<cbc:ID> INV-001 </cbc:ID>
<!-- صحيح: التشفير للنص الموحد بدقة -->
<cbc:ID>INV-001</cbc:ID>

يجب أن يكون التوقيع هو آخر شيء تتم إضافته قبل تضمينه في امتدادات UBL.

2. فشل تسلسل التشفير (Hash Chain Failure - PIH)

الخطأ: The Previous Invoice Hash (PIH) does not match the computed hash. السبب: أنت ترسل الفاتورة رقم 5 ولكنك تربطها بتشفير (Hash) الفاتورة رقم 3. الحل:

تسلسل صارم: الفاتورة N يجب أن تحتوي على تشفير الفاتورة N-1.
الفاتورة الأولى: إذا كانت هذه هي الفاتورة الأولى لنظام الفوترة (EGS)، فإن التشفير السابق (PIH) يجب أن يكون تشفير SHA256 لقيمة “0” (صفر) مشفرة بصيغة Base64.
- القيمة: NWZl... (تشفير الصفر)

3. معرف UUID غير صالح (KSA-2)

الخطأ: BR-KSA-03: The UUID must be a universally unique identifier. السبب: إعادة استخدام نفس المعرف (UUID) أو استخدام تنسيق غير قياسي. الحل: قم بإنشاء معرف UUID (الإصدار 4) جديد لكل مستند جديد تماماً.

<cbc:UUID>550e8400-e29b-41d4-a716-446655440000</cbc:UUID>

أخطاء الحسابات وضريبة القيمة المضافة

4. تقريب بنود الفاتورة (BR-S-09)

الخطأ: BR-S-09: The sum of the line item amounts does not equal the total invoice amount. السبب: حساب (السعر * الكمية * الضريبة) لكل بند مقابل حسابه على الإجمالي. الحل: تتطلب الهيئة دقة على مستوى البند.

احسب الضريبة لكل بند.
قرب الناتج لمنزلتين عشريتين.
اجمع القيم المقربة. لا تقم بالجمع أولاً ثم تطبيق الضريبة.

5. رمز الفئة الضريبية غير صحيح

الخطأ: BR-KSA-EN16931-12: The tax category code is invalid. السبب: استخدام الرمز S (أساسي) لفاتورة تصدير أو Z (صفري) بدون ذكر كود السبب. الحل:

أساسي (15%): الرمز S
صفري (0%): الرمز Z (يتطلب cbc:TaxExemptionReasonCode)
معفى: الرمز E

6. فقدان الرقم الضريبي للمشتري (VRN)

الخطأ: BR-KSA-26: Buyer VAT number is required for B2B. السبب: إرسال فاتورة “ضريبية” (B2B) ولكن معاملتها كفاتورة “مبسطة” (B2C). الحل: إذا كان InvoiceTypeCode هو 0100000 (ضريبية)، يجب عليك تضمين الرقم الضريبي للمشتري في cac:AccountingCustomerParty.

الأخطاء الهيكلية و XML

7. فقدان امتدادات UBL الخاصة بالهيئة

الخطأ: The UBL extension for ZATCA is missing. السبب: استخدام مولد UBL 2.1 قياسي دون الأغلفة الخاصة بمتطلبات السعودية. الحل: يجب أن يحتوي ملف XML الخاص بك على كتلة <ext:UBLExtensions> التي تحتوي على رمز الاستجابة السريعة (QR)، التوقيع، والخصائص الموقعة.

8. رمز QR غير صالح

الخطأ: KSA-QR-01: The QR code is not decodable. السبب: ترميز TLV (Tag-Length-Value) خاطئ. الحل: رمز QR ليس مجرد رابط. إنه سلسلة Base64 لبيانات TLV تحتوي على:

اسم البائع
الرقم الضريبي
الطابع الزمني
الإجمالي مع الضريبة
مبلغ الضريبة
تشفير الفاتورة (Hash)
التوقيع الرقمي (ECDSA)
المفتاح العام
توقيع الختم

9. التواريخ المستقبلية

الخطأ: The IssueDate cannot be in the future. السبب: اختلاف المنطقة الزمنية للخادم. الحل: تأكد من مزامنة وقت الخادم مع توقيت السعودية القياسي (UTC+3).

10. فجوات في التسلسل الرقمي

الخطأ: Metric: Invoices must be sequential. السبب: حذف فاتورة من قاعدة البيانات الخاصة بك. الحل: لا تحذف فاتورة أبداً. إذا ارتكبت خطأ، أصدر إشعار دائن (Credit Note). التسلسل INV-001، INV-002، INV-004 سيؤدي إلى تدقيق من الهيئة.

أخطاء التهيئة والشهادات

11. رمز التحقق (OTP) غير صالح أو منتهي الصلاحية

الخطأ: Invalid OTP. السبب: استخدام OTP تم إنشاؤه منذ أكثر من ساعة أو للبوابة الخطأ (Sandbox مقابل Simulation). الحل: قم بإنشاء رمز OTP جديد من بوابة “فاتورة” مباشرة قبل تشغيل سكريبت التهيئة.

12. عدم تطابق CSR

الخطأ: The Certificate Signing Request (CSR) organization does not match. السبب: الرقم الضريبي في إعدادات CSR (ملف cnf) لا يطابق الرقم الضريبي لحساب الدخول في بوابة “فاتورة”. الحل: تحقق مرتين من إعدادات openssl الخاصة بك. حقل UID في الموضوع (Subject) يجب أن يكون رقمك الضريبي المكون من 15 خانة.

13. نوع الفاتورة خاطئ للشهادة (CSID)

الخطأ: Compliance check failed. السبب: محاولة اعتماد فاتورة ضريبية باستخدام شهادة تم إنشاؤها للفواتير المبسطة (أو العكس). الحل: عند التهيئة، حدد النوع بشكل صحيح:

1000: ضريبية فقط (Standard)
0100: مبسطة فقط (Simplified)
1100: كلاهما

أخطاء “خفية” (منطقية)

14. غياب الترجمة العربية

الخطأ: Rule: Invoice must contain Arabic. السبب: إرسال أوصاف باللغة الإنجليزية فقط. الحل: تتطلب الهيئة وجود اللغة العربية للحقول الأساسية.

<cbc:Description>Consulting Services | خدمات استشارية</cbc:Description>

15. أخطاء الفاتورة الصفرية (Nominal)

الخطأ: Price cannot be zero. السبب: منح خصم 100% بشكل خاطئ بجعل السعر صفر. الحل: لا تجعل السعر 0. ضع السعر بالقيمة الفعلية، واستخدم cac:AllowanceCharge لتطبيق الخصم.

هل تعبت من تصحيح أخطاء XML؟

لا ينبغي أن تكون خبيراً في لغة XML لتتمكن من بيع منتجاتك.

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

تحقق من ملف XML الآن

أشهر 15 خطأ رفض في الفوترة الإلكترونية (ZATCA) وكيفية إصلاحها