نموذج استجابة API (Sample Response)

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

هذا المرجع موجّه لفرق التطوير التي تتكامل مع الفاتورة الإلكترونية من قيود أو تبني تكاملها الخاص مع منصة فاتورة التابعة لهيئة الزكاة والضريبة والجمارك (ZATCA). نشرح بنية الاستجابة حقلًا حقلًا، ونعرض ثلاثة نماذج كاملة: فاتورة مقبولة (CLEARED)، فاتورة مقبولة مع تحذير (CLEARED مع WARNING)، وفاتورة مرفوضة (ERROR برمز 422). كل نموذج مشروح بالعربية مع توضيح دلالة كل حقل.

ما المقصود باستجابة الـ API؟

عندما يرسل نظامك فاتورة إلى منصة فاتورة، ترد المنصة برسالة منظّمة بصيغة JSON. هذه الرسالة هي «الاستجابة» (Response). تحمل الاستجابة ثلاث معلومات أساسية: حالة الفاتورة، نتائج التحقق التفصيلية، ونسخة الفاتورة المعتمدة إن قُبلت.

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

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

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

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

• status: الحالة العامة للفاتورة. قيمها الشائعة: CLEARED (معتمدة)، REPORTED (مبلَّغة)، NOT_CLEARED (لم تُعتمد)، ERROR (مرفوضة لخطأ بنيوي).
• validationResults: كائن يحوي نتائج التحقق التفصيلية. بداخله ثلاث قوائم: infoMessages (رسائل معلوماتية)، warningMessages (تحذيرات لا تمنع الاعتماد)، وerrorMessages (أخطاء تمنع الاعتماد).
• clearedInvoice: نسخة الفاتورة المعتمدة بصيغة Base64 (XML موقّع). تظهر فقط عند الاعتماد الناجح عبر واجهة المقاصة.
• reportingStatus أو clearanceStatus: الحالة النهائية للعملية حسب الواجهة (إبلاغ أم مقاصة).

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

فهم القوائم الثلاث داخل validationResults

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

• infoMessages (رسائل معلوماتية): رسائل إيجابية أو محايدة تخبرك أن قاعدة تحقق معيّنة نجحت. مثالها الأشهر تأكيد توافق الفاتورة مع معيار UBL 2.1. وجود رسائل هنا لا يعني وجود مشكلة، بل يعني أن المنصة فحصت هذا الجانب ووجدته سليمًا. لا تبنِ منطق رفض عليها.
• warningMessages (تحذيرات): ملاحظات لا تمنع الاعتماد لكنها تستحق المراجعة. الفاتورة تمرّ، لكن المنصة تنبّهك إلى أمر قد يصبح مشكلة لاحقًا. تعامل معها كقائمة مهام مؤجّلة لا كحاجز.
• errorMessages (أخطاء مانعة): هذه هي القائمة الحاسمة. أي عنصر فيها يعني رفض الفاتورة. إذا كانت غير فارغة، فالفاتورة لم تُعتمد مهما بدت بقية الحقول. اجعل فحص هذه القائمة أول خطوة في معالجك.

كل عنصر في هذه القوائم يحمل البنية نفسها: type (نوع الرسالة)، code (رمز القاعدة)، category (فئة القاعدة مثل KSA أو EN16931)، message (وصف نصي)، وstatus (حالة هذه القاعدة تحديدًا). الرمز code هو مفتاحك لبناء جدول داخلي يترجم كل رمز إلى رسالة عربية مفهومة لمستخدمك.

فئات قواعد التحقق (category)

حقل category يخبرك من أين جاءت القاعدة التي طُبّقت. معرفة الفئة تساعدك على فهم طبيعة الخطأ بسرعة:

• XSD validation: تحقق من بنية ملف XML نفسه ومطابقته للمخطط (Schema). أخطاء هذه الفئة بنيوية بحتة، مثل حقل ناقص أو ترتيب عناصر خاطئ.
• EN16931: قواعد المعيار الأوروبي للفوترة الإلكترونية الذي بُنيت عليه مواصفات الهيئة. أغلب القواعد الحسابية والمنطقية تنتمي لهذه الفئة.
• KSA: قواعد خاصة بالمملكة أضافتها الهيئة فوق المعيار الأساسي، مثل متطلبات الرقم الضريبي المحلي أو حقول العنوان الوطني.

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

