واجهة الإبلاغ Reporting API

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

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

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

متى تستدعي نقطة الإبلاغ؟

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

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

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

الفرق بين الإصدار والإبلاغ في تصميم نظامك

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

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

مبادئ عامة قبل أي طلب إبلاغ

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

أولًا، الطلب يتبع نمط REST فوق HTTPS، ويتبادل بياناته الوصفية بصيغة JSON. الفاتورة نفسها تُحمَل بصيغة XML متوافقة مع UBL 2.1، لكنها تُرسَل مُرمَّزة بـ Base64 داخل حقل JSON اسمه invoice. أي طلب لا يلتزم بهذا الغلاف يُرفض مباشرة دون فحص محتوى الفاتورة.

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

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

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

نقطة النهاية والطريقة

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

# الطريقة والمسار النسبي لنقطة الإبلاغ الفردي
POST /invoices/reporting/single

# يُضاف بعد العنوان الأساسي للبيئة:
# بيئة الاختبار (Sandbox)
https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal/invoices/reporting/single

# بيئة الإنتاج (Production)
https://gw-fatoora.zatca.gov.sa/e-invoicing/core/invoices/reporting/single

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

هل هناك نقطة إبلاغ جماعي؟

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

الترويسات المطلوبة

طلب الإبلاغ يحمل أربع ترويسات أساسية. كل واحدة منها لها دور محدّد، وإهمال أيٍّ منها قد يردّ الطلب على مستوى البوابة قبل أن يصل لمنطق العمل.

• Authorization: مصادقة من نوع Basic. القيمة هي معرّف الختم المشفّر للإنتاج (Production CSID) وكلمة السر المرتبطة به، مدموجين ومُرمَّزين بـ Base64. هذا هو ما يثبت للهيئة هوية الجهاز الذي يبلّغ.
• Accept-Version: قيمتها V2. تثبّت إصدار الواجهة فتحمي تكاملك من تغييرات غير متوقّعة عند ترقية المنصة.
• Clearance-Status: قيمتها 0 في مسار الإبلاغ. هذه القيمة هي ما يفرّق طلب الإبلاغ عن طلب المقاصة الذي قيمته 1.
• Content-Type: قيمتها application/json. جسم الطلب JSON دائمًا، حتى لو حمل في داخله مستند XML مُرمَّزًا.

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

تنبيه على التسمية: الاختصار الصحيح هو CSID أي معرّف الختم المشفّر (Cryptographic Stamp Identifier)، وليس أي ترتيب آخر للأحرف. الخطأ في كتابته داخل الكود أو التوثيق يسبّب لبسًا في فِرَق التكامل، فاضبطه من البداية.

# ترويسات طلب الإبلاغ الفردي
POST /invoices/reporting/single HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
Authorization: Basic VFNUMDExL...<Base64(ProductionCSID:secret)>
Accept-Version: V2
Clearance-Status: 0
Content-Type: application/json
Accept-Language: ar

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

جسم الطلب

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

• invoiceHash: تجزئة المستند بخوارزمية SHA-256 بعد ترميزها بـ Base64. تربط الطلب بمحتوى الفاتورة فيكشف أي تلاعب. للتفصيل ارجع إلى دليل التجزئة (Hashing) في الفاتورة الإلكترونية.
• uuid: المعرّف الفريد للفاتورة، قيمة لا تتكرّر تولّدها أنت لكل فاتورة. للتفصيل ارجع إلى دليل المعرّف الفريد UUID في الفاتورة الإلكترونية.
• invoice: مستند الفاتورة كاملًا بصيغة UBL 2.1، مُرمَّزًا بـ Base64. للتفصيل ارجع إلى دليل ترميز Base64 في الفاتورة الإلكترونية.

الترتيب الذي تبني به هذه الحقول مهم. تبني مستند الفاتورة بصيغة UBL 2.1 أولًا، متضمّنًا تجزئة الفاتورة السابقة وعدّاد الفاتورة والتوقيع الرقمي ورمز الاستجابة السريع. ثم تحسب تجزئة المستند بخوارزمية SHA-256. ثم تُرمّز المستند كاملًا بـ Base64 وتضعه في حقل invoice. ثم تضع التجزئة في invoiceHash والمعرّف الفريد في uuid.

// جسم طلب الإبلاغ الفردي (Request Body)
{
  "invoiceHash": "NmY49NQ...<Base64(SHA-256 hash)>",
  "uuid": "3cf5ee18-ee25-44ea-a444-2c37ba7f28be",
  "invoice": "PD94bWwgdmVyc2lvbj0...<Base64(UBL 2.1 XML)>"
}

الحقول الثلاثة يجب أن تكون متّسقة فيما بينها. التجزئة في invoiceHash يجب أن تطابق فعلًا تجزئة المستند المُرمَّز في invoice. والمعرّف في uuid يجب أن يطابق المعرّف المضمّن داخل المستند نفسه. أي عدم تطابق بين الغلاف والمستند يردّه الفحص.

لماذا تُرسَل الفاتورة بصيغة Base64؟

لأن مستند الفاتورة بصيغة XML متوافقة مع UBL 2.1، ولا يُحمَل XML خامًا داخل JSON بأمان. الترميز بـ Base64 يحوّل المستند إلى نص آمن ينتقل داخل حقل JSON دون أن تكسر محارفه بنية الغلاف. هذا يفصل بين طبقة النقل (JSON) والمستند الضريبي الرسمي (XML) الذي تفحصه الهيئة.

الاستجابة المتوقّعة

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

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

// استجابة الإبلاغ الناجح (200 OK)
{
  "reportingStatus": "REPORTED",
  "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"
  }
}

