التوقيع الرقمي المشفر ECDSA لفواتير زاتكا UBL 2.1 بلغة Node.js
الخلاصة التنفيذية (BLUF): يتطلب الامتثال لمنظومة الفوترة الإلكترونية (المرحلة الثانية - الربط والتكامل ZATCA Phase 2) في المملكة العربية السعودية توليد توقيع رقمي مشفر غير قابل للتلاعب لكل فاتورة ضريبية بصيغة UBL 2.1 XML. يعتمد الامتثال على تجريد الفاتورة المعيارية (Canonicalization C14N11)، وحساب تجزئة SHA-256 للمحتوى المشفر، وتوقيعه بمفتاح خاص مشفر بمنحنى ECDSA (secp256k1) ومطابق لشهادة التشفير Cryptographic Stamp Identifier (CSID). يوضح هذا الدليل المعمارية التنفيذية الكاملة بلغة Node.js لضمان قبول الفواتير لدى منصة فاتورة وتفادي أخطاء التحقق وغرامات عدم الامتثال.
معايير المرحلة الثانية (الربط والتكامل) ومتطلبات التشفير الرسمية
حددت هيئة الزكاة والضريبة والجمارك (ZATCA) متطلبات تقنية صارمة لإصدار الفواتير الضريبية (B2B) والفواتير الضريبية المبسطة (B2C) عبر منظومة "فاتورة". لا تكتفي الهيئة باستقبال بيانات الفاتورة بصيغة JSON أو XML تقليدية، بل تشترط أن تكون الفاتورة مطابقة لمعيار Universal Business Language (UBL 2.1) وموقعة رقميا وفق معايير XAdES-BES المشفرة.
يتكون التوقيع الرقمي في منظومة زاتكا من ثلاثة عناصر مترابطة حسابيا:
- تجزئة الفاتورة (Invoice Hash): استخراج خلاصة رقمية SHA-256 للفاتورة بعد استبعاد عناصر التوقيع والوسوم المتغيرة وتجريدها معياريا وفق C14N.
- التوقيع الرقمي المشفر (Digital Signature Value): تشفير الهاش المحسوب باستخدام مفتاح خاص ECDSA (بمنحنى secp256k1 القياسي).
- شهادة التشفير (X.509 Certificate): تضمين الشهادة الرقمية المعتمدة (CSID) الصادرة عن منصة فاتورة داخل بنية الـ XML للتحقق من هوية المنشأة.
خطوات معالجة وتوقيع فاتورة UBL 2.1 برمجيا في Node.js
تتم عملية إنشاء وتوقيع الفاتورة وفق 5 مراحل تسلسلية إلزامية:
- تجريد الفاتورة (XML Canonicalization): استبعاد وسوم التوقيع والـ QR وفق محددات زاتكا الرسمية (وهي:
ext:UBLExtensionsوcac:Signatureوcac:AdditionalDocumentReferenceالتي تحمل المعرف'QR') قبل حساب الهاش، مع بقاء الوسوم المعيارية مثلcbc:UBLVersionIDكما هي دون حذف. - حساب تجزئة الفاتورة (Invoice Hash): تطبيق دالة التشفير SHA-256 على النص المعياري وتحويل الناتج إلى تنسيق Base64.
- التوقيع بمفتاح ECDSA: استخدام المفتاح الخاص المطابق لمنحنى secp256k1 لتوقيع الهاش وتوليد قيمة التوقيع بصيغة ASN.1 / DER ثم تحويلها إلى Base64.
- توليد ختم التشفير ورمز الاستجابة السريعة (TLV QR Code): تشفير الحقول الإلزامية التسعة للفاتورة المبسطة وفق ترميز Tag-Length-Value (TLV) وتشفيرها بصيغة Base64.
- سلسلة التجزئة المتصلة (Invoice Hash Chaining): ربط الفاتورة الحالية بتجزئة الفاتورة السابقة (Previous Invoice Hash - PIH) لضمان عدم إمكانية تعديل أو حذف أي فاتورة لاحقا.
نموذج كودي توضيحي لتوقيع الفاتورة (للاسترشاد الهندسي - غير معتمد في Sandbox زاتكا)
تنبيه هندسي: هذا النموذج كود توضيحي أولي للاسترشاد المعماري فقط، ولم يتم التحقق منه عمليا في بيئة الفحص الرسمية (ZATCA Sandbox) أو مطابقته مع حزمة ZATCA SDK. يجب اختباره واعتماده رسميا مع الهيئة قبل استخدامه في بيئة الإنتاج.
import crypto from "node:crypto";
/**
* Signs a canonicalized ZATCA UBL 2.1 XML invoice using an ECDSA secp256k1 private key.
* ILLUSTRATIVE ONLY - NOT VALIDATED AGAINST OFFICIAL ZATCA SANDBOX.
* In production, test against the official ZATCA Java SDK / Sandbox validator
* to confirm whether your integration requires direct signing or pre-hashed digest signing.
*/
export function signZatcaInvoice(
canonicalXml: string | Buffer,
privateKeyPem: string
): { invoiceHashBase64: string; signatureBase64: string } {
const xmlBuffer = Buffer.isBuffer(canonicalXml) ? canonicalXml : Buffer.from(canonicalXml, "utf-8");
const invoiceHash = crypto.createHash("sha256").update(xmlBuffer).digest();
const signer = crypto.createSign("SHA256");
signer.update(xmlBuffer);
const signatureBase64 = signer.sign(privateKeyPem, "base64");
return { invoiceHashBase64: invoiceHash.toString("base64"), signatureBase64 };
}
/** Sign pre-computed 32-byte SHA-256 digest directly without double hashing */
export function signPrecomputedDigest(digestBuffer: Buffer, privateKeyPem: string): string {
return crypto.sign(null, digestBuffer, { key: privateKeyPem, dsaEncoding: "der" }).toString("base64");
}
/**
* Validates whether a signature matches the given invoice hash and public key.
*/
export function verifyZatcaSignature(
invoiceHashBase64: string,
signatureBase64: string,
publicKeyPem: string
): boolean {
const hashBuffer = Buffer.from(invoiceHashBase64, "base64");
const verify = crypto.createVerify("SHA256");
verify.update(hashBuffer);
return verify.verify(publicKeyPem, signatureBase64, "base64");
}
مؤشرات تشغيلية مقترحة (أمثلة هندسية داخلية وليست متطلبات قانونية من زاتكا)
المقاييس التالية تمثل مؤشرات أداء تشغيلية مقترحة (Internal SLOs) لمراقبة سرعة النظام واستقراره عبر Prometheus و Grafana، وليست قيودا منصوصا عليها قانونيا من هيئة الزكاة:
zatca_api_clearance_duration_seconds < 0.8(مثال لمؤشر SLO داخلي): سرعة استجابة خدمة الاعتماد اللحظي لتفادي تأخير إتمام الشراء.zatca_reporting_queue_lag == 0: ضمان إرسال الفواتير المبسطة خلال نافذة الـ 24 ساعة الإلزامية دون تراكم.xml_c14n_hash_error_count == 0: انعدام تام لأخطاء تطابق الهاش (Invalid Invoice Hash) الناتجة عن أخطاء التجريد أو فوارق السطور.
توصيات ختامية لفرق التطوير والمنشآت السعودية
احرص دائما على عزل مفاتيح التشفير الخاصة في وحدة إدارة مفاتيح آمنة (KMS / HSM) لمنع تسريبها، وقم بتنفيذ بيئة فحص أولية في الـ Sandbox ومقارنة مخرجات الـ SDK الرسمي الخاص بزاتكا قبل التفعيل على بيئة الإنتاج الحية.
استشارات وشراكة هندسة البنية التحتية والمنصات
هل تحتاج مهندس أول لحماية واستقرار وتوسيع منصتك السحابية؟
من خوادم كوبرنيتيس وتالوس لينكس المستقلة وتخفيض فواتير السحابة بشكل جذري، إلى ضبط أداء وقفل بوستجريس وبناء مسارات الذكاء الاصطناعي السيادي، أعمل مباشرة مع الفرق الهندسية لبناء أنظمة مرنة ومملوكة بالكامل.