واجهة المقاصة Clearance API

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

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

تُصدر هيئة الزكاة والضريبة والجمارك (ZATCA) متطلبات الفوترة الإلكترونية، ومنصة فاتورة هي البوابة الفنية التي تستقبل الفواتير. كل ما سيرد هنا يتبع مواصفة المرحلة الثانية (الربط والتكامل) ومعيار UBL 2.1.

ما المقصود باستدعاء المقاصة؟

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

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

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

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

متى تستدعي Clearance ومتى تستدعي Reporting؟

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

نقطة النهاية والمتطلبات الأساسية

نقطة النهاية الخاصة بمقاصة فاتورة واحدة هي:

POST /invoices/clearance/single

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

قبل الاستدعاء تحتاج ثلاثة عناصر جاهزة:

• معرّف الختم المشفر (CSID): المعرّف الذي حصلت عليه من منصة فاتورة بعد إكمال مسار التسجيل. ينقسم إلى CSID للامتثال (للاختبار) وCSID للإنتاج (للفواتير الحيّة).
• فاتورة XML صالحة: مبنية وفق UBL 2.1 وموقّعة بالختم المشفّر، تحتوي على عدّاد الفاتورة (ICV) وبصمة الفاتورة السابقة (سلسلة التحقق).
• بصمة الفاتورة (invoiceHash): قيمة SHA-256 للفاتورة بعد تقييسها (canonicalization).

ملاحظة مهمة حول الاسم: الاختصار الصحيح هو CSID (معرّف الختم المشفّر)، وليس أي ترتيب آخر للأحرف. الخلط في ترتيب الحروف من أكثر أخطاء التكامل شيوعًا.

الحصول على معرّف الختم قبل أول استدعاء

لا يمكنك استدعاء المقاصة قبل أن تملك معرّف ختم صالحًا. مسار الحصول عليه يمرّ بخطوات محدّدة في منصة فاتورة. تبدأ بتوليد طلب توقيع شهادة (CSR) للجهاز أو المنشأة، ثم ترسله عبر بوابة فاتورة مرفقًا برمز تحقق لمرة واحدة (OTP) يحصل عليه المكلّف من حسابه.

بعد ذلك تستلم معرّف الختم للامتثال (Compliance CSID). هذا المعرّف يفتح لك واجهات الامتثال في بيئة الاختبار فقط. تستخدمه لإرسال فواتير تجريبية تغطّي الحالات المطلوبة: فاتورة معيارية، فاتورة مبسّطة، إشعار دائن، وإشعار مدين. عند اجتياز هذه الفحوص تستلم معرّف الإنتاج (Production CSID)، وهو الذي يوقّع كل فاتورة حيّة لاحقًا.

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

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

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

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

الترويسات المطلوبة (Headers)

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

الترويسة Authorization تتبع مخطط Basic القياسي: تأخذ معرّف الختم المشفّر وسرّه، تدمجهما بنقطتين، ترمّز الناتج بـ Base64، ثم تسبقه بكلمة Basic. الترويسة Clearance-Status تميّز بين طلب المقاصة الكامل والفحص فقط، لذا تأكّد من تمرير القيمة 1 في الإنتاج.

مثال على الترويسات الكاملة

POST /invoices/clearance/single HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
Authorization: Basic VFNUMDIxMjM0NTY3ODk6c2VjcmV0X3ZhbHVl
Accept-Version: V2
Clearance-Status: 1
Content-Type: application/json
Accept-Language: ar

القيمة في ترويسة المصادقة أعلاه مجرّد مثال توضيحي مُرمّز بـ Base64. استبدلها بقيمة معرّف الختم المشفّر الفعلي الخاص بك.

جسم الطلب (Request Body)

جسم الطلب كائن JSON بثلاثة حقول إلزامية. كل حقل له دور محدّد في عملية التحقق:

{
  "invoiceHash": "NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzk=",
  "uuid": "3cf5ee18-ee25-44ea-a444-2c37ba7f28be",
  "invoice": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."
}

تفصيل كل حقل:

• invoiceHash: بصمة الفاتورة، وهي قيمة SHA-256 محسوبة على نسخة XML بعد تقييسها وفق قواعد التقييس المعتمدة. أي اختلاف بسيط في المحتوى يغيّر البصمة، لذا احسبها على النسخة النهائية الموقّعة بالضبط.
• uuid: المعرّف الفريد للفاتورة بصيغة UUID النسخة الرابعة. يجب أن يطابق المعرّف الموجود داخل الفاتورة نفسها. تكراره عبر فواتير مختلفة يسبب الرفض.
• invoice: فاتورة XML الكاملة بعد ترميزها بـ Base64. هذا هو المحتوى الفعلي الذي ستفحصه الهيئة وتضيف ختمها عليه.

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

كيف تبني حقل invoice المرمّز؟

الخطوات بالترتيب: ابنِ فاتورة XML وفق UBL 2.1، أضف عدّاد الفاتورة وبصمة الفاتورة السابقة، وقّع الفاتورة بالختم المشفّر، احسب بصمة SHA-256 على النسخة المقيّسة، ثم رمّز XML النهائي بـ Base64. الناتج هو قيمة الحقل invoice، والبصمة هي قيمة الحقل invoiceHash.

انتبه إلى الترتيب: التوقيع أولًا، ثم حساب البصمة، ثم الترميز. عكس الترتيب ينتج بصمة لا تطابق المحتوى المرسَل فتُرفض الفاتورة.

أهم الحقول داخل فاتورة XML المعيارية

الفاتورة التي ترسلها للمقاصة ليست XML عاديًا، بل بنية UBL 2.1 تحوي حقولًا إلزامية تفحصها الهيئة. معرفتها تساعدك على قراءة سبب أي رفض بسرعة:

• عدّاد الفاتورة (ICV): رقم متسلسل تصاعدي عبر كل الفواتير الصادرة من الجهاز. لا يجوز تكراره ولا تجاوز قيمة في التسلسل.
• بصمة الفاتورة السابقة: قيمة تربط الفاتورة الحالية بسابقتها في سلسلة تحقق. أول فاتورة تستخدم قيمة بداية محدّدة في المواصفة.
• المعرّف الفريد (UUID): داخل XML نفسه، ويجب أن يطابق قيمة الحقل uuid في جسم الطلب.
• الختم المشفّر: توقيع ECDSA باستخدام معرّف الختم، يُضاف ضمن قسم التوقيع في الفاتورة.
• رمز الاستجابة السريعة (QR): بصيغة TLV مُرمّزة بـ Base64، يحوي بيانات البائع والفاتورة والتوقيع.
• أرقام التعريف: الرقم الضريبي للبائع والمشتري والسجل التجاري، كلٌّ بصيغته وطوله المحدّدين.

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

الاستجابة عند المصادقة الناجحة

عند نجاح المقاصة، تُعيد منصة فاتورة رمز الحالة 200 مع كائن يحتوي على الفاتورة المُصادَق عليها ونتائج الفحص. الفاتورة المُصادَقة تحمل ختم الهيئة، وهي النسخة التي تُسلَّم للمشتري:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "validationResults": {
    "infoMessages": [
      {
        "type": "INFO",
        "code": "XSD_ZATCA_VALID",
        "category": "XSD validation",
        "message": "Complied with UBL 2.1 standards in line with ZATCA specifications",
        "status": "PASS"
      }
    ],
    "warningMessages": [],
    "errorMessages": [],
    "status": "PASS"
  },
  "clearanceStatus": "CLEARED",
  "clearedInvoice": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZ..."
}

أهم حقلين هنا:

• clearedInvoice: الفاتورة المُصادَق عليها بصيغة Base64. فُكّ ترميزها لتحصل على XML النهائي الموقّع من الهيئة. هذه هي النسخة الرسمية التي تُسلَّم للمشتري وتُحفظ.
• clearanceStatus: حالة المقاصة. القيمة CLEARED تعني نجاح المصادقة الكامل. أي قيمة أخرى تستوجب مراجعة نتائج الفحص.

الكائن validationResults يلخّص نتائج الفحص في ثلاث قوائم: رسائل معلوماتية، تحذيرات، وأخطاء، مع حقل status عام. عند المصادقة الكاملة تكون قائمتا التحذيرات والأخطاء فارغتين والحالة PASS.

