الربط الصحيح يتطلب تهيئة كل وحدة إصدار، والحصول على CSID، وتوليد UBL XML مطابق، وتطبيق الختم وQR، ثم إرسال الفواتير القياسية إلى Clearance قبل مشاركتها، ورفع المبسطة إلى Reporting خلال 24 ساعة. اختبر الدورة كاملة في بيئة ZATCA قبل الإنتاج، واحفظ XML والاستجابات وسجل التدقيق بلا عبث.
1. ثبّت نطاق التكامل قبل كتابة الكود
ابدأ بحصر وحدات حلول إصدار الفواتير EGS، لا بعدد الفروع فقط. قد يكون لديك جهاز نقطة بيع لكل فرع، وخدمة مركزية للفواتير القياسية، ووظيفة مستقلة للإشعارات المدينة والدائنة. لكل وحدة هوية تشفيرية ودورة تهيئة ومراقبة يجب أن تكون معروفة.
حدّد أيضاً أنواع المستندات: فاتورة ضريبية قياسية غالباً لمعاملات B2B، وفاتورة ضريبية مبسطة غالباً لمعاملات B2C، وإشعارات دائنة أو مدينة مرتبطة بالأصل. لا تجعل نوع العميل نصاً حراً؛ اربطه بقاعدة قرار واختبارات.
توضح هيئة الزكاة والضريبة والجمارك أن المرحلة الثانية تتطلب تكامل الحل الإلكتروني مع أنظمتها وإصدار الفواتير بالصيغ المطلوبة. أما مواعيد إشعار المنشأة والمجموعات المستهدفة فتُراجع من موقع الهيئة مباشرة، لا من ثابت برمجي أو مقال قديم.
2. نفّذ Onboarding لكل وحدة EGS
أنشئ زوج المفاتيح داخل بيئة آمنة، ثم كوّن طلب توقيع الشهادة CSR بالحقول المطلوبة في المواصفات. استخدم رمز التحقق OTP الذي يولده المكلف عبر بوابة فاتورة ضمن مدته وإجراءاته الرسمية. النتيجة الأولى هي Compliance CSID المخصص لاختبارات المطابقة.
مرّر حالات الاختبار المطلوبة للفواتير القياسية والمبسطة والإشعارات ذات الصلة. بعد نجاح المطابقة، اطلب Production CSID للوحدة، وخزّن الشهادة والمفتاح الخاص وأسرار المصادقة في مخزن أسرار، لا في المستودع أو ملف إعدادات مكشوف.
صمّم دورة تجديد وإلغاء قبل انتهاء الشهادة أو استبدال الجهاز. سجّل رقم الوحدة والفرع والبيئة وبصمة الشهادة وتاريخ التفعيل والمسؤول عنها. لا تنسخ CSID إنتاجياً بين وحدات مستقلة لمجرد أنها تتبع الرقم الضريبي نفسه.
3. ولّد XML وفق UBL وقواعد السعودية
صيغة الأساس هي UBL 2.1 مع قواعد الأعمال والحقول والقيود التي تنشرها الهيئة. لا يكفي أن يكون XML صالحاً نحوياً؛ يجب أن يطابق مخطط XSD وقواعد EN 16931 والتخصيص السعودي وقاموس البيانات. راجع أحدث نسخة من مواصفات تنفيذ XML الرسمية.
ثبّت توليد المعرف UUID، ورقم الفاتورة الداخلي، والتاريخ والوقت والمنطقة الزمنية، ورمز العملة، وبيانات المورد والمشتري، والضريبة والتقريب والإجماليات والمراجع. يجب أن يساوي مجموع الأسطر والخصومات والرسوم والضريبة النتيجة النهائية وفق قواعد التقريب، لا وفق حساب الواجهة فقط.
اكتب اختبارات Golden Files لكل نوع فاتورة وحالة ضريبية، ثم شغّل SDK أو المدقق الرسمي في خط البناء. افصل نموذج البيانات التجاري عن محوّل UBL حتى تتغير المواصفة من دون إعادة بناء منطق الطلبات.
4. طبّق الختم والتسلسل بلا اختصارات
تتطلب المنظومة سلامة المحتوى وتسلسل المستندات. احسب تجزئة الفاتورة بالطريقة والترتيب المحددين، واحتفظ بقيمة عداد الفواتير ICV وتجزئة الفاتورة السابقة PIH لكل وحدة. أي اختلاف في canonicalization أو العناصر المستثناة من التوقيع يغيّر الناتج ويرفض المستند.
الفاتورة المبسطة تُختم بواسطة حل المكلف باستخدام هوية الوحدة الإنتاجية قبل Reporting. أما الفاتورة القياسية فتمر عبر Clearance وتعيدها الهيئة بعد التحقق مع ختمها ورمزها وفق المسار الرسمي. لا تعمم خطوة توقيع واحدة على النوعين.
تحقّق من الساعة، وحماية المفتاح الخاص، والتشغيل المتزامن. إذا أصدرت عمليتان فواتير من الوحدة نفسها في اللحظة ذاتها من دون قفل أو تسلسل ذري، قد تفسدان ICV وPIH. عالج الترتيب في طبقة ثابتة حتى لو كانت خدمات التطبيق موزعة.
5. أنشئ QR من البيانات المعتمدة
رمز QR ليس صورة زخرفية ولا رابطاً إلى PDF. كوّنه وفق TLV والحقول المطلوبة في المواصفات، وبالقيم نفسها المستخدمة في XML. في الفواتير المبسطة يتحمل الحل مسؤولية توليد الرمز والختم قبل الرفع؛ وفي الفواتير القياسية استخدم النسخة التي تعيدها منصة فاتورة بعد Clearance.
اختبر QR على تمثيل الفاتورة العربية والإنجليزية، وعلى الطابعة الحرارية وPDF/A-3 والشاشة. لا تجعل ضغط الصورة أو القص يمنع القراءة. اختبر حقول Base64 كتسلسل بايتات، لا كنص يبدو صحيحاً للمستخدم فقط.
تتضمن المتطلبات الأمنية الرسمية مواصفات الختم وحماية سلامة المستند. احتفظ باختبار يفك QR ويقارن كل حقل بمصدره قبل السماح بإصدار الفاتورة.
تحدث مع فريق CloudTopia على واتساب لمراجعة نموذج XML وسلسلة الختم قبل الإنتاج. تبدأ باقة تدقيق الجاهزية وإثبات الربط في بيئة الاختبار من 3,900 ر.س، ولا تشمل رسوم أنظمة خارجية أو معالجة محاسبية أو ضريبية.
6. افصل Clearance عن Reporting
استخدام endpoint خاطئ ليس خطأ تسمية؛ إنه يغيّر وقت الإرسال ومن يختم المستند وما يجوز مشاركته مع العميل.
العنصر | Clearance للفواتير القياسية B2B | Reporting للفواتير المبسطة B2C |
متى يُرسل؟ | قبل مشاركة الفاتورة المعتمدة مع المشتري | بعد الإصدار، خلال 24 ساعة |
ما الذي تعيده المنصة؟ | فاتورة cleared مع ختم ZATCA وQR عند النجاح، أو أخطاء/تحذيرات | حالة قبول أو قبول مع تحذير أو رفض وأسبابه |
من يضع الختم؟ | ZATCA على المستند الذي اجتاز Clearance | حل المكلف قبل الإبلاغ |
مسار الفشل | لا تعامل النسخة كمفاتورة cleared؛ أصلح الأخطاء وأعد الإرسال قبل المشاركة | احتفظ بالمستند وسجله، عالج سبب الرفض وأعد الإبلاغ وفق الإجراء الرسمي |
أثر انقطاع الاتصال | أوقف إصدار النسخة النهائية القياسية أو فعّل الإجراء الرسمي المعتمد للحالة | خزّن الطلب في طابور متين وأرسله فور عودة الاتصال ضمن المهلة |
لا تعتبر HTTP 200 وحده نجاحاً. افحص جسم الاستجابة، وحالة التحقق، والتحذيرات، ومعرّف الطلب، والنسخة المعادة. طبّق retry محدوداً مع backoff للأخطاء المؤقتة، لكن لا تعاود إرسال فاتورة مقبولة كأنها جديدة.
7. صمّم مسار الفشل قبل المسار السعيد
قسّم الأعطال إلى تحقق تجاري، أو XML، أو مصادقة وشهادة، أو شبكة، أو معدل طلبات، أو خدمة خارجية. لكل فئة سياسة مختلفة. الخطأ التجاري يحتاج تصحيح البيانات؛ فشل المصادقة يحتاج فحص CSID والسر؛ وانقطاع الشبكة يحتاج طابوراً وإعادة محاولة لا تعديل الفاتورة.
نفّذ المعالجة بهذا التسلسل:
- سجّل رمز الاستجابة ومعرّف التتبع من دون كشف الأسرار.
- صنّف الخطأ إلى دائم أو مؤقت وفق الوثائق.
- امنع التكرار باستخدام معرّف داخلي ثابت وحالة إصدار واضحة.
- أعد المحاولة للأخطاء المؤقتة ضمن سياسة محدودة.
- ارفع تنبيهاً بشرياً عند اقتراب مهلة Reporting أو تكرار الرفض.
- احفظ الاستجابة النهائية بجوار XML المرسل والمستلم.
لا تسمح للمستخدم بحذف فاتورة مرفوضة من السجل. قد تحتاج إلى مستند مصحح أو إشعار مرتبط، ويحدد الفريق المحاسبي الإجراء المناسب.
8. استخدم الـ sandbox كعقد اختبار
بيئة الاختبار ليست لإثبات أن endpoint يرد فقط. اختبر onboarding والتجديد، وكل نوع مستند، والتحذيرات، والرفض، وانتهاء الشهادة، وانقطاع الشبكة، والتكرار، وتسلسل PIH. مرّر ملفاتك عبر SDK والمدقق قبل الاتصال حتى تفصل خطأ المحتوى عن خطأ الشبكة.
أنشئ مجموعة بيانات لا تحتوي معلومات عملاء حقيقية. افصل عناوين sandbox ومفاتيحه وشهاداته عن الإنتاج، واجعل الانتقال متغير بيئة محمياً لا تعديل كود. لا تستخدم شهادة اختبار في الإنتاج أو العكس.
ينشر دليل بوابة المطورين أدوات SDK ومدقق الويب وواجهات اختبار onboarding والتجديد وReporting وClearance. اعتبر نجاح سيناريوهات القبول والرفض شرطاً للنشر.
9. أرشف المستند والدليل التشغيلي
احفظ XML الأصلي والنسخة cleared والاستجابة والطلب الآمن ومعرفات التتبع ووقت الإرسال وحالة التحقق. يمكن تقديم تمثيل PDF/A-3 مع XML مضمّن وفق المواصفات، لكن الملف المرئي وحده لا يغني عن البيانات المنظمة المطلوبة.
طبّق تخزيناً غير قابل للتعديل للمستخدم العادي، وتشفيراً أثناء النقل والتخزين، ونسخاً احتياطية واختبار استعادة. افهرس الأرشيف بالرقم الضريبي ورقم الفاتورة وUUID ونوع المستند والفرع والحالة. احجب الأسرار ومفاتيح المصادقة عن السجلات.
اربط الإشعار الدائن أو المدين بالفاتورة الأصلية، واحتفظ بتسلسل الأحداث. حدّد مدة الاحتفاظ والسياسة النهائية مع الفريق القانوني والضريبي وفق الأنظمة السارية، ولا تضع رقماً ثابتاً في الكود من مقال تقني.
10. راقب الإنتاج واختبر التحديثات
أنشئ لوحة مراقبة لعدد الفواتير المقبولة والمقبولة مع تحذير والمرفوضة، وزمن الاستجابة، وعمق طابور Reporting، وعمر أقدم مستند غير مبلغ، وصلاحية CSID. التنبيه المفيد يذكر الوحدة ونوع الخطأ ومعرّف التتبع من دون بيانات شخصية زائدة.
ثبّت نسخة المحوّل والمواصفة، وراقب تحديثات صفحة المطورين. اختبر كل تحديث على ملفات مرجعية قبل نشره. لا تجعل التحذير الدائم ضوضاء؛ افتح له مهمة إصلاح لأن التحذير اليوم قد يصبح رفضاً بعد تحديث القواعد.
تكتمل قائمة ZATCA Phase 2 عندما تنجح دورة الفاتورة من حدث البيع إلى الأرشيف، لا عندما ينجح أول طلب API. يجب أن تستطيع إثبات من أنشأ المستند، وبأي CSID، وماذا أرسِل، وماذا أعادت المنصة، وماذا استلم العميل.
راسل فريق CloudTopia على واتساب لتنفيذ الربط من sandbox إلى الإنتاج. يقرأ الفريق وثائق الهيئة بالعربية والإنجليزية، ويسلّم الكود المصدري للعميل بموجب العقد مع تسعير واضح بالريال السعودي ونطاق اختبار محدد.
الأسئلة الشائعة
ما هو CSID في نظام فاتورة؟
CSID هو معرّف ختم تشفيري يربط وحدة حل إصدار الفواتير بهوية المكلف وشهادة موثوقة. يبدأ المطور عادةً بمعرّف امتثال لاختبارات المطابقة، ثم يحصل على معرّف إنتاج للوحدة بعد النجاح. يجب حماية المفتاح الخاص المرتبط به، ومتابعة التجديد والإلغاء وعدم مشاركته بين وحدات مستقلة.
ما الفرق بين Clearance وReporting؟
يُستخدم Clearance عادةً للفواتير الضريبية القياسية B2B، ويجب الحصول على النسخة المعتمدة من ZATCA قبل مشاركتها مع المشتري. أما Reporting فيُستخدم للفواتير المبسطة B2C التي يختمها حل المكلف ثم يرفعها خلال 24 ساعة. لكل مسار endpoint واستجابة ومعالجة فشل مختلفة.
هل أستطيع ربط ZATCA بنفسي أم أحتاج مزوداً؟
يمكنك تنفيذ الربط داخلياً إذا امتلك الفريق خبرة UBL XML والتشفير وإدارة الشهادات والعمليات الضريبية والمراقبة. وتوضح الهيئة أن الالتزام لا يقتصر على مزودي قائمتها الاسترشادية. يبقى المكلف مسؤولاً عن المطابقة، لذلك استخدم مراجعة مستقلة واختبارات رسمية إذا كان التكامل داخلياً.
ما الصيغة التي تستخدمها فواتير ZATCA؟
تستخدم الفواتير الإلكترونية بيانات XML منظمة مبنية على UBL 2.1 مع قواعد EN 16931 والتخصيص السعودي الذي تحدده ZATCA. ويمكن إنشاء تمثيل PDF/A-3 يتضمن XML عند الحاجة. لا يكفي PDF عادي أو صورة فاتورة؛ التحقق والتوقيع والربط تعتمد على بنية XML والحقول المحددة.
اقرأ أيضاً
هل تحتاج إلى نظام إدارة علاقات العملاء (CRM) أو نظام تخطيط موارد المؤسسات (ERP) أو لوحة معلومات مخصصة؟
تحول كلاود توبيا جداول البيانات الفوضوية والعمليات اليدوية إلى أنظمة أعمال واضحة يمكن لفريقك استخدامها بالفعل.
شارك هذا المقال
كُتب بواسطة
Mohamad Shahm | محمد شـهم
أسس محمد شهم شركة كلاود توبيا بعد مدة طويلة من بناء منصات الويب، وأنظمة التجارة الإلكترونية، للأفراد والشركات. محمد شهم يكتب أيضًا مقالات عن القرارات الهندسية والتجارية وراء إطلاق برمجيات يستخدمها الناس فعلاً.
