أخطاء هيئة الزكاة والضريبة والجمارك في الفوترة

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

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

الجمهور المستهدف هنا هو المطوّر أو مسؤول التكامل التقني الذي يبني أو يصون اتصال نظام محاسبي بمنصة فاتورة. لذلك تجد أمثلة JSON فعلية لاستجابات الهيئة، وشرحاً للحقول التقنية كما تظهر في الواقع. الرموز التقنية الإنجليزية مثل validationResults وstatus تبقى كما هي لأنها أسماء حقول فعلية في الـ API.

لماذا تفشل الفواتير الإلكترونية أصلاً

الفاتورة الإلكترونية في المرحلة الثانية ليست ملف PDF يُرسل بالبريد. هي مستند XML منظم يتبع معيار UBL 2.1، موقّع رقمياً، ومربوط بسلسلة تجزئة (hash chain) مع الفاتورة السابقة. كل عنصر في هذا المستند خاضع لقواعد تحقق صارمة وضعتها الهيئة. أي انحراف عن المواصفة يُنتج خطأً.

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

• طبقة البنية وصيغة XML. هل المستند XML سليم نحوياً؟ هل يتبع مخطط UBL 2.1؟ هل الحقول الإلزامية موجودة وفي أماكنها الصحيحة؟
• طبقة قواعد الأعمال. هل القيم منطقية؟ هل مجموع بنود الفاتورة يساوي الإجمالي؟ هل نسبة ضريبة القيمة المضافة المحسوبة تطابق المبلغ؟ هل الرقم الضريبي بالتنسيق الصحيح؟
• طبقة التوقيع والتجزئة. هل التوقيع الرقمي صحيح؟ هل الشهادة (CSID) سارية؟ هل قيمة التجزئة للفاتورة السابقة مطابقة لما تتوقعه الهيئة؟
• طبقة المقاصة مقابل الإبلاغ. هل أرسلت الفاتورة عبر المسار الصحيح؟ الفاتورة الضريبية (B2B) تمرّ بالمقاصة، والفاتورة المبسّطة (B2C) تُبلَّغ خلال 24 ساعة.

تفصيل الطبقات الأربع

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

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

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

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

الطبقة الرابعة: المقاصة مقابل الإبلاغ. هذه الطبقة تتعلق بالمسار والنتيجة. حتى لو كانت الفاتورة سليمة بنيوياً ومنطقياً وموقّعة بشكل صحيح، فإرسالها عبر المسار الخطأ يُنتج خطأ حالة. تصنيف نوع الفاتورة (B2B أم B2C) بشكل صحيح شرط لاجتياز هذه الطبقة.

كيف تعيد الهيئة الأخطاء: بنية الاستجابة

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

تحوي الاستجابة عادة الحقول الأساسية التالية:

• validationResults: الكائن الذي يجمع نتائج التحقق كلها.
• status: الحالة العامة للفاتورة. القيم الشائعة PASS أو WARNING أو ERROR.
• errorMessages: مصفوفة رسائل الأخطاء التي تمنع قبول الفاتورة.
• warningMessages: مصفوفة رسائل التحذير التي لا تمنع القبول لكنها تشير إلى مشكلة محتملة.

كل رسالة داخل المصفوفتين تتبع الشكل نفسه: حقل type لنوع الرسالة، وcode لكود الخطأ الذي يميّزه، وcategory لفئة الخطأ، وmessage للنص الوصفي. الكود هو مفتاحك الأهم، لأنه ثابت لا يتغير، بينما النص قد يصاغ بطرق مختلفة.

هذا مثال لاستجابة فاتورة قُبلت لكن مع تحذير. لاحظ أن status هنا WARNING ومصفوفة errorMessages فارغة، لذلك الفاتورة مقبولة:

{
  "validationResults": {
    "status": "WARNING",
    "errorMessages": [],
    "warningMessages": [
      {
        "type": "WARNING",
        "code": "BR-KSA-EN16931-08",
        "category": "EN_16931",
        "message": "Buyer address is recommended but missing"
      }
    ]
  }
}

وهذا مثال لفاتورة رُفضت. status هنا ERROR، ومصفوفة errorMessages تحوي رسالة واحدة على الأقل. وجود أي عنصر في errorMessages يعني أن الفاتورة لن تُقبل حتى تُصحّح:

{
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "BR-CO-10",
        "category": "BR_CALCULATION",
        "message": "Sum of Invoice line net amount must equal the invoice total without VAT"
      }
    ],
    "warningMessages": []
  }
}