قراءة التحذيرات والأخطاء

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

المصادقة مع تحذيرات

التحذير لا يمنع المصادقة، لكنه يشير إلى أمر يجب إصلاحه مستقبلًا. تبقى الحالة PASS وتعود clearanceStatus بقيمة CLEARED، لكن قائمة warningMessages تحمل تفاصيل:

{
  "validationResults": {
    "warningMessages": [
      {
        "type": "WARNING",
        "code": "BR-KSA-F-06",
        "category": "KSA",
        "message": "The seller address must contain a valid additional number",
        "status": "WARNING"
      }
    ],
    "errorMessages": [],
    "status": "PASS"
  },
  "clearanceStatus": "CLEARED"
}

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

الرفض بأخطاء

عند وجود خطأ فعلي، تفشل المقاصة. تكون الحالة ERROR وقائمة errorMessages مملوءة، ولا تُعاد فاتورة مُصادَقة:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "validationResults": {
    "warningMessages": [],
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "BR-KSA-F-04",
        "category": "KSA",
        "message": "Invoice hash does not match the submitted invoice",
        "status": "ERROR"
      }
    ],
    "status": "ERROR"
  },
  "clearanceStatus": "NOT_CLEARED"
}

القاعدة الذهبية: لا تُسلّم الفاتورة للمشتري ما لم تعد clearanceStatus بقيمة CLEARED. عند الرفض، صحّح السبب المذكور في رمز الخطأ ورسالته، أعد بناء الفاتورة، ثم أعد الاستدعاء.

رموز الأخطاء الشائعة وأسبابها

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

بعد عشرات عمليات التكامل، تتكرّر الأخطاء نفسها. تجنّبها يوفّر عليك ساعات تصحيح:

• الخلط بين الاختبار والإنتاج: معرّف الختم للامتثال يعمل فقط مع نقاط نهاية الاختبار، ومعرّف الإنتاج فقط مع نقاط الإنتاج. لا تخلط بينهما.
• حساب البصمة قبل التوقيع: البصمة تُحسب على النسخة النهائية الموقّعة. حسابها قبل التوقيع يُنتج قيمة لا تطابق المحتوى المرسَل.
• نسيان Accept-Version: غياب الترويسة أو إرسال قيمة خاطئة يُرجع خطأ إصدار غير مدعوم.
• تجاهل التحذيرات: التحذير اليوم قد يصبح خطأً غدًا. عالجه مبكرًا.
• عدم التعامل مع المهلة الزمنية: استدعاء المقاصة متزامن. اضبط مهلة معقولة وأعد المحاولة عند انتهائها أو عند رمز خادم 502 أو 504.
• عدم تطابق المعرّف الفريد بين الطلب والفاتورة: قيمة uuid في جسم الطلب يجب أن تطابق المعرّف داخل XML حرفيًا. أي اختلاف يسبب الرفض.

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

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

إعادة المحاولة والتعامل مع الانقطاع

لأن استدعاء المقاصة متزامن ويسبق تسليم الفاتورة، عليك التعامل بحذر مع حالات الانقطاع الشبكي. إذا انتهت المهلة الزمنية أو عاد رمز خادم 502 أو 503 أو 504، فالفاتورة لم تُصادَق بعد ويمكن إعادة المحاولة بالطلب نفسه.

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

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

الإشعارات الدائنة والمدينة في المقاصة

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

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

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

اعتبارات الأمان والأداء عند الإنتاج

معرّف الختم المشفّر وسرّه بيانات حسّاسة. احفظهما في خزانة أسرار آمنة، لا في الكود ولا في ملفات الإعدادات المكشوفة. أي تسرّب لهذه القيم يسمح بتوقيع فواتير باسم منشأتك.

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

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

كيف يساعدك قيود في تكامل المقاصة

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

