متطلبات XML في فواتير زاتكا: UBL 2.1 والحقول الإلزامية
دليل تقني لمتطلبات ملف XML في فاتورة زاتكا الإلكترونية: بنية UBL 2.1، الحقول الإلزامية والشرطية، التوقيع الرقمي XAdES-BES، وأخطاء XML الشائعة وكيفية تجنبها.
الفاتورة الإلكترونية في منظومة زاتكا ليست مجرد ملف نصي بامتداد .xml؛ إنها وثيقة قانونية منظَّمة تلتزم بمعيار UBL 2.1 الدولي مع إضافات ومتطلبات خاصة بالمملكة العربية السعودية عُرفت بـ KSA-UBL. فهم بنية هذا الملف أمر حيوي لكل مطوِّر نظام فوترة وكل مدير مالي يريد ضمان صحة فواتيره وقبولها من زاتكا دون رفض أو تأخير.
أصدرت زاتكا وثائق تقنية مفصَّلة تُحدد المخطط (Schema) الكامل لملف XML، وكل حقل إلزامي أو شرطي أو اختياري، ورموز الضريبة والإعفاء، ومتطلبات التوقيع الرقمي. في هذه المقالة نستعرض أهم هذه المتطلبات بلغة واضحة مع أمثلة مُبسَّطة لمساعدتك على فهم ما يحدث خلف الكواليس في نظام الفوترة الذي تستخدمه.
بنية UBL 2.1 في زاتكا
يعتمد مخطط زاتكا على معيار UBL 2.1 (Universal Business Language) الصادر من منظمة OASIS، مع تخصيصات سعودية تُعرف بـ KSA Profile. ينقسم ملف XML إلى أقسام رئيسية:
- Invoice Header: معلومات الفاتورة العامة (رقم، تاريخ، نوع، عملة).
- AccountingSupplierParty: بيانات البائع الكاملة.
- AccountingCustomerParty: بيانات المشتري (إلزامية في B2B).
- AllowanceCharge: الخصومات والرسوم على مستوى الفاتورة.
- TaxTotal: ملخص ضريبة القيمة المضافة.
- LegalMonetaryTotal: الإجماليات المالية.
- InvoiceLine: تفاصيل كل بند (متكرر).
- UBLExtensions: حقول التوسعة الخاصة بزاتكا (QR، التوقيع).
رموز نوع الفاتورة
تُحدد زاتكا نوع الفاتورة برمزين متزامنَين في حقل InvoiceTypeCode:
| الرمز الرقمي | نوع الفاتورة | الحقل الإضافي |
|---|---|---|
| 388 | فاتورة ضريبية (B2B) | KSA-1 (خاصية B2B) |
| 381 | إشعار دائن | مرجع الفاتورة الأصلية |
| 383 | إشعار مدين | مرجع الفاتورة الأصلية |
| 388 | فاتورة مبسَّطة (B2C) | KSA-2 (خاصية B2C) |
يتضمن حقل InvoiceTypeCode أيضاً رموز الخصائص الإضافية: مثل 0100000 للفاتورة العادية، و0200000 للفاتورة الدورية، وغيرها وفق وثائق زاتكا التقنية.
رموز الضريبة والإعفاء
في كل بند فاتورة يجب تحديد رمز فئة الضريبة (TaxCategoryID) والنسبة المقابلة:
| رمز الفئة | الوصف | نسبة الضريبة | مثال |
|---|---|---|---|
| S | الخاضع للضريبة بالنسبة القياسية | 15% | معظم السلع والخدمات |
| Z | خاضع بنسبة صفرية | 0% | الصادرات خارج الخليج |
| E | معفى من الضريبة | 0% | الخدمات الصحية والتعليمية |
| O | خارج نطاق ضريبة القيمة المضافة | لا تنطبق | بعض العمليات المالية |
عند استخدام رمز Z أو E يجب تحديد سبب الإعفاء (TaxExemptionReasonCode) وفق قائمة أسباب زاتكا المعتمدة.
الحقول الإلزامية التفصيلية
فيما يلي أبرز الحقول الإلزامية في ملف XML مع مساراتها:
على مستوى الفاتورة
cbc:ID— رقم الفاتورة التسلسليcbc:UUID— معرِّف فريد بتنسيق UUID v4cbc:IssueDateوcbc:IssueTime— التاريخ والوقت بصيغة ISO 8601cbc:InvoiceTypeCode— رمز نوع الفاتورة مع الخصائصcbc:DocumentCurrencyCode— رمز العملة (SAR أو غيرها)
على مستوى البائع
- رقم التسجيل الضريبي في
cac:PartyTaxScheme/cbc:CompanyID - رقم السجل التجاري في
cac:PartyLegalEntity/cbc:CompanyID - العنوان الوطني الكامل في
cac:PostalAddress
على مستوى كل بند
- وصف البند (
cac:Item/cbc:Name) - الكمية والوحدة (
cbc:InvoicedQuantityمعunitCode) - السعر الصافي (
cac:Price/cbc:PriceAmount) - المبلغ الخاضع للضريبة (
cbc:TaxableAmount) - مبلغ الضريبة (
cbc:TaxAmount)
التوقيع الرقمي XAdES-BES
تعتمد زاتكا معيار XAdES-BES (XML Advanced Electronic Signatures - Basic Electronic Signature) للتوقيع على ملفات XML. تسلسل عملية التوقيع:
- تنقية XML (Canonicalization) باستخدام C14N.
- حساب هاش SHA-256 للـ XML المُنقَّى.
- إنشاء عنصر
ds:SignedInfoيتضمن الهاش. - توقيع SignedInfo بالمفتاح الخاص ECDSA P-256.
- تضمين التوقيع والشهادة في
UBLExtensions/ext:UBLExtension.
أي خطأ في تسلسل التوقيع يُؤدي إلى رفض فوري من زاتكا برمز خطأ محدد. لهذا السبب لا يُنصح أبداً بتطوير آلية التوقيع يدوياً؛ استخدم مكتبات برمجية موثوقة تدعم XAdES.
أخطاء XML الشائعة وحلولها
| رمز الخطأ | السبب الشائع | الحل |
|---|---|---|
| XSD-002 | حقل إلزامي غائب | مراجعة الـ Schema الكاملة وإضافة الحقل |
| XSD-020 | رمز فئة ضريبة غير صحيح | استخدام S, Z, E, O فقط |
| VAL-051 | مجموع الضريبة لا يتطابق | التحقق من دقة الأرقام (جولة حسابية) |
| SIG-001 | التوقيع غير صحيح | التحقق من المفتاح الخاص والشهادة |
| BR-KSA-68 | رقم تسجيل ضريبة القيمة المضافة خاطئ | يجب أن يبدأ بـ 3 وينتهي بـ 3، 15 رقماً |
المعيار: UBL 2.1 بتخصيصات KSA. الحقول: 20+ حقلاً إلزامياً على مستويات مختلفة. رموز الضريبة: S/Z/E/O مع أسباب الإعفاء. التوقيع: XAdES-BES بمفتاح ECDSA P-256 وشهادة CSID. التحقق: استخدم أداة Compliance Check API قبل الإرسال الإنتاجي. الأرشفة: احتفظ بـ XML الأصلي + استجابة زاتكا + الختم.
أسئلة شائعة عن XML في زاتكا
هل يمكنني تعديل ملف XML بعد توقيعه؟
لا. أي تعديل على XML بعد التوقيع يُبطل التوقيع الرقمي ويجعل الفاتورة مرفوضة. إذا احتجت تصحيح فاتورة، أصدر إشعاراً دائناً يُلغي الفاتورة الخاطئة ثم أصدر فاتورة جديدة صحيحة.
ما الفرق بين UUID الفاتورة ورقمها التسلسلي؟
UUID (مثال: a1b2c3d4-...) هو معرِّف عشوائي فريد يُولَّد آلياً ولا يظهر للعميل. رقم الفاتورة التسلسلي (مثال: INV-2025-0001) هو الرقم المرئي على الفاتورة ويجب أن يكون متسلسلاً دون فجوات.
هل يجب أن تكون كل الأرقام في XML بالصيغة العشرية؟
نعم، تستخدم زاتكا الصيغة العشرية الدولية (نقطة كفاصل عشري، لا فاصلة) وبدقة محددة لكل حقل. على سبيل المثال مبالغ الضريبة بدقة خانتين عشريتين على الأقل.
كيف أتحقق من صحة XML قبل إرساله لزاتكا؟
توفر زاتكا Compliance Check API يمكن استخدامها في بيئة Sandbox للتحقق من XML قبل الإرسال الإنتاجي. كما يمكن التحقق محلياً من الـ Schema باستخدام XSD Validator.
هل يمكن استخدام عملة غير الريال السعودي؟
نعم، يمكن إصدار الفاتورة بعملة أجنبية، لكن يجب تحديد عملة الفاتورة (DocumentCurrencyCode) وعملة الضريبة بشكل منفصل. مبلغ الضريبة في حقل TaxTotal يجب أن يكون بعملة الضريبة المحددة.
لا تحتاج إلى إتقان تفاصيل UBL 2.1 وXAdES-BES بنفسك. رَقْمَنَة يُعالج كل هذا تلقائياً: يُولِّد XML صحيحاً، يُوقِّعه رقمياً، ويرسله لزاتكا مع إدارة الأخطاء والإعادة. متوافق مع المرحلتين الأولى والثانية.
اكتشف رَقْمَنَةكاتب المقالة
فريق تحرير رَقْمَنَة
A team specialized in accounting and business management technology, delivering practical content for Arab businesses.