الفوترة الإلكترونية في السعودية: دليل المطورين لنظام ZATCA

## ما هي الفوترة الإلكترونية من هيئة الزكاة والضريبة والجمارك؟ تفرض هيئة الزكاة والضريبة والجمارك (ZATCA) الفوترة الإلكترونية على جميع المنشآت المسجلة في ضريبة القيمة المضافة في المملكة العربية السعودية. يتم التطبيق على مرحلتين: **المرحلة الأولى — الإصدار (ديسمبر ٢٠٢١):** يجب إصدار الفواتير وتخزينها إلكترونياً بصيغة منظمة. يُشترط وجود رمز QR في الفواتير المبسطة (B2C). المرجع الرسمي: [بوابة الفوترة الإلكترونية — هيئة الزكاة والضريبة](https://zatca.gov.sa/ar/E-Invoicing/Pages/default.aspx) **المرحلة الثانية — الربط والتكامل (يناير ٢٠٢٣+):** يجب إرسال الفواتير إلى منصة فاتورة للاعتماد أو المشاركة عبر واجهة برمجة التطبيقات (API) بشكل فوري، مع التوقيع الرقمي وتقديم ملف XML. ## المتطلبات التقنية كل فاتورة متوافقة مع ZATCA يجب أن تستوفي: - **الصيغة:** UBL 2.1 XML - **المعرّف الفريد:** UUID v4 لكل فاتورة - **الترقيم التسلسلي:** عداد فواتير تصاعدي (ICV) - **هاش الفاتورة السابقة:** سلسلة SHA-256 تربط كل فاتورة بالسابقة - **رمز QR:** ترميز TLV مشفر بـ Base64 - **التوقيع الرقمي:** ECDSA مع منحنى secp256k1 وشهادة X.509 من الهيئة ## هيكل رمز QR (ترميز TLV) رمز QR هو مصفوفة بايتات مشفرة بـ Base64 باستخدام صيغة Tag-Length-Value: - **الوسم ١:** اسم البائع - **الوسم ٢:** الرقم الضريبي - **الوسم ٣:** الطابع الزمني (ISO 8601) - **الوسم ٤:** إجمالي الفاتورة شاملة الضريبة - **الوسم ٥:** مبلغ الضريبة - **الوسم ٦-٨:** هاش XML والتوقيع والمفتاح العام (المرحلة الثانية) ## مثال برمجي: ترميز TLV بلغة Python ```python import base64 def tlv_encode(tag: int, value: str) -> bytes: data = value.encode('utf-8') return bytes([tag, len(data)]) + data def generate_qr(seller, vat, timestamp, total, vat_amount): tlv = b'' tlv += tlv_encode(1, seller) tlv += tlv_encode(2, vat) tlv += tlv_encode(3, timestamp) tlv += tlv_encode(4, total) tlv += tlv_encode(5, vat_amount) return base64.b64encode(tlv).decode() qr = generate_qr("شركة عزيز", "300000000000003", "2026-02-27T12:00:00Z", "115.00", "15.00") ``` ## أخطاء شائعة يقع فيها المطورون **١. صيغة التاريخ:** يجب استخدام ISO 8601 مع المنطقة الزمنية. استخدام صيغة بدون حرف T أو Z سيسبب رفض الفاتورة. **٢. النص العربي في TLV:** يجب ترميز اسم البائع بـ UTF-8. طول البايتات في حقل L يجب أن يعكس حجم UTF-8 وليس عدد الأحرف. **٣. بيئة الاختبار مقابل الإنتاج:** شهادات بيئة الاختبار (Sandbox) لا تعمل في بيئة الإنتاج. يجب التسجيل بشهادة حقيقية من الهيئة. **٤. انقطاع سلسلة الهاش:** كل فاتورة تعتمد على هاش الفاتورة السابقة. حذف أو إعادة إنشاء فاتورة يكسر السلسلة بالكامل. ## كيف يحل مُفوتر هذه المشكلة؟ [مُفوتر](/apps/mufawtir/) هو تطبيق الفوترة من برمجيات عزيز، مصمم خصيصاً للتوافق مع متطلبات هيئة الزكاة والضريبة. يتعامل مع ترميز QR والترقيم التسلسلي وتنسيق الفواتير المتوافق مع الهيئة — حتى لا تبني البنية التحتية بنفسك. إذا كنت تبحث عن حل جاهز بدلاً من البناء من الصفر، [اطلع عليه هنا](/apps/mufawtir/). ## أسئلة شائعة **س: هل أحتاج التوافق مع المرحلة الثانية الآن؟** ج: الهيئة تطبق المرحلة الثانية على دفعات حسب حجم الإيرادات. راجع جدول الموجات الرسمي، لكن البناء للمرحلة الثانية من البداية يوفر عليك ترحيلاً مؤلماً لاحقاً. **س: هل يمكنني استخدام JSON بدلاً من XML؟** ج: لا. الهيئة تشترط UBL 2.1 XML حصراً. واجهة فاتورة تقبل XML فقط. **س: ما مكتبة QR المناسبة؟** ج: أي مكتبة تنشئ رموز QR قياسية تعمل. الجزء الخاص بـ ZATCA هو المحتوى (سلسلة TLV المشفرة بـ Base64) وليس رسم الرمز نفسه. **س: هل يحتاج المستقلون للفوترة الإلكترونية؟** ج: إذا كنت مسجلاً في ضريبة القيمة المضافة (إيرادات فوق ٣٧٥,٠٠٠ ريال)، نعم. الحد ينطبق بغض النظر عن حجم المنشأة.