دليل المستخدم لوحدة ZATCA (الفوترة الإلكترونية السعودية)

نظرة عامة على وحدة ZATCA

توفر وحدة ZATCA في النظام حلاً متكاملاً للامتثال لمتطلبات الفوترة الإلكترونية في المملكة العربية السعودية الصادرة عن هيئة الزكاة والضريبة والجمارك (ZATCA). تهدف هذه الوحدة إلى ضمان أن جميع الفواتير الإلكترونية الصادرة من النظام متوافقة تمامًا مع لوائح ZATCA من حيث المحتوى والشكل والرمز QR والتوقيع الرقمي. وتنقسم متطلبات الالتزام إلى مرحلتين[1]:

المرحلة الأولى (Phase 1 – مرحلة الإصدار والتوليد): بدءًا من ديسمبر 2021، أصبح على جميع المنشآت المسجلة في ضريبة القيمة المضافة إصدار فواتير ضريبية إلكترونيًا تحتوي على حقول محددة، بما في ذلك رمز استجابة سريعة (QR code) يتضمن معلومات أساسية مثل اسم البائع، الرقم الضريبي، تاريخ ووقت الفاتورة، إجمالي الفاتورة مع الضريبة، وقيمة الضريبة[2]. في هذه المرحلة لم يكن مطلوبًا إرسال الفواتير إلى أنظمة الهيئة بشكل لحظي، بل كان التركيز على ضمان وجود العناصر المطلوبة في الفاتورة الإلكترونية وتخزينها إلكترونيًا دون إمكانية العبث بها. تقوم وحدة ZATCA تلقائيًا بإضافة رمز QR المطلوب لكل فاتورة وضمان تضمين الحقول الإلزامية[1].

المرحلة الثانية (Phase 2 – مرحلة التكامل ابتداءً من 2023): تتطلب هذه المرحلة التكامل المباشر مع أنظمة هيئة الزكاة والضريبة والجمارك، حيث يجب توقيع الفواتير رقميًا باستخدام شهادة مشفرة معتمدة، وإرسال بيانات الفاتورة إلى منصة ZATCA للمراجعة إما للمصادقة الفورية (الفواتير بين المنشآت B2B) أو للإبلاغ خلال 24 ساعة (فواتير المستهلك النهائي B2C)[3][4]. بعد الإرسال، تقوم الهيئة بإصدار ختم تشفير يتضمن رقمًا معرفًا (وربما توقيع الهيئة) كدليل على أن الفاتورة تمت معالجتها والمصادقة عليها. يجب تضمين بعض بيانات هذا الختم في الفاتورة مثل تحديث محتوى رمز QR بمعلومات التوقيع المشفر[3]. وحدة ZATCA تتولى عنك هذه المهام المعقدة: حيث تقوم بتوليد ملف الفاتورة بصيغة إلكترونية معتمدة (صيغة UBL XML) يحتوي على كافة المعلومات المطلوبة، وتوقعه رقميًا بالشهادة المجهزة، ثم ترسله عبر واجهة برمجية (API) إلى منصة ZATCA وتتلقى الرد بما في ذلك الختم والنتيجة[3]. كل ذلك يتم بشكل تلقائي لتقليل الجهد اليدوي وضمان الامتثال دون تعقيد للمستخدم.

باختصار، وحدة ZATCA تضمن أن فواتيرك الإلكترونية مهيأة وفق لوائح المرحلة الأولى (تضمين QR والحقول اللازمة) ومتوافقة مع متطلبات المرحلة الثانية (التوقيع الرقمي والإرسال الآلي للهيئة) لتجنب أي مخالفات أو غرامات[1]. بهذا تكون فواتيرك صحيحة قانونيًا ويمكن التحقق من صحتها عبر أدوات الهيئة بسهولة من قبل العملاء أو الجهات الرقابية.

المتطلبات الأولية قبل استخدام الوحدة

قبل البدء في استخدام وحدة ZATCA، تأكد من توفر المتطلبات التالية:

التسجيل في ضريبة القيمة المضافة: يجب أن تكون منشأتك مسجلة في ضريبة القيمة المضافة السعودية وحاصلة على رقم ضريبي (VAT) صالح، فهذا الرقم سيتم استخدامه في تكوين الوحدة وفي رمز QR[2].

حساب في بوابة فاتورة (FATOORA): بوابة فاتورة هي المنصة التابعة لـ ZATCA لإدارة التكامل في مرحلة الفوترة الإلكترونية. ستحتاج إلى حساب للوصول إلى الشهادات وطلب جهاز إلكتروني للفوترة.

تحديث النظام إلى أحدث إصدار: تأكد من أن نظام إدارة الفواتير لديك (الذي تم تثبيت الوحدة عليه) محدث ويدعم التكامل مع الوحدة. أيضًا تأكد من تفعيل وحدة ZATCA عبر لوحة تحكم المسؤول. عند تثبيت الوحدة لأول مرة قد تحتاج إلى دخول إعدادات النظام وتفعيلها للمستخدمين الإداريين. يمكن للمسؤول التحكم بصلاحيات الوحدة للمستخدمين (الموظفين) عبر إعدادات الصلاحيات كما سنوضح لاحقًا[5][6].

تهيئة معلومات الشركة: ضمن إعدادات النظام الأساسية، تأكد من إدخال الدولة = السعودية إذا كانت منشأتك سعودية. هذا الأمر مهم لأن الوحدة بشكل افتراضي لا تظهر إلا إذا كانت دولة الشركة هي السعودية أو إذا سمحت بإظهارها لغير السعودية بشكل يدوي[7]. كما تأكد من إدخال اسم مؤسستك الرسمي والرقم الضريبي في الحقول المخصصة بالنظام لأن الوحدة قد تستخدمها تلقائيًا إذا لم تُدخلها في إعدادات الوحدة نفسها.

