100% متوافق مع زاتكا - المرحلتان الأولى والثانية

الدليل الشامل للفوترة الإلكترونية (زاتكا) في السعودية

كل ما تحتاج معرفته عن منظومة الفاتورة الإلكترونية: متطلبات XML، رمز QR، التوقيع الرقمي، والأخطاء الشائعة وحلولها.

ابدأ التجربة المجانية تعرف على المتطلبات ↓

100%

نسبة النجاح في الربط

<2 ثانية

متوسط وقت الإرسال

صفر

حالات رفض للفواتير

24/7

دعم فني باللغة العربية

متطلبات الفوترة الإلكترونية (ZATCA)

المتطلبات التقنية الرسمية من هيئة الزكاة والضريبة والجمارك

1. هيكل XML المطلوب

يجب أن تكون الفاتورة بصيغة UBL 2.1 (Universal Business Language) وتحتوي على العناصر التالية^[7]:

<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
  <cbc:ID>INV-2025-001</cbc:ID>
  <cbc:IssueDate>2025-01-15</cbc:IssueDate>
  <cbc:IssueTime>14:30:00</cbc:IssueTime>
  
  <!-- معلومات البائع -->
  <cac:AccountingSupplierParty>
    <cac:Party>
      <cac:PartyTaxScheme>
        <cbc:CompanyID>310122393500003</cbc:CompanyID>
        <cac:TaxScheme>
          <cbc:ID>VAT</cbc:ID>
        </cac:TaxScheme>
      </cac:PartyTaxScheme>
    </cac:Party>
  </cac:AccountingSupplierParty>
  
  <!-- معلومات العميل -->
  <cac:AccountingCustomerParty>...</cac:AccountingCustomerParty>
  
  <!-- بنود الفاتورة -->
  <cac:InvoiceLine>...</cac:InvoiceLine>
</Invoice>

تحذير مهم

أي خطأ في هيكل XML سيؤدي إلى رفض الفاتورة فوراً. قيمة تتحقق من الصيغة تلقائياً قبل الإرسال.

2. رمز QR الإلزامي (صيغة TLV)

يستخدم رمز QR بنية TLV (Tag-Length-Value) ومشفر بـ Base64 (الحد الأقصى 700 حرف)^[5]:

المرحلة الأولى - الوسوم الأساسية (جميع الفواتير):

الوسم 1: اسم البائع
الوسم 2: الرقم الضريبي للبائع
الوسم 3: التاريخ والوقت (صيغة ISO: 2025-01-15T14:30:00Z)
الوسم 4: إجمالي الفاتورة مع الضريبة
الوسم 5: قيمة ضريبة القيمة المضافة

المرحلة الثانية - الوسوم التشفيرية (B2B و B2C):

الوسم 6: تجزئة الفاتورة (SHA-256 لملف XML)
الوسم 7: التوقيع الرقمي ECDSA
الوسم 8: المفتاح العام ECDSA (secp256k1)
الوسم 9: توقيع الجهة المصدرة للشهادة

💡 نصيحة: قيمة تولد جميع الوسوم التسعة تلقائياً بصيغة TLV والتشفير Base64 الصحيح. بدون أي عمل يدوي.

3. التوقيع الرقمي والربط (المرحلة الثانية)

في المرحلة الثانية، يجب ربط نظامك مع منصة فاتورة:

الحصول على شهادة التشفير (Cryptographic Stamp)

شهادة رقمية من زاتكا لتوقيع الفواتير إلكترونياً

إرسال الفاتورة للمنصة (Clearance/Reporting)

فواتير B2B: Clearance (تتطلب موافقة قبل الإصدار)
فواتير B2C: Reporting (الإبلاغ خلال 24 ساعة)

الحصول على رقم التعريف الفريد (UUID)

زاتكا تعيد رقم تعريف للفاتورة بعد قبولها

✅ قيمة تدير كل هذا تلقائياً: الربط، التوقيع، والإرسال دون تدخل يدوي.

اقرأ دليلنا الشامل حول المرحلة الثانية من زاتكا ←

4. عملية التسجيل (المرحلة الثانية)

قبل البدء بالعمل الفعلي، يجب إكمال عملية التسجيل في زاتكا:

الخطوة 1: إنشاء رمز OTP (كلمة مرور لمرة واحدة)

• صالح لمدة ساعة واحدة^[8]
• حد أقصى 100 رمز لكل طلب
• يتم الحصول عليه من بوابة زاتكا

الخطوة 2: إنشاء طلب شهادة التوقيع (CSR)

يجب أن يحتوي على 11 حقلاً إلزامياً:

• الاسم المشترك (CN)
• الرقم التسلسلي (رقم جهاز EGS)
• معرف المنظمة (الرقم الضريبي)
• اسم قسم المنظمة
• اسم المنظمة
• رمز الدولة (SA)
• نوع الفاتورة (صيغة TSXY)
• الموقع (العنوان)
• الصناعة (فئة النشاط)

الخطوة 3: فحوصات الامتثال (الاختبار)

إرسال 3 مستندات اختبار للتحقق:

✓ فاتورة قياسية (B2B)
✓ إشعار دائن
✓ إشعار مدين

الحصول على شهادة امتثال (Compliance CSID) للاختبار

الخطوة 4: شهادة الإنتاج

بعد اجتياز فحوصات الامتثال، الحصول على شهادة الإنتاج (Production CSID) (صالحة لمدة 365 يوماً)^[6]

🚀 قيمة تدير عملية التسجيل بالكامل: التعامل مع OTP، إنشاء CSR، اختبارات الامتثال، وتجديد الشهادات.

5. قواعد العمل (BR-KSA) والتحقق

زاتكا تتحقق من الفواتير باستخدام هرم تحقق ثلاثي المستويات^[1]:

🔺

الأولوية 1: قواعد السعودية (BR-KSA)

🔸

الأولوية 2: المعيار الأوروبي (EN 16931)

◾

الأولوية 3: مواصفات UBL 2.1

قواعد الدقة العشرية

• المبالغ: منزلتان عشريتان
• أسعار الوحدة: منازل عشرية غير محدودة
• الكميات: منازل عشرية غير محدودة

فئات ضريبة القيمة المضافة^[2]

• S: قياسية (15%)
• Z: معدل صفري (0%)
• E: معفاة
• O: غير خاضعة للضريبة

نتائج التحقق

❌

غير صالحة: الفاتورة مرفوضة مع أخطاء (يجب الإصلاح وإعادة الإرسال)

⚠️

مقبولة مع تحذيرات: الفاتورة مقبولة ولكن بها مشاكل غير حرجة

✅

صالحة/متوافقة: الفاتورة متوافقة بالكامل (بدون أخطاء أو تحذيرات)

📋 مهم: تسلسل الفواتير عبر التجزئة السابقة (PIH) - حتى الفواتير المرفوضة تُتتبع في التسلسل.

أشهر 10 أخطاء تؤدي لرفض الفاتورة

أخطاء التحقق BR-KSA الشائعة وكيفية إصلاحها

اطلع على جميع الأخطاء الـ15 الشائعة مع الحلول التفصيلية ←

❌

1. رقم ضريبي غير صحيح أو منتهي

الخطأ: "Invalid VAT Registration Number" أو "310122393500003 is not registered"

✅ الحل: تحقق من صحة الرقم الضريبي من موقع الهيئة مباشرة: zatca.gov.sa

❌

2. رمز QR غير مكتمل (المرحلة الثانية)

الخطأ: "وسوم تشفيرية مفقودة في رمز QR" (BR-KSA-51)

الاستجابة: 400 Bad Request | رمز الخطأ: MISSING_QR_TAGS_6_9

✅ الحل: المرحلة الثانية تتطلب جميع الوسوم التسعة (بما في ذلك 6-9: التجزئة، التوقيع ECDSA، المفتاح العام، توقيع CA) بصيغة TLV.

❌

3. خطأ في حساب الضريبة (BR-KSA-DEC-02)

الخطأ: "خطأ في دقة مبلغ الضريبة" أو "عدم تطابق حساب TaxAmount"

الاستجابة: 400 Bad Request | رمز الخطأ: VAT_CALCULATION_ERROR

✅ الحل: المبالغ يجب أن تكون بمنزلتين عشريتين بالضبط. الصيغة: TaxAmount = ROUND(TaxableAmount × 0.15, 2)

❌

