ترفض زاتكا الفواتير برموز أخطاء مقتضبة، وفك شيفرتها تحت ضغط الموعد النهائي مرهق. إليك أكثر سبعة أسباب نراها في الإنتاج، مرتبةً بحسب التكرار، مع حل مُجرَّب لكلٍّ منها.
1. ENT_ICV-001 — قيمة عدّاد الفاتورة خارج التسلسل
يجب أن تزيد قيمة ICV تصاعدياً وحصرياً لكل جهاز. والسبب غالباً هو الإصدار المتوازي من عمليّتين على نفس EGS. الحل: تسلسل تعيين ICV خلف مصدر حقيقة وحيد (تسلسل قاعدة بيانات يفي بالغرض).
2. ENT_PIH-002 — عدم تطابق تجزئة الفاتورة السابقة
التجزئة التي أرسلتها بوصفها السابقة لا تطابق ما لدى زاتكا. السبب: إعادة إرسال فاتورة قديمة أو تأخر الكاش المحلي. الحل: استعلِم من فاتورة عن آخر تجزئة معتمدة وأعِد بذر سلسلتك.
3. KSA-25 — رمز فئة الضريبة مفقود أو غير صالح
كل بند فاتورة يحتاج إلى رمز فئة من UNCL5305: S أو Z أو E أو O أو AE. خطأ شائع: تركه فارغاً للبنود ذات النسبة الصفرية. الحل: أصدِر Z صراحةً، ولا تحذفها.
4. KSA-12 — رقم VAT للبائع غير سليم
أرقام التسجيل الضريبي السعودية تتكون من 15 رقماً تبدأ بـ 3 وتنتهي برقم تحقق. خطأ شائع: إرسال رقم السجل التجاري المكوّن من 10 أرقام بدلاً منه. الحل: اقرأ VAT من جدول tax_registrations بالنوع 'VAT'، لا من حقل الرخصة التجارية.
5. CLOCK_DRIFT — تاريخ الإصدار يبتعد عن الزمن المرجعي بأكثر من 30 ثانية
انحراف ساعة الخادم. الحل: مزامنة NTP مع pool.ntp.org كل دقيقة، على كل خادم يصدر فواتير.
6. KSA-08 — فاتورة قياسية بلا VAT للمشتري
فواتير B2B في السعودية تشترط رقم VAT للمشتري. أما الفواتير المبسّطة (B2C) فلا. الحل: تفرّع في المُسلسِل (serializer) بناءً على InvoiceTypeCode (388 = قياسية، 388 بنوع فرعي 02 = مبسّطة).
7. KSA-19 — مبلغ الضريبة غير متسق مع إجماليات البنود
مجموع ضرائب البنود لا يساوي TaxTotal. السبب دائماً تقريب في منتصف الحساب. الحل: قرّب فقط الإجمالي الفرعي النهائي لكل نسبة (تقريب البنوك)، لا في كل بند.