الفوترة الإلكترونية في السعودية: ما تتطلبه هيئة الزكاة والضريبة (فاتورة) فعليًا
زاتكا ليست صيغة تُضاف في نهاية المسار، بل نظام تصديق تتخلله سلسلة تجزئة. نوعا الفاتورة، وسلسلة ICV/PIH التي تقيّد معماريتك، وموضع الختم التشفيري.
زاتكا ليست صيغة يمكن إضافتها في نهاية مسار الفوترة لديك. إنها نظام تصديق تتخلله سلسلة تجزئة — وللسلسلة رأي في طريقة بناء ذلك المسار. وهذا هو الجزء الذي تغفله معظم خطط التكامل.
زاتكا في فقرة واحدة
الفاتورة الإلكترونية السعودية مبنية على UBL 2.1 — لكنها ليست EN 16931. تحمل ProfileID بقيمة «reporting:1.0» دون CustomizationID، ورمز نوع فاتورة من سبع خانات، ورمز QR خاصًا بها، وسلسلة تكامل. المرحلة الثانية (الربط) هي المرحلة السارية: توقّع الفاتورة، ثم تصدّقها أو تبلّغ عنها بحسب هوية المشتري.
نوعان مختلفان فعليًا من الفواتير
- الفاتورة الضريبية القياسية (B2B / B2G) — تُصدَّق قبل تسليمها إلى المشتري. ترسلها، فتضيف الهيئة ختمها وتعيد إليك الفاتورة المصدَّقة، وتلك النسخة المعادة هي الفاتورة القانونية، لا نسختك.
- الفاتورة الضريبية المبسطة (B2C) — يُبلَّغ عنها خلال 24 ساعة من الإصدار. هنا يكون رمز QR الخاص بك هو النهائي، ويحصل العميل على الفاتورة فورًا.
الحقول الإلزامية تختلف فعليًا بين النوعين: القياسية تتطلب الرقم الضريبي للمشتري وعنوانه الكامل، والمبسطة لا تتطلب ذلك. قد تغريك فكرة نمذجة شكل واحد مع مؤشر تبديل — قاوم ذلك، فالفرق ليس شكليًا، ورمز النوع من سبع خانات يعلن أيهما قصدت.
الجزء الذي يكسر المسارات: ICV و PIH
كل فاتورة زاتكا تحمل حقلَي سلسلة: عدّاد ICV تسلسلي بلا فجوات، و PIH وهو تجزئة SHA-256 للفاتورة السابقة مُرمّزة بـ base64. كل فاتورة تشير إلى سابقتها. إنها سلسلة تجزئة لكل وحدة إصدار.
هذا متطلب معماري يرتدي زيّ حقل بيانات. أصدر فاتورتين بالتوازي لنفس الوحدة وتكون قد شطرت السلسلة. أعد محاولة واحدة خارج الترتيب وتكون قد كسرتها. إذا كان نظام الفوترة لديك موزّعًا أفقيًا وعديم الحالة — وهو التصميم المعقول عادةً — فإن السعودية تطلب منك إضافة عدّاد دائم ومتسلسل بصرامة لكل وحدة. هذا تغيير في التصميم، لا مجرد ربط حقول، واكتشافه الآن أرخص بكثير من اكتشافه بعد الإطلاق.
الختم التشفيري مسألة حفظ مفاتيح، لا رسوم
التوقيع يتطلب CSID: شهادة تصدرها الهيئة مرتبطة بمكلّف سعودي مسجَّل فعليًا في ضريبة القيمة المضافة. أمران يستحقان المعرفة لأن الافتراض الشائع فيهما خاطئ: الهيئة لا تتقاضى أي رسوم مقابل الشهادة أو واجهات البرمجة — لا توجد رسوم اعتماد. والبيئة التجريبية تعمل برمز OTP وهمي، فيمكنك بناء المسار كاملًا واختباره دون مكلّف سعودي. القيد الحقيقي الوحيد أن شهادة الإنتاج تعود لمنشأة مسجَّلة فعلًا.
إذن الختم ليس مشكلة تكلفة، بل مشكلة حفظ مفاتيح: على أحدهم أن يحتفظ بذلك المفتاح الخاص.
أين يقع MyInvoice — وأين يتوقف
ننتج مستند زاتكا كاملًا ومطابقًا للـ XSD — قياسيًا كان أم مبسطًا، مع رمز نوع الفاتورة وحقول سلسلة ICV/PIH ورمز QR للمرحلة الأولى — انطلاقًا من البيانات التي تصدّرها أصلًا:
curl -X POST https://api.myinvoice.llc/v1/convert \
-H "X-API-Key: ek_live_..." \
-F "[email protected]" \
-F "format=csv" \
-F "profile=zatca-sa"وما لا نفعله عن قصد: التوقيع. يخرج المستند غير موقَّع، ويبقى الختم التشفيري ونداء التصديق أو الإبلاغ لدى نظامك المُسجَّل في فاتورة — وهو المكان الطبيعي لمفتاحك الخاص على أي حال. نفضّل أن نقول ذلك بوضوح على أن نسلّمك مستندًا يبدو مكتملًا وهو ليس كذلك.
أما رمز QR فهو بنية TLV مُرمّزة بـ base64. الوسوم من 1 إلى 5 حقائق فاتورة بسيطة — اسم البائع، والرقم الضريبي، والطابع الزمني، والإجمالي، وإجمالي الضريبة. أما الوسوم من 6 إلى 9 فتُشتق من الختم. لذا فإن رمز QR قبل الختم يحمل الوسوم 1–5 ليس رمزًا معطوبًا، بل هو الرمز الصادق.
أنشئ فاتورة سعودية في متصفحكتُحدِّث الهيئة مواصفاتها ونقاط النهاية بانتظام — تحقق دائمًا من قائمة الحقول الإلزامية وعقد الواجهة البرمجية الحاليين مقابل حزمة التطوير والوثائق الرسمية قبل الإطلاق.
اقرأ وثائق الواجهة البرمجية