خطوات التهيئة والإعداد الأولي للوحدة

بعد التأكد من المتطلبات أعلاه، يمكنك البدء بتهيئة وحدة ZATCA عبر الخطوات التالية:

الدخول إلى صفحة إعدادات وحدة ZATCA: من قائمة الإعدادات في النظام، ابحث عن خيار "ZATCA" أو "الفوترة الإلكترونية" ضمن إعدادات الإضافات أو الوحدات (قد تجدها في قائمة الإعدادات الجانبية). بالنقر عليها ستفتح صفحة إعدادات وحدة ZATCA[8]. ستجد في أعلى الصفحة عنوانًا مثل "إعدادات ZATCA" حيث يمكنك ضبط معلمات التكامل.

تفعيل الوحدة: فعّل خيار "تمكين وحدة ZATCA" عبر التأشير على مربع الاختيار المسمى مثلا بـ "تفعيل التكامل مع ZATCA" (Enable ZATCA)[9]. هذا الخيار يضمن تشغيل خصائص الوحدة على الفواتير. بدون تفعيله، ستعتبر الوحدة غير نشطة ولن تضيف رمز QR أو توقيع للفواتير.

قصر التطبيق على الفواتير السعودية (اختياري): ستجد خيار "إظهار للمنشآت السعودية فقط"[10]. عند تفعيله، لن تُطبق الوحدة أو تظهر ميزاتها إلا على الفواتير الخاصة بعملاء تقع بلدانهم في السعودية. هذا الخيار مفيد إذا كان نظامك يصدر فواتير لدول متعددة وترغب في حصر تطبيق قوانين ZATCA على الفواتير المحلية السعودية فقط. إن كنت تريد تطبيق الوحدة على كل الفواتير بغض النظر عن بلد العميل (مثلًا للاختبار أو التجربة)، قم بإلغاء تأشير هذا الخيار.

إدخال اسم البائع والرقم الضريبي: أدخل اسم المنشأة (البائع) الرسمي في حقل "اسم البائع" وأدخل الرقم الضريبي (VAT) الخاص بمنشأتك في حقل "الرقم الضريبي"[11]. تأكد من صحة هذه المعلومات لأنها ستظهر في رمز QR وستُرسل إلى الهيئة ضمن بيانات كل فاتورة.

اختيار المرحلة أو وضع التشغيل: إذا كانت الوحدة تتيح تحديد المرحلة (Phase 1 أو Phase 2) أو تحتوي على خيار تمكين المرحلة الثانية (Wave 2)[12]، فحدد الوضع المناسب. عادةً:

اترك المرحلة الثانية غير مفعلة (أو الخيار "Wave 2" = No) إذا كنت تريد تشغيل المرحلة الأولى فقط (أي توليد رمز QR بدون تكامل API). هذا مفيد في حال لم تكن جاهزًا بعد لعملية التكامل المباشر مع الهيئة.

فعّل خيار "تفعيل المرحلة الثانية" عندما تكون جاهزًا لربط النظام بمنصة ZATCA وإرسال الفواتير إلكترونيًا[12]. تفعيل هذا الخيار سيمكن الإعدادات الإضافية الخاصة بالتوقيع الإلكتروني والتكامل اللحظي.

ملاحظة: يُنصح باختبار المرحلة الثانية أولًا في وضع البيئة التجريبية (Sandbox) قبل تفعيلها على الإنتاج، كما سنوضح أدناه[13].

تحديد البيئة (Environment): اختر بيئة التكامل من القائمة المنسدلة "البيئة"[14]. لديك خياران:

Sandbox (بيئة تجريبية): لاختبار الإرسال إلى خوادم الاختبار لدى ZATCA. يُنصح بالبدء بها للتأكد من إعداداتك قبل الإرسال الحقيقي[15].

Production (بيئة إنتاجية): للإرسال إلى المنصة الحقيقية الخاصة بالهيئة. استخدمها فقط بعد نجاح الاختبارات في الـ Sandbox وعند حصولك على شهادة جهاز فعالة للإنتاج.

الحصول على الشهادة الرقمية (شهادة التوقيع الإلكتروني): هذه الخطوة من أهم المتطلبات للمرحلة الثانية. يجب عليك:

إنشاء طلب توقيع شهادة (CSR): وهو ملف طلب شهادة يحتوي على معلومات منشأتك ومفتاح عام. يمكنك توليد هذا الطلب باستخدام أدوات خارجية أو عبر بوابة فاتورة. أيضًا سيُنشأ معه مفتاح خاص (Private Key) يحتفظ به لديك. تأكد من حفظ المفتاح الخاص بسرية تامة؛ ستحتاجه في النظام لتوقيع الفواتير[16][17].

إرسال الـ CSR إلى هيئة الزكاة (عملية Onboarding): عبر بوابة فاتورة، ستقوم بتسجيل جهاز إلكتروني جديد للفوترة. ستحتاج إلى إدخال الـ CSR في بوابة الهيئة. عند تسجيل الجهاز ستعطيك البوابة رمز تحقق لمرة واحدة OTP. هذا الرمز بمثابة كلمة سر مؤقتة تؤكد أنك مخول لطلب الشهادة.

إدخال OTP في إعدادات الوحدة: في صفحة إعدادات ZATCA لديك حقل لرمز الـ OTP المقدم من البوابة[18]. قم بإدخاله في مكانه المحدد (مثلاً حقل بعنوان "OTP").

