التكامل التقني للمرحلة الثانية في زاتكا — UBL 2.1 و XAdES و فوترة B2B

نظرة عامة

المرحلة الثانية لزاتكا (الفوترة الإلكترونية المتكاملة — فاتورة) تنقل الفوترة من PDF محلي إلى تدفّق فوري موقَّع وتُجيزه الحكومة. كل فاتورة قياسية (B2B) تحتاج موافقة فورية، وكل فاتورة مبسطة (B2C) تُرسل خلال 24 ساعة. القلب التقني: UBL 2.1 + توقيع XAdES + Fatoora API.

على من يطبَّق

• كل مكلّف بضريبة القيمة المضافة في المملكة.
• التطبيق على موجات.
• مستثنون: غير المقيمين وقطاعات محدودة.

المعمارية

ERP → مولّد الفاتورة → UBL XML → توقيع XAdES بـ CSID → POST /clearance
                                                       ↓
                                                ZATCA Fatoora
                                                       ↓
                                          XML موقَّع + QR + علامة الإجازة
                                                       ↓
                                              PDF/A-3 إلى المشتري
                                              XML أرشيف 6 سنوات

الخطوة 1: بنية UBL 2.1

ملف بسيط مع عناصر إلزامية:

<Invoice>
  <cbc:ID>INV-2026-00187</cbc:ID>
  <cbc:UUID>3cf5ee18-ee25-44ea-a444-2c37ba7f28be</cbc:UUID>
  <cbc:IssueDate>2026-05-27</cbc:IssueDate>
  <cbc:IssueTime>14:25:43</cbc:IssueTime>
  <cac:AdditionalDocumentReference>
    <cbc:ID>ICV</cbc:ID>
    <cbc:UUID>187</cbc:UUID>
  </cac:AdditionalDocumentReference>
  <cac:AdditionalDocumentReference>
    <cbc:ID>PIH</cbc:ID>
    ...
  </cac:AdditionalDocumentReference>
</Invoice>

• ICV عدّاد تصاعدي لكل CSID.
• PIH = base64(SHA-256(XML الفاتورة السابقة الموقَّعة)).

الخطوة 2: توقيع XAdES B-B

استخدم ECDSA على secp256k1 مع SHA-256. وقّع XML بعد التطبيع (canonicalisation)، ثم احقن التوقيع.

الخطوة 3: نقاط Fatoora

تجريبي: gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal/ إنتاج: gw-fatoora.zatca.gov.sa/e-invoicing/core/

curl -X POST '.../invoices/clearance/single' \
  -H 'Authorization: Basic <BASE64(csid:secret)>' \
  -H 'Clearance-Status: 1' \
  --data '{"invoiceHash":"...","uuid":"...","invoice":"BASE64XML"}'

الخطوة 4: رمز QR

TLV يحوي: اسم البائع، الرقم الضريبي، الطابع الزمني، الإجمالي، الضريبة، تجزئة XML، توقيع ECDSA، المفتاح العام، توقيع الشهادة.

الخطوة 5: رموز الأخطاء

| الرمز | المعنى | الإصلاح | |---|---|---| | BR-KSA-15 | ICV ليس تصاعديًا | كاتب واحد لـ ICV | | BR-KSA-26 | PIH لا يطابق | احفظ PIH بعد كل إرسال ناجح | | BR-S-08 | فئة ضريبية خاطئة | راجع جدول الأصناف | | ZATCA-INV-008 | XML لا يطابق XSD | تحقق محليًا أولًا | | ZATCA-CRT-005 | توقيع غير صالح | وقّع بعد التطبيع |

أخطاء شائعة

• توليد XML، توقيعه، ثم إعادة تسلسل تكسر التوقيع.
• ICV غير محفوظ بعد إعادة التشغيل.
• المنطقة الزمنية ناقصة.

التحقق

• تطابق XSD.
• سلامة سلسلة ICV على آخر 1000 فاتورة.
• تحقق التوقيع.
• اختبار شامل في sandbox بـ 30 سيناريو.
• أرشفة 6 سنوات.

الخلاصة

المرحلة الثانية ليست ميزة تصدير بل تكامل فوري مع الهيئة؛ ابنِ idempotency وثباتًا وملاحظة.

أدلة ذات صلة

• تأهيل CSID للإنتاج
• الفوترة الذاتية وإيصالات B2C
• PDPL — الدليل الكامل