تشريح أخطاء الربط مع زاتكا للورش والمراكز الفنية

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

التوقيت يجعل الفهم ضروريًا الآن. أعلنت الهيئة في 24 يوليو 2026 أن المجموعة 25 تشمل كل من تجاوزت إيراداته الخاضعة للضريبة 187,500 ريال في أي سنة من 2022 إلى 2025، وأن الربط مطلوب في موعد أقصاه 1 فبراير 2027. ورش كثيرة ستعبر هذا الحد لأول مرة، وأول ما ستواجهه بعد الربط هو الرفض.

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

قبل أي إصلاح: ماذا يقول رد منصة فاتورة؟

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

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

الخطأ 1: شهادة CSID منتهية أو غير مطابقة

كل جهاز أو نظام يُصدر الفواتير يُسجَّل في منصة فاتورة كوحدة إصدار، ويحمل شهادة تشفير خاصة به. الوحدة تمر بمرحلتين: شهادة امتثال تُستخرج برمز OTP وطلب توقيع شهادة (CSR)، ثم فحوص امتثال، ثم شهادة إنتاج هي التي تُرسل بها الفواتير الحقيقية.

العَرَض المميز هنا أن كل الفواتير ترفض دفعة واحدة بعد فترة عمل طبيعية، والرد 401. لا شيء تغيّر في الفواتير نفسها؛ الذي تغيّر هو صلاحية الشهادة.

الخطأ 2: عداد ICV قفز رقمًا أو تكرر

ICV (Invoice Counter Value) عداد متسلسل لكل وحدة إصدار، يبدأ من 1 ويزيد واحدًا مع كل فاتورة، دون فجوة ودون تكرار. هو ليس رقم الفاتورة الذي يراه العميل، بل رقم داخلي تتحقق منه المنصة.

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

الخطأ 3: انقطاع سلسلة PIH

كل فاتورة تحمل في حقل PIH (Previous Invoice Hash) بصمة الفاتورة السابقة الصادرة من الوحدة نفسها، فتصير الفواتير سلسلة لا يمكن حذف حلقة منها دون أن ينكشف ذلك. الفاتورة الأولى لا سابق لها، فتحمل قيمة ثابتة هي ترميز Base64 لبصمة SHA-256 للحرف «0»:

NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiNTdlOQ==

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

الخطأ 4: Invalid Invoice Hash

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

{
  "invoiceHash": "<SHA-256 للنسخة النهائية من XML، بترميز Base64>",
  "uuid": "<المعرّف الفريد للفاتورة>",
  "invoice": "<ملف XML نفسه، بترميز Base64>"
}

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

الخطأ 5: رمز QR بخمسة وسوم فقط

رمز QR في الفاتورة ليس رابطًا، بل بيانات مرمّزة بصيغة TLV (وسم، طول، قيمة) ثم Base64. المرحلة الأولى اكتفت بخمسة وسوم. المرحلة الثانية أضافت أربعة وسوم تشفيرية تربط الرمز بالفاتورة الموقّعة، فرمز المرحلة الأولى لا يكفي بعد الربط.

الخطأ 6: حقل إلزامي فارغ أو بصيغة خاطئة في XML

ملف الفاتورة يُفحص بقواعد تحقق مكتوبة لكل حقل. الأكثر إسقاطًا لفواتير الورش هو العنوان الوطني: يجب أن يحمل عنوان البائع اسم الشارع ورقم المبنى والرمز البريدي والمدينة والحي ورمز الدولة SA. والقاعدة BR-KSA-37 تشترط أن يكون رقم المبنى 4 أرقام، والرمز البريدي السعودي 5 أرقام.

<cac:PostalAddress>
  <cbc:StreetName>طريق الملك فهد</cbc:StreetName>
  <cbc:BuildingNumber>1234</cbc:BuildingNumber>   <!-- 4 أرقام -->
  <cbc:CitySubdivisionName>العليا</cbc:CitySubdivisionName>
  <cbc:CityName>الرياض</cbc:CityName>
  <cbc:PostalZone>12345</cbc:PostalZone>          <!-- 5 أرقام -->
  <cac:Country><cbc:IdentificationCode>SA</cbc:IdentificationCode></cac:Country>
</cac:PostalAddress>

العَرَض المعتاد أن فواتير الأفراد تمر وفواتير الشركات ترفض: الفاتورة الضريبية لعميل منشأة تتطلب بياناته، فإن سُجّل العميل باسم وجوال فقط سقطت فاتورته. ويتكرر معه عدم اتساق فئة الضريبة مع نسبتها، أو إجمالي لا يساوي مجموع الصافي والضريبة.

بعد القبول: الفاتورة لا تُعدَّل

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

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