رمز الخطأ 1017: حقل إلزامي مفقود في الترويسة

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

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

ماذا يعني رمز الخطأ 1017 بالضبط

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

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

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

الحقول الإلزامية في الترويسة

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

لاحظ أن رمز نوع الفاتورة InvoiceTypeCode يحمل سمات إضافية تحدد قياسية الفاتورة من بساطتها، لكن غيابه ككل، لا قيمته الخاطئة، هو ما يعني الرمز 1017. قيمته الخاطئة شأن آخر يعالَج برمز مختلف. هنا نتكلم عن الغياب وحده.

كيف تقرأ رسالة الرفض

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

{
  "validationResults": {
    "infoMessages": [
      {
        "type": "INFO",
        "code": "XSD_ZATCA_VALID",
        "category": "XSD validation",
        "message": "Complied with UBL 2.1 standards"
      }
    ],
    "warningMessages": [],
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "1017",
        "category": "Invoice header validation",
        "message": "A mandatory header field is missing from the invoice."
      }
    ],
    "status": "ERROR"
  },
  "clearanceStatus": "NOT_CLEARED",
  "clearedInvoice": null
}

المفاتيح التي تهمّك في القراءة:

• status بقيمة ERROR يعني رفضاً قاطعاً، فالفاتورة لن تُعتمد حتى تُصحّح.
• code بقيمة 1017 هو ما تعتمد عليه في تصنيف الخطأ. اربط منطق نظامك بالكود لا بالنص الوصفي، لأن الكود ثابت بينما النص قد يصاغ بطرق مختلفة.
• category بقيمة Invoice header validation يؤكد أن الخلل في الترويسة لا في البنود أو الحساب.
• infoMessages هنا يخبرك أن المستند سليم نحوياً ومتوافق مع UBL 2.1، أي أن المشكلة ليست في صيغة XML نفسها بل في غياب حقل بعينه.

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

كيف يفشل كل حقل من حقول الترويسة على حدة

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

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

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

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

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

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

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

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

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

<Invoice>
  <cbc:ID>INV-2026-00417</cbc:ID>
  <!-- cbc:UUID مفقود هنا: هذا هو سبب الرمز 1017 -->
  <cbc:IssueDate>2026-06-24</cbc:IssueDate>
  <cbc:IssueTime>14:35:00</cbc:IssueTime>
  <cbc:InvoiceTypeCode name="0100000">388</cbc:InvoiceTypeCode>
  <cbc:DocumentCurrencyCode>SAR</cbc:DocumentCurrencyCode>
  <cac:AccountingSupplierParty>
    <!-- بيانات البائع -->
  </cac:AccountingSupplierParty>
</Invoice>

التصحيح هنا أن تضيف سطر cbc:UUID بقيمة معرّف فريد مولّد، ثم تعيد توليد المستند وتوقيعه. الأهم أن تعالج المصدر الذي ترك السطر يسقط، لا أن تضيف السطر يدوياً مرة واحدة، وإلا تكرر الخطأ في الفاتورة التالية. وللتعمق في موضع كل عنصر داخل شجرة المستند راجع صفحة ترويسة الفاتورة (Invoice Header) في XML.

لماذا تسقط حقول الترويسة أصلاً

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

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

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

كيف تصحّح الفاتورة وتعيد إرسالها

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

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

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

كيف تميّز 1017 عن خطأ بنية XML 1013

أكثر ما يربك الفرق بين رمز الخطأ 1017 ورمز الخطأ 1013. كلاهما يقع في طبقة البنية، وكلاهما يوقف الفاتورة قبل الحساب والتوقيع، لكن مصدر كل منهما مختلف، ومعالجتهما مختلفة. خلطهما يجعلك تبحث في المكان الخطأ.

القاعدة العملية: إذا قبل التحقق بنية المستند ككل (تجد XSD_ZATCA_VALID في رسائل المعلومات) لكنه رفض لغياب حقل، فأنت أمام 1017. أما إن رفض المستند على مستوى المخطط نفسه فأنت أمام 1013. الأول مشكلة محتوى ناقص في هيكل سليم، والثاني مشكلة هيكل مكسور. للتفصيل الكامل عن بنية المستند راجع صفحة أخطاء XML في الفاتورة الإلكترونية، ولفهم الحقول كما تظهر في رأس المستند راجع صفحة ترويسة الفاتورة (Invoice Header) في XML.

سيناريو عملي: متجر في جدة ينسى وقت الإصدار

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

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

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

أين يقع الرمز 1017 في ترتيب طبقات التحقق

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

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

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

ماذا يحدث إن تركت الخطأ دون حلّ

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

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

كيف تمنع تكرار الخطأ نهائياً

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

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

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

كيف يتولى قيود حقول الترويسة عنك

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

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

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

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

ما الحقول التي يقصدها الرمز 1017 في الترويسة؟
الحقول الإلزامية الستة في رأس المستند: معرّف الفاتورة، والمعرّف الفريد UUID، وتاريخ ووقت الإصدار، ورمز نوع الفاتورة، ورمز العملة، وبيانات البائع. غياب أيّ منها، أو تركه فارغاً، ينتج الرمز نفسه.

ما الفرق بين الرمز 1017 والرمز 1013؟
الرمز 1017 يعني أن حقلاً إلزامياً بعينه مفقود من ترويسة سليمة البنية. الرمز 1013 يعني خللاً في بنية المستند نفسها أو مخالفة لمخطط UBL 2.1. الأول مشكلة محتوى ناقص في هيكل سليم، والثاني مشكلة هيكل مكسور.

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

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

هل تظهر الفاتورة في طبقة المقاصة بعد الرمز 1017؟
لا. الرمز 1017 يوقف الفاتورة في طبقة التحقق البنيوي قبل المقاصة، فتأتي قيمة clearanceStatus بقيمة NOT_CLEARED. لن تصل الفاتورة للمقاصة حتى تكتمل ترويستها.

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