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

مع تطبيق المرحلة الثانية من نظام الفوترة الإلكترونية (مرحلة الربط والتكامل)، أصبح ربط API بحلول الفوترة الإلكترونية ضرورة تشغيلية وليست خيارًا. هذا الدليل يشرح خطوات تكامل الفوترة الإلكترونية مع منصة فاتورة التابعة لهيئة الزكاة والضريبة والجمارك — بأسلوب يناسب المدير والمطور معًا، مع أمثلة كود حقيقية وحلول لأبرز الأخطاء.

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

• ما هو؟ توصيل نظام الفوترة بمنصة فاتورة ZATCA تلقائيًا عبر واجهة برمجية (API)
• لمن؟ كل منشأة خاضعة لضريبة القيمة المضافة وصلت إليها المرحلة الثانية من الفوترة الإلكترونية
• الخيارات؟ برنامج محاسبي معتمد · ربط ERP · تطوير مخصص · وسيط Middleware
• الأهم تقنيًا؟ XML UBL 2.1 · شهادة CSID · توقيع رقمي ECDSA · Mutual TLS
• Clearance أم Reporting؟ B2B = Clearance قبل الإرسال / B2C = Reporting خلال 24 ساعة

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

واجهة برمجة التطبيقات (API) هي القناة التقنية التي تربط نظامك المحاسبي مباشرةً بمنصة فاتورة، بحيث تُرسَل الفواتير آليًا عند إصدارها للتحقق منها واعتمادها — دون تدخل يدوي.

في المرحلة الأولى كان يكفي إصدار الفاتورة إلكترونيًا وحفظها. أما في مرحلة الربط والتكامل، فيجب أن يصل كل مستند للهيئة عبر هذه الواجهة — إما قبل تسليمه للعميل (Clearance) أو خلال 24 ساعة (Reporting).

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

التكامل مع منصة فاتورة لا يُحقق الامتثال فحسب، بل يُحسّن الكفاءة التشغيلية بشكل مباشر:

• أتمتة كاملة: لا رفع يدوي للفواتير على البوابة الإلكترونية.
• تقليل الأخطاء: البيانات تنتقل مباشرةً من نظامك دون إعادة إدخال.
• اعتماد فوري: تلقّي قبول أو رفض كل فاتورة في الوقت الفعلي.
• تجنب العقوبات: عدم ربط منصة فاتورة في الموعد يعرّض المنشأة لغرامات نظامية. راجع جدول عقوبات ZATCA الكامل.
• تقارير مالية دقيقة: بيانات الفواتير متزامنة مع سجلات الهيئة دائمًا.

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

تختلف طريقة تكامل الفوترة الإلكترونية بحسب حجم المنشأة وبنيتها التقنية:

1. برنامج محاسبي معتمد من ZATCA

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

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

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

إذا كانت منشأتك تستخدم SAP أو Oracle أو Microsoft Dynamics، يمكن إضافة وحدة تكامل تربطه بمنصة فاتورة مباشرةً. هذا الخيار يحافظ على البيانات موحدة داخل النظام الموجود.

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

3. تطوير مخصص عبر ZATCA API مباشرةً

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

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

4. وسيط برمجي (Middleware / iPaaS)

طبقة وسيطة تربط نظامك الحالي بمنصة فاتورة دون تعديل النظام الأصلي. مرن ومناسب للمتاجر التي تعمل على منصات جاهزة. للتفاصيل راجع دليلنا عن ربط Shopify مع ZATCA: الفوترة الإلكترونية 2026.

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

مقارنة طرق تكامل الفوترة الإلكترونية

خطوات ربط منصة فاتورة ZATCA خطوة بخطوة