4. صيغة التاريخ والوقت خاطئة

الخطأ: "Invalid IssueDate format" أو "IssueTime must be in HH:MM:SS format"

✅ الحل: استخدم الصيغة الدقيقة: 2025-01-15 للتاريخ و 14:30:00 للوقت.

❌

5. نقص في بيانات العميل (فواتير B2B)

الخطأ: "Customer VAT Number is required for B2B invoices"

✅ الحل: في فواتير B2B (شركة لشركة)، يجب إدخال الرقم الضريبي للعميل إلزامياً.

❌

6. شهادة CSID منتهية (BR-KSA-CERT-01)

الخطأ: "معرف الطابع التشفيري (CSID) منتهي الصلاحية"

الاستجابة: 401 Unauthorized | رمز الخطأ: EXPIRED_CERTIFICATE

✅ الحل: تجديد CSID قبل انتهاء 365 يوماً. قيمة تجدد تلقائياً قبل 30 يوماً من الانتهاء.

❌

7. رقم فاتورة مكرر (BR-KSA-45)

الخطأ: "رقم الفاتورة تم إرساله مسبقاً"

الاستجابة: 400 Bad Request | رمز الخطأ: DUPLICATE_INVOICE_ID

✅ الحل: يجب أن يكون كل رقم فاتورة فريداً لكل شركة. استخدم ترقيم تسلسلي (INV-2025-0001, INV-2025-0002...).

❌

8. تجزئة الفاتورة السابقة غير صالحة (BR-KSA-PIH-01)

الخطأ: "عدم تطابق أو فقدان تجزئة الفاتورة السابقة (PIH)"

الاستجابة: 400 Bad Request | رمز الخطأ: INVALID_PIH_CHAIN

✅ الحل: كل فاتورة يجب أن تشير إلى تجزئة الفاتورة السابقة (بما في ذلك المرفوضة). الفاتورة الأولى تستخدم تجزئة فارغة.

❌

9. حقول اللغة العربية مفقودة (BR-KSA-16)

الخطأ: "اللغة العربية مطلوبة للفاتورة المرئية"

الاستجابة: 400 Bad Request | رمز الخطأ: MISSING_ARABIC_LANGUAGE

✅ الحل: الفواتير المرئية (PDF/مطبوعة) يجب أن تتضمن اللغة العربية. XML يمكن أن يكون ثنائي اللغة (عربي + إنجليزي).

❌

10. مهلة الموافقة B2B (BR-KSA-CLR-01)

الخطأ: "تم إصدار الفاتورة قبل الموافقة على التخليص"

الاستجابة: 303 See Other | رمز التحذير: PREMATURE_ISSUANCE

✅ الحل: فواتير B2B تتطلب تخليصاً قبل الإصدار للعميل. انتظر استجابة 202 Accepted من واجهة زاتكا API.

لماذا قيمة مختلفة؟

نحن نتحقق من أكثر من 100 قاعدة امتثال BR-KSA قبل الإرسال باستخدام SDK الرسمي من زاتكا. كل فاتورة تمر عبر نفس التحقق الذي تستخدمه زاتكا.

النتيجة: صفر فواتير مرفوضة في الإنتاج منذ الإطلاق. كل فاتورة يتم التحقق منها محلياً قبل إرسالها لواجهة API.

كيف تعمل قيمة؟

من إصدار الفاتورة إلى الربط مع زاتكا - كل شيء تلقائي

أنشئ الفاتورة

أضف البنود والعملاء كالمعتاد. لا تقلق بشأن XML أو QR.

التحقق التلقائي

قيمة تتحقق من 71 نقطة (XML، QR، الضريبة، التواريخ) وتصلح الأخطاء.

الإرسال الفوري

الفاتورة تُرسل لزاتكا تلقائياً. تحصل على UUID في أقل من ثانيتين.

""

— هيئة الزكاة والضريبة والجمارك مبادرة الفوترة الإلكترونية

المصادر والمراجع التقنية

جاهز للربط مع زاتكا؟

ابدأ مجاناً اليوم. لا حاجة لبطاقة ائتمان. ربط كامل مع منظومة الفاتورة الإلكترونية في أقل من 10 دقائق.

ابدأ التجربة المجانية احجز عرض توضيحي