0

ربط ZATCA API مع FATOORA: دليل تكامل الفوترة الإلكترونية

خالد ترليون خالد ترليون

🕒 آخر مراجعة: أكتوبر 2026

تنبيه للمطورين: تتغير مواصفات ZATCA وواجهات API وبيئات الاختبار والإنتاج. استخدم هذا المقال للفهم والتخطيط، ثم راجع أحدث نسخة من Developer Portal قبل تنفيذ التكامل في بيئة الإنتاج.

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

يشرح هذا الدليل طريقة التخطيط لتكامل نظام الفوترة مع ZATCA باستخدام API، ومتطلبات XML وUBL 2.1 وCSID والتوقيع التشفيري وHash وUUID، مع أمثلة تعليمية لاختبار النظام ومعالجة الأخطاء وفصل بيئة الاختبار عن بيئة الإنتاج.

  • 4 طرق شائعة لتكامل نظام الفوترة مع ZATCA.
  • UBL 2.1 أساس بنية XML المستخدمة في مواصفات الفوترة السعودية.
  • 24 ساعة مهلة Reporting للفواتير الضريبية المبسطة بعد إصدارها.
  • CSID شهادة تشفير وهوية رقمية مرتبطة بوحدة إصدار الفواتير.
  • Clearance للفواتير الضريبية القياسية وفق متطلبات المرحلة الثانية.

تمت المراجعة: تمت مراجعة الهيكل مقابل المواد التقنية والإرشادات الرسمية المنشورة من ZATCA، بما في ذلك متطلبات المرحلة الثانية ومواصفات XML والمتطلبات الأمنية. آخر تحديث للمقال: أكتوبر 2026.

الخلاصة السريعة

  • ما هو التكامل؟ ربط حل إصدار الفواتير بمنصة FATOORA عبر واجهات API.
  • لمن؟ للمنشآت الخاضعة للفوترة الإلكترونية التي دخل موعد تكاملها ضمن موجات المرحلة الثانية.
  • الخيارات؟ برنامج فوترة جاهز، أو تكامل ERP، أو تطوير مخصص، أو Middleware.
  • أهم المتطلبات؟ XML وفق مواصفات ZATCA المبنية على UBL 2.1، وCSID، والتوقيع التشفيري، وHash، وUUID، ومتطلبات الأمان.
  • Clearance أم Reporting؟ يعتمد المسار على نوع المستند. الفواتير الضريبية القياسية تخضع لـClearance، بينما تُرسل الفواتير الضريبية المبسطة إلى FATOORA عبر Reporting خلال 24 ساعة من إصدارها. [714]

الإجابة المباشرة: يتطلب تكامل المرحلة الثانية ربط حل إصدار الفواتير بمنصة FATOORA وإرسال المستندات وفق المتطلبات الفنية الرسمية. تُعالج الفواتير الضريبية القياسية عبر Clearance، بينما تُرفع الفواتير الضريبية المبسطة إلى FATOORA عبر Reporting خلال 24 ساعة من إصدارها.

شرح تكامل API للفوترة الإلكترونية مع منصة ZATCA في المرحلة الثانية
مخطط يوضح تكامل API للفوترة الإلكترونية مع منصة FATOORA التابعة لـZATCA.

ما معنى ربط API بحلول الفوترة الإلكترونية؟

واجهة برمجة التطبيقات API هي قناة تقنية تسمح لحل الفوترة الإلكتروني بالتواصل مع خدمات ZATCA ومنصة FATOORA بطريقة آلية.

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

في المرحلة الأولى كان التركيز على إصدار الفواتير الإلكترونية وحفظها. أما المرحلة الثانية فتضيف متطلبات التكامل مع منصة الهيئة والصيغ والحقول والمتطلبات الأمنية المحددة من ZATCA.

تطبق المرحلة الثانية تدريجيًا على شكل موجات، وتُبلغ الهيئة المنشآت المستهدفة بموعد التكامل الخاص بها.

يمكنك متابعة آخر التعليمات من بوابة الفوترة الإلكترونية الرسمية لـZATCA .

وللاطلاع على العقوبات والمتطلبات النظامية ذات الصلة، راجع أيضًا دليل غرامات ZATCA للفوترة الإلكترونية .

لماذا تكامل الفوترة الإلكترونية مع ZATCA مهم؟

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

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

طرق ربط API بحلول الفوترة الإلكترونية

