دليل المطور الشامل للفوترة الإلكترونية فاتورة: المرحلة الأولى والثانية

الفاتورة الإلكترونية في السعودية ليست ميزة PDF. بل هي بنية ضريبية تفرضها هيئة الزكاة والضريبة والجمارك. منذ ديسمبر 2021 تشترط المرحلة الأولى الإصدار الإلكتروني، ومنذ 2023 تشترط موجات المرحلة الثانية المقاصة أو الإبلاغ عبر API. إذا كنت تبني SaaS أو ERP أو نقاط بيع أو متاجر مخصصة لعملاء سعوديين فإن تكامل فاتورة يحدد هل برنامجك قابل للبيع.

يغطي هذا الدليل النظام ونموذج البيانات والتسجيل والتوقيع ومعالجة الأخطاء والتشغيل لتكاملات فاتورة الإنتاجية.

1. الخلفية النظامية بتبسيط

كل منشأة مسجلة في القيمة المضافة مع توريدات خاضعة يجب أن تصدر فواتير إلكترونية. ويشمل ذلك فواتير B2B الضريبية وفواتير B2C المبسطة وإشعارات الدائن والمدين. والورق أو PDF بدون XML مهيكل لم يعد متوافقا.

المرحلة الأولى من 4 ديسمبر 2021 هي عن التوليد. يجب إنتاج UBL 2.1 مع حقول إلزامية ورمز QR مع PDF/A-3 مقروء يتضمن XML. ولم يكن هناك استدعاء API لكن الهيئة قد تدقق الصيغة.

المرحلة الثانية المسماة الربط هي بموجات حسب الإيراد. وتبلغ الهيئة كل مكلف بموعد موجته بدءا من كبرى المؤسسات 2023 إلى المنشآت الصغيرة 2024 إلى 2026. وبعد موعدك يجب ربط وحدات EGS. والفواتير الضريبية تستخدم المقاصة والمبسطة تستخدم الإبلاغ. وتجاوز الموعد يعرض للغرامات وتعطيل النشاط.

افهم هذا التقسيم لأن البنية تتبعه. المقاصة متزامنة وحاجبة. والإبلاغ شبه فوري بمهلة 24 ساعة.

2. الضريبية مقابل المبسطة بالتفصيل

الفاتورة الضريبية هي B2B حيث يملك المشتري رقما ضريبيا. والمسار هو إنشاء مسودة في نظامك ثم توقيع محلي ثم POST لنقطة مقاصة الهيئة ثم استلام فاتورة مختومة بتوقيع الهيئة وHash وQR ثم تسليم النسخة المختومة للمشتري عبر إيميل أو بوابة. والنسخة المختومة فقط هي القانونية. ولا ترسل ما قبل المقاصة كنهائية.

الفاتورة المبسطة هي B2C للتجزئة ونقاط البيع والمتاجر للأفراد. والمسار هو إصدار فوري للعميل مع QR ثم إبلاغ الهيئة خلال 24 ساعة. وتعيد الهيئة إقرارا لكنها لا تحجب الإصدار. وهذا يسمح لنقاط البيع دون اتصال بالبيع أثناء انقطاع الإنترنت طالما يفرغ الطابور بالوقت.

إشعارات الدائن للمرتجعات والمدين للتعديلات تعكس النوع الأب. ومرتجع B2B يحتاج مقاصة ومرتجع B2C يحتاج إبلاغا. وحافظ على الربط عبر BillingReference إلى UUID وICV الأصل.

3. نموذج البيانات الذي يجب ضبطه

حقول UBL التي تكسر معظم التكاملات هي العداد والطوابع الزمنية وحساب الضريبة وبيانات الأطراف.

عداد ICV يجب أن يكون تسلسليا لكل EGS بدون فجوات. وإذا فشلت المقاصة بتحقق لا ترفع. وأعد نفس ICV وUUID. وإذا ألغيت أصدر إشعار دائن بدل الحذف. والمدققون يفحصون الفجوات.

وUUID يجب أن يكون فريدا نسخة 4 لكل فاتورة. والطوابع تحتاج تاريخا ووقتا بالثواني بتوقيت السعودية وساعة الخادم مضبوطة NTP خلال دقائق من وقت الهيئة. والانحراف يسبب الرفض.

وكتلة البائع تحتاج الاسم المسجل عربيا وإنجليزيا كما في السجل التجاري ورقما ضريبيا من 15 رقما يبدأ بـ 3 وعنوانا مع حقول العنوان الوطني حيث توفر. وكتلة المشتري لـ B2B تحتاج رقم المشتري واسمه. ولـ B2C يمكن حدا أدنى.

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

وQR هو TLV base64 مع وسوم 1 اسم البائع و2 الرقم الضريبي و3 الطابع و4 الإجمالي مع الضريبة و5 مبلغ الضريبة و6 الـ Hash والتوقيع للمرحلة الثانية. وترتيب الوسوم مهم. والترميز يجب UTF-8 للأسماء العربية.

4. تسجيل EGS خطوة بخطوة

وEGS هي كل جهاز فوترة منطقي أو نظام فرع. وSaaS بعشرة فروع يحتاج عشر وحدات.

الخطوة الأولى OTP من بوابة فاتورة. ويدخل المدير بحساب الضريبة ويختار تسجيل EGS ويستلم OTP من 6 أرقام صالح ساعة تقريبا. والخطوة الثانية CSR بمفتاح secp256k1. وولد المفتاح محليا وأنشئ CSR مع المنظمة والرقم الضريبي وتسلسل EGS. ولا ترفع المفتاح إلى git أبدا.

والخطوة الثالثة شهادة الامتثال. وأرسل CSR مع OTP لنقطة الامتثال واستلم binarySecurityToken وسرا للاختبار. والخطوة الرابعة فحوص الامتثال. وأرسل 3 إلى 6 عينات تغطي ضريبية ومبسطة ودائنة ضريبية ودائنة مبسطة مع حالات مثل خصم وإعفاء. وعالج تحذيرات قواعد BR-KSA قبل المتابعة.

والخطوة الخامسة شهادة الإنتاج PCSID. واستدعِ الإصدار الإنتاجي مع معرف طلب الامتثال واستلم شهادة طويلة. وخزن الشهادة مع المفتاح في خزنة مثل AWS Secrets أو Azure Key Vault أو HSM للحجم العالي. والخطوة السادسة التجديد والإلغاء. وتتبع الانتهاء في لوحة التشغيل ودور قبل الموعد. وألغِ عند استبدال الجهاز.

وافصل بيانات التجريبي والمحاكاة والإنتاج صارما. وكثيرا ما يخلط المطورون التوكن ويضيعون أياما في أخطاء 401.

5. خط التوقيع بالكود

لا تكتب XML يدويا. واستخدم SDK الرسمي لجافا ودوت نت وجافاسكربت. والمسار هو اربط نموذج الطلب إلى كائن UBL ثم canonicalize ثم Hash بـ SHA256 ثم وقع بمفتاح ECDSA ثم ضمن التوقيع وQR ثم تحقق محليا من XSD مع schematron.

وفي Node ابنِ JSON ثم حول إلى XML ثم نفذ دالة التوقيع مع مسارات الشهادة والمفتاح واستلم XML الموقع والـ Hash وQR. وفي دوت نت استخدم توقيع SDK مع مخزن الشهادات. وسجل دائما كود قاعدة الهيئة عند الفشل مثل BR-KSA-08 لعدم تطابق الضريبة.

والأداء مهم. والتوقيع ثقيل CPU. ولنقاط بيع 50 فاتورة بالدقيقة سخن SDK وأعد استخدام مقابض المفاتيح وافصل طوابير التوقيع عن طوابير API.

6. API المقاصة والإبلاغ

نقطة المقاصة تقبل Hash وUUID وbase64 للفاتورة الموقعة مع توكن PCSID. والنجاح يعيد 200 مع فاتورة مختومة وHash وQR للطباعة. وفشل التحقق يعيد 400 مع رموز قواعد. وخطأ خادم يعيد 500 ويجب إعادة نفس UUID.

والقاعدة الحاسمة هي منع التكرار. ومهلة الشبكة لا تعني الرفض. وقبل إعادة الإرسال استعلم بالـ Hash. وتكرار ICV بمحتوى مختلف يطلق أعلام تدقيق.

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

وابنِ جدول outbox موحدا مع أعمدة UUID وICV والنوع والحالة queued أو cleared أو reported أو failed والمحاولات وآخر خطأ ورد الهيئة. وعامل خلفية يفرغه مع تراجع أسي.

7. PDF وتجربة المستخدم السعودي

يجب أن يكون PDF/A-3 مع XML مضمن ويعرض اسمي البائع عربيا وإنجليزيا والرقمين الضريبيين لـ B2B وتفصيل ضريبة الأسطر والإجماليات وQR كبيرا يكفي للمسح من الجوال مع شارة مختوم بعد المقاصة. وأضف شروط الدفع ورقم السجل ورقم الدعم. ولـ B2C أبق إيصالا من صفحة مع إجمالي كبير بالريال.

8. التشغيل والمراقبة والتدقيق

راقب نسبة نجاح المقاصة فوق 99.5 بالمئة وزمن p95 وعمر الطابور وأيام انتهاء الشهادة. ولوحة لكل عميل مع عد تنازلي لموعد الموجة. وانسخ المفاتيح يوميا مشفرة خارجيا وأرشف الفواتير 6 سنوات حسب نظام الضريبة وقواعد PDPL.

وحوادث الإنتاج الشائعة هي انحراف الساعة بعد ترحيل VM وفجوات ICV بعد تعديل DB يدوي وQR غير مقروء لضعف تباين الطباعة وانتهاء PCSID في العطل. ويجب أن تغطي runbooks كل حالة مع رجوع لوضع مبسط دون اتصال حيث يسمح نظاما.

9. المدد والتكاليف

نقطة بيع فرع واحد أسبوعان إلى ثلاثة مع التجريبي والمحاكاة. وERP متعدد الفروع مع إشعارات وإعفاءات 6 إلى 10 أسابيع. وSaaS متعدد المستأجرين مع EGS لكل عميل 8 إلى 12 أسبوعا مع دعم الموجات.

واحسب خطوات البوابة العربية فقط وتأخر مدير ضريبة العميل في OTP والاختبار بأرقام ضريبية سعودية حقيقية. واعرض فاتورة كوحدة امتثال مدفوعة مع صيانة سنوية لتدوير الشهادات وتحديثات القواعد.

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