أخطاء المقاصة (Clearance Errors)

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

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

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

كيف يعمل مسار المقاصة، ولماذا تختلف أخطاؤه

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

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

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

قراءة استجابة المقاصة

الحقل الحاسم في كل استجابة هو clearanceStatus. القيمة CLEARED تعني أن الفاتورة قُبلت وخُتمت، وستجد نسختها المختومة في clearedInvoice. القيمة NOT_CLEARED تعني الرفض، ولن تجد فاتورة مختومة. إلى جانب ذلك تأتي قائمة validationResults التي تفصّل رسائل الأخطاء والتحذيرات. هذه البنية ثابتة، وفهمها يختصر نصف وقت التشخيص.

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

1. رفض الفاتورة في المقاصة (NOT_CLEARED)

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

العَرَض. الاستجابة تحمل clearanceStatus بقيمة NOT_CLEARED، والحقل clearedInvoice فارغ أو غير موجود، وقائمة errorMessages مليئة برسائل تشرح القاعدة التي انكسرت. كود حالة HTTP غالباً 303 أو 400 بحسب نوع الفشل.

المثال التالي استجابة فعلية لفاتورة رُفضت في المقاصة بسبب عدم تطابق مبلغ الضريبة المحسوب مع نسبة 15%:

{
  "clearanceStatus": "NOT_CLEARED",
  "clearedInvoice": null,
  "validationResults": {
    "status": "ERROR",
    "warningMessages": [],
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "BR-KSA-EN16931-09",
        "category": "EN_16931",
        "message": "The VAT category tax amount does not equal the taxable amount multiplied by the VAT rate."
      }
    ]
  }
}

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

أمثلة شائعة لرسائل الرفض في المقاصة

• رقم تسجيل ضريبي غير صالح. الرقم الضريبي للبائع أو المشتري لا يتبع تنسيق الهيئة المكوّن من 15 رقماً يبدأ وينتهي بالرقم 3.
• عدم توازن إجمالي الفاتورة. مجموع البنود مع الضريبة لا يساوي المبلغ الإجمالي المعلن في الفاتورة.
• حقل إلزامي مفقود. غياب عنوان البائع أو تاريخ الإصدار أو معرّف العملة في الموضع الذي تتطلبه المواصفة.
• نوع فاتورة خاطئ للمسار. إرسال فاتورة مبسّطة (B2C) إلى نقطة المقاصة بدلاً من مسار الإبلاغ.

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

2. فاتورة مقبولة مع تحذير (CLEARED مع warningMessages)

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

العَرَض. clearanceStatus بقيمة CLEARED، وحقل clearedInvoice يحمل الفاتورة المختومة فعلاً، لكن قائمة warningMessages غير فارغة. الخطأ الشائع هنا أن يعامل النظام التحذير معاملة الرفض، فيوقف فاتورة سليمة بلا سبب.

{
  "clearanceStatus": "CLEARED",
  "clearedInvoice": "PHN1Ymxxxx...base64-signed-xml...",
  "validationResults": {
    "status": "WARNING",
    "errorMessages": [],
    "warningMessages": [
      {
        "type": "WARNING",
        "code": "BR-KSA-EN16931-08",
        "category": "EN_16931",
        "message": "Buyer address is recommended but missing"
      }
    ]
  }
}

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

3. رفض التوقيع أو التجزئة أثناء المقاصة

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

العَرَض. الاستجابة NOT_CLEARED، ورسائل الخطأ تذكر invalid signature أو invalid certificate أو hash mismatch أو previous invoice hash. الفاتورة لا تُختم ولا تُسلَّم.

{
  "clearanceStatus": "NOT_CLEARED",
  "clearedInvoice": null,
  "validationResults": {
    "status": "ERROR",
    "warningMessages": [],
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "signing-error",
        "category": "SIGNATURE",
        "message": "Invoice signature is invalid or certificate (CSID) has expired."
      }
    ]
  }
}

الحل. ابدأ بالتحقق من صلاحية شهادة التشغيل CSID وتاريخ انتهائها. شهادة التشغيل (Compliance Cryptographic Stamp Identifier) هي الهوية المشفّرة التي تختم بها فواتيرك، ولها مدة صلاحية يجب تجديدها قبل انتهائها. إذا كانت الشهادة سارية، فتحقق من أن قيمة تجزئة الفاتورة السابقة في سلسلة التجزئة مطابقة لما تتوقعه الهيئة، لأن أي فجوة في التسلسل تكسر السلسلة. انتبه أيضاً إلى أن التوقيع يجب أن يُحسب على المحتوى النهائي للفاتورة، فأي تعديل بعد التوقيع يبطله. في قيود تُدار شهادة CSID وتُجدَّد دورتها وتُبنى سلسلة التجزئة تلقائياً، فتختفي هذه الفئة من الأخطاء عملياً.

4. انتهاء المهلة دون استجابة من المقاصة

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