رموز حالة HTTP في استجابات منصة فاتورة

قبل قراءة جسم الاستجابة (Body)، انظر إلى رمز حالة HTTP في الترويسة (Header). هذا الرمز يخبرك بالنتيجة العامة قبل تحليل التفاصيل.

• 200 OK: العملية نجحت والفاتورة اعتُمدت أو بُلِّغت. اقرأ جسم الاستجابة لاستخراج النسخة المعتمدة.
• 202 Accepted: قُبلت العملية لكن مع وجود تحذيرات. الفاتورة معتمدة، لكن راجع قائمة warningMessages لتصحيح ما يلزم في الفواتير القادمة.
• 400 Bad Request: خطأ في صيغة الطلب نفسه قبل وصوله لمنطق التحقق.
• 401 Unauthorized: مشكلة في المصادقة. تحقق من شهادتك أو من رمز الدخول.
• 422 Unprocessable Entity: الطلب صحيح بنيويًا لكن فشل التحقق الموضوعي. هذه أكثر حالة تحتاج معالجتها برمجيًا. تجد التفاصيل في errorMessages.
• 500 Internal Server Error: خطأ في خدمة المنصة. أعد المحاولة لاحقًا.

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

النموذج الأول: استجابة فاتورة معتمدة (CLEARED)

هذه هي الحالة المثالية. أرسلت فاتورة أعمال (B2B) عبر واجهة المقاصة، اجتازت كل قواعد التحقق، فأعادت المنصة الفاتورة معتمدة وموقّعة. رمز HTTP هنا 200.

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

شرح الحقول:

• validationResults.status = “PASS”: كل قواعد التحقق نجحت. هذه هي الإشارة الأهم للنجاح الكامل.
• infoMessages: رسالة معلوماتية واحدة تؤكد توافق الفاتورة مع معيار UBL 2.1 ومواصفات الهيئة. هذه ليست خطأ ولا تحذيرًا، بل تأكيد إيجابي.
• warningMessages = []: قائمة فارغة، أي لا تحذيرات. ممتاز.
• errorMessages = []: قائمة فارغة، أي لا أخطاء. الفاتورة نظيفة تمامًا.
• clearedInvoice: هذا هو الناتج الذهبي. سلسلة Base64 تحوي ملف XML الموقّع للفاتورة المعتمدة. فُكّ ترميزها لتحصل على النسخة الرسمية التي تحمل الختم المشفّر ورمز QR.
• clearanceStatus = “CLEARED”: تأكيد نهائي أن الفاتورة اعتُمدت من الهيئة، ويمكنك الآن تسليمها للمشتري.

منطق التعامل في نظامك: إذا كان clearanceStatus = "CLEARED" وerrorMessages فارغة، احفظ clearedInvoice كنسخة رسمية، وعلّم الفاتورة في قاعدة بياناتك بأنها معتمدة، وأرسلها للمشتري.

لاحظ أن استجابة واجهة الإبلاغ (Reporting API) لفواتير المستهلك (B2C) تشبه هذا النموذج، لكن بدل clearedInvoice وclearanceStatus تجد الحقل reportingStatus = "REPORTED". السبب أن فواتير المستهلك تُبلَّغ بعد إصدارها لا تُعتمد قبله، فلا تعيد المنصة نسخة معتمدة جديدة.

كيف تقرأ النسخة المعتمدة (clearedInvoice)

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

العناصر التي تضيفها المنصة في النسخة المعتمدة:

• الختم المشفّر (Cryptographic Stamp): توقيع رقمي يثبت أن الفاتورة مرّت عبر الهيئة واعتُمدت. لا يمكن تزويره أو تعديله بعد الاعتماد.
• المعرّف الفريد (UUID): رقم تعريف فريد لهذه الفاتورة تحديدًا، يضمن عدم تكرارها.
• رمز الاستجابة السريعة (QR Code): رمز يحوي بيانات الفاتورة وتوقيعها، يُطبع على نسخة المشتري.
• تجزئة الفاتورة السابقة (Hash): قيمة تربط هذه الفاتورة بالتي قبلها لتكوين سلسلة سلامة لا تنكسر.

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

النموذج الثاني: استجابة معتمدة مع تحذير (CLEARED مع WARNING)

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

{
  "validationResults": {
    "infoMessages": [
      {
        "type": "INFO",
        "code": "XSD_ZATCA",
        "category": "XSD validation",
        "message": "Complied with UBL 2.1 standards in line with ZATCA specifications",
        "status": "PASS"
      }
    ],
    "warningMessages": [
      {
        "type": "WARNING",
        "code": "BR-KSA-F-06",
        "category": "KSA",
        "message": "The buyer identification (BT-46) is recommended but missing",
        "status": "WARNING"
      }
    ],
    "errorMessages": [],
    "status": "WARNING"
  },
  "clearedInvoice": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEludm9pY2U...",
  "clearanceStatus": "CLEARED"
}

شرح الحقول:

• validationResults.status = “WARNING”: الحالة العامة تحذير، لا خطأ. الفرق المهم: الفاتورة اعتُمدت رغم التحذير.
• warningMessages: قائمة فيها تحذير واحد. الرمز BR-KSA-F-06 والرسالة توضح أن معرّف المشتري (BT-46) موصى به لكنه مفقود. هذا مسموح لكنه غير مثالي.
• errorMessages = []: لا أخطاء مانعة. لهذا اعتُمدت الفاتورة.
• clearedInvoice: موجود. الفاتورة المعتمدة عادت كاملة رغم التحذير.
• clearanceStatus = “CLEARED”: معتمدة فعلًا.

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

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

النموذج الثالث: استجابة فاتورة مرفوضة (ERROR برمز 422)

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

{
  "validationResults": {
    "infoMessages": [],
    "warningMessages": [],
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "BR-KSA-EN16931-08",
        "category": "EN16931",
        "message": "The VAT category tax amount does not match the calculated value",
        "status": "ERROR"
      },
      {
        "type": "ERROR",
        "code": "BR-CO-15",
        "category": "EN16931",
        "message": "Invoice total amount with VAT (BT-112) does not equal the sum of lines plus VAT",
        "status": "ERROR"
      }
    ],
    "status": "ERROR"
  },
  "clearedInvoice": null,
  "clearanceStatus": "NOT_CLEARED"
}

شرح الحقول:

• validationResults.status = “ERROR”: الحالة العامة خطأ. الفاتورة مرفوضة.
• errorMessages: قائمة فيها خطآن. الأول BR-KSA-EN16931-08: مبلغ الضريبة في فئة الضريبة لا يطابق القيمة المحسوبة. الثاني BR-CO-15: إجمالي الفاتورة شامل الضريبة لا يساوي مجموع البنود زائد الضريبة. كلاهما خطأ حسابي في الفاتورة.
• infoMessages وwarningMessages فارغتان: لأن التحقق توقّف عند الأخطاء المانعة.
• clearedInvoice = null: لا توجد نسخة معتمدة، لأن الفاتورة لم تُعتمد أصلًا.
• clearanceStatus = “NOT_CLEARED”: تأكيد صريح أن الفاتورة لم تُعتمد.

منطق التعامل في نظامك: عند رمز 422 وstatus = "ERROR"، لا تسلّم الفاتورة للمشتري. اقرأ كل عنصر في errorMessages، اعرض رسالة واضحة للمستخدم تشرح كل خطأ بالعربية، صحّح الفاتورة، ثم أعد الإرسال. لكل رمز خطأ دلالة محددة تساعدك على توجيه التصحيح بدقة.

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

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

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

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