القاعدة التشخيصية الأولى تنبع مباشرة من هذه البنية: اقرأ status أولاً، ثم افحص errorMessages قبل warningMessages. لا تضيّع وقتك في تحذير بينما هناك خطأ يمنع القبول. عالج الأخطاء، ثم انظر في التحذيرات.

الفاتورة المرفوضة بسبب فشل في طبقة التوقيع تأخذ شكلاً مختلفاً. لاحظ هنا أن category تشير إلى التوقيع لا إلى الحساب، وهذا يوجّهك مباشرة للطبقة الثالثة:

{
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "BR-KSA-60",
        "category": "SIGNATURE",
        "message": "Invalid digital signature: certificate (CSID) expired"
      }
    ],
    "warningMessages": []
  }
}

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

{
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "XSD_SCHEMA_INVALID",
        "category": "XML_SCHEMA",
        "message": "Element 'cbc:ID' is required but was not found"
      }
    ],
    "warningMessages": []
  }
}

المقارنة بين الأمثلة الثلاثة المرفوضة تكشف قاعدة عملية: حقل category وحده يخبرك بالطبقة التي تحتاج فحصها، قبل أن تقرأ نص الرسالة. BR_CALCULATION توجّهك لقواعد الأعمال، وSIGNATURE للتوقيع، وXML_SCHEMA للبنية. ابنِ منطق توجيهك على هذا الحقل لتختصر زمن التشخيص.

التحذير مقابل الرفض: الفرق الذي يغيّر كل شيء

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

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

الرفض أو الخطأ (error) يعني أن الفاتورة لم تُقبل ولا توجد قانونياً. لا يمكنك تسليمها للعميل كمستند ضريبي معتمد قبل تصحيح الخطأ وإعادة الإرسال. أي عنصر في مصفوفة errorMessages يكفي لرفض الفاتورة بالكامل.

خلاصة عملية: عامل كل error كأولوية قصوى توقف العملية، وعامل كل warning كبند في قائمة مهام التحسين. لا تخلط بينهما في منطق التطبيق لديك.

المقاصة مقابل الإبلاغ: مساران مختلفان لاستجابتين مختلفتين

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

المقاصة (Clearance) تخص الفاتورة الضريبية القياسية بين المنشآت (B2B). هنا ترسل الفاتورة إلى الهيئة قبل تسليمها للمشتري، وتنتظر اعتمادها لحظياً. إن فشلت المقاصة، فلا فاتورة لديك أصلاً لتسلّمها. تفاصيل هذا المسار في صفحة المقاصة (Clearance) في الفاتورة الإلكترونية.

الإبلاغ (Reporting) يخص الفاتورة الضريبية المبسّطة للمستهلك (B2C). هنا تصدر الفاتورة وتسلّمها للعميل فوراً، ثم تبلّغ بها الهيئة خلال 24 ساعة. الفاتورة صالحة عند الإصدار، والإبلاغ خطوة لاحقة. لكن فشل الإبلاغ المتكرر يعرّضك للمساءلة لاحقاً.

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

فئات الأخطاء وصفحاتها المتخصصة

تتوزع أخطاء الفوترة الإلكترونية على فئات واضحة، يقابل كل منها حقل category في رسالة الخطأ. فيما يلي خريطة الفئات الكبرى مع ما تعنيه عملياً.

أخطاء البنية وصيغة XML

هذه الفئة تظهر حين يكون مستند XML نفسه معطوباً أو غير مطابق لمخطط UBL 2.1. أمثلة: حقل إلزامي مفقود، ترتيب عناصر خاطئ، نوع بيانات غير صحيح، أو فضاء أسماء (namespace) ناقص. هذه أخطاء بنيوية تمنع الهيئة من قراءة الفاتورة أصلاً. صفحة أخطاء XML المتخصصة قيد الإعداد وستغطي كل رموز هذه الفئة بالتفصيل.

أخطاء قواعد الأعمال والتحقق

هذه أكثر الفئات شيوعاً. الفاتورة سليمة بنيوياً، لكن قيمها لا تجتاز قواعد الحساب. أشهرها أخطاء سلسلة BR مثل عدم تطابق مجموع البنود مع الإجمالي، أو خطأ في حساب ضريبة القيمة المضافة. قواعد التحقق الكاملة موثّقة في صفحة قواعد التحقق (Validation Rules) للفاتورة، وصفحة أخطاء التحقق المتخصصة قيد الإعداد لربط كل كود بسببه وحله.

أخطاء التوقيع والتجزئة

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

أخطاء المقاصة وأخطاء الإبلاغ والفواتير المرفوضة