تنفيذ عملية Onboard عبر الوحدة: بجانب حقل OTP، قد تجد زرًا أو رابطًا بعنوان "Onboard in Sandbox" وآخر "Onboard in Production"[19]. تأكد أن البيئة المحددة أعلى الصفحة مطابقة (مثلاً Sandbox)، ثم اضغط زر الـ Onboard المناسب. سيقوم النظام بإرسال طلب إلى منصة ZATCA لتسجيل جهاز الفوترة باستخدام الـ CSR والـ OTP اللذين زودته بهما[20]. إذا كانت المعلومات صحيحة وتمت العملية بنجاح، ستحصل على معرف الجهاز (CSID) الخاص بشهادتك[21]. سترى رسالة نجاح في النظام (مثلاً "تم تقديم طلب الاعتماد بنجاح")[21]. سيتم تخزين معرف CSID في الحقل المخصص له في الإعدادات تلقائيًا.

استلام الشهادة الرقمية من الهيئة: بعد نجاح عملية الاعتماد، ستصدر الهيئة شهادة رقمية خاصة بجهازك (ملف بصيغة .pem أو .cer) يمكنك تنزيلها من بوابة فاتورة. قم بنسخ محتوى الشهادة (نص PEM) والصقه في حقل "الشهادة (PEM)" في إعدادات وحدة ZATCA[22]. إذا وفرت لك الهيئة أيضًا سلسلة شهادات (Certificate Chain) للصلاحيات، الصقها كذلك في الحقل المخصص (وإلا يمكن تركه فارغًا)[23].

إدخال المفتاح الخاص: خذ المفتاح الخاص Private Key الذي ولدته سابقًا مع CSR (غالبًا محفوظ لديك بملف .key) وافتحه بمحرر نصوص، ثم انسخ محتواه بالكامل (بما في ذلك عبارة -----BEGIN PRIVATE KEY----- وما يليها) والصقه في حقل "المفتاح الخاص (PEM)" في إعدادات الوحدة[24]. تأكد أن هذا المفتاح يتطابق مع الشهادة التي حصلت عليها (أي تم توليده معها)، وإلا سيظهر خطأ أن المفتاح غير صالح عند محاولة التوقيع[25].

ستجد أيضًا حقولًا مثل معرّف الجهاز CSID وسر CSID ورقم الجهاز التسلسلي. معرّف CSID يتم تعبئته تلقائيًا عند نجاح طلب Onboarding[21]. حقل "سر CSID" قد يكون مطلوبًا إذا قدمته الهيئة (بعض الأجهزة تتطلب Secret مع الـ CSID)، أدخله إن وُجد. الرقم التسلسلي للجهاز هو رقم تقوم الهيئة بتوفيره أحيانًا للجهاز المسجل، أدخله إذا كان مطلوبًا أو اتركه إن لم يُستخدم.

حفظ الإعدادات: بعد تعبئة جميع الحقول أعلاه (تمكين الوحدة، اسم البائع، الرقم الضريبي، إعدادات المرحلة الثانية والشهادة)، اضغط زر الحفظ (حفظ التغييرات) في أسفل صفحة الإعدادات[26]. سيقوم النظام بتخزين الإعدادات وستظهر رسالة تأكيد بأن الإعدادات تم تحديثها بنجاح.

ملاحظة: يفضّل قبل الانتقال إلى التشغيل الفعلي اختبار الاتصال مع منصة ZATCA عبر إرسال فاتورة تجريبية من خلال بيئة Sandbox للتأكد من أن الشهادة تم تكوينها بشكل صحيح وأن النظام قادر على الاتصال والتوقيع[15]. إذا واجهتك أخطاء في هذه المرحلة، راجع الرسائل التحذيرية والإعدادات (كالمفتاح الخاص والشهادة) وحاول مرة أخرى قبل التوجه إلى البيئة الإنتاجية.

إنشاء الفواتير الإلكترونية في النظام

بعد إكمال الإعدادات، يمكنك البدء بإنشاء الفواتير الإلكترونية كالمعتاد من خلال نظام الفوترة. فيما يلي إرشادات إنشاء الفاتورة مع مراعاة متطلبات ZATCA:

إدخال بيانات العميل والفاتورة بدقة: أنشئ فاتورة جديدة وأضف بيانات العميل كالاسم والعنوان. إذا كانت الفاتورة موجهة إلى منشأة مسجلة في ضريبة القيمة المضافة (فاتورة B2B)، احرص على إدخال الرقم الضريبي للعميل في خانته المخصصة حتى يتم تضمينه في بيانات الفاتورة[27]. أما إذا كان العميل فردًا (فاتورة مبسطة B2C) وليس لديه رقم ضريبي، يمكنك استخدام بيانات عميل عامة مثل "مستهلك" بدون رقم ضريبي. في كل الأحوال، أضف بنود الفاتورة والمبالغ مع تطبيق ضريبة القيمة المضافة بنسبة 15% (أو النسبة المطبقة) لضمان حساب مبلغ الضريبة الإجمالي بشكل صحيح.

حفظ وإصدار الفاتورة: بعد تعبئة جميع التفاصيل، قم بحفظ الفاتورة أو إصدارها حسب إجراءات النظام المعتادة. عند هذه النقطة، ستقوم وحدة ZATCA تلقائيًا بتوليد رمز QR وإدراجه في نسخة الفاتورة (سواء المعاينة على الشاشة أو ملف PDF المصدّر)[27][15]. لن تحتاج لاتخاذ إجراء يدوي لإضافة رمز QR في المرحلة الأولى – فالوحدة تضيفه بمجرد أن تكون الفاتورة مستوفية الشروط وتم حفظها. يمكنك التأكد من ظهور رمز QR على الفاتورة من خلال معاينة طباعتها؛ ينبغي أن ترى مربعًا يحوي رمز الاستجابة السريعة بعنوان "ZATCA QR" في مكان ما أسفل تفاصيل الفاتورة[15]. هذا الرمز يحتوي على البيانات المطلوبة (اسم البائع، الرقم الضريبي، الوقت والتاريخ، إجمالي المبلغ، إجمالي الضريبة) مشفرة بصيغة TLV وتم تحويلها إلى Base64[28][29].

