إطار تكامل الفوترة الإلكترونية خطوة بخطوة للسعودية
آخر تحديث: ٣٠ مارس ٢٠٢٦
تتطلب المرحلة الثانية من زكاتكا (هيئة الزكاة والضريبة والجمارك) من جميع الشركات الخاضعة للضريبة في السعودية دمج أنظمتها للفوترة الإلكترونية. يغطي هذا الدليل الشامل كل ما تحتاج إلى معرفته - من شهادات CSD إلى تكامل API.
إنشاء طلب توقيع الشهادة (CSR) من خلال بوابة فاتورة لربط نظام نقاط البيع الخاص بك.
بدء الربط: إنشاء طلب توقيع الشهادة (CSR) من خلال بوابة فاتورة لربط نظامك.
يجب إنشاء الفواتير بتنسيق XML UBL 2.1 بما في ذلك UUID والتجزئة ورمز QR.
إنشاء ملف XML: يجب إنشاء الفواتير بتنسيق UBL 2.1 بما في ذلك الـ UUID والهاش والرمز.
يجب أن يكون رمز QR بتنسيق TLV المشفر بـ Base64. استخدم أداة صفحتنا الرئيسية للتحقق من ترميز QR الخاص بك.
معايير الرمز: يجب أن يكون الرمز مشفرًا بتنسيق Base64 TLV. استخدم أدواتنا للفحص.
يجب الإبلاغ عن جميع الفواتير الضريبية المبسطة في غضون ٢٤ ساعة من الإنشاء.
الإبلاغ اللحظي: يجب الإبلاغ عن جميع الفواتير الضريبية المبسطة في غضون 24 ساعة.
المرحلة الثانية هي مرحلة التكامل الإلزامي حيث يجب على المكلفين ربط أنظمتهم مباشرة ببوابة فاتورة التابعة لزكاتكا عبر واجهات برمجة التطبيقات. على عكس المرحلة الأولى (التي تطلبت فقط رموز QR على الفواتير)، تتطلب المرحلة الثانية تقديم بيانات الفاتورة في الوقت الفعلي أو شبه الفعلي.
شهادة CSD إلزامية للمرحلة الثانية. تمكن التوقيع الرقمي والطابع التشفيري للفواتير. يجب الحصول عليها من مزودين معتمدين من زكاتكا مثل Geotrust أو Digicert.
يجب إنشاء جميع الفواتير بتنسيق XML UBL 2.1 الموحد. يتضمن حقلاً محددة لتفاصيل البائع/المشتري وبنود العناصر ومبالغ الضريبة والأختام التشفيرية.
يجب أن يحتوي رمز QR على طابع تشفيري مشفر بتنسيق TLV ثم Base64. يشمل اسم البائع و TRN والطابع الزمني وإجمالي الفاتورة ومبلغ الضريبة والتوقيع الرقمي.
نموذج الموافقة (B2B): التحقق الفوري من زكاتكا قبل أن يستلم المشتري الفاتورة. نموذج الإبلاغ (B2C): التقديم في غضون ٢٤ ساعة من الإصدار. اختر بناءً على نوع المعاملة الخاصة بك.
الخطوة ١: التسجيل في بوابة فاتورة. الخطوة ٢: إنشاء CSR والحصول على شهادة CSD. الخطوة ٣: إنشاء بيانات اعتماد API. الخطوة ٤: تنفيذ إنشاء XML بتنسيق UBL 2.1. الخطوة ٥: تنفيذ إنشاء رمز QR مع ترميز TLV. الخطوة ٦: اختبار جميع واجهات برمجة التطبيقات في بيئة اختبار زكاتكا. الخطوة ٧: التقدم بطلب للحصول على الوصول إلى الإنتاج. الخطوة ٨: الانتقال إلى الإنتاج بنموذج الموافقة أو الإبلاغ.
| Endpoint Name | URL | Method |
|---|---|---|
| الموافقة (B2B) | https://api.fatoora.zatca.gov.sa/api/v1/invoice/clearance | POST |
| الإبلاغ (B2C) | https://api.fatoora.zatca.gov.sa/api/v1/invoice/reporting | POST |
| إنشاء CSR | https://api.fatoora.zatca.gov.sa/api/v1/csr | POST |
| فحص الامتثال | https://sandbox.fatoora.zatca.gov.sa/api/v1/compliance | POST |
A: تختلف المواعيد النهائية حسب إيرادات الشركة. لدى دافعي الضرائب الكبار (أكثر من ٣ ملايين ريال) مواعيد نهائية مبكرة. تحقق من بوابة زكاتكا لتاريخ التكامل الخاص بك.
A: نعم، ما لم يقدم مزود نقاط البيع الخاص بك تكاملًا مدمجًا مع زكاتكا. يتطلب تطوير API خبرة فنية في PHP و REST API وإنشاء XML والتشفير.
A: لا. شهادات SSL المجانية (مثل Let's Encrypt) غير مقبولة. يجب عليك شراء شهادة CSD مدفوعة من مزودين معتمدين من زكاتكا مثل Geotrust أو Digicert.
A: قد تفرض زكاتكا غرامات تصل إلى ٥٠,٠٠٠ ريال وتعلق امتيازات الفوترة الإلكترونية الخاصة بك. لن يتمكن عملك من إصدار فواتير إلكترونية متوافقة.
A: عادة ٥-١٠ أيام عمل بعد تقديم جميع المستندات المطلوبة إلى مزود معتمد. خطط جيدًا قبل الموعد النهائي للتكامل الخاص بك.
A: توفر زكاتكا بيئة اختبار (محاكاة) على https://sandbox.fatoora.zatca.gov.sa. اختبر جميع استدعاءات API قبل الانتقال إلى الإنتاج.