حقول استجابة نظام الفوترة الوطني: دليل عناصر EINV

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

الجواب المختصر أن الدليل التقني الصادر عن دائرة ضريبة الدخل والمبيعات (الإصدار 1.5) يسرد في جدول عناصر ملف الاستجابة سبعة عناصر، هي Response Status Code وEINV_STATUS وEINV_RESULTS وEINV_MESSAGE وEINV_QR وEINV_NUM وEINV_INV_UUID، ويظهر في نماذج الاستجابة عنصر ثامن هو EINV_SINGED_INVOICE. والحكم على الفاتورة يكون بقيمة EINV_STATUS، لا برمز HTTP وحده.

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

ما هي حقول استجابة نظام الفوترة الوطني

يصف الدليل التقني ملف الاستجابة في الجزء الخاص بإرسال الفاتورة واستلام الاستجابة (ص97 إلى ص100). ويبدأ بجدول من عمودين، العنصر ووصفه، ثم يعرض قيم الحالة الثلاث، ثم ثلاثة نماذج للاستجابة بصيغة JSON. والجدول التالي يجمع الحقول الثمانية، بوصف كل منها كما ورد في جدول الدليل، وما يحدث له حين تُرفض الفاتورة.

الأسماء في الجدول مكتوبة كما ترد في الدليل، وحروفها الإنجليزية جزء من المفتاح الذي يقرؤه نظامك. فلا تترجمها في الكود ولا تصحح هجاءها، وهذا يشمل EINV_SINGED_INVOICE الذي يرد في الدليل بهذا الهجاء.

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

يحدد الدليل (ص97) ستة أغراض لملف الاستجابة.

1. التحقق من نجاح عملية إرسال الفاتورة.
2. معرفة ما إذا قُبلت الفاتورة أو رُفضت.
3. إظهار أسباب الأخطاء.
4. استرجاع رمز QR الخاص بالفاتورة.
5. استرجاع المعرّف الفريد للفاتورة UUID.
6. تمكين الأنظمة المرتبطة من معالجة نتيجة الإرسال آليًا.

الغرض السادس هو ما يعني المطوّر قبل غيره. فالاستجابة مكتوبة لتقرأها الآلة، ونظامك هو الذي يحوّلها إلى حالة يراها المستخدم وإلى سجل يرجع إليه. وإذا قابلت الأغراض الخمسة الأولى بأوصاف العناصر في الجدول، وجدت لكل غرض حقلًا يجيب عنه، رمز الاستجابة الفني لنجاح الإرسال، وEINV_STATUS للقبول أو الرفض، وEINV_RESULTS وEINV_MESSAGE لأسباب الأخطاء، وEINV_QR للرمز، وEINV_INV_UUID للمعرّف. وهذه المقابلة قراءة منا لأوصاف الجدول، لا نص في الدليل.

Response Status Code رمز فني لا حكم على الفاتورة

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

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

أما الرموز الأخرى فلكل منها سبب موثق في الدليل (ص101). الرمز 400 يخص أخطاء في قيم ملف XML وتفاصيلها في EINV_MESSAGE، والرمز 403 يخص رقم المستخدم والمفتاح السري، والرمز 504 يعني تعذر الوصول إلى النظام، والرمز 500 يرتبط بالرقم الضريبي أو تسلسل مصدر الدخل، وبدرجة أقل ببيانات الاعتماد، أو بنسبة ضريبة ليست ضمن النسب المعتمدة لدى الدائرة. وتفصيل كل رمز وطريقة التعامل معه في مقال أخطاء نظام الفوترة الوطني.

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

EINV_STATUS الحقل الذي تحكم به على الفاتورة

يصف الدليل هذا العنصر بأنه «يوضح الحالة النهائية للفاتورة»، ويذكر له ثلاث قيم (ص98). وعليه يقوم منطق نظامك كله، فكل فرع في المعالجة يبدأ من قيمته.

• SUBMITTED. وصفها في الدليل «تم اعتماد الفاتورة بنجاح». قُبلت الفاتورة وعاد رمزها في EINV_QR، وما تحفظه وتعرضه بعدها في مقال حالة SUBMITTED في نظام الفوترة الوطني.
• ALREADY_SUBMITTED. وصفها «الفاتورة معتمدة مسبقًا». أُرسلت الفاتورة نفسها بالرقم والمعرّف نفسيهما بعد قبولها، فيعود رمز QR الأصلي، وهي الطريقة الموثقة لاسترجاع رمز لم يُحفظ. والتفصيل في مقال حالة ALREADY_SUBMITTED في نظام الفوترة الوطني.
• NOT_SUBMITTED. وصفها «لم يتم اعتماد الفاتورة بسبب وجود خطأ». رُفضت الفاتورة، وتعود حقول الرمز والمعرّف والرقم والفاتورة الموقعة فارغة. وخطوات التصحيح وإعادة الإرسال في مقال حالة NOT_SUBMITTED في نظام الفوترة الوطني.

