الربط مع منصة فاتورة: دليل تقني للمرحلة الثانية من الفوترة الإلكترونية لأنظمة ERP والفوترة

الربط مع منصة فاتورة هو الاتصال التقني بين نظام تخطيط موارد المؤسسة أو نظام الفوترة أو نقاط البيع لديك ومنصة «فاتورة» التابعة لهيئة الزكاة والضريبة والجمارك. ويُسجَّل كل وحدة فوترة بمعرّف ختم تشفيري (CSID)، ثم تُرسل الفواتير بصيغة UBL 2.1 XML موقّعة عبر الواجهات البرمجية: القياسية للاعتماد قبل تسليمها للمشتري، والمبسطة للإبلاغ خلال 24 ساعة.

بدأت هيئة الزكاة والضريبة والجمارك تطبيق مرحلة الربط والتكامل في 1 يناير 2023، وتطبّقها على دفعات (موجات)، مع إشعار كل فئة من المكلفين قبل ستة أشهر على الأقل، كما توضح صفحة مراحل التطبيق في موقع الهيئة. وفي 24 يوليو 2026 أعلنت الهيئة الموجة الخامسة والعشرين: المكلفون الذين تجاوزت إيراداتهم الخاضعة لضريبة القيمة المضافة 187,500 ريال في عام 2022 أو 2023 أو 2024 أو 2025 ملزمون بالربط في موعد أقصاه 1 فبراير 2027. وهذا الحد يُدخل كثيراً من المنشآت المتوسطة، والأنظمة الداخلية أو القديمة التي تعتمد عليها، ضمن النطاق.

هذا المقال موجّه لمن يتولى تنفيذ الربط فعلياً: مديري تقنية المعلومات، ومسؤولي أنظمة ERP، وفرق التطوير. وللاطلاع على الصورة الأشمل للالتزامات وأنواع الفواتير والمواعيد، راجع دليل الفوترة الإلكترونية في السعودية. أما هنا فنركّز على الجانب الهندسي: التسجيل، ومسارا الاعتماد والإبلاغ، والاختبار، ومعالجة الأخطاء.

كيف تعمل بنية الربط في المرحلة الثانية؟

يقوم نموذج الهيئة على «وحدة حل الفوترة الإلكترونية» (EGS): أي الجهاز أو التطبيق أو نسخة الخدمة التي تُصدر الفواتير. ولكل وحدة هويتها التشفيرية الخاصة وسلسلة فواتيرها المستقلة. وقد تمتلك الشركة الواحدة عشرات الوحدات موزعة على الفروع ونقاط البيع وقنوات التجارة الإلكترونية ونسخ أنظمة ERP.

ولكل مستند، يجب على وحدة الفوترة أن:

• تُنشئ الفاتورة أو الإشعار الدائن أو المدين بصيغة UBL 2.1 XML متضمنة الحقول التي تشترطها الهيئة.
• تُسند معرّفاً فريداً (UUID) وقيمة عدّاد الفاتورة (ICV) التي لا يجوز تكرارها أبداً.
• تُدرج قيمة تجزئة الفاتورة السابقة (PIH)، فتربط كل مستند بالمستند الذي يسبقه.
• تحسب تجزئة المستند وتوقّعه بالمفتاح الخاص والشهادة الخاصة بالوحدة.
• تُنشئ رمز الاستجابة السريعة (QR) وترسل ملف XML إلى الواجهة البرمجية الصحيحة لدى الهيئة.
• تحفظ النتيجة، بما فيها رد الهيئة، لأغراض التدقيق.

ولأن تسلسل الفواتير خاص بكل وحدة ويشمل فواتير المنشآت والمستهلكين معاً، فإن طريقة تحديدك للوحدات تؤثر مباشرة في التزامن، والتعامل مع الأعطال، وسهولة التوسّع.

كيف يتم التسجيل والحصول على معرّف الختم التشفيري (CSID)؟

قبل أن تتمكن وحدة الفوترة من إرسال فواتير فعلية، يجب تسجيلها. ووفق الدليل التقني التفصيلي للفوترة الإلكترونية الصادر عن الهيئة، تسير العملية كما يلي:

1. إنشاء رمز تحقق لمرة واحدة (OTP) من بوابة فاتورة. يسجّل مستخدم المكلف الدخول ويُنشئ الرموز. وصلاحية كل رمز ساعة واحدة، ويمكن إنشاء ما يصل إلى 100 رمز في طلب واحد، وهذا مفيد عند تسجيل وحدات كثيرة. ولا توجد واجهة برمجية لإنشاء الرموز، فهي تُنشأ من البوابة فقط.
2. إنشاء زوج المفاتيح وطلب توقيع الشهادة (CSR). تُنشئ الوحدة مفتاحها الخاص وطلب توقيع شهادة يتضمن حقولاً إلزامية، منها الاسم الشائع، والرقم التسلسلي، ورقم التسجيل الضريبي أو رقم المجموعة الضريبية، والوحدة التنظيمية، واسم المنشأة، والدولة، وأنواع الفواتير التي ستصدرها الوحدة (قياسية أو مبسطة أو كلتاهما)، والموقع، والقطاع.
3. طلب معرّف ختم الامتثال. تستدعي الوحدة واجهة Compliance CSID بطلب الشهادة ورمز التحقق، فتحصل على معرّف ختم الامتثال.
4. اجتياز فحوصات الامتثال. باستخدام معرّف الامتثال، ترسل الوحدة مستندات نموذجية: فاتورة قياسية وإشعاراً دائناً ومديناً للإصدار القياسي، وما يقابلها من المستندات المبسطة للإصدار المبسط. وإذا فشل أي فحص، تبدأ العملية من جديد برمز تحقق وطلب شهادة جديدين.
5. طلب معرّف ختم الإنتاج. بعد اجتياز الفحوصات، تُصدر جهة التصديق التابعة للهيئة معرّف ختم الإنتاج، الذي يوثّق الوحدة لاستخدام واجهات الاعتماد والإبلاغ الأساسية.
6. الحماية والتجديد. احفظ المفتاح الخاص بشكل آمن، وراقب انتهاء صلاحية الشهادة، وجدّدها قبل انتهائها. ويتبع التجديد المسار نفسه، ويُلغى المعرّف السابق.

ملاحظتان عمليتان: يجب على المكلفين المسجلين حديثاً في ضريبة القيمة المضافة الانتظار يومي عمل قبل التسجيل، ويمكن إلغاء معرّفات الختم يدوياً عبر البوابة أو تلقائياً، كما في حالة إلغاء التسجيل الضريبي.

ما الفرق بين الاعتماد (Clearance) والإبلاغ (Reporting)؟

الجانب	الاعتماد (Clearance)	الإبلاغ (Reporting)
المستندات	الفواتير الضريبية القياسية وإشعاراتها الدائنة والمدينة (غالباً بين المنشآت)	الفواتير الضريبية المبسطة وإشعاراتها (غالباً للمستهلكين)
التوقيت	قبل مشاركة الفاتورة مع المشتري	خلال 24 ساعة من إتمام المعاملة
من يختمها	تتحقق الهيئة منها وتختمها وتضيف رمز QR	توقّعها وحدة الفوترة لدى البائع وتُنشئ رمز QR
الصلاحية	لا تُعد صالحة إلا بعد اعتمادها من الهيئة	تُصدر فوراً ثم يتبعها الإبلاغ
عند الرفض	تُصحَّح الأخطاء ويُرسل مستند جديد بمعرّف وعدّاد وتجزئة وطابع زمني جديدة	تُصحَّح وتُعاد إرسالها، ولا يلزم إعادة إصدار نسخة العميل

وهذا الفرق يحدد البنية. فالاعتماد متزامن ويقع في المسار الحرج لعملية الفوترة، لذا يهمّ زمن الاستجابة والتوافر. أما الإبلاغ فيمكن تشغيله بشكل غير متزامن من طابور، ما دامت مهلة 24 ساعة محترمة.

ما المتطلبات التقنية في كل فاتورة بالمرحلة الثانية؟