تختلف طريقة التكامل حسب حجم المنشأة، ونظام المحاسبة أو ERP المستخدم، وعدد الفواتير، وقدرة الفريق التقني على إدارة التكامل والصيانة.

1. برنامج فوترة إلكترونية جاهز ومتوافق

هذا الخيار مناسب للمنشآت التي لا تريد بناء التكامل داخليًا. يتولى مزود الحل عادةً توليد المستندات وإدارة متطلبات الفوترة والتكامل مع خدمات ZATCA وفق ما يدعمه الحل.

المناسب لـ: المنشآت الصغيرة والمتوسطة التي تريد تقليل التطوير البرمجي الداخلي.

2. ربط نظام ERP الحالي

إذا كانت المنشأة تستخدم نظام ERP مثل SAP أو Oracle أو Microsoft Dynamics، يمكن بناء طبقة تكامل تربط النظام بحل الفوترة الإلكتروني وخدمات ZATCA.

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

المناسب لـ: الشركات المتوسطة والكبيرة التي لديها نظام ERP وفريق تقني أو شريك تكامل.

3. تطوير مخصص باستخدام API

يمكن للشركات التي لديها منصة تجارة إلكترونية أو نظام ERP داخلي أو تطبيق خاص بناء حل تكامل وفق مواصفات ZATCA الرسمية.

يتطلب ذلك فهم XML وUBL 2.1 وبنية المستند والتوقيع التشفيري وUUID وHash وإدارة الشهادات والاستجابات والأخطاء.

للمطورين، راجع: شرح XML UBL 2.1 وربط ZATCA API للمطورين .

المناسب لـ: الشركات التقنية والمنشآت التي لديها فريق تطوير داخلي.

4. وسيط برمجي Middleware أو iPaaS

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

للمتاجر الإلكترونية، راجع: دليل ربط Shopify مع ZATCA .

المناسب لـ: المتاجر والمنشآت التي لديها أنظمة متعددة.

مقارنة طرق التكامل

طريقة الربط التعقيد طبيعة التكلفة الفريق التقني
برنامج جاهز منخفض اشتراك أو ترخيص محدود
ربط ERP متوسط إعداد وتكامل وصيانة متوسط
تطوير API مخصص مرتفع تطوير وصيانة مرتفع
Middleware / iPaaS منخفض إلى متوسط اشتراك وإعداد متوسط

خطوات التكامل مع FATOORA

  1. حدد نطاق التكامل وموعد المنشأة.

    تحقق من موجة المرحلة الثانية التي تنتمي إليها المنشأة وموعد التكامل المحدد لها في إشعار ZATCA.

  2. اختر حل الفوترة الإلكتروني.

    اختر بين حل جاهز أو تكامل ERP أو تطوير مخصص أو Middleware، وتأكد من أن الحل يحقق المتطلبات الفنية والأمنية.

  3. جهز عملية Onboarding.

    أعد وحدة إصدار الفواتير الإلكترونية وربطها بمتطلبات FATOORA، بما في ذلك إجراءات الهوية التشفيرية والشهادات المطلوبة.

  4. أنشئ CSR واحصل على CSID الاختباري.

    يجب إنشاء طلب الشهادة CSR وفق متطلبات ZATCA، ثم استخدام إجراءات الاختبار أو Onboarding للحصول على CSID اختباري قبل الانتقال إلى الإنتاج. لا تستخدم شهادة الإنتاج داخل بيئة التطوير. [700]

  5. اختبر المستندات في بيئة الاختبار.

    اختبر XML والتوقيع وHash وUUID وQR والاستجابات وحالات الرفض وانقطاع الاتصال وإعادة المحاولة.

  6. استخدم أدوات ZATCA للتحقق.

    تساعد أدوات ZATCA على التحقق من توافق المستندات، لكن اجتياز أداة التحقق لا يعني أن الهيئة وافقت على كل عملية تجارية أو أعفت المنشأة من المسؤولية.

  7. انتقل إلى الإنتاج بعد الاختبارات.

    افصل شهادات الإنتاج عن الاختبار، وفعل مراقبة الاستجابات، وسجل العمليات المهمة، واختبر خطط الطوارئ قبل التشغيل الفعلي.

المتطلبات التقنية الأساسية

XML وUBL 2.1