نصيحة: يمكنك استخدام كاميرا هاتف ذكي وتطبيق قارئ QR لمحاولة مسح الرمز الظاهر على الفاتورة. ستجد أنه يُظهر بيانات مشفرة (ليست نصًا واضحًا) – هذا أمر متوقع، حيث يكون المحتوى مشفرًا بتنسيق خاص. يمكن لتطبيق ZATCA الرسمي أو أدواتهم قراءة هذا الرمز وإظهار محتوياته (مثل اسم البائع والمبلغ) للتحقق من صحة الفاتورة[15].

إرسال الفواتير إلى منصة ZATCA (مرحلة التكامل)

بمجرد إنشاء الفاتورة وظهور رمز QR الأساسي، ننتقل إلى خطوة التكامل مع منصة ZATCA (المرحلة الثانية)، أي إرسال الفاتورة إلكترونيًا للحصول على مصادقة (للفواتير الضريبية إلى شركات) أو تقرير (للفواتير المبسطة إلى أفراد) من الهيئة. أضافت وحدة ZATCA لوحة وأزرار خاصة في صفحة تفاصيل الفاتورة (للمستخدم الإداري) لتسهيل هذه العملية[30]. للوصول إليها، افتح الفاتورة المطلوبة من قائمة الفواتير (عرض كمسؤول). ستلاحظ وجود قسم جديد أو لوحة بعنوان "ZATCA" تحتوي على معلومات وأزرار. إليك شرحًا لكيفية استخدامها:

عرض حالة الامتثال للفاتورة: في لوحة ZATCA ستجد حالة الفاتورة بالنسبة للتكامل مع الهيئة. فعلى سبيل المثال، قد تظهر عبارة "No Wave-2 activity yet" (لا توجد عملية تكامل بعد) إذا لم يتم إرسال الفاتورة حتى الآن[31]. بعد إرسال الفاتورة ستتغير هذه الحالة إلى “reported” (مبلّغة) أو “cleared” (مصفّاة) أو غير ذلك حسب نتيجة الإرسال[32]. كما قد تظهر شفرة تعريفية (ACK) أو رقم مرجعي إذا تم إصدارها من الهيئة عند المصادقة على فاتورة B2B[33]. هذه المعلومات تساعدك على متابعة ما إذا تمت معالجة الفاتورة بنجاح أم لا.

أزرار إرسال/معالجة الفاتورة: توفر الوحدة أربعة أزرار رئيسية تظهر عادة في أعلى أو أسفل لوحة ZATCA. استخدام هذه الأزرار يكون يدويًا من قبل الموظف بعد إنشاء الفاتورة. فيما يلي الأزرار ودورها[30]:

زر "ZATCA XML": يقوم بتوليد ملف الفاتورة الإلكتروني بتنسيق UBL XML وتوقيعه رقميًا بالمفتاح الخاص وشهادتك، دون إرساله إلى الهيئة[34]. عند النقر عليه، سيقوم النظام بإنشاء ملف XML مطابق للفاتورة الحالية يحتوي على كل البنود والبيانات المطلوبة، ويضيف إليه التوقيع الإلكتروني (ختمك الرقمي). يتم حفظ هذا الملف في النظام للرجوع إليه، وتُحدث حالة الفاتورة إلى "xml_generated" في قاعدة البيانات[34]. استخدام هذا الزر اختياري ويُفيد في حال رغبت في مراجعة الملف يدويًا قبل الإرسال أو إجراء اختبار أولي. على سبيل المثال، يمكنك توليد XML ثم تنزيله ومشاركته مع وضع الاختبار في بوابة ZATCA للتأكد من خلوه من الأخطاء[35]. بعد توليد الـ XML الموقّع، يقوم النظام أيضًا بتحديث رمز QR الخاص بالفاتورة ليشمل العناصر التشفيرية الجديدة (مثل بصمة الفاتورة الرقمية والتوقيع) مما يرتقي بمستوى الرمز إلى متطلبات المرحلة الثانية[34].

زر "ZATCA Report": هذا الزر مخصص للفواتير المبسطة (B2C) أو في حال أردت الإبلاغ عن الفاتورة دون طلب مصادقة فورية[36]. عند النقر عليه، سيقوم النظام بتجهيز ملف الـXML الموقّع (سيولد ويوقع آليًا إذا لم تكن استخدمت زر XML سابقًا) ثم يرسله إلى واجهة API الخاصة بـ ZATCA بوضع "Reporting"[36]. إذا تمت العملية بنجاح فسيكون قد تم تبليغ الفاتورة إلى الهيئة (أي تسجيلها في النظام خلال 24 ساعة)[36]. لا تتوقع الحصول على رقم إذن (ACK) للفواتير المبلغة؛ يكفي أنك أبلغتها. سيقوم النظام بتحديث حالة الفاتورة إلى "reported" (مبلّغة)[36]. بالنسبة لفواتير B2C، هذا الإجراء يكفي قانونيًا، حيث يجب فقط إرسال الفاتورة للهيئة خلال المهلة المحددة. بعد التبليغ، يمكنك تزويد العميل بفاتورته (إلكترونيًا أو مطبوعة) لأنها الآن تحمل ختمًا رقمياً صالحًا (من توقيعك) وقد تم تسجيلها في النظام[36].