ملاحظة عند الرجوع إلى الدليل، نموذج الاستجابة المعروض في ص100 هو نموذج الحالة NOT_SUBMITTED، لكن العنوان المكتوب فوقه يذكر ALREADY_SUBMITTED. فاعتمد على محتوى النموذج لا على عنوانه.

عناصر مصفوفة EINV_RESULTS

يصف الدليل EINV_RESULTS بأنه «يحتوي على نتائج التحقق والتنبيهات والأخطاء». وفي نماذج الدليل (ص98 إلى ص100) يتكون من حقل status قيمته PASS أو ERROR، وثلاث قوائم هي INFO وWARNINGS وERRORS.

ويحمل كل عنصر داخل هذه القوائم خمسة مفاتيح، هي type وstatus وEINV_CODE وEINV_CATEGORY وEINV_MESSAGE. ويعرض الدليل لها مثالين.

• عنصر من قائمة INFO في نموذج القبول (ص98). النوع INFO، والنتيجة PASS، والرمز XSD_VALID، والفئة XSD validation، والرسالة Complied with UBL 2.1 standards.
• مثال الخطأ. الرمز totalGeneralTaxesAmount، والفئة invoice، والرسالة Total General Amount is Not Correct، وهي رسالة تخص حساب مجاميع الفاتورة.

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

EINV_MESSAGE تفاصيل الخطأ وسبب الرفض

يصف جدول الدليل EINV_MESSAGE بأنه «يوضح تفاصيل الخطأ أو سبب الرفض». وفي نماذج الاستجابة يظهر هذا المفتاح داخل عناصر EINV_RESULTS، فهو في نموذج القبول (ص98) يحمل رسالة معلوماتية ضمن قائمة INFO، لا رسالة خطأ.

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

EINV_QR رمز الفاتورة المقبولة

يصفه الدليل بأنه «يحتوي على QR Code الخاص بالفاتورة». ويعود فيه الرمز مع الحالة SUBMITTED، ويعود الرمز الأصلي مع الحالة ALREADY_SUBMITTED، ويكون فارغًا مع الحالة NOT_SUBMITTED.

• وجوده شرط. يربط الدليل اكتمال استلام الفاتورة واعتمادها بوجود الرمز في هذا العنصر، فالحالة وحدها لا تكفي دون رمز.
• إظهاره مطلوب. يطلب الدليل (ص98 وص104) إظهار رمز QR على فاتورة البائع.
• مصدره الدائرة. الرمز يعود من دائرة ضريبة الدخل والمبيعات في الرد، ولا يولّده نظامك.
• التحقق منه. يتم بحسب الدليل من خلال تطبيق سند فقط، من خيار «التحقق من المستندات الرقمية».

ولا يشرح الدليل طريقة ترميز الرمز، وكل ما يذكره عن محتواه أن تطبيق سند يعرض عند التحقق بيانات الفاتورة الأساسية الموجودة داخله (ص105). فلا تفك محتواه ولا تبنِ عليه منطقًا في برنامجك. وكل ما يخص الرمز من مصدره إلى استرجاعه في مقال رمز QR الصادر من دائرة ضريبة الدخل والمبيعات EINV_QR.

EINV_NUM وEINV_INV_UUID هوية الفاتورة في الرد

يصف الدليل EINV_NUM بأنه «رقم الفاتورة المرسل»، وEINV_INV_UUID بأنه «الرقم الفريد العالمي للفاتورة (UUID)». فالعنصران يعيدان إليك هوية الفاتورة التي أرسلها نظامك، ويعودان فارغين مع الحالة NOT_SUBMITTED.

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

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

EINV_SINGED_INVOICE الفاتورة الموقعة من الدائرة

لا يرد هذا العنصر في جدول العناصر (ص97)، لكنه يظهر في نماذج الاستجابة، ومنها نموذج القبول أعلاه. ويحمل الفاتورة الموقعة التي يعيدها النظام في الرد، واسمه يرد بهذا الهجاء EINV_SINGED_INVOICE، فاقرأه في نظامك كما يعود.

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

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

ترتيب معالجة الاستجابة داخل نظامك

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

