تجهيز بيانات الفواتير قبل الربط مع زاتكا

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

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

الربط لا يبدأ من واجهة البرمجة

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

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

ابدأ بخريطة البيانات

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

يجب أن تغطي الخريطة:

• بيانات البائع والمشتري، وأرقام التسجيل، والعنوان الوطني للمنشأة؛
• تاريخ الإصدار وتاريخ التوريد، والعملة، ومراجع الطلبات أو العقود؛
• البنود، والخصومات والإضافات، والضرائب، والإجماليات؛
• علاقة المستندات اللاحقة بالفاتورة الأصلية، كما في الإشعار الدائن والمدين.

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

حدّد مالك كل حقل

الملكية تمنع منطق التخمين:

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

وحّد القيم قبل احتساب الإجماليات

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

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

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

ضع التحقق قبل الختم والإرسال

التحقق المبكر أقل كلفة من تصحيح مستند وصل إلى قائمة الرفض. صمّم طبقات تحقق متتابعة:

1. الوجود: هل الحقل موجود أصلًا؟
2. الصيغة: هل الرقم الضريبي بطوله وبنيته الصحيحين؟
3. الاتساق الحسابي: هل تساوي الإجماليات مجموع البنود بعد الخصم والضريبة؟
4. قواعد الأعمال: هل رمز الضريبة يتفق مع نوع المشتري وحالة الإعفاء؟
5. متطلبات الهيئة: هل يطابق المستند قواعدها المنشورة؟

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

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

افصل هوية المستند عن حالته لدى الهيئة

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

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

ويرتبط كل كيان قانوني بهويته وشهادته الخاصة، فلا يُختم مستند كيانٍ بشهادة كيان آخر. تفاصيل ذلك في تسجيل شهادة الختم الإلكتروني وإدارة فواتير عدة كيانات قانونية.

صنّف الأخطاء قبل أن تعيد المحاولة

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

• خطأ يُصلَح من المصدر: يعود إلى مالك الحقل.
• خطأ مؤقت: يُعاد تلقائيًا ضمن حدود.
• خطأ يحتاج مراجعة بشرية: يُصعَّد بسبب واضح.

مؤشرات جودة البيانات

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

كيف يبدو هذا في منصة الفاتورة

في الفاتورة كونكت يرسل نظامك شكل JSON واحدًا، ونتولى التحويل والتحقق قبل الختم والإرسال:

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

وإن كنت ما زلت تقارن بين بناء هذه الطبقة بنفسك أو الاعتماد على منصة، فابدأ من هل تبني ربط زاتكا بنفسك أم تشتريه؟.

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