الخلاصة: منطق قراءة validationResults واحد في الواجهتين. الاختلاف فقط في اسم حقل الحالة النهائية، وفي وجود النسخة المعتمدة من عدمه. ابنِ معالجك ليفحص الحقلين clearanceStatus وreportingStatus معًا حتى يعمل مع الواجهتين.

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

حين تظهر فاتورة مرفوضة برمز 422، يكون رمز الخطأ (code) هو دليلك للتصحيح. بناء جدول داخلي يربط كل رمز برسالة عربية واضحة يحوّل تجربة مستخدمك من إحباط إلى توجيه عملي. إليك أبرز الفئات التي ستواجهها:

• أخطاء حسابية (EN16931): عدم تطابق مبلغ الضريبة المحسوب مع المصرّح، أو اختلاف إجمالي الفاتورة عن مجموع البنود زائد الضريبة. سببها غالبًا تقريب الكسور أو ترتيب عمليات الحساب. الحل: وحّد منطق التقريب قبل الإرسال، واحسب الضريبة على مستوى البند ثم اجمع.
• أخطاء الرقم الضريبي (KSA): رقم ضريبي مفقود أو بصيغة غير صحيحة للبائع أو المشتري في فواتير الأعمال. الحل: تحقق من طول الرقم الضريبي وصحته قبل بناء الفاتورة.
• أخطاء بنيوية (XSD validation): حقل إلزامي مفقود في ملف XML أو ترتيب عناصر خاطئ. الحل: راجع مولّد XML لديك ليطابق مخطط UBL 2.1 بدقة.
• أخطاء التوقيت والتسلسل: تاريخ إصدار غير منطقي أو كسر في سلسلة التجزئة بين الفواتير. الحل: تأكد أن كل فاتورة تحمل تجزئة الفاتورة السابقة بترتيب صحيح.

القاعدة الحاكمة: لا تعرض رمز الخطأ الخام للمستخدم النهائي. ترجمه إلى جملة عربية تقول له ماذا حدث وما الإجراء. مثال: بدل عرض BR-CO-15، اعرض «إجمالي الفاتورة لا يطابق مجموع البنود مع الضريبة، راجع المبالغ». هذا الفرق بين نظام يربك المستخدم ونظام يساعده.

دورة حياة الفاتورة من الطلب إلى الاستجابة

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

• الإنشاء: ينشئ نظامك الفاتورة بصيغة XML بمعيار UBL 2.1، ويضيف الحقول الإلزامية والختم الأولي.
• الإرسال: يرسل نظامك الطلب إلى منصة فاتورة عبر واجهة المقاصة (B2B) أو الإبلاغ (B2C).
• التحقق: تفحص المنصة الفاتورة ضد قواعد XSD وEN16931 وKSA، وتبني قوائم الرسائل الثلاث.
• الاستجابة: تعيد المنصة الـ JSON الذي يحوي status وvalidationResults وclearedInvoice (عند الاعتماد).
• المعالجة: يقرأ نظامك الاستجابة، ويقرر: اعتماد وحفظ، أم تسجيل تحذير، أم رفض وتصحيح.

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

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

أفضل الممارسات في قراءة الاستجابة

قراءة الاستجابة بشكل سليم تحميك من أخطاء صامتة قد تسبب مشاكل ضريبية لاحقًا. إليك ممارسات عملية:

• افحص errorMessages أولًا: إذا كانت غير فارغة، فالفاتورة مرفوضة مهما كانت بقية الحقول. لا تكتفِ بقراءة status العام.
• سجّل كل استجابة كاملة: احفظ نص JSON الكامل في سجلّ نظامك. عند أي نزاع أو مراجعة، هذا السجلّ هو إثباتك.
• فُكّ ترميز clearedInvoice وخزّنه: النسخة المعتمدة هي المرجع الرسمي، لا الفاتورة التي أرسلتها أنت. احفظ XML الموقّع.
• عالج التحذيرات دوريًا: لا توقف العمليات عند التحذير، لكن اجمع التحذيرات وراجعها أسبوعيًا لتصحيح مصدرها.
• أعد المحاولة بذكاء: رموز 500 تُعاد محاولتها لاحقًا، أما 422 فلا تُعاد إلا بعد تصحيح الفاتورة فعليًا. إعادة إرسال فاتورة خاطئة كما هي لن تنجح.

