INVALID-INVOICE-HASH 🔐 التشفير والتوقيع والهاش error

خطأ هاش الفاتورة غير صالح: عدم تطابق بصمة الفاتورة الرقمية

INVALID-INVOICE-HASH: Cryptographic Invoice Hash Mismatch

المواصفة التقنية المعتمدة من زاتكا:

يقوم نظام زاتكا بالتحقق من بصمة SHA-256 بعد تطبيق قواعد المعيارية C14N11. أي اختلاف في المسافات أو الترميز يبطل الهاش.

XPath Context: /ubl:Invoice/ext:UBLExtensions/.../ds:DigestValue

📌 نبذة عن القاعدة وسبب التدقيق

بصمة SHA-256 المحتسبة لملف XML لا تطابق البصمة المستخرجة بواسطة مدقق زاتكا نتيجة أخطاء في التحويل المعياري C14N.

English Description: The generated SHA-256 digest of the canonicalized invoice does not match the hash verified by ZATCA validator.

⚠️ الأسباب الشائعة لظهور الخطأ ورفض الفاتورة

  • ✕ عدم استبعاد عقد UBLExtensions وعقدة QR والتوقيع قبل تطبيق معيارية C14N
  • ✕ استخدام مكتبات تحويل نصي عادية بدلاً من خوارزمية C14N11 المعتمدة
  • ✕ اختلاف نهايات الأسطر بين أنظمة ويندوز (CRLF) ولينكس (LF)
  • ✕ تعديل أي بيان في الفاتورة بعد احتساب الهاش

✅ خطوات الحل وتصحيح الفاتورة

1

اتباع خطوات التحويل الرسمية

1. إزالة UBLExtensions. 2. إزالة عقدة QR. 3. إزالة Signature. 4. تطبيق C14N11. 5. احتساب SHA-256. 6. تحويله إلى Base64.

2

توحيد الترميز بـ UTF-8 ونهايات أسطر LF

تأكد من معالجة ملفات XML بترميز UTF-8 بدون BOM ومع نهايات أسطر قياسية \n.

💻 نموذج برمجي لمقارنة ملف XML (قبل وبعد التصحيح)

❌ النموذج الخاطئ (مرفوض من زاتكا) Invalid XML 
// Anti-pattern: Hashing the full XML directly without transforms
const hash = crypto.createHash('sha256').update(fullXmlString).digest('base64');
✓ النموذج الصحيح (المعتمد رسمياً) Valid UBL 2.1 
// Best practice: Transform, canonicalize, then hash
const cleanedXml = stripSignatureNodes(rawXml);
const canonicalXml = c14n11Canonicalize(cleanedXml);
const invoiceHash = crypto.createHash('sha256').update(canonicalXml, 'utf8').digest('base64');

تحقق من صحة ملف الفاتورة الآن مجاناً

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

فحص XML والهاش ← محلل رمز QR ←

❓ الأسئلة الشائعة حول INVALID-INVOICE-HASH

هل يمكن فحص هاش الفاتورة قبل الإرسال الفعلي لزاتكا؟

نعم، يمكنك استخدام أداة فاحص XML والهاش المجانية من قيمة للتأكد من صحة التحويل المعياري وبصمة SHA-256.

🔗 قواعد وأخطاء زاتكا ذات صلة

BR-KSA-26

BR-KSA-26: خطأ في احتساب هاش الفاتورة السابقة (PIH / KSA-13)

يجب أن يكون هاش الفاتورة السابقة (KSA-13) مشفراً بـ Base64 لترميز SHA-256 للفاتورة السابقة، أو الهاش المبدئي الصفري للفاتورة الأولى.

BR-KSA-27

BR-KSA-27: رمز الاستجابة السريعة (QR Code / KSA-14) مفقود أو غير مطابق

يجب أن تحتوي الفاتورة على رمز QR مشفر بنظام Base64 ومبني بترميز TLV وفق متطلبات المرحلة الثانية من هيئة الزكاة.

ودّع مشاكل الربط وأخطاء الفوترة مع برنامج قيمة

يتكفل نظام قيمة بكافة متطلبات هيئة الزكاة والضريبة والجمارك تلقائياً في الخلفية: اعتماد فوري للفواتير، توقيع رقمي، وربط كامل مع منصة فاتورة.

ابدأ تجربتك المجانية الآن ← تصفح باقي قواعد أخطاء زاتكا