أخطاء التجزئة (Hash) في الفاتورة

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

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

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

كيف تقرأ رسالة رفض متعلقة بالبصمة

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

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

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

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

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

عدم تطابق PIH وكسر سلسلة التجزئة

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

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

السلسلة المرئية للتجزئة

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

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

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

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

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

خطأ البصمة الأساسية في أول فاتورة

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

العَرَض أن أول فاتورة ترفضها المنصة فورًا، مع أن السلسلة لم تبدأ بعد. السبب الجذري إما وضع قيمة PIH فارغة، أو وضع أصفار، أو وضع نص القيمة الأساسية بصيغة سداسية عشرية بدل Base64، أو اقتطاع جزء من القيمة. القيمة الأساسية الصحيحة هي بصمة النص الفارغ بخوارزمية SHA-256 بعد ترميزها Base64، وتساوي:

PIH (first invoice) = NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjM2M=
// SHA-256 of empty string, hex then Base64 encoded

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

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

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

حساب SHA-256 بترميز خاطئ: سداسي مقابل Base64

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

الترميزان لنفس البصمة

// نفس البصمة، ترميزان مختلفان
HEX    = 7d3a9f2c8b1e4f6a0d5c2b8e9a1f4d7c3e6b9a2d5f8c1b4e7a0d3c6f9b2e5a8d
Base64 = fTqfLIseT2oNXCuOmh9NfD5rmi1fjBtOeg08b5suWo0=

// خطأ شائع: إرسال HEX حيث ينتظر النظام Base64
errorCode: "INVALID-HASH-ENCODING"

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

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

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

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

خطأ التقنين قبل حساب البصمة

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

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

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

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

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

حساب البصمة على نسخة XML الخاطئة

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

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

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

عدم تزامن ICV مع PIH

إلى جانب PIH، تحمل كل فاتورة عدّاد فاتورة متسلسلًا اسمه ICV، يزيد بواحد مع كل فاتورة من جهاز الإصدار نفسه. يجب أن يتحرّك هذا العدّاد بالتزامن مع سلسلة التجزئة: الفاتورة التي تحمل ICV رقم N يجب أن تحمل في PIH بصمة الفاتورة رقم N ناقص واحد. عند انفصال العدّادين تنكسر العلاقة بينهما.

تزامن العدّاد مع السلسلة

Invoice #41  ICV=41  PIH=hash(#40)   OK
Invoice #42  ICV=42  PIH=hash(#41)   OK
Invoice #43  ICV=45  PIH=hash(#41)   ERROR
// ICV قفز إلى 45 وPIH ما زال يشير للفاتورة 41
errorCode: "ICV-PIH-OUT-OF-SYNC"

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

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

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

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

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

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

يولّد قيود ملف XML بصيغته المعتمَدة، ويطبّق التقنين الصحيح، ويحسب بصمة SHA-256 بالترميز الذي تنتظره المنصة، ويربط حقل PIH ببصمة آخر فاتورة مُعتمَدة، ويزامن عدّاد ICV مع السلسلة، ويوقّع الفاتورة، ويرسلها لمنصة فاتورة للاعتماد الفوري للفواتير بين المنشآت أو الإبلاغ خلال 24 ساعة لفواتير المستهلك. يدير قيود كذلك معرّف ختم التوقيع المعتمَد (Compliance Cryptographic Stamp Identifier, CSID) المرتبط بحسابك آليًا.

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

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

ما معنى عدم تطابق PIH عند إرسال الفاتورة؟

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

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

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

لماذا ترفض المنصة بصمتي رغم أنها صحيحة رياضيًا؟

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

لماذا يجب تطبيق التقنين قبل حساب البصمة؟

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

على أي نسخة من XML أحسب البصمة؟

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

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

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