القرار الوزاري رقم 2108 • المواصفات الفنية لمنظومة فاتورة

الدليل الشامل للربط المشفر مع منصة فاتورة (المرحلة الثانية)

كيف تبني منظومة ربط إلكتروني متوافقة 100% مع هيئة الزكاة والضريبة والجمارك (ZATCA): بدءاً من استخراج شهادات CSID، وتوقيع الفواتير بخوارزمية ECDSA secp256k1، وانتهاءً بتوليد رموز الاستجابة السريعة TLV ذات الوسوم التسعة الإلزامية وتجنب غرامات تصل إلى 50,000 ريال.

إعداد: الفريق الهندسي للامتثال الضريبي • زمن القراءة: 9 دقائق • محدث طبقا للوائح 2026

⚠️ تحذير نظامي: جدول مخالفات وغرامات الفوترة الإلكترونية

تنص المادة الرابعة والعشرون من اللائحة التنفيذية لضريبة القيمة المضافة وقرارات هيئة زاتكا على فرض عقوبات مالية صارمة: غرامة تصل إلى 50,000 ريال سعودي في حالات عدم إصدار أو حفظ الفواتير إلكترونياً، أو التخلف عن الربط والتكامل مع منصة فاتورة بعد انقضاء المهلة المقررة للمجموعة الملزمة، أو التلاعب في الأرقام التسلسلية والتجزئة المشفرة (Invoice Hash).

المرحلة 01

1. التهيئة واستخراج شهادات التشفير (CSID Onboarding)

كل وحدة فوترة إلكترونية (EGS) يجب أن تمتلك زوج مفاتيح مشفر وشهادة معرف الطابع التشفيري صادرة عن هيئة زاتكا.

تتضمن عملية التسجيل خطوتين رئيسيتين:

توليد المفتاح الخاص وطلب التوقيع (CSR): باستخدام خوارزمية ECDSA مع المنحنى البيضاوي secp256k1 (أو secp384r1).
الحصول على شهادة الامتثال المؤقتة (Compliance CSID): عبر استدعاء نقطة النهاية /compliance باستخدام رمز كلمة المرور لمرة واحدة (OTP) المستخرج من بوابة زاتكا "فاتورة".

توليد المفتاح الخاص وملف CSR عبر OpenSSL: Bash / Terminal

# 1. توليد المفتاح الخاص للمنحنى البيضاوي secp256k1
openssl ecparam -name secp256k1 -genkey -noout -out privatekey.pem

# 2. إنشاء ملف طلب شهادة الامتثال (CSR)
openssl req -new -sha256 -key privatekey.pem -out tax_device.csr -config zatca_config.cnf

المرحلة 02

2. اجتياز اختبارات الامتثال (Compliance Invoices Testing)

قبل الانتقال إلى الإنتاج الفعلي، تلزم زاتكا وحدة الفوترة بإرسال عينات اختبارية من الفواتير وإشعارات الدائن والمدين بنجاح.

يجب على النظام إرسال ستة أنواع مختلفة من الوثائق المشفرة لاختبار المحاكي:

1. فاتورة ضريبية قياسية (B2B)

تختبر محرك الاعتماد اللحظي Clearance API والختم الرقمي.

2. إشعار دائن قياسي (B2B Credit Note)

يختبر الإشارة المرجعية للفاتورة الأصلية ومبالغ الخصم.

3. فاتورة مبسطة (B2C)

تختبر مسار الإشعار Reporting API خلال مهلة 24 ساعة ورمز الـ QR.

4. إشعار دائن ومدين مبسط (B2C Debit/Credit)

يختبر صحة تسلسل التجزئة المسبقة وتعديل الإيرادات.

بمجرد اجتياز جميع الفحوصات بـ Status: PASS، يتم استدعاء /production/csids للحصول على شهادة الإنتاج الدائمة (Production CSID).

المرحلة 03

3. الختم الرقمي وتسلسل التجزئة المسبقة (PIH & SHA-256)

تعتمد زاتكا بنية غير قابلة للتعديل تشبه تقنية البلوكشين (Tamper-proof chaining).

كل فاتورة جديدة تُصدرها المنشأة يجب أن تحتوي داخل وسم الـ XML على تجزئة الفاتورة السابقة:

الفاتورة الأولى للمنشأة: تستخدم قيمة ثابتة للتجزئة المسبقة وهي تجزئة الصفر المشفرة Base64: NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODU....
الفواتير اللاحقة: تُحسب قيمة SHA-256 للفاتورة بعد استبعاد عناصر التوقيع والـ QR (Canonical XML C14N11) وتوضع في حقل cbc:PreviousInvoiceHash.