تتعلق هذه الفئات بمسار الإرسال نفسه ونتيجته النهائية. أخطاء المقاصة تحدث في مسار B2B قبل التسليم، وأخطاء الإبلاغ في مسار B2C بعد التسليم، أما الفواتير المرفوضة فهي النتيجة النهائية لأي خطأ غير معالج. صفحات هذه الفئات الثلاث (أخطاء المقاصة، أخطاء الإبلاغ، الفواتير المرفوضة) قيد الإعداد، وستربط كل سيناريو رفض بإجراء التصحيح المناسب.

للتعامل البرمجي مع هذه الاستجابات، راجع دليل معالجة الأخطاء (Error Handling) في API، الذي يشرح كيف تلتقط الاستجابة وتفسّر حقولها وتبني منطق إعادة المحاولة.

رموز حالة HTTP مقابل أخطاء التحقق

يخلط كثير من المطورين بين مستويين من الاستجابة: رمز حالة HTTP من جهة، ومحتوى validationResults من جهة أخرى. التمييز بينهما ضروري لبناء منطق تعامل سليم.

رمز حالة HTTP يخبرك هل وصل طلبك إلى الهيئة وعولج تقنياً. أما نتيجة التحقق من الفاتورة فتعيش داخل جسم الاستجابة في validationResults. قد تحصل على رمز نجاح على مستوى HTTP بينما الفاتورة مرفوضة على مستوى التحقق، والعكس وارد أيضاً.

القاعدة العملية: لا تعتمد على رمز HTTP وحده للحكم على قبول الفاتورة. افتح دائماً جسم الاستجابة واقرأ status وerrorMessages. الرمز 200 لا يعني تلقائياً أن فاتورتك مقبولة، بل يعني أن طلبك عولج وأن النتيجة بانتظارك في الجسم.

منطق إعادة المحاولة والتعامل مع الأخطاء المؤقتة

ليست كل الأخطاء أخطاء بيانات. بعضها مؤقت ويتعلق بانقطاع شبكة أو ضغط على خادم الهيئة. التمييز بين الخطأ الدائم والخطأ المؤقت يحدد ما إذا كانت إعادة الإرسال مفيدة أم مضرة.

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

الخطأ المؤقت يتعلق بالاتصال أو بحالة خادم الهيئة، مثل الرمز 500 أو انقطاع المهلة. هنا إعادة المحاولة منطقية، لكن وفق ضوابط:

• منطق التراجع التدريجي (exponential backoff). لا تعد المحاولة فوراً بل بفواصل متزايدة، حتى لا تضغط على الخادم.
• حد أقصى للمحاولات. ضع سقفاً لعدد المحاولات قبل تسجيل الفاتورة للمراجعة اليدوية.
• منع التكرار (idempotency). استخدم المعرّف الفريد للفاتورة (UUID) لضمان عدم إنشاء فاتورتين عند تكرار الإرسال بعد انقطاع غامض.

هذا التمييز جوهري في مسار المقاصة تحديداً. لأن المقاصة لحظية، فانقطاع مؤقت يجب أن يعالَج بإعادة محاولة ذكية، لا بإلغاء المعاملة مع العميل. منطق إعادة المحاولة المفصّل موثّق في دليل معالجة الأخطاء في الـ API.

منهجية تشخيص الخطأ خطوة بخطوة

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

1. اقرأ status. إن كان PASS فالفاتورة مقبولة وانتهى الأمر. إن كان WARNING فهي مقبولة مع ملاحظات. إن كان ERROR فابدأ التصحيح.
2. افحص errorMessages أولاً. تجاهل التحذيرات مؤقتاً وركّز على ما يمنع القبول.
3. التقط حقل code. الكود ثابت ويميّز الخطأ بدقة، بعكس النص الذي قد يتغير. سجّل الكود في نظامك لتتبع تكراره.
4. حدّد category. الفئة ترشدك إلى الطبقة: قاعدة أعمال، توقيع، بنية، أو مسار إرسال.
5. اربط الكود بصفحته المتخصصة. كل كود موثّق في صفحة فئته مع سببه الجذري وخطوات حله.
6. صحّح ثم أعد الإرسال. بعد التصحيح، أعد إرسال الفاتورة وتحقق أن status صار PASS.

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

كيف يساعدك قيود في التعامل مع أخطاء الهيئة

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