كيف تبني معالج استجابة موثوقًا

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

• الخطوة الأولى: افحص رمز HTTP. إذا كان 500 أو 503، فالمشكلة في الخدمة لا في فاتورتك، فأعد المحاولة لاحقًا ضمن سياسة إعادة محاولة محددة. إذا كان 401، فأوقف العملية وتحقق من المصادقة.
• الخطوة الثانية: افحص errorMessages. إن لم تكن فارغة، فالفاتورة مرفوضة. اجمع كل رسائلها، ترجمها للعربية، اعرضها للمستخدم، ووسم الفاتورة بأنها بحاجة تصحيح. لا تتقدّم خطوة أخرى.
• الخطوة الثالثة: افحص حالة الاعتماد. اقرأ clearanceStatus أو reportingStatus. القيمة CLEARED أو REPORTED تعني نجاحًا. القيمة NOT_CLEARED تعني رفضًا حتى لو لم تظهر رسائل خطأ صريحة.
• الخطوة الرابعة: عالج التحذيرات. إن وُجدت warningMessages مع اعتماد ناجح، فاعتمد الفاتورة وسجّل التحذيرات في سجلّ منفصل للمراجعة الدورية. لا توقف العملية بسببها.
• الخطوة الخامسة: استخرج النسخة المعتمدة. إن وُجد clearedInvoice، فُكّ ترميز Base64، احفظ ملف XML الموقّع، واربطه بسجلّ الفاتورة في قاعدة بياناتك.
• الخطوة السادسة: سجّل كل شيء. احفظ نص JSON الكامل للاستجابة بطابعه الزمني. هذا السجلّ مرجعك عند أي مراجعة لاحقة.

الالتزام بهذا التسلسل يجعل معالجك متوقّع السلوك وقابلًا للاختبار. اختبره ضد النماذج الثلاثة في هذا الدليل: مرّر له استجابة CLEARED فيحفظ النسخة، واستجابة WARNING فيعتمد ويسجّل، واستجابة 422 فيرفض ويصحّح. إن تصرّف بشكل صحيح في الحالات الثلاث، فمنطقك سليم.

أخطاء شائعة في بناء المعالج

هذه أخطاء تتكرر عند فرق التطوير الجديدة على التكامل، تجنّبها من البداية:

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

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

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

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

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

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

ما الفرق بين CLEARED وREPORTED في الاستجابة؟

CLEARED تعني أن فاتورة الأعمال (B2B) اعتُمدت لحظيًا عبر واجهة المقاصة قبل تسليمها للمشتري. REPORTED تعني أن فاتورة المستهلك (B2C) بُلِّغت للهيئة بعد إصدارها عبر واجهة الإبلاغ. الأولى تعيد نسخة معتمدة، والثانية لا تعيدها.

ماذا أفعل إذا كانت الاستجابة WARNING؟

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

لماذا أحصل على رمز 422 رغم أن فاتورتي تبدو صحيحة؟

رمز 422 يعني فشل التحقق الموضوعي لا الشكلي. الأسباب الشائعة أخطاء حسابية: تقريب خاطئ، عدم تطابق نسبة الضريبة 15% مع المبلغ، أو خطأ في جمع البنود. اقرأ errorMessages لمعرفة الخطأ بدقة.

أين أجد النسخة المعتمدة من الفاتورة؟

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

هل يجب أن أحفظ كامل نص الاستجابة؟

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

كيف أفرّق برمجيًا بين فاتورة مقبولة وأخرى مرفوضة؟

افحص errorMessages أولًا: إذا كانت غير فارغة فالفاتورة مرفوضة. ثم افحص clearanceStatus أو reportingStatus: قيمة CLEARED أو REPORTED تعني النجاح، وNOT_CLEARED تعني الرفض. لا تكتفِ بقراءة رمز HTTP وحده.