سلسلة التجزئة المستمرة (Continuous Hash Chaining):

الفاتورة #1 [Hash: A1b2...] ➔ تُحفظ في قاعدة البيانات

الفاتورة #2 [PIH: A1b2...] ➔ [New Hash: C3d4...]

الفاتورة #3 [PIH: C3d4...] ➔ [New Hash: E5f6...]

المرحلة 04

4. تشفير رمز الاستجابة السريعة (Phase 2 TLV 9-Tags Breakdown)

في المرحلة الثانية، لم يعد رمز الاستجابة السريعة يقتصر على 5 وسوم كما في المرحلة الأولى، بل أصبح إلزامياً أن يشمل 9 وسوم مشفرة بنظام TLV (Tag-Length-Value) ومحولة إلى Base64.

الوسم (Tag)	الحقل (Field Name)	نوع البيانات	الوصف والمتطلبات النظامية
Tag 1	اسم المورد (Seller Name)	String (UTF-8)	الاسم التجاري للمنشأة مطابقاً للسجل التجاري وشهادة ضريبة القيمة المضافة.
Tag 2	الرقم الضريبي (TRN)	15 Digits	رقم التسجيل الضريبي الإلزامي (15 رقماً ويبدأ وينتهي بـ 3).
Tag 3	التاريخ والوقت (Timestamp)	ISO 8601	توقيت إصدار الفاتورة بالصيغة القياسية: `2026-09-12T14:30:00Z`.
Tag 4	الإجمالي شامل الضريبة (Invoice Total)	Decimal	المبلغ الإجمالي للفاتورة شاملاً ضريبة القيمة المضافة بالريال السعودي.
Tag 5	مبلغ الضريبة (VAT Total)	Decimal	إجمالي قيمة ضريبة القيمة المضافة (15% القياسية).
Tag 6	تجزئة الفاتورة (Invoice Hash)	SHA-256 Digest	ملخص التجزئة المشفر للفاتورة لضمان عدم تلاعب أي طرف بالمحتوى بعد الإصدار.
Tag 7	الختم الرقمي (ECDSA Signature)	Binary Signature	التوقيع الإلكتروني لوحدة الفوترة المولّد باستخدام المفتاح الخاص للشهادة.
Tag 8	المفتاح العام (ECDSA Public Key)	Binary Public Key	المفتاح العام لجهاز الفوترة للتحقق من صحة التوقيع دون الحاجة للمفتاح السري.
Tag 9	توقيع شهادة الهيئة (Certificate Signature)	CSID Signature	ختم التحقق الصادر من خوادم زاتكا والذي يثبت تسجيل وحدة الفوترة نظامياً.

كود تنفيذي متكامل

5. نموذج Node.js لتوليد رمز TLV ذي الـ 9 وسوم

تنفيذ معماري نظيف باستخدام مكتبات Node.js القياسية (Buffer & crypto) بدون أي تبعيات خارجية ثقيلة:

zatca_phase2_tlv_encoder.js Node.js ES6+

function encodeTLV(tag, value) {
  const tagBuf = Buffer.from([tag]);
  const valBuf = Buffer.isBuffer(value) ? value : Buffer.from(String(value), 'utf8');
  const lenBuf = Buffer.from([valBuf.length]);
  return Buffer.concat([tagBuf, lenBuf, valBuf]);
}

function generatePhase2QRCode({
  sellerName,
  sellerTRN,
  invoiceTimestamp,
  invoiceTotal,
  vatTotal,
  invoiceHash,
  ecdsaSignature,
  publicKey,
  csidSignature
}) {
  const buffers = [
    encodeTLV(1, sellerName),
    encodeTLV(2, sellerTRN),
    encodeTLV(3, invoiceTimestamp),
    encodeTLV(4, invoiceTotal),
    encodeTLV(5, vatTotal),
    encodeTLV(6, invoiceHash),
    encodeTLV(7, ecdsaSignature),
    encodeTLV(8, publicKey),
    encodeTLV(9, csidSignature)
  ];
  return Buffer.concat(buffers).toString('base64');
}

وفر على شركتك عناء بناء البنية التحتية المشفرة

يقوم محرك OmniTax AI بإجراء كافة خطوات التشفير، الاعتماد الفوري (Clearance)، وإشعار منصة فاتورة (Reporting) عبر واجهة برمجة تطبيقات فائقة السرعة مع ضمان الصفر أخطاء.

تجربة الباقة المجانية (0 ر.س) عرض باقات الشركات (ابتداءً من 39 ر.س) ←