العَرَض. طلب المقاصة لا يعيد جسم استجابة مكتملاً، بل ينتهي بمهلة زمنية (timeout) أو خطأ شبكة، أو يعود بكود حالة من فئة 5xx يدل على عطل مؤقت في الخدمة.

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

5. تسليم الفاتورة قبل اكتمال المقاصة

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

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

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

التسلسل الصحيح لمسار المقاصة

6. حالة Clearance-Status خاطئة أو متناقضة

تُعيد منصة فاتورة في رأس الاستجابة ترويسة باسم Clearance-Status توجز نتيجة المقاصة، إلى جانب الحقل clearanceStatus داخل جسم الاستجابة. أحياناً يحدث لبس عندما يقرأ النظام مصدراً ويهمل الآخر، أو عندما يفسّر قيمة غير متوقعة في هذه الترويسة على أنها نجاح. النتيجة قرار خاطئ بشأن الفاتورة: تسليم ما لم يُختم، أو حجب ما خُتم.

العَرَض. تناقض ظاهري بين ما تقرؤه من الترويسة Clearance-Status وما يحمله جسم الاستجابة، أو قيمة في الترويسة لا يتعامل معها النظام صراحة فيقع في سلوك افتراضي خاطئ.

الحل. اجعل القرار النهائي مبنياً على الحقل clearanceStatus داخل جسم الاستجابة، وتعامل مع الترويسة Clearance-Status كمؤشر سريع فقط. تعامل صراحة مع القيمتين المعروفتين CLEARED وNOT_CLEARED، وأي قيمة أخرى غير متوقعة عاملها كحالة فشل تستوجب التوقف والاستعلام، لا كنجاح ضمني. هذا المبدأ يحميك من أخطر الأخطاء: تسليم فاتورة بناءً على تفسير خاطئ لحالة لم تُختم فعلاً.

أكواد الرفض الأكثر تكراراً في المقاصة

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

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

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

اختبر في بيئة التجربة قبل الإنتاج

أغلب أخطاء المقاصة المفاجئة في الإنتاج كان يمكن اكتشافها مبكراً في بيئة التجربة (sandbox) التي توفّرها منصة فاتورة. الانتقال المباشر إلى الإنتاج دون اختبار كافٍ يحوّل كل خطأ إلى فاتورة معطّلة أمام عميل حقيقي. لذلك ابنِ خط تكاملك على مرحلتين واضحتين.

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

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

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

عندما يصلك خطأ في المقاصة، لا تبدأ بالتخمين. اتبع تسلسلاً ثابتاً يوصلك إلى السبب بأقل وقت.

• اقرأ clearanceStatus أولاً. CLEARED يعني نجاحاً حتى مع التحذيرات. NOT_CLEARED يعني رفضاً يستوجب إصلاحاً. أي قيمة أخرى تعامل معها كفشل وتوقف.
• افصل الخطأ عن التحذير. errorMessages تحجب الفاتورة، وwarningMessages لا تحجبها. لا تخلط بينهما في منطق نظامك.
• اقرأ الحقل code لا الرسالة فقط. الكود يحدد القاعدة المكسورة بدقة، والرسالة شرح بشري قد يتغيّر.
• حدّد الطبقة. هل الخطأ في التوقيع والشهادة، أم في قواعد العمل، أم في المسار نفسه؟ كل طبقة لها حل مختلف.
• أصلح ثم وقّع من جديد. أي تعديل على محتوى الفاتورة يلغي التوقيع السابق ويستوجب توقيعاً جديداً قبل إعادة الإرسال.

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

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

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

كيف يساعدك قيود في تجاوز أخطاء المقاصة

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

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

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

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

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

ما الفرق بين CLEARED وNOT_CLEARED؟ CLEARED يعني أن الهيئة قبلت الفاتورة وختمتها، وتجد نسختها المختومة في الحقل clearedInvoice، فيحق لك تسليمها للمشتري. NOT_CLEARED يعني الرفض، ولا توجد فاتورة مختومة، ويلزمك إصلاح السبب وإعادة التوقيع والإرسال.

هل أسلّم الفاتورة إذا عادت CLEARED مع تحذيرات؟ نعم. التحذيرات في warningMessages لا تحجب التسليم. ما دامت الحالة CLEARED والفاتورة مختومة في clearedInvoice، سلّمها وسجّل التحذير لمعالجته لاحقاً.

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

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

هل يجوز تسليم الفاتورة للمشتري قبل المقاصة؟ لا. فاتورة الأعمال (B2B) لا تُسلَّم قبل ختم الهيئة. التسليم المبكّر يعني مستنداً غير قانوني. اجعل خطوة التسليم مشروطة بحالة CLEARED دائماً.

أين أقرأ الحالة النهائية للمقاصة؟ اعتمد على الحقل clearanceStatus داخل جسم الاستجابة كمصدر القرار، وعامل الترويسة Clearance-Status كمؤشر سريع فقط. أي قيمة غير CLEARED أو NOT_CLEARED عاملها كفشل يستوجب الاستعلام.