• توليد XML متوافق تلقائياً. يبني قيود مستند الفاتورة وفق معيار UBL 2.1 ومواصفة المرحلة الثانية، فينتفي خطأ البنية والصيغة من المنبع.
• إدارة شهادة CSID والتوقيع. يدير قيود معرّف ختم الامتثال (CSID) والتوقيع الرقمي وسلسلة التجزئة تلقائياً، فلا تقلق بشأن انتهاء الشهادة أو انقطاع التسلسل.
• المقاصة اللحظية والإبلاغ خلال 24 ساعة. يرسل قيود الفاتورة الضريبية (B2B) للمقاصة لحظياً، ويبلّغ بالفاتورة المبسّطة (B2C) خلال المهلة النظامية، عبر المسار الصحيح لكل نوع.
• حساب ضريبة القيمة المضافة آلياً. يحسب قيود الضريبة بنسبة 15% على كل معاملة ويطابق مجاميع البنود مع الإجمالي، فيتجنّب أشهر أخطاء قواعد الأعمال.

يبقى عليك تسجيل معرّف الامتثال (CSID) لدى الهيئة مرة واحدة عند البدء، ويرشدك قيود خلال هذه الخطوة. دعم قيود الفني متاح 24 ساعة طوال أيام الأسبوع لمساعدتك إن واجهت أي رسالة خطأ لا تفهمها.

أخطاء شائعة تستحق الانتباه المبكر

بعض الأخطاء تتكرر عند كل من يبدأ التكامل. معرفتها مسبقاً يختصر الطريق.

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

الرقم الضريبي بتنسيق خاطئ. الرقم الضريبي للمنشأة يجب أن يكون 15 رقماً يبدأ وينتهي برقم محدد وفق قاعدة الهيئة. خطأ في عدد الخانات يرفض الفاتورة فوراً.

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

إرسال الفاتورة عبر المسار الخاطئ. إرسال فاتورة B2B عبر مسار الإبلاغ بدل المقاصة (أو العكس) يُنتج أخطاء حالة. تأكد أن نظامك يصنّف نوع الفاتورة بشكل صحيح قبل الإرسال.

التسجيل الأولي ومعرّف الامتثال CSID

كثير من أخطاء التوقيع الأولى لا تتعلق بالفواتير، بل بإعداد معرّف ختم الامتثال (CSID) عند بدء التكامل. هذه الخطوة تتم مرة واحدة، لكن الخطأ فيها يوقف كل الفواتير لاحقاً.

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

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

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

من إصلاح الفاتورة إلى إصلاح النظام

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

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

لذلك يستحق بناء سجل أخطاء داخلي العناء. سجّل كل كود وتاريخه وعدد تكراره، ورتّب الأكواد بحسب التكرار. أعلى الأكواد تكراراً هو أول ما تعالجه، لأن إصلاحه يحقق أكبر أثر. هذه المقاربة تحوّل الأخطاء من إزعاج يومي إلى خريطة تحسين واضحة.

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

الأسئلة الشائعة

ما الفرق بين warningMessages وerrorMessages في استجابة الهيئة؟

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

هل تُعتبر الفاتورة صالحة إذا عاد status بقيمة WARNING؟

نعم. حالة WARNING تعني أن الفاتورة قُبلت ومصفوفة errorMessages فارغة. الفاتورة صالحة قانونياً، والتحذير مجرد ملاحظة على جودة البيانات يُستحسن معالجتها لاحقاً.

ما الفرق بين المقاصة والإبلاغ عند ظهور خطأ؟

المقاصة تخص الفاتورة الضريبية (B2B) وتحدث قبل تسليم الفاتورة للمشتري، فخطؤها يوقف المعاملة فوراً. الإبلاغ يخص الفاتورة المبسّطة (B2C) ويحدث خلال 24 ساعة بعد الإصدار، فخطؤه لا يبطل فاتورة صدرت أصلاً لكنه يستوجب المعالجة.

لماذا يجب أن أعتمد على حقل code لا على النص؟

حقل code ثابت ويميّز الخطأ بدقة، بينما النص الوصفي في message قد يصاغ بطرق مختلفة أو يتغير. اربط منطق نظامك بالكود لتضمن تشخيصاً مستقراً وتتبعاً دقيقاً لتكرار كل خطأ.

ما أكثر أخطاء قواعد الأعمال شيوعاً؟

عدم تطابق مجموع صافي البنود مع إجمالي الفاتورة قبل الضريبة، وأخطاء حساب ضريبة القيمة المضافة بنسبة 15%، والرقم الضريبي بتنسيق غير صحيح. توحيد منطق التقريب والتحقق من التنسيق يمنع معظمها.

هل يعفيني قيود من التعامل مع هذه الأخطاء؟

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