تعتمد مواصفات ZATCA على بنية XML مبنية على معيار UBL 2.1، مع قواعد وحقول إضافية خاصة بالفوترة الإلكترونية السعودية.

يجب أن يطابق المستند معيار XML وقاموس البيانات وقواعد الأعمال والمواصفات الأمنية المحددة في أحدث وثائق ZATCA.

عند إرسال الفواتير الضريبية المبسطة في المرحلة الثانية، تُرسل بيانات الفاتورة بصيغة XML عبر Reporting API خلال 24 ساعة من إصدارها. أما الفواتير الضريبية القياسية فتخضع لمسار Clearance. [714]

للتفاصيل، راجع: دليل الفوترة الإلكترونية في السعودية 2026 .

CSID والشهادة التشفيرية

يُعد CSID شهادة تشفير وهوية رقمية مرتبطة بوحدة إصدار الفواتير الإلكترونية EGS. تُستخدم هذه الهوية ضمن عمليات التوقيع التشفيري والتحقق والوصول إلى واجهات Clearance وReporting وفق متطلبات ZATCA.

يجب فصل CSID الاختباري عن CSID الإنتاجي، وحماية المفتاح السري، وعدم تخزينه داخل مستودعات عامة أو كود JavaScript مكشوف. كما يجب مراقبة صلاحية الشهادة واتباع إجراءات ZATCA عند التجديد أو الاستبدال. [699][700]

المصادقة مع واجهات ZATCA

تستخدم واجهات الفوترة بيانات المصادقة المرتبطة بـCSID والسر الخاص به وفق آلية ZATCA المعتمدة. يجب تنفيذ طلبات API من الخادم وليس من المتصفح. 

Authorization: Basic BASE64(CSID:SECRET)

هذا السطر توضيحي فقط. لا تضع CSID أو Secret الحقيقيين داخل المقال أو GitHub أو JavaScript الموجود في الواجهة الأمامية. خزّن الأسرار في Secret Manager أو متغيرات بيئة محمية.

التوقيع وHash

تحدد مواصفات ZATCA قواعد التوقيع التشفيري وHash وحماية المفاتيح. لا تعتمد على مثال برمجي أو مكتبة دون مطابقة الإصدار والإعدادات مع أحدث مواصفات ZATCA.

UUID

يحتاج كل مستند إلى معرف فريد UUID. استخدم مكتبة موثوقة واحفظ المعرف في قاعدة البيانات لمنع التكرار عند إعادة الإرسال.

Previous Invoice Hash

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

لا تعِد حساب Hash بعد تعديل XML أو التوقيع، ولا تغير تسلسل المستندات بعد إصدارها.

QR Code

تتضمن متطلبات ZATCA قواعد محددة لرمز QR، بما في ذلك الحقول وطريقة الترميز وفق نوع الفاتورة ومتطلبات المرحلة. لا تنشئ QR بطريقة مخصصة خارج المواصفات.

أمثلة توضيحية على Clearance وReporting

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

مثال 1: طلب Clearance

POST https://gw-fatoora.zatca.gov.sa/e-invoicing/core/invoices/clearance/single
Content-Type: application/json
Authorization: Basic BASE64(CSID:SECRET)
Accept-Language: en

{
  "invoiceHash": "BASE64_SHA256_HASH",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "invoice": "BASE64_ENCODED_XML"
}

يوضح المثال فكرة إرسال Hash وUUID وملف XML مشفر بصيغة Base64. استخدم دائمًا الحقول والترويسات المحددة في أحدث Developer Portal.

مثال 2: طلب Reporting

POST https://gw-fatoora.zatca.gov.sa/e-invoicing/core/invoices/reporting/single
Content-Type: application/json
Authorization: Basic BASE64(CSID:SECRET)
Accept-Language: en

{
  "invoiceHash": "BASE64_SHA256_HASH",
  "uuid": "987fcdeb-51a2-43f7-b321-123456789abc",
  "invoice": "BASE64_ENCODED_XML"
}

تستخدم الفاتورة الضريبية المبسطة مسار Reporting، ويجب إرسالها إلى FATOORA خلال 24 ساعة من إصدارها وفق متطلبات المرحلة الثانية. [714]

مثال 3: معالجة الأخطاء وإعادة المحاولة

