تكامل بوابة فاتورة لزكاتكا

دليل API كامل للامتثال للمرحلة الثانية من الفوترة الإلكترونية

آخر تحديث: ٣٠ مارس ٢٠٢٦

📋 المتطلبات الأساسية للتكامل

حساب مكلف ZATCA نشط مع TRN صالح
شهادة CSD من مزود معتمد من زكاتكا
فريق تقني لديه خبرة في تطوير API
الوصول إلى بيئة الاختبار للاختبار قبل الإنتاج
قدرة إنشاء XML بتنسيق UBL 2.1
إنشاء رمز QR مع ترميز TLV و Base64

🔗 نقاط نهاية API لفاتورة

Endpoint Name	Endpoint URL	Method	Description
الموافقة (B2B)	https://api.fatoora.zatca.gov.sa/api/v1/invoice/clearance	POST	التحقق في الوقت الفعلي لفواتير B2B
الإبلاغ (B2C)	https://api.fatoora.zatca.gov.sa/api/v1/invoice/reporting	POST	تقديم خلال ٢٤ ساعة لفواتير B2C
إنشاء CSR	https://api.fatoora.zatca.gov.sa/api/v1/csr	POST	إنشاء طلب توقيع الشهادة
فحص الامتثال	https://sandbox.fatoora.zatca.gov.sa/api/v1/compliance	POST	التحقق من XML قبل التقديم

🔐 المصادقة (OAuth 2.0)

تستخدم واجهات برمجة تطبيقات فاتورة OAuth 2.0 مع بيانات اعتماد العميل. بعد تثبيت شهادة CSD، يجب الحصول على بيانات الاعتماد من بوابة زكاتكا:

تسجيل الدخول إلى بوابة فاتورة زكاتكا بحساب المكلف الخاص بك
انتقل إلى إعدادات المطور → بيانات اعتماد API
إنشاء client_id و client_secret جديدين
تخزين بيانات الاعتماد بشكل آمن
استخدام بيانات الاعتماد للحصول على access_token عبر نقطة نهاية OAuth 2.0
تضمين access_token في رأس الترخيص لجميع استدعاءات API

نقطة نهاية الرمز المميز: https://api.fatoora.zatca.gov.sa/oauth2/token

⚙️ عملية التكامل خطوة بخطوة

✓ ١. التسجيل في بوابة فاتورة زكاتكا والحصول على CSR

✓ ٢. شراء وتثبيت شهادة CSD من مزود معتمد

✓ ٣. إنشاء بيانات اعتماد API من بوابة زكاتكا

✓ ٤. اختبار جميع استدعاءات API في بيئة الاختبار قبل الإنتاج

✓ ٥. تنفيذ إنشاء فواتير XML بتنسيق UBL 2.1

✓ ٦. إنشاء رمز QR مع طابع تشفيري

✓ ٧. تقديم الفواتير عبر نقطة نهاية الموافقة أو الإبلاغ

✓ ٨. معالجة ردود زكاتكا بشكل مناسب

✓ ٩. تنفيذ webhook أو عنوان URL لرد الاتصال للردود غير المتزامنة

✓ ١٠. الانتقال إلى الإنتاج بعد اختبار بيئة الاختبار الناجح

💻 نموذج استدعاء API (PHP cURL)

إليك مثال كامل لـ PHP cURL لتقديم فاتورة إلى نقطة نهاية الموافقة:

<?php
// ZATCA فاتورة API - تقديم فاتورة الموافقة
$access_token = "YOUR_ACCESS_TOKEN";
$xml_invoice_data = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Invoice>...</Invoice>";
$qr_base64 = "Base64EncodedQRDataHere";

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.fatoora.zatca.gov.sa/api/v1/invoice/clearance",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . $access_token,
        "Content-Type: application/json",
        "Accept-Language: en"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "invoice" => base64_encode($xml_invoice_data),
        "qr_code" => $qr_base64
    ])
]);

$response = curl_exec($curl);
$http_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$curl_error = curl_error($curl);
curl_close($curl);

if ($http_code == 200) {
    $result = json_decode($response, true);
    echo "Invoice Status: " . $result["status"];
} else {
    echo "Error: HTTP $http_code - $curl_error";
}
?>

📨 فهم ردود API لزكاتكا

CLEARED

تم قبول الفاتورة من قبل زكاتكا. يمكنك مشاركتها مع المشتري.

Action: المتابعة مع التسليم

REJECTED

فشل التحقق من الفاتورة. تحقق من هيكل XML والحقول.

Action: تصحيح وإعادة تقديم فاتورة جديدة

REPORTED

تم قبول الفاتورة للإبلاغ (لا يوجد تحقق في الوقت الفعلي).

Action: لا حاجة لمزيد من الإجراءات

PENDING

الفاتورة قيد المراجعة. انتظر الحالة النهائية.