داخل الاستجابة يوجد حقل validationResults الذي يحمل تفصيل الفحص. يضمّ ثلاث قوائم: infoMessages للرسائل المعلوماتية، وwarningMessages للتحذيرات، وerrorMessages للأخطاء. الحقل status داخله يلخّص النتيجة العامة بقيمة PASS عند النجاح أو WARNING أو ERROR.

الفرق بين النجاح بتحذير والرفض

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

أما حين يكون status بقيمة ERROR وتمتلئ قائمة errorMessages، فالفاتورة مرفوضة ولم تُسجَّل. هنا يلزمك قرار: تصحّح المستند وتعيد الإبلاغ بمعرّف فريد، أو تصدر إشعارًا دائنًا يلغي أثر الفاتورة المعيبة. اقرأ كل رسالة خطأ بحقولها code وcategory وmessage لتعرف السبب الدقيق.

قراءة رسائل الفحص بالتفصيل

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

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

ميّز بين فئتي الفحص. فحص المخطط (XSD) يتأكّد أن المستند يطابق بنية UBL 2.1 الشكلية. فحص قواعد العمل (Business Rules) يتأكّد أن القيم الضريبية متّسقة ومنطقية، مثل تطابق مجموع الضريبة مع حاصل ضرب الوعاء في النسبة. خطأ المخطط يعني مشكلة في توليد الـ XML، وخطأ قواعد العمل يعني مشكلة في بيانات الفاتورة نفسها.

التعامل مع الاستجابة في نظامك

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

عند النجاح بحالة REPORTED وفحص PASS، تحدّث حالة الفاتورة في قاعدة بياناتك إلى «مُبلَّغ عنها» وتخزّن المعرّف الفريد وتجزئة المستند. هذه التجزئة تصبح مدخلًا لتجزئة الفاتورة السابقة في الفاتورة التالية، فتحافظ على السلسلة. ارجع إلى دليل تجزئة الفاتورة السابقة PIH لفهم كيف تتشكّل هذه السلسلة.

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

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

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

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

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

مثال متكامل على رحلة فاتورة مبسّطة

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

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

تدخل الفاتورة بعدها طابور الإبلاغ. يلتقطها مكوّن الخلفية، فيحسب تجزئة المستند، ويرمّزه بـ Base64، ويجمّع جسم JSON، ويستدعي POST /invoices/reporting/single بالترويسات الأربع. عند رجوع reportingStatus: REPORTED يحدّث المكوّن حالة الفاتورة إلى «مُبلَّغ عنها» ويخزّن تجزئتها لتكون مدخلًا للفاتورة التالية.

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

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

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

في المسار، الإبلاغ يستدعي /invoices/reporting/single بينما المقاصة تستدعي /invoices/clearance/single. في الترويسة، الإبلاغ يرسل Clearance-Status: 0 بينما المقاصة ترسل Clearance-Status: 1. في التوقيت، الإبلاغ بعد التسليم خلال نافذة أربع وعشرين ساعة، بينما المقاصة قبل التسليم وبشكل لحظي.

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

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

كيف يتولّى قيود مسار الإبلاغ نيابةً عنك

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

• إدارة معرّف الختم المشفّر: يدير قيود معرّف الإنتاج (Production CSID) وكلمة سرّه ويضعهما في ترويسة المصادقة تلقائيًا، فلا تتعامل أنت مع ترميز Base64 للمصادقة يدويًا.
• توليد المستند والتوقيع: يبني قيود مستند UBL 2.1 ويحسب تجزئته بـ SHA-256 ويوقّعه محليًا ويولّد رمز الاستجابة السريع، فتسلّم المشتري إيصالًا متوافقًا فورًا.
• توجيه كل فاتورة لمسارها: يميّز قيود الفاتورة المبسّطة (B2C) فيوجّهها لمسار الإبلاغ بترويسة Clearance-Status: 0، والفاتورة الضريبية (B2B) لمسار المقاصة، دون تدخّل منك.
• إدارة النافذة وإعادة المحاولة: يبلّغ قيود الهيئة ضمن نافذة الأربع والعشرين ساعة، ويعيد المحاولة تلقائيًا عند انقطاع الشبكة مع ثبات المعرّف الفريد.
• قراءة الاستجابة وحفظ السلسلة: يقرأ قيود حالة REPORTED ونتائج الفحص، ويحفظ تجزئة كل فاتورة لتكون مدخلًا للتالية، فتبقى سلسلة فواتيرك متماسكة.

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

أسئلة شائعة عن نقطة الإبلاغ الفردي

ما نقطة النهاية الصحيحة للإبلاغ الفردي؟
المسار النسبي هو POST /invoices/reporting/single، يُضاف بعد العنوان الأساسي لبيئة الاختبار أو الإنتاج. المسار نفسه لا يتغيّر بين البيئتين، يتغيّر العنوان الأساسي والمعرّف فقط.

أي قيمة أضع في ترويسة Clearance-Status؟
القيمة 0 في مسار الإبلاغ. القيمة 1 تخصّ مسار المقاصة. هذه الترويسة مع اختلاف المسار هما ما يفرّقان طلب الإبلاغ عن طلب المقاصة.

ماذا تحمل ترويسة Authorization؟
مصادقة Basic قيمتها معرّف الختم المشفّر للإنتاج (Production CSID) وكلمة سرّه، مدموجين ومُرمَّزين بـ Base64. وليس اسم مستخدم وكلمة سر بشريين.

ما الحقول الثلاثة في جسم الطلب؟
invoiceHash وهو تجزئة المستند بـ SHA-256 مُرمَّزة بـ Base64، وuuid وهو المعرّف الفريد للفاتورة، وinvoice وهو مستند UBL 2.1 كاملًا مُرمَّزًا بـ Base64.

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

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