• صيغة UBL 2.1 XML. تقبل واجهات الهيئة ملفات XML، ولا يُغني ملف PDF عن الإرسال بهذه الصيغة.
• التجزئة. تجزئة SHA-256 للفاتورة بعد توحيد صيغتها، تُحسب بعد استبعاد عناصر الامتدادات ورمز QR والتوقيع، وتُرمّز بصيغة Base64.
• التوقيع. توقيع ECDSA على التجزئة باستخدام المفتاح الخاص بالوحدة، مع الإشارة إلى الشهادة في الخصائص الموقّعة.
• سلامة السلسلة. يجب أن تساوي قيمة PIH تجزئة آخر مستند أنشأته الوحدة. والمستندات المرفوضة تبقى ضمن السلسلة، ولا يجوز تكرار قيم ICV أو UUID أبداً.
• رمز QR. بنية TLV مرمّزة بصيغة Base64 بحد أقصى 700 حرف، تشمل اسم البائع، والرقم الضريبي، والطابع الزمني، والإجماليات، وتجزئة الفاتورة، والتوقيع، والمفتاح العام، وفي المستندات المبسطة توقيع الختم من جهة التصديق التابعة للهيئة.

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

كيف تختبر الربط في بيئة الاختبار وبوابة المحاكاة؟

توفر الهيئة بيئتي اختبار مختلفتين، والخطة السليمة تستخدم الاثنتين.

بوابة المطورين وبيئة الاختبار (Sandbox)

تقدّم بوابة المطورين للفوترة الإلكترونية، الموصوفة في دليل بوابة المطورين، حزمة تطوير برمجية (SDK) بلغة Java للتحقق دون اتصال من ملفات XML والإشعارات ورموز QR، وأداة تحقق عبر الويب لما يصل إلى خمسة ملفات XML، وبيئة اختبار للتكامل توفر واجهات Compliance CSID وProduction CSID وفحوصات الامتثال والإبلاغ والاعتماد. وبيانات الاعتماد فيها تجريبية ولا يمكن استخدامها في بيئة الإنتاج. استخدمها أثناء التطوير وضمن مسار الاختبار الآلي.

بوابة محاكاة فاتورة

بوابة المحاكاة، التي أُطلقت في ديسمبر 2022، نسخة مطابقة لبوابة فاتورة يُوصل إليها من حساب المكلف نفسه. وتتيح التدرّب على الرحلة كاملة، من إنشاء رموز التحقق وتسجيل الوحدات إلى اعتماد المستندات والإبلاغ عنها، باستخدام بيانات تجريبية أو تاريخية. وردودها ليست اعتماداً أو إبلاغاً رسمياً. استخدمها للتجربة الشاملة بإعدادات منشأتك الفعلية قبل الإطلاق.

ما الذي يجب أن تغطيه خطة الاختبار؟

• كل نوع مستند تُصدره، بما في ذلك الإشعارات الدائنة والمدينة المرتبطة بالفواتير الأصلية.
• حالات الرفض والتحذيرات، واستمرارية السلسلة بشكل صحيح بعد رفض أحد المستندات.
• أعطال الشبكة وانتهاء المهلة، واستعادة الفواتير المتراكمة غير المُبلّغ عنها.
• تجديد الشهادة دون إيقاف الفوترة.
• أحجام الذروة، مثل دفعات نهاية الشهر أو العروض الترويجية في التجزئة.
• أسماء البائع والمشتري وعناوينهم وأرقامهم الضريبية باللغة العربية في جميع الحقول.

كيف تُعالَج الأخطاء والتحذيرات والانقطاعات؟

تُعيد واجهات الهيئة رموز حالة HTTP قياسية، ويحتاج كل منها إلى استجابة محددة في نظامك:

الرد	المعنى	ما يجب أن يفعله نظامك
200	مقبول، أي تم الاعتماد أو الإبلاغ	حفظ رد الهيئة وملف XML المعتمد، ثم تسليم الفاتورة
202	مقبول مع تحذيرات	تسليم الفاتورة، وتسجيل التحذيرات، وتوجيهها لتصحيح البيانات الأساسية
303	مسار خاطئ، كأن يكون الاعتماد معطّلاً	إعادة إرسال الفاتورة القياسية إلى واجهة الإبلاغ وفق التوجيه
400	مرفوض بسبب أخطاء في التحقق	تصحيح البيانات وإصدار مستند جديد بمعرّف وعدّاد وتجزئة جديدة
500	خطأ في الخادم	إعادة المحاولة بفواصل زمنية متزايدة، ثم التنبيه عند استنفاد المحاولات