• يولّد فاتورة XML بمعيار UBL 2.1 مع رمز الاستجابة السريعة (QR) والختم المشفّر وسلسلة بصمات الفواتير، جاهزة للمقاصة دون صياغة يدوية للـ XML.
• يدير معرّف الختم المشفّر (CSID) لكل فرع أو جهاز عبر مسار التسجيل في منصة فاتورة، فلا تتعامل يدويًا مع طلبات توقيع الشهادات.
• يتحقّق من صيغة أرقام التعريف لحظيًا (السجل التجاري برقم من 10 خانات، الرقم الضريبي من 10 خانات يبدأ بـ 3، وغيرها) عند الإدخال في إعدادات المنشأة وملفات العملاء والفواتير، ما يلتقط أحد أكثر أسباب التحذيرات شيوعًا قبل الإرسال.
• يدمج XML داخل ملف PDF/A-3 تلقائيًا في فواتير البيع والإشعارات المدينة، فتحصل على ملف واحد يحوي صيغة العرض وصيغة XML معًا، مع بقاء زر تنزيل XML المستقل متاحًا.
• يدير حالتي المقاصة والإبلاغ فيرسل الفواتير المعيارية (B2B) للمقاصة والفواتير المبسّطة (B2C) للإبلاغ خلال 24 ساعة دون أن تختار يدويًا المسار الصحيح.

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

دورة الحياة الكاملة لاستدعاء المقاصة

لنجمع الخطوات في تسلسل واحد تطبّقه في كل فاتورة معيارية:

• 1) البناء: أنشئ فاتورة XML وفق UBL 2.1 مع عدّاد الفاتورة وبصمة الفاتورة السابقة.
• 2) التوقيع: وقّع الفاتورة بالختم المشفّر المرتبط بمعرّف الختم.
• 3) البصمة والترميز: احسب SHA-256 على النسخة المقيّسة، ثم رمّز XML بـ Base64.
• 4) الاستدعاء: أرسل POST إلى نقطة نهاية المقاصة بالترويسات الثلاث وجسم JSON.
• 5) القراءة: افحص clearanceStatus ونتائج الفحص. عند CLEARED استخرج clearedInvoice.
• 6) التسليم: سلّم الفاتورة المُصادَقة للمشتري واحفظها.

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

ربط هذه الصفحة بباقي مركز المطوّرين

إذا أردت الصورة النظرية الكاملة لمفهوم المقاصة وموقعها في رحلة الفاتورة، فابدأ من صفحة المقاصة (Clearance) في الفاتورة الإلكترونية. وإذا أردت استكشاف بقية الواجهات المتاحة في منصة فاتورة (الامتثال، الإبلاغ، إدارة الشهادات)، فراجع صفحة نقاط نهاية API (Endpoints) لمنصة فاتورة. هذه الصفحة الثلاثة معًا تغطّي الجانبين النظري والتطبيقي.

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

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

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

ماذا تعني قيمة Clearance-Status في الترويسة؟

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

لماذا تُرفض الفاتورة برسالة عدم تطابق البصمة؟

السبب الأشيع هو حساب بصمة SHA-256 على نسخة مختلفة عن المحتوى المرسَل فعليًا. تأكّد أنك تحسب البصمة على نسخة XML النهائية بعد التوقيع والتقييس، وأنك ترسل النسخة نفسها في حقل invoice.

هل يجب توليد uuid جديد لكل فاتورة؟

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

ما الفرق بين معرّف الختم للامتثال ومعرّف الإنتاج؟

معرّف الامتثال (Compliance CSID) يُستخدم في بيئة الاختبار لإكمال فحوص الامتثال على فواتير تجريبية. معرّف الإنتاج (Production CSID) يُستخدم في البيئة الحيّة لتوقيع كل فاتورة فعلية. لكل بيئة معرّفها ونقاط نهايتها.

ماذا أفعل إذا انقطع الاتصال أثناء استدعاء المقاصة؟

إذا انتهت المهلة أو عاد رمز خادم 502 أو 503 أو 504، فالفاتورة لم تُصادَق ويمكن إعادة إرسال الطلب نفسه دون تغيير المعرّف الفريد أو البصمة. حافظ على ثبات جسم الطلب بين المحاولات، وحدّ عدد المحاولات بفواصل متزايدة، ثم حوّل الفاتورة لطابور معالجة يدوية إذا استمر الفشل.

هل أرسل الإشعارات الدائنة والمدينة للمقاصة أيضًا؟

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

هل يتولّى قيود استدعاء المقاصة نيابةً عني؟

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