1. اختر طريقة الربط المناسبة بناءً على حجم منشأتك وبنيتها التقنية، حدد أيًا من الطرق الأربعة يناسبك. إذا كان لديك برنامج محاسبي حالي، تحقق أولًا من قائمة البرامج المعتمدة من الهيئة.
2. سجّل في منصة فاتورة ZATCA ادخل بوابة هيئة الزكاة والضريبة والجمارك بالرقم الضريبي وكلمة المرور، وانتقل لقسم الفوترة الإلكترونية لتسجيل نظامك وتفعيل ربط API.
3. احصل على شهادة CSID أرسل طلب Certificate Signing Request (CSR) عبر Onboarding API. ستحصل أولًا على Compliance CSID للاختبار، ثم Production CSID للإنتاج. راقب تاريخ انتهاء الشهادة وجدّدها قبل 30 يومًا.
4. اختبر التكامل في بيئة Sandbox الهيئة توفر بيئة تجريبية تحاكي الإنتاج تمامًا. اختبر Clearance وReporting وسيناريوهات الفشل والإعادة — لا تتجاوز هذه الخطوة أبدًا.
5. تحقق من صحة الفواتير قبل الإرسال استخدم ZATCA SDK أو أداة fatoora CLI للتحقق من XML قبل إرساله. أي خطأ في البنية أو Namespace يؤدي لرفض المستند فورًا.
6. أطلق في بيئة الإنتاج وراقب الاستجابات ثبّت Production CSID وابدأ إرسال الفواتير الفعلية. احفظ Clearance ID وInvoice Hash لكل مستند في قاعدة البيانات فور اعتماده.

المتطلبات التقنية الأساسية لـ e-invoicing integration

صيغة XML وفق معيار UBL 2.1

جميع مستندات الفوترة الإلكترونية في السعودية يجب أن تُرسَل بصيغة XML وفق معيار Universal Business Language 2.1. أي صيغة أخرى (PDF، Excel، JSON) لا تُقبل. البرامج المعتمدة تتولى توليد هذه الصيغة تلقائيًا. للتفاصيل الكاملة راجع دليل الفوترة الإلكترونية في السعودية 2026.

شهادة التوقيع الرقمي CSID

كل مستند يجب أن يحمل توقيعًا رقميًا بخوارزمية ECDSA (منحنى P-256) باستخدام المفتاح الخاص من شهادة CSID الصادرة عن الهيئة. الشهادة تنتهي صلاحيتها — راقب تاريخ الانتهاء وجددها قبل 30 يومًا على الأقل.

بروتوكول HTTPS مع Mutual TLS (mTLS)

الاتصال بمنصة فاتورة يتطلب HTTPS مع Mutual TLS — مصادقة ثنائية: النظام يُثبت هويته للهيئة والهيئة تُثبت هويتها للنظام. يجب إرسال الشهادة الرقمية مع كل طلب API.

معرّف UUID فريد لكل فاتورة

كل مستند يحتاج UUID v4 لا يتكرر أبدًا حتى عبر أنظمة مختلفة. استخدم مكتبات UUID المعيارية في لغة البرمجة التي تستخدمها.

سلسلة Hash بين الفواتير (PIH)

كل مستند يحتوي على Hash المستند السابق مما ينشئ سلسلة لا يمكن التلاعب بها. يجب حفظ Hash كل فاتورة في قاعدة البيانات — إذا فُقد رقم واحد، تنكسر السلسلة كاملًا وتتوقف عملية إصدار الفواتير.

أمثلة كود عملية: Clearance وReporting

مثال 1 — طلب Clearance (B2B)

POST https://gw-fatoora.zatca.gov.sa/e-invoicing/core/invoices/clearance/single
Content-Type: application/json
Accept-Language: ar
Accept-Version: V2
Authorization: Basic {base64(username:password)}