صمّم النظام لتحمّل الانقطاع منذ اليوم الأول. استخدم صندوقاً صادراً أو طابوراً دائماً حتى لا تضيع أي فاتورة، واجعل الإرسال آمناً عند التكرار، وراقب طول الطابور مقارنةً بمهلة الإبلاغ البالغة 24 ساعة، ونبّه عند ارتفاع معدلات الرفض. ويُلزم الدليل التقني المكلفين أيضاً بإشعار الهيئة بالأعطال التقنية، على أن تُعتمد جميع المعاملات الصادرة أثناء الانقطاع أو يُبلَّغ عنها لاحقاً بصيغة XML متوافقة. ولا ينبغي أن تتوقف الأعمال بسبب الفوترة، لذا يجب توثيق إجراء بديل والتدرّب عليه.

هل يرتبط كل نظام مباشرة أم عبر خدمة مركزية؟

نادراً ما تمتلك المؤسسات نظام فوترة واحداً. فقد تُصدر الفروع ومنصات التجارة الإلكترونية والشركات التابعة ونقاط البيع وأدوات الفوترة القديمة فواتيرها كلٌّ على حدة. والقرار المعماري الأهم هو: هل يرتبط كل نظام بالهيئة مباشرة، أم تتولى خدمة فوترة إلكترونية مركزية متطلبات الامتثال نيابةً عنها جميعاً؟

• الربط المباشر يناسب نظام ERP حديثاً واحداً يتضمن دعماً مدمجاً للفوترة الإلكترونية يتكفّل به المورّد.
• الخدمة المركزية تناسب البيئات المتنوعة. إذ ترسل الأنظمة المصدرية بيانات الفاتورة إلى خدمة واحدة تتولى بناء ملف XML والتوقيع والإرسال والأرشفة. فتبقى بيانات الاعتماد ومنطق السلسلة والمراقبة في مكان واحد، وتُستوعب أي تغييرات مستقبلية في المواصفات مرة واحدة.

وتواجه منشآت التجزئة والضيافة التي تشغّل نقاط بيع كثيرة أسئلة خاصة بالعمل دون اتصال وتسجيل كل جهاز كوحدة مستقلة، ويتناولها دليلنا عن أنظمة نقاط البيع المتوافقة مع الهيئة. وإذا كنت تستبدل نظام ERP في الوقت نفسه، فيشرح دليلنا عن أنظمة ERP كيفية تقييم دعم الفوترة الإلكترونية المدمج.

كيف يبدو مشروع الربط النموذجي؟

1. الحصر. حصر كل نظام وقناة تُصدر فواتير أو إشعارات دائنة أو مدينة، والبيانات التي يحتفظ بها كل منها.
2. تحليل الفجوات. مقارنة البيانات المتاحة، مثل الأرقام الضريبية للمشترين والعناوين والفئات الضريبية للأصناف، بالحقول التي تشترطها الهيئة.
3. البنية. تحديد حدود وحدات الفوترة، والاختيار بين الربط المباشر والخدمة المركزية، وطريقة حفظ المفاتيح، ونموذج الطوابير.
4. البناء والاختبار في بيئة الاختبار. تطوير إنشاء ملفات XML والتوقيع ورمز QR وعملاء الواجهات البرمجية، والتحقق المستمر عبر حزمة التطوير وبيئة الاختبار.
5. التجربة على بوابة المحاكاة. تسجيل الوحدات وتشغيل سيناريوهات واقعية على بوابة المحاكاة.
6. التسجيل في بيئة الإنتاج والإطلاق. إنشاء رموز التحقق، والحصول على معرّفات ختم الإنتاج، والانتقال، والمراقبة الدقيقة خلال دورات الفوترة الأولى.

الخطوة التالية

إذا كان موعد موجتك يقترب، فابدأ بالحصر وتحليل الفجوات، فمشكلات جودة البيانات تظهر هناك لا في استدعاءات الواجهات البرمجية. وتصمّم أمواج للحلول حلول الربط مع منصة فاتورة لأنظمة ERP والفوترة ونقاط البيع وتبنيها عبر خدمة الربط مع الفوترة الإلكترونية. تواصل معنا لتحديد نطاق مشروع الربط الخاص بك.