زر "ZATCA Clear": استخدمه للفواتير الضريبية القياسية بين منشآت (B2B) التي تتطلب تصريح/موافقة فورية من الهيئة قبل إصدارها للعميل[4]. عند الضغط على هذا الزر، سينشئ النظام ملف XML الموقع للفاتورة (إن لم يكن موجودًا) ثم يرسله إلى واجهة API بوضع "Clearance"[4]. سيعالج نظام ZATCA الطلب فورًا، وإذا تمت المصادقة بنجاح ستعود استجابة تحمل موافقة الهيئة. تتضمن الموافقة عادة رقم معرف يسمى Acknowledgment ID (شهادة التصريح) يدل على أن الفاتورة تمت تصفيتها واعتمادها[33]. قد تتضمن الاستجابة أيضًا نسخة من توقيع الهيئة أو ختمها على الفاتورة. يقوم النظام بتسجيل تلك الاستجابة: سيتم تحديث حالة الفاتورة إلى "cleared" (مصفّاة) وتخزين أي بيانات مهمة مثل رقم الـ ACK في قاعدة البيانات[33]. كما قد يحدث النظام رمز QR أو معلومات الفاتورة لإضافة دليل التصريح – على سبيل المثال قد يُضاف رقم الموافقة كعلامة أو يتم التأكد من أن الختم المشفر في QR يتطابق مع المعلومات الجديدة[33]. الآن أصبحت الفاتورة موثقة ومصرح بها ويمكنك إصدارها للعميل مع الثقة بأنها صالحة رسميًا.

زر "ZATCA Send": هذا الزر بمثابة اختصار ذكي يقوم تلقائيًا باختيار الإجراء المناسب (Report أو Clear) اعتمادًا على نوع الفاتورة[37]. فالنظام يحدد تلقائيًا ما إذا كانت الفاتورة B2B أو B2C بناءً على بيانات العميل (إذا كان يحتوي على اسم شركة أو رقم ضريبي يعتبره B2B وإلا فيعامله كـB2C)[38]. عند الضغط على "Send":

إن كانت الفاتورة B2B فسيقوم بما يعادل الضغط على زر Clear وإرسال طلب تصريح[37].

وإن كانت B2C فسيقوم بما يعادل الضغط على زر Report[37].

بهذه الطريقة لا يحتاج المستخدم لاتخاذ قرار يدوي؛ فقط اضغط "Send" ودع الوحدة تقرر وتسلك المناسب. يُفضل استخدام هذا الزر بعد مراجعة الفاتورة بالكامل وجاهزيتك لإرسالها، لتجنب الأخطاء. وفي حال احتجت تجاوز التحديد التلقائي لأي سبب (مثلًا: فاتورة لعميل شركة لكن تريد فقط تبليغها دون تصريح فوري)، توفر لك الوحدة خيار "تجاوز نوع الإرسال (Routing Override)" داخل لوحة ZATCA[39][40]. عبر هذا الخيار تستطيع تحديد وضع الفاتورة يدويًا (إما دائمًا B2B أو دائمًا B2C) ثم حفظه، وبعدها زر "Send" سيتبع هذا التحديد الثابت بدل التحديد التلقائي. لكن في الظروف العادية، الوضع التلقائي كافٍ وفعال[37].

استلام نتيجة الإرسال: بعد استخدام أي من الأزرار أعلاه (Report/Clear/Send)، ستظهر لك تنبيه في أعلى الشاشة بنتيجة العملية. مثلاً: إذا نجح التصريح ستظهر رسالة خضراء تفيد بذلك (مثل "Invoice Cleared" أو "تم التصريح بنجاح")، وإذا فشل سترى تنبيهًا أصفر أو أحمر يحتوي على وصف الخطأ (مثل "فشل الإرسال" أو "خطأ في التوقيع")[41][42]. كذلك، يمكنك إعادة فتح الفاتورة والاطلاع على لوحة ZATCA مجددًا لرؤية التحديثات:

سترى أن حالة الفاتورة تغيرت من "لا يوجد نشاط" إلى حالة جديدة ("reported" أو "cleared" أو ربما "xml_generated" إن كنت استخدمت زر XML فقط)[32].

إذا كانت هنالك أخطاء تفصيلية من منصة ZATCA، ستجدها ظاهرة في لوحة الفاتورة بشكل رسالة أو في مربع "Errors" ضمن تفاصيل اللوحة[43][44]. الوحدة تحتفظ بنص الرد الخطأ كما ورد من الهيئة (قد يكون باللغة الإنجليزية) لمساعدتك في فهم المشكلة.

بالنسبة لفواتير B2B المصروفة، يجب أن تجد رقم ACK ظاهرًا إذا نجحت العملية[33]. قد يظهر مثلاً بجوار الحالة على شكل تسمية "ACK #####" لتأكيد حصولك على رقم تصديق.

إرسال الفاتورة للعميل: بعد الحصول على حالة ناجحة (سواء تقرير مستلم أو تصريح)، يمكنك الآن متابعة إجراءاتك المعتادة بإرسال الفاتورة للعميل عبر البريد الإلكتروني أو طباعتها. ولكن انتبه:

بالنسبة لفواتير B2B: يجب عدم تسليم الفاتورة للعميل إلا بعد الحصول على التصريح (الحالة "cleared") وإلا تعتبر غير معتمدة. النظام الآن يحتوي بفاتورتك على الختم الإلكتروني المطلوب وقد تم تسجيلها، وبالتالي يمكنك مشاركتها. سيستطيع العميل أو مراجع الحسابات لديه التحقق منها عبر المسح الضوئي للـQR أو عبر بوابة ZATCA باستخدام رقم الـACK[45].

بالنسبة لفواتير B2C: يجب تبليغها خلال 24 ساعة كما ذكرنا. وبعد الضغط على Report (أو Send وتم التبليغ)، أصبحت الفاتورة تحمل توقيعك الرقمي وختمك الإلكتروني (لكن بدون ACK كونها مبسطة)[36]. عليك إرسالها أو تسليمها للعميل خلال المهلة النظامية وهي الآن صالحة قانونيًا.