{
  // الفاتورة بصيغة UBL 2.1 مشفرة بـ Base64
  "invoice": "PD94bWwgdmVyc2lvbj0iMS4wIi...",

  // Hash الفاتورة الحالية (SHA-256 ثم Base64)
  "invoiceHash": "NWZlY2ViNjZmZmM4NmYzOG...",

  // UUID فريد لهذه الفاتورة (v4)
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

// استجابة نجاح (200 OK)
{
  "clearedInvoice": "PD94bWwg...",   // الفاتورة بعد ختم الهيئة
  "validationResults": {
    "status": "PASS",
    "infoMessages": [],
    "warningMessages": [],
    "errorMessages": []
  }
}

مثال 2 — طلب Reporting (B2C)

POST https://gw-fatoora.zatca.gov.sa/e-invoicing/core/invoices/reporting/single
Content-Type: application/json
Accept-Language: ar
Accept-Version: V2
Authorization: Basic {base64(username:password)}

{
  // نفس البنية — لكن profileID في XML = reporting:1.0
  "invoice": "PD94bWwgdmVyc2lvbj0iMS4wIi...",
  "invoiceHash": "YWJjZGVmMTIzNDU2Nzg5MA...",
  "uuid": "987fcdeb-51a2-43f7-b321-123456789abc"
}

// استجابة نجاح (202 Accepted)
{
  "reportingStatus": "REPORTED",
  "validationResults": { "status": "PASS" }
}

مثال 3 — معالجة الخطأ وإعادة الإرسال (Retry Logic)

// JavaScript — نمط Retry مع Exponential Backoff
async function sendWithRetry(payload, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const res = await fetch(ZATCA_ENDPOINT, {
        method: "POST",
        headers: { "Content-Type": "application/json", ...authHeaders },
        body: JSON.stringify(payload)
      });

      if (res.ok) {
        const data = await res.json();
        // احفظ Hash و ClearanceID فوراً
        await db.saveInvoiceHash(payload.uuid, data.invoiceHash);
        return data;
      }

      // 4xx = خطأ في البيانات — لا تعيد المحاولة
      if (res.status >= 400 && res.status < 500) {
        throw new Error(`Client error ${res.status} — fix payload`);
      }

    } catch (err) {
      if (attempt === maxRetries) throw err;
      // انتظر: 2s → 4s → 8s
      await sleep(1000 * Math.pow(2, attempt));
    }
  }
}

Clearance مقابل Reporting: متى تستخدم كل منهما؟

أخطاء شائعة في ربط API تُكلّفك وقتًا ومالًا

بعد متابعة عشرات حالات تكامل الفوترة الإلكترونية، هذه هي الأخطاء الأكثر تكرارًا:

جدول أخطاء ZATCA API وحلولها

✅ Checklist قبل الإطلاق في بيئة الإنتاج

• تم اختيار طريقة ربط API المناسبة لحجم المنشأة
• تم التسجيل في منصة فاتورة والحصول على بيانات الوصول
• تم توليد CSR والحصول على Production CSID (ليس Compliance)
• الفواتير تُولَّد بصيغة XML صالحة وفق UBL 2.1 مع Namespace صحيح
• تم التحقق من المستندات باستخدام ZATCA SDK قبل الإرسال
• تم اختبار Clearance وReporting في Sandbox بالكامل
• تم اختبار سيناريوهات الفشل وإعادة الإرسال (Retry)
• Hash كل مستند محفوظ في قاعدة البيانات فور الاعتماد
• آلية تجديد شهادة CSID مُعدّة وتنبيهاتها مفعّلة (30 يومًا)
• قائمة انتظار (Queue) لإعادة الإرسال عند فشل الاتصال مُفعّلة

الأسئلة الشائعة عن ربط API بالفوترة الإلكترونية

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

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

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

Clearance للمعاملات B2B ويتطلب موافقة قبل تسليم الفاتورة للعميل، بينما Reporting للمعاملات B2C ويتم خلال 24 ساعة من الإصدار.

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

تتوقف جميع الفواتير عن الإرسال فورًا وتُرفض بخطأ 401. يجب تجديد الشهادة عبر Onboarding API وتحديث نظامك بالشهادة الجديدة قبل استئناف الإرسال.

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

نعم، تدعم منصة فاتورة إرسال دفعات (Batch) عبر Endpoints مخصصة. لكن لكل بيئة حدود معدل إرسال (Rate Limits) — تحقق من التوثيق الرسمي لمعرفة الحد المسموح به.

هل Sandbox مجاني ومتاح دائمًا؟

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

هل Shopify أو WooCommerce تدعمان ربط API مع ZATCA؟

لا مباشرةً، لكن يمكن الربط عبر Middleware أو مزودي خدمة متخصصين. تفاصيل أكثر في دليل ربط Shopify مع ZATCA.

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

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

تنويه: المعلومات للتوجيه العام. راجع موقع ZATCA الرسمي أو استشر مستشارًا تقنيًا معتمدًا للحالات الخاصة.