رمز الخطأ 1005: تجزئة الفاتورة السابقة PIH مفقودة

عند انتقال منشأتك إلى المرحلة الثانية من الفوترة الإلكترونية، لا تعود كل فاتورة مستندًا مستقلًا. تصبح كل فاتورة حلقة في سلسلة مترابطة، تحمل في داخلها بصمة الفاتورة التي سبقتها. هذه البصمة المنقولة من فاتورة إلى أخرى تُسمّى تجزئة الفاتورة السابقة، أو PIH اختصارًا لعبارة Previous Invoice Hash. ومن أكثر أسباب رفض الفواتير شيوعًا عند الربط مع هيئة الزكاة والضريبة والجمارك (ZATCA) أن تكون هذه القيمة مفقودة أو خاطئة، فترفض منصة فاتورة الفاتورة برمز الخطأ 1005.

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

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

ما الذي يعنيه رمز الخطأ 1005

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

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

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

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

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

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

{
  "validationResults": {
    "status": "ERROR",
    "errorMessages": [
      {
        "type": "ERROR",
        "code": "1005",
        "category": "INVOICE-HASHING",
        "message": "Provided PIH is missing or does not match the hash of the last cleared invoice."
      }
    ]
  }
}

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

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

الأسباب الجذرية لرمز الخطأ 1005

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

السبب الأول: حقل PIH فارغ أو غائب

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

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

السبب الثاني: قيمة أساسية خاطئة في أول فاتورة

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

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

السبب الثالث: عدّاد متقدّم بعد فاتورة مرفوضة

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

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

السبب الرابع: بصمة محسوبة على بيانات خاطئة

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

التسلسل الصحيح للعمليات: توليد XML، ثم التقنين، ثم حساب البصمة، ثم التوقيع، ثم الإرسال. البصمة التي تُنقل إلى الفاتورة التالية يجب أن تُحسب على النسخة المقنّنة قبل التوقيع، بالترميز نفسه الذي تنتظره المنصة. أي تبديل في ترتيب هذه الخطوات يغيّر البايتات التي تمرّ على دالة التجزئة، فيُنتج بصمة لا تطابق المرجع. لتفاصيل هذه الفئة من الأخطاء، راجع توثيق أخطاء التجزئة (Hash) في الفاتورة.

خطوات الإصلاح العملية

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

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

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

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

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

كيف تميّز رمز الخطأ 1005 عمّا يجاوره

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

أقرب الأخطاء إليه خطأ عدم تطابق عدّاد الفاتورة، الذي يشير إليه عادةً حقل ICV لا حقل PIH. الفرق أن خطأ العدّاد يقول إن ترتيب الفاتورة في السلسلة غير متوقَّع، بينما رمز الخطأ 1005 يقول إن البصمة المنقولة من الفاتورة السابقة غير صحيحة. قد يظهر الخطآن معًا حين يتقدّم العدّاد بعد رفض، لأن تقدّمه يكسر ترتيب الفاتورة وقيمة PIH في آنٍ واحد. عندها أصلح الجذر المشترك، وهو الفصل بين الإرسال والاعتماد، فيختفي الخطآن معًا.

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

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

كيف تقي نظامك من هذا الخطأ

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

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

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

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

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

كيف يساعدك قيود

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

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

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

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

ما معنى رمز الخطأ 1005 عند إرسال الفاتورة؟

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

ما القيمة الصحيحة لحقل PIH في أول فاتورة؟

هي القيمة الأساسية التي تحدّدها الهيئة، وهي بصمة النص الفارغ بخوارزمية SHA-256 بعد ترميزها بصيغة Base64. تُطبَّق هذه القيمة على الفاتورة الأولى وحدها. الخطأ الشائع كتابتها بصيغة سداسية عشرية أو وضع أصفار مكانها.

لماذا يظهر الخطأ بعد أن أعدت إرسال فاتورة مرفوضة؟

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

أرسلت قيمة PIH موجودة وغير فارغة، فلماذا تُرفض؟

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

هل يؤثّر رمز الخطأ 1005 على الفواتير التالية؟

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

هل أحتاج لمعالجة قيمة PIH بنفسي عند استخدام قيود؟

لا. يتولّى قيود ملء حقل PIH وتثبيت القيمة الأساسية لأول فاتورة وتزامن العدّاد وحساب البصمة بالترميز الصحيح والتوقيع والربط مع منصة فاتورة آليًا. لا تحتاج لكتابة أي كود ولا لتشخيص رمز الخطأ 1005 بنفسك.