فاتورتك مرفوضة؟
أصلحها هنا.
اعثر على رمز الخطأ أدناه، افهم سبب حدوثه، واحصل على الحل في ثوانٍ. يغطي هذا الدليل أكثر 15 خطأ شيوعاً في رفض فواتير المرحلة الثانية من زاتكا.
تجزئة الفاتورة غير صالحة
❌ تجزئة الفاتورة لا تتطابق مع القيمة المحسوبة
API Response: 400 Bad Request | Error Code: INVALID_INVOICE_HASH
🔍 لماذا يحدث هذا:
تجزئة SHA-256 في UBLExtensions لا تتطابق مع محتوى الفاتورة الفعلي. يحدث هذا عند تعديل الفاتورة بعد التوقيع.
✅ الحل:
أعد إنشاء تجزئة الفاتورة بعد الانتهاء من جميع الحقول. يجب حساب التجزئة على XML المعياري (C14N) قبل التوقيع. لا تعدل الفاتورة بعد التجزئة أبداً.
هيكل رمز QR غير صالح
❌ رمز QR لا يحتوي على جميع حقول TLV المطلوبة
API Response: 400 Bad Request | Error Code: INVALID_QR_STRUCTURE
🔍 لماذا يحدث هذا:
المرحلة الثانية تتطلب 9 علامات TLV في رمز QR (العلامات 1-9). المرحلة الأولى تطلبت 5 علامات فقط.
✅ الحل:
تأكد من أن رمز QR يتضمن جميع العلامات التسع: اسم البائع، الرقم الضريبي، الطابع الزمني، إجمالي الفاتورة، إجمالي الضريبة، تجزئة الفاتورة، توقيع ECDSA، المفتاح العام، وتوقيع الشهادة.
الرقم الضريبي للبائع مفقود
❌ الرقم الضريبي للبائع مطلوب
API Response: 400 Bad Request | Error Code: MISSING_SELLER_VAT
🔍 لماذا يحدث هذا:
قسم AccountingSupplierParty يفتقد عنصر PartyTaxScheme/CompanyID أو أنه فارغ.
✅ الحل:
أضف الرقم الضريبي المكون من 15 رقماً في cac:AccountingSupplierParty > cac:Party > cac:PartyTaxScheme > cbc:CompanyID. الصيغة: 3XXXXXXXXXX00003
صيغة الرقم الضريبي غير صالحة
❌ الرقم الضريبي لا يتطابق مع متطلبات صيغة زاتكا
API Response: 400 Bad Request | Error Code: INVALID_VAT_FORMAT
🔍 لماذا يحدث هذا:
أرقام ضريبة القيمة المضافة السعودية يجب أن تكون 15 رقماً بالضبط، تبدأ بـ '3' وتنتهي بـ '00003'.
✅ الحل:
تحقق من صيغة الرقم الضريبي: 3XXXXXXXXXX00003. الرقم الأول يجب أن يكون 3، والأرقام الخمسة الأخيرة يجب أن تكون 00003.
رمز نوع الفاتورة غير صالح
❌ رمز نوع الفاتورة لا يتطابق مع القيم المسموح بها
API Response: 400 Bad Request | Error Code: INVALID_INVOICE_TYPE
🔍 لماذا يحدث هذا:
استخدام InvoiceTypeCode غير صحيح. زاتكا تقبل رموزاً محددة فقط لأنواع الفواتير المختلفة.
✅ الحل:
استخدم الرموز الصحيحة: 388 (فاتورة عادية)، 381 (إشعار دائن)، 383 (إشعار مدين). لفواتير B2C المبسطة، يجب تحديد النوع الفرعي أيضاً.
شهادة CSID منتهية الصلاحية
❌ شهادة الختم الرقمي انتهت صلاحيتها
API Response: 401 Unauthorized | Error Code: CERTIFICATE_EXPIRED
🔍 لماذا يحدث هذا:
شهادة CSID لها فترة صلاحية (عادةً سنة واحدة). بعد انتهائها، سترفض جميع الفواتير.
✅ الحل:
جدد شهادة CSID عبر بوابة فاتورة قبل انتهاء الصلاحية. أنشئ CSR جديد وأكمل عملية التجديد. قيمة تراقب انتهاء الشهادة وتنبهك قبل 30 يوماً.
تاريخ إصدار الفاتورة مفقود
❌ تاريخ إصدار الفاتورة (cbc:IssueDate) مطلوب
API Response: 400 Bad Request | Error Code: MISSING_ISSUE_DATE
🔍 لماذا يحدث هذا:
عنصر cbc:IssueDate مفقود أو فارغ في عنصر الفاتورة الرئيسي.
✅ الحل:
أضف IssueDate بصيغة YYYY-MM-DD. مثال: <cbc:IssueDate>2026-01-08</cbc:IssueDate>. يجب أن يكون تاريخاً تقويمياً صالحاً.
وقت إصدار الفاتورة مفقود
❌ وقت إصدار الفاتورة (cbc:IssueTime) مطلوب
API Response: 400 Bad Request | Error Code: MISSING_ISSUE_TIME
🔍 لماذا يحدث هذا:
المرحلة الثانية تتطلب التاريخ والوقت معاً. كثير من أنظمة المرحلة الأولى لا تتضمن عنصر الوقت.
✅ الحل:
أضف IssueTime بصيغة HH:MM:SS. مثال: <cbc:IssueTime>14:30:00</cbc:IssueTime>. استخدم نظام 24 ساعة.
التوقيع الرقمي غير صالح
❌ فشل التحقق من التوقيع الرقمي
API Response: 400 Bad Request | Error Code: INVALID_SIGNATURE
🔍 لماذا يحدث هذا:
توقيع ECDSA لا يتطابق مع المحتوى الموقع، أو تم إنشاء التوقيع بمفتاح خاص خاطئ.
✅ الحل:
تأكد من توقيع محتوى XML المعياري الصحيح بالمفتاح الخاص المطابق لشهادة CSID. استخدم منحنى secp256k1 لـ ECDSA.
عدم تطابق تجزئة الفاتورة السابقة (PIH)
❌ تجزئة الفاتورة السابقة لا تتطابق مع السلسلة
API Response: 400 Bad Request | Error Code: PIH_MISMATCH
🔍 لماذا يحدث هذا:
PIH (تجزئة الفاتورة السابقة) يجب أن تساوي تجزئة الفاتورة المقدمة سابقاً. هذا ينشئ سلسلة مقاومة للتلاعب.
✅ الحل:
احفظ تجزئة كل فاتورة مقدمة. استخدم تلك التجزئة المحفوظة كـ PIH للفاتورة التالية. للفاتورة الأولى، استخدم تجزئة صفرية (64 صفراً).
لا ترَ هذه الأخطاء مجدداً
قيمة تتحقق من أكثر من 100 قاعدة BR-KSA باستخدام SDK الرسمي من زاتكا قبل كل إرسال. نكتشف الأخطاء قبل حدوثها. صفر فواتير مرفوضة منذ الإطلاق.
هل أنت مستعد للتخلص من أخطاء زاتكا؟
انضم لمئات الشركات السعودية بدون فواتير مرفوضة. ابدأ تجربتك المجانية اليوم.