التحقق من صحة الفواتير والإجراءات بعد الإرسال

بفضل وحدة ZATCA، يتم التحقق من صحة الفواتير تلقائيًا أثناء كل من مرحلتي الإصدار والإرسال:

التحقق أثناء الإصدار (Phase 1): تتأكد الوحدة من إضافة رمز QR يحتوي على المعلومات المطلوبة. إذا كان QR مفقودًا أو البيانات ناقصة (مثلاً نسيت إدخال الرقم الضريبي للبائع في الإعدادات)، قد لا يظهر QR على الفاتورة. لذا أول خطوة للتحقق هي معاينة الفاتورة والتأكد من وجود QR. إن لم يظهر، راجع إعدادات الوحدة (هل تم التفعيل؟ هل أدخلت اسم البائع ورقمه الضريبي؟)[11].

التحقق أثناء التكامل (Phase 2): عند محاولة إرسال الفواتير، يقوم النظام بالتحقق من وجود الشهادة والمفتاح الخاص. إذا وجد أن أي منهما مفقود أو غير صحيح، سيمنع الإرسال ويعطيك خطأ مناسب مثل "مفتاح خاص أو شهادة مفقودة"[25] أو "مفتاح خاص غير صالح"[46]. كذلك تُرفَض أي محاولة إرسال إذا لم تكن الفاتورة موجودة أو تحمل بيانات أساسية.

بعد الإرسال: تعتمد سلامة الفاتورة على نتيجة الاستجابة من منصة ZATCA:

إذا نجح التقرير أو التصريح، فهذا يعني أن الفاتورة مطابقة للشروط الفنية، وتم تسجيلها لدى الهيئة. عندها تعتبر فاتورة صحيحة ويمكن استخدامها في الدفاتر المحاسبية أو لتقديمها للعميل/المحاسب القانوني بثقة.

إذا فشل الإرسال، فذلك مؤشر أن هناك خلل يجب تصحيحه قبل إعادة المحاولة. على سبيل المثال، قد تتلقى خطأ بسبب:

خلل في البيانات: مثل نقص حقل إلزامي أو تنسيق غير صحيح (كرقم ضريبي للعميل مكتوب بطريقة خاطئة). قم بمراجعة البيانات المذكورة في رسالة الخطأ وصححها (مثلاً تحديث رقم الضريبة أو اسم العميل) ثم أعد المحاولة[47].

توقيت النظام: إذا كان وقت النظام المحلي غير متزامن مع الوقت الحقيقي، قد ترفض الهيئة التوقيع لعدم صلاحية الطابع الزمني. تأكد أن ساعة النظام مضبوطة بشكل صحيح على التوقيت الفعلي[47].

تكرار الرقم التسلسلي للفاتورة: الهيئة لا تسمح بازدواج أرقام الفواتير. تأكد أن رقم الفاتورة فريد وغير مستخدم سابقًا في فواتيرك المبلغة.

مشكلة في الشهادة: كأن تكون الشهادة منتهية الصلاحية أو تم إلغاؤها. في هذه الحالة يجب تجديد الشهادة عبر بوابة ZATCA ثم تحديثها في النظام.

أخطاء أخرى شائعة: مثل محاولة التصريح بفاتورة B2C بالخطأ أو العكس، أو عدم إكمال خطوات Onboarding بشكل صحيح. الرسالة القادمة من ZATCA ستوضح نوع الخطأ[48].

بمجرد تصحيح السبب، يمكنك الضغط على زر Send أو الإجراء المناسب مرة أخرى لإعادة إرسال الفاتورة. نظام الوحدة مصمم بحيث يسمح بإعادة المحاولة إذا كانت الحالة السابقة فشلت، ولن يكرر الإرسال من تلقاء نفسه إن كانت الفاتورة سبق واعتمدت إلا إذا قمت بتغيير وضعها (مثلاً استخدام override)[48]. لذا لا تقلق من التكرار غير المقصود، وتابع المحاولة حتى تنجح العملية.

التدقيق والارشفة: جميع الفواتير المرسلة يتم حفظ نسخة XML الموقعة الخاصة بها في النظام. كما يتم تخزين سجل الحالة والرمز المشفر (hash) في قاعدة البيانات[49][50]. هذا يعني أنه يمكنك دائمًا العودة لأي فاتورة ورؤية:

متى أرسلت،

ماذا كانت حالتها (مولدة، مبلغة، مصرح بها)،

وهل يوجد أخطاء مسجلة عليها،

وما هو معرّف التصريح (إن وجد).

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

منع التلاعب بعد الإصدار: حسب أنظمة ZATCA، لا يجوز حذف الفواتير الإلكترونية أو تعديلها جوهريًا بعد إصدارها. أي تعديل يجب أن يتم عبر إصدار إشعارات دائن/مدين مرتبطة. وحدة ZATCA تراعي ذلك، حيث أن الفواتير الموقعة والمبلغة لا يمكن حذفها من النظام (تم تعطيل زر الحذف للفواتير عند تفعيل الوحدة للامتثال للPhase 1)[51]. وإذا استدعى الأمر تعديل مبلغ أو إلغاء فاتورة، قم بإنشاء إشعار دائن للإلغاء أو إشعار مدين للتعديل حسب الحالة. هذا يضمن الحفاظ على سجلات نظامية سليمة ويتوافق مع اشتراطات عدم السماح بالعبث في الفواتير.

واجهات ووظائف الوحدة في النظام

توفر وحدة ZATCA عدة شاشات/عناصر واجهة ضمن النظام للتعامل مع الفواتير الإلكترونية:

صفحة إعدادات ZATCA: وقد تناولناها بالتفصيل، حيث يمكن للمسؤول ضبط كل الإعدادات المتعلقة بالتكامل (تفعيل/تعطيل الوحدة، خيارات المرحلة الأولى والثانية، بيانات البائع، إعدادات الشهادة الرقمية والتوقيع الإلكتروني، وغيرها). تأكد من أن فقط المستخدمين المخولين (مثل المدير المالي أو مسؤول النظام) يمكنهم الوصول إلى هذه الصفحة نظرًا لحساسيتها (تحتوي على مفاتيح خاصة وشهادات).

لوحة ZATCA في شاشة تفاصيل الفاتورة: تظهر هذه اللوحة فقط لموظفي النظام الذين لديهم صلاحية عرض الفواتير وصلاحية استخدام وحدة ZATCA (انظر قسم الصلاحيات أدناه)[52]. تتضمن اللوحة كما شرحنا معلومات حالة الفاتورة وأزرار التكامل. هذه اللوحة غير مرئية للعملاء؛ فهي مخصصة للاستخدام الداخلي فقط.

رمز QR في قالب الفاتورة: تقوم الوحدة بتضمين QR في نموذج الفاتورة سواء الإلكتروني (PDF/المطبوع) أو عند العرض على الشاشة. لا يوجد إجراء يدوي مطلوب هنا سوى التأكد من ظهور الرمز. قد ترغب في تعديل تصميم قالب الفاتورة في النظام لتغيير موضع الـQR أو حجمه حسب رغبتك، لكن بشكل افتراضي سيظهر بموقع محدد وبحجم قياسي (حوالي 5×5 سم)[53][54]. وجود عبارة "ZATCA QR" تحت الصورة أمر طبيعي لتعريفه.

قاعدة بيانات الفواتير المدمجة: هناك جدول داخلي يحتفظ بمتابعة حالة كل فاتورة بالنسبة للتكامل (مثل xf_zatca_wave2_invoices الذي يسجل معرف الفاتورة وحالتها الحالية ورقم التجزئة hash ووقت آخر تحديث... إلخ). هذا ليس واجهة مرئية للمستخدم، لكنه يُستخدم لتغذية المعلومات للوحة الـZATCA في الواجهة[43]. فقط للعلم أن النظام يتابع خلف الكواليس كل شيء لضمان عدم نسيان أي فاتورة.

الصلاحيات المطلوبة واستخدام الوحدة من قبل الموظفين

يُمكن للمسؤول التحكم في من له صلاحية استخدام وحدة ZATCA عبر إعدادات الأدوار والصلاحيات في النظام. عند تثبيت الوحدة، سيتم تلقائيًا إنشاء مجموعة صلاحيات جديدة تحت اسم مثلاً "ZATCA" أو "ZATCA Compliance" ضمن إعدادات الأمان الخاصة بالمستخدمين[5]. من هناك يمكنك تحديد ما إذا كان دور معين (مثل المحاسبين أو المدراء) لديه قدرة على:

عرض (View): لرؤية لوحة ZATCA في الفاتورة والاطلاع على الحالة والمعلومات[52].

إنشاء/إرسال (Create): لتنفيذ عمليات الإرسال (Report/Clear) وتوليد XML عبر الأزرار.

تعديل (Edit): ربما لتعديل إعدادات متعلقة أو إعادة محاولات.

حذف (Delete): على الأرجح غير مستخدمة فعليًا هنا (لأنه لا يُحذف شيء في الوحدة)، لكنها وُضعت للاتساق مع هيكل الصلاحيات.

يُنصح بأن يمنح المسؤول صلاحية العرض والإرسال فقط للأفراد المعنيين (مثلاً المحاسب أو موظف الفواتير)، وألا يمنح صلاحيات تعديل الإعدادات إلا للمدير التقني أو من يقوم بضبط التكامل. علمًا بأن محاولة الوصول لوظائف الوحدة دون صلاحية سيمنعها النظام برسالة "Access Denied" أو ما شابه[55][56]. كذلك عملية Onboarding عبر الإعدادات مقصورة على المدير (Admin فقط)[57][58]، لأنها خطوة حساسة تتعلق بتوليد شهادات. تأكد من ضبط هذه الصلاحيات بعد تثبيت الوحدة وقبل البدء بالاستخدام الفعلي.

الأخطاء الشائعة وكيفية معالجتها

فيما يلي قائمة بأخطاء أو مشاكل قد تواجهها أثناء استخدام وحدة ZATCA، مع طرق حلها:

خطأ "Missing Private Key or Certificate" (مفتاح أو شهادة مفقودة): يظهر عند محاولة توقيع أو إرسال فاتورة بدون وجود شهادة رقمية أو مفتاح خاص محفوظ في الإعدادات[25]. الحل: تأكد من إدخال نص الشهادة الرقمية في حقلها ونص المفتاح الخاص في حقله ضمن إعدادات الوحدة، ثم احفظ الإعدادات وحاول مجددًا.

خطأ "Invalid Private Key (PEM)" (مفتاح خاص غير صالح): يعني أن النص الذي أدخلته في خانة المفتاح الخاص ليس مفتاحًا صالحًا أو لا يتطابق مع الشهادة[46]. الحل: تأكد أنك قمت بنسخ المفتاح الصحيح المولد من الـ CSR نفسه وأنك لم تقم بلصق شهادة أخرى أو مفتاح مختلف. يجب أن يكون المفتاح بصيغة PEM ويبدأ بـ -----BEGIN PRIVATE KEY-----. أدخل المفتاح المطابق للشهادة.