async function sendInvoice(payload, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(ZATCA_ENDPOINT, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "Authorization": AUTHORIZATION_HEADER,
          "Accept-Language": "en"
        },
        body: JSON.stringify(payload)
      });

      const result = await response.json();

      if (response.ok) {
        await database.saveSubmission({
          uuid: payload.uuid,
          invoiceHash: payload.invoiceHash,
          response: result
        });

        return result;
      }

      if (response.status >= 400 && response.status < 500) {
        throw new Error(
          "Validation or authentication error. Fix the request before retrying."
        );
      }

      if (attempt === maxRetries) {
        throw new Error(
          "Temporary server error after maximum retries."
        );
      }

    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }

      const delay = 1000 * Math.pow(2, attempt);

      await new Promise(resolve => {
        setTimeout(resolve, delay);
      });
    }
  }
}

لا تعِد إرسال المستند تلقائيًا عند وجود خطأ في XML أو التوقيع أو البيانات. عالج أخطاء التحقق أولًا. أما أخطاء الشبكة أو الخادم المؤقتة فقد تحتاج إلى Queue وRetry آمن مع منع إنشاء مستندات مكررة.

Clearance مقابل Reporting

الجانب Clearance Reporting
نوع المستند الفواتير الضريبية القياسية والإشعارات المرتبطة بها الفواتير الضريبية المبسطة والإشعارات المرتبطة بها
التوقيت قبل تسليم المستند للعميل وفق متطلبات Clearance خلال 24 ساعة من إصدار المستند المبسط
البيانات XML وفق مواصفات ZATCA XML وفق مواصفات ZATCA
الواجهة Clearance API Reporting API
النتيجة التحقق ومعالجة المستند قبل التسليم وفق المتطلبات إرسال المستند والحصول على استجابة التحقق أو الإقرار

لا تختَر Endpoint بناءً على كون العميل شركة أو فردًا فقط. العامل الأساسي هو نوع المستند ومتطلبات ZATCA الخاصة به.

أخطاء شائعة في التكامل

استخدام شهادة الاختبار في الإنتاج

افصل بيئة الاختبار عن الإنتاج، ولا تستخدم شهادات أو مفاتيح الاختبار مع النظام الفعلي.

تخزين الأسرار في الكود

لا تضع CSID أو Secret داخل JavaScript العام أو المستودعات المفتوحة. استخدم Secret Manager أو متغيرات بيئة محمية.

عدم حفظ UUID وHash والاستجابات

احفظ UUID وHash وبيانات الاستجابة المرتبطة بكل مستند، لأن فقدانها يصعب تتبع المستندات ومعالجة حالات الفشل.

تأجيل Reporting

يجب إرسال الفواتير الضريبية المبسطة إلى FATOORA خلال 24 ساعة من إصدارها. لذلك أنشئ Queue ومراقبة لوقت الإصدار والإرسال بدل الاعتماد على إرسال يدوي.

إعادة إرسال المستند المرفوض كما هو

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

عدم مراقبة الشهادات

ضع تنبيهات لمواعيد انتهاء الشهادات والمفاتيح، واتبع إجراءات ZATCA الرسمية للتجديد أو التحديث.

اعتبار نجاح SDK موافقة نهائية

تساعد SDK على التحقق من توافق المستندات، لكن نجاح التحقق لا يعني أن الهيئة وافقت على كل عملية أو أعفت المنشأة من مسؤولية الامتثال. [716]

أخطاء API وطريقة التعامل معها

الحالة سبب محتمل الإجراء المقترح
رفض المستند خطأ في XML أو الحقول أو قواعد الأعمال اقرأ validation response وأصلح السبب.
خطأ في التوقيع مشكلة في الشهادة أو المفتاح أو الإعدادات راجع متطلبات Security Features والتوقيع.
Hash غير صحيح عدم تطابق Hash أو PIH تحقق من XML والتسلسل قبل إعادة الإرسال.
انتهاء الشهادة استخدام شهادة غير صالحة تحقق من حالة الشهادة واتبع إجراء التجديد.
UUID مكرر إعادة استخدام معرف سابق استخدم مولد UUID وتحقق من قاعدة البيانات.
Timeout أو 5xx مشكلة مؤقتة في الاتصال أو الخادم استخدم Queue وRetry آمنًا مع منع التكرار.