1. سجّل الطلب والرد. احفظ كل عملية إرسال واستجابتها في سجل العمليات، كما يطلب الإرشاد العاشر «تتبع العمليات»، واستخدم تنسيقًا زمنيًا موحدًا كما يطلب الإرشاد التاسع «التوقيت الزمني».
2. تعامل مع غياب الرد. إذا انقطع الاتصال أو انتهت المهلة، أعد الإرسال بالرقم والمعرّف نفسيهما دون توليد معرّف جديد.
3. اقرأ EINV_STATUS أولًا. لا تحكم على الفاتورة برمز HTTP وحده في أي فرع من فروع المعالجة.
4. في الحالة SUBMITTED. تحقق أن EINV_QR يحمل رمزًا، ثم احفظ ID وUUID وQR Code وEINV_STATUS كما يطلب الإرشاد الخامس، وأظهر الرمز على فاتورة البائع.
5. في الحالة ALREADY_SUBMITTED. الفاتورة مقبولة من قبل، فخذ الرمز الأصلي من EINV_QR واحفظه إن لم يكن محفوظًا، ولا تعاملها كفاتورة جديدة.
6. في الحالة NOT_SUBMITTED. اقرأ عناصر قائمة ERRORS ورسالة كل عنصر، وسجّلها تفصيليًا، واعرض للمستخدم رسالة مبسطة، ثم أعد الإرسال بعد التصحيح بالرقم والمعرّف نفسيهما.

هذا الترتيب يطابق ما يطلبه الدليل في إرشاداته، وشرح كل إرشاد منها في مقال الإرشادات العشر لنظام الفوترة الوطني.

ما لا يذكره الدليل عن حقول الاستجابة

بعض الأسئلة التي يطرحها المطوّر عن الاستجابة لا يجيب عنها الدليل التقني 1.5. والصمت هنا لا يعني أن الجواب المتوقع صحيح، بل يعني أنه غير موثق.

• قائمة رموز الفحص. لا ينشر الدليل قائمة بقيم EINV_CODE وEINV_CATEGORY ولا معانيها، ويكتفي بالمثالين المذكورين أعلاه.
• بنية رمز QR. لا يشرح الدليل طريقة ترميز EINV_QR ولا ترتيب البيانات داخله، ويكتفي بذكر بيانات الفاتورة الأساسية التي يعرضها تطبيق سند عند التحقق منه.
• بنية الفاتورة الموقعة. لا يشرح الدليل محتوى EINV_SINGED_INVOICE ولا طريقة قراءته.
• عدد مرات إعادة المحاولة. يطلب الدليل إعادة الإرسال بالمعرّف نفسه، ولا يحدد عدد المحاولات ولا الفاصل الزمني بينها.

وفي كل هذه الحالات يبقى المرجع واحدًا، قيمة EINV_STATUS ووجود الرمز في EINV_QR.

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

ما سبق عمل يقع على النظام المربوط بنظام الفوترة الوطني. ويعمل تكامل قيود مع نظام الفوترة الوطني على هذه الطبقة كما يلي.

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

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

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

ما حقول استجابة نظام الفوترة الوطني؟

يسرد الدليل التقني 1.5 سبعة عناصر في جدول الاستجابة، هي Response Status Code وEINV_STATUS وEINV_RESULTS وEINV_MESSAGE وEINV_QR وEINV_NUM وEINV_INV_UUID. ويظهر في نماذج الاستجابة عنصر ثامن هو EINV_SINGED_INVOICE الذي يحمل الفاتورة الموقعة من الدائرة.

هل يكفي رمز HTTP 200 لأعدّ الفاتورة مقبولة؟

لا يكفي هذا الرمز وحده. يطلب الإرشاد الرابع «التعامل مع الاستجابة» تحديد الحالة النهائية من EINV_STATUS، ويربط الدليل اكتمال القبول بوجود الرمز في EINV_QR.

ما الحقول التي تعود فارغة مع الحالة NOT_SUBMITTED؟

تعود الحقول EINV_QR وEINV_NUM وEINV_INV_UUID وEINV_SINGED_INVOICE بقيمة null مع الحالة NOT_SUBMITTED، ولا يكون رمز الاستجابة 200. ويبقى سبب الرفض في عناصر EINV_RESULTS ورسالة EINV_MESSAGE.

هل ينشر الدليل قائمة بقيم EINV_CODE وEINV_CATEGORY؟

لا ينشر الدليل هذه القائمة ولا يشرح معاني القيم. ويعرض مثالين فقط، XSD_VALID في نموذج القبول وtotalGeneralTaxesAmount في مثال الخطأ.

لماذا يُكتب EINV_SINGED_INVOICE بهذا الهجاء؟

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

ماذا أفعل برمز QR العائد في الاستجابة؟

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

المراجع

• دائرة ضريبة الدخل والمبيعات، الدليل التقني للربط مع نظام الفوترة الوطني من خلال واجهة برمجة التطبيقات (API)، الإصدار 1.5، 2026، ص97 وص98 وص99 وص100 وص101 وص104 وص105.