خطأ في OTP أو فشل Onboarding: إذا قمت بالضغط على زر Onboard ولم يتم إصدار CSID (مثلاً ظهرت رسالة خطأ تحتوي رمز HTTP مثل 401 أو 400)[41]، فهذا يعني أن رمز الـ OTP الذي استخدمته غير صحيح أو منتهي الصلاحية أو أن الـ CSR غير مقبول. الحل: تأكد من نسخ OTP الصحيح من بوابة فاتورة فور إصداره (صلاحية OTP قصيرة الزمن). وإذا انتهت صلاحيته، اطلب OTP جديد. تأكد أيضًا أن الـCSR متوافق مع المطلوب (مثلاً يحتوي على معلومات المؤسسة الصحيحة). ثم حاول عملية Onboarding مرة أخرى.

خطأ رفض من واجهة ZATCA عند الإرسال (Clearing/Reporting failed): أحيانًا قد يصلك خطأ عام مثل "Report failed" أو "Clearance failed" دون تفاصيل كثيرة في التنبيه[59]. التفاصيل الكاملة قد تظهر في لوحة الأخطاء الخاصة بالفاتورة ضمن النظام. من الأسباب الشائعة:

خلل في بيانات الفاتورة: ربما رقم ضريبي للعميل خاطئ الصيغة، أو حقول عنوان مفقودة، أو استخدام رموز غير مقبولة. الحل: راجع بيانات العميل والفاتورة وأصلح أي معلومة غريبة أو ناقصة ثم أعد الإرسال[48].

عدم استيفاء شروط معينة: مثلاً حاولت تصنيف فاتورة كـB2B دون وضع رقم ضريبي للعميل – سيعتبرها النظام B2C بينما أنت أرسلتها كـClearance مما يؤدي لخطأ. الحل: إما أن تضيف رقم ضريبي للعميل لجعلها B2B حقيقي أو تستخدم وضع Report إذا كانت فعليًا بلا رقم ضريبي.

مشكلة توقيت أو رقم فاتورة مكرر: إذا كان توقيت إنشاء الفاتورة بعيد جدًا عن وقت الإرسال (بفارق كبير) قد ترفض الهيئة ذلك. أيضًا رقم الفاتورة يجب ألا يكون استخدم من قبل. الحل: تحقق من ساعة الخادم لديك. وتأكد أنك لا تعيد استخدام نفس الرقم لفواتير مختلفة[48].

خطأ 500 أو 503 من الخادم: ربما مشكلة من جهة منصة ZATCA نفسها أو مشكلة في الاتصال (SSL) بالشهادة. الحل: انتظر قليلاً وحاول مرة أخرى. تأكد أن الشهادة المستخدمة صالحة ولم تواجه انتهاء صلاحية.

لا يظهر رمز QR على الفاتورة: إذا بعد حفظ الفاتورة لم يظهر QR في التصميم، ربما الوحدة غير مفعلة أو الفاتورة لا تحقق الشروط. تأكد أنك فعّلت خيار تمكين ZATCA في الإعدادات[60]، وأن الفاتورة ليست مسودة (فقط الفواتير المكتملة يظهر عليها QR). أيضًا تحقق من خيار "إظهار للمنشآت السعودية فقط" ربما يمنع الظهور إذا كان عميل الفاتورة من بلد آخر ولم تعطل الخيار[7].

الفاتورة لم تتغير حالتها بعد الإرسال: في بعض الحالات قد ترسل الفاتورة وينجح الإرسال لكن حالة الفاتورة في لوحة ZATCA لا تتحدث تلقائيًا إلا بعد إعادة فتح الصفحة. الحل: قم بإعادة تحميل صفحة الفاتورة وستظهر الحالة الجديدة[31]. هذا الأمر طبيعي إذ لا يتم التحديث المباشر للواجهة في بعض الإصدارات.

عدم القدرة على حذف فاتورة: كما ذكرنا، الوحدة تمنع حذف الفواتير الصادرة تجنبًا لمخالفة اللوائح[51]. إذا كنت بحاجة لتعديل فاتورة بعد إصدارها، الإصدار السليم هو إنشاء إشعار وتصحيحها بدل حذفها. هذه ليست مشكلة برمجية بل ميزة أمان.

مشاكل أخرى محتملة: إن واجهت أمرًا غير معتاد (مثلاً توقف عملية الإرسال بسبب خطأ لم تعرف سببه)، يمكنك تفحص سجل الأخطاء في لوحة التحكم (إن وفر النظام سجلًا لتفاصيل الطلبات) أو التواصل مع الدعم التقني للوحدة. دائما تأكد أن لديك أحدث إصدار من الوحدة، حيث يجري تحسينها لتلبية أي تحديثات من قبل ZATCA[61].

باستخدام هذه الوحدة بالشكل الصحيح، ستصبح عملية إصدار الفواتير الإلكترونية compliant أمراً سلساً. احرص على مراجعة الإعدادات دورياً والتأكد من صلاحية شهادتك الرقمية، كما يُنصح بتجربة الإجراءات في وضع الاختبار Sandbox عند أي تغييرات كبيرة (مثلاً عند تجديد الشهادة) للتأكد من أن كل شيء يعمل قبل إرسال الفواتير الحقيقية. بذلك تضمن امتثال منشأتك الكامل لقوانين هيئة الزكاة والضريبة والجمارك، وتتفادى العقبات أو الأخطاء قبل وقوعها. [61]

[1] [2] [3] [4] [6] [13] [15] [27] [30] [32] [33] [34] [35] [36] [37] [45] [47] [48] [51] [61] index.html

[5] [7] [31] [39] [40] [43] [44] [52] hooks.php

[8] [53] [54] xf_zatca.php

[9] [11] [14] [18] [19] [22] [23] [24] [26] [60] settings.php

[10] [12] xf_zatca_lang.php

[16] [17] [20] [21] [25] [38] [41] [42] [46] [59] ZatcaWave2.php

[28] [29] xf_zatca_qr_helper.php

[49] [50] [55] [56] [57] [58] Xf_zatca.php