قائمة التحقق قبل الإنتاج

  • ☐ تم تحديد موجة المرحلة الثانية وموعد المنشأة.
  • ☐ تم اختيار حل فوترة متوافق مع متطلبات ZATCA.
  • ☐ تم فصل بيئة الاختبار عن الإنتاج.
  • ☐ تم إعداد CSR وCSID وفق الإجراءات الرسمية.
  • ☐ تم فصل مفاتيح الاختبار عن مفاتيح الإنتاج.
  • ☐ الفواتير تُولد وفق XML وUBL 2.1 ومتطلبات ZATCA.
  • ☐ تم اختبار UUID وHash وPIH والتوقيع وQR.
  • ☐ تم اختبار Clearance وReporting حسب نوع المستند.
  • ☐ تم اختبار الرفض وأخطاء الشبكة وإعادة المحاولة.
  • ☐ تم حفظ UUID وHash والاستجابات المهمة.
  • ☐ تم إعداد مراقبة للشهادات والمفاتيح.
  • ☐ تم إنشاء Queue للفواتير التي لم تُرسل بنجاح.
  • ☐ تم اختبار النظام أثناء انقطاع الشبكة أو فشل الخدمة المؤقت.

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

هل يمكن التكامل مع ZATCA بدون مطور؟

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

ما الفرق بين Clearance وReporting؟

Clearance يرتبط بالفواتير الضريبية القياسية التي يجب معالجتها وفق متطلبات Clearance قبل تسليمها، بينما Reporting يستخدم للفواتير الضريبية المبسطة التي يجب إرسالها إلى FATOORA خلال 24 ساعة من إصدارها. [714]

هل Reporting خاص بالفواتير B2C فقط؟

ليس من الدقيق اختزال القاعدة في B2C فقط. العامل الأساسي هو نوع المستند. الفواتير الضريبية المبسطة تخضع لـReporting، بينما الفواتير الضريبية القياسية تخضع لـClearance وفق متطلبات المرحلة الثانية.

ماذا يحدث إذا انتهت صلاحية CSID؟

قد تفشل عمليات التوقيع أو الاتصال. لذلك يجب مراقبة الشهادة والمفاتيح واتباع إجراءات ZATCA الرسمية للتجديد أو التحديث.

هل يمكن إرسال عدة فواتير في طلب واحد؟

يعتمد ذلك على الواجهات والإجراءات التي تدعمها النسخة الحالية من خدمات ZATCA. راجع Developer Portal قبل بناء Batch أو تحديد Rate Limits.

هل يمكن استخدام بيئة Sandbox؟

توفر ZATCA أدوات وبيئات لمساعدة المكلفين والمطورين على اختبار الحلول قبل الانتقال إلى الإنتاج. اختبر حالات النجاح والفشل وإعادة الإرسال.

هل تدعم Shopify وWooCommerce تكامل ZATCA؟

يمكن ربط منصات التجارة الإلكترونية بحلول الفوترة من خلال Middleware أو موصلات أو مزود خدمات متخصص. وجود المنصة وحده لا يحقق متطلبات ZATCA تلقائيًا.

راجع أيضًا: دليل ربط Shopify مع ZATCA .

المراجع الرسمية

بقلم فريق Trelyoon — دليل تقني تعليمي حول تكامل حلول الفوترة الإلكترونية مع ZATCA وFATOORA.

آخر تحديث: أكتوبر 2026. تمت مراجعة المحتوى مقابل المواد التقنية والإرشادات الرسمية المتاحة من ZATCA. وبسبب إمكانية تحديث المواصفات وواجهات API، تحقق دائمًا من أحدث نسخة من التوثيق الرسمي قبل تنفيذ التكامل في الإنتاج.

تنويه: هذا الدليل تعليمي ولا يمثل استشارة ضريبية أو قانونية أو ضمانًا للامتثال. تظل المنشأة مسؤولة عن التأكد من توافق حل الفوترة المستخدم مع أحدث متطلبات هيئة الزكاة والضريبة والجمارك.

📢 لا يفوتك أي جديد!

انضم لقناة TRELYOON على تيليجرام ليصلك كل مقال جديد فور نشره.

اشترك في القناة ←
Share on Facebook Share on X
✓
خالد ترليون مؤسس الموقع وكاتبه
أكتب شروحات عملية لمشكلات الهاتف والتطبيقات وويندوز. أذكر مصدر المعلومة، وأوضّح ما جرّبته بنفسي وما نقلته من مصدر رسمي، وأحدّث المقال عند تغيّر الخدمة.

مقالات قد تهمك

تعليقات