Action: تنفيذ webhook لتلقي التحديث

⚠️ معالجة الأخطاء ورموز الحالة

HTTP Code	Meaning	Solution
200	نجاح - تمت معالجة الفاتورة بشكل صحيح	مواصلة التدفق الطبيعي
400	طلب غير صالح - تنسيق XML غير صالح أو حقول مفقودة	التحقق من XML مقابل مخطط UBL 2.1
401	غير مصرح - فشلت المصادقة	التحقق من صحة access_token وإعادة إنشائه إذا انتهت صلاحيته
403	محظور - شهادة CSD منتهية الصلاحية أو غير صالحة	تجديد شهادة CSD فورًا
429	تم تجاوز حد المعدل - عدد الطلبات كبير جدًا	تنفيذ التراجع الأسي وتقليل معدل الطلبات
500	خطأ في الخادم الداخلي - مشكلة في خادم زكاتكا	إعادة المحاولة مع التراجع الأسي
503	الخدمة غير متوفرة - صيانة أو حمل زائد	الانتظار وإعادة المحاولة بعد ٥-١٠ دقائق

🧪 بيئة الاختبار (الاختبار)

اختبر دائمًا تكاملك في بيئة اختبار زكاتكا قبل الانتقال إلى الإنتاج:

شهادات CSD اختبارية متاحة مجانًا
ردود API محاكاة لجميع نقاط النهاية
لا يوجد التحقق الضريبي الحقيقي - آمن للاختبار
نفس هيكل API مثل الإنتاج

🔗 https://sandbox.fatoora.zatca.gov.sa

✅ أفضل الممارسات للإنتاج

تنفيذ التحديث التلقائي للرمز المميز قبل انتهاء صلاحيته
تخزين جميع ردود API في قاعدة البيانات لمسار التدقيق
تنفيذ منطق إعادة المحاولة مع التراجع الأسي للطلبات الفاشلة
مراقبة حدود المعدل وتنفيذ نظام قائمة انتظار للحجم الكبير
استخدام webhooks للتحديثات غير المتزامنة للحالة
الاحتفاظ بتذكيرات انتهاء صلاحية شهادة CSD
اختبار جميع التغييرات في بيئة الاختبار قبل النشر في الإنتاج
الاحتفاظ بسجلات مفصلة لجميع استدعاءات API والردود

❓ الأسئلة الشائعة

Q: كم من الوقت يستغرق رد API؟

A: نقطة نهاية الموافقة: ٢-٥ ثوانٍ (متزامن). نقطة نهاية الإبلاغ: رد في غضون ثوانٍ (غير متزامن)، ولكن قد يتم تحديث حالة الفاتورة لاحقًا عبر webhook.

Q: ما هو حد المعدل لواجهات برمجة تطبيقات فاتورة؟

A: الحد القياسي هو ١٠ طلبات في الثانية. للأحجام الأعلى، اتصل بدعم زكاتكا لطلب حدود متزايدة. قم بتنفيذ نظام قائمة انتظار للتقديمات المجمعة.

Q: هل يمكنني استخدام نفس رمز الوصول لطلبات متعددة؟

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

Q: ماذا لو تم رفض فاتورتي؟

A: لا يمكنك تحرير فاتورة مرفوضة. يجب عليك تصحيح المشكلة في نظامك وتقديم فاتورة جديدة برقم فاتورة جديد. لا يمكن إعادة تقديم الفواتير المرفوضة.

Q: كيف يمكنني الحصول على شهادة CSD اختبارية لبيئة الاختبار؟

A: توفر بيئة اختبار زكاتكا شهادات CSD اختبارية مجانًا. يمكنك إنشاؤها مباشرة من بوابة بيئة الاختبار دون الشراء من مقدمي الخدمات التجاريين.

Q: ما الفرق بين واجهات برمجة التطبيقات المتزامنة وغير المتزامنة؟

A: الموافقة متزامنة - تنتظر ردًا فوريًا. الإبلاغ غير متزامن - تقدم وتتلقى إقرارًا، لكن الحالة النهائية تأتي لاحقًا عبر webhook.

Q: هل أحتاج إلى عنوان IP ثابت لـ API فاتورة؟

A: لا، IP الثابت غير مطلوب. ومع ذلك، تأكد من عدم حظر IP الصادر لخادمك بواسطة جدار حماية زكاتكا.

Q: ما هو تنسيق عنوان URL webhook المقبول؟

A: تقبل زكاتكا نقاط نهاية HTTPS فقط. يجب أن يكون عنوان URL متاحًا للجمهور. استخدم طريقة POST لاستقبال حمولات JSON مع تحديثات حالة الفاتورة.

📚 موارد زكاتكا ذات الصلة

📘 Complete Guide 🔐 CSD Certificate ⚖️ Clearance vs Reporting 📄 Tax Invoice Format