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

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

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

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

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

لماذا التكامل عبر واجهة برمجية ضروري؟

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال عملي: طلب Clearance API

هذا مثال مبسط لطلب Clearance يوضح البنية الأساسية للـ HTTP request الذي يرسله نظامك لمنصة فاتورة:

POST https://gw-fatoora.zatca.gov.sa/e-invoicing/core/invoices/clearance/single
Content-Type: application/json
Accept-Language: ar
Accept-Version: V2

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

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

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

استجابة ZATCA عند النجاح تحتوي على clearanceStatus: "CLEARED" وعلى نسخة الفاتورة الموقّعة من الهيئة التي يجب إرسالها للعميل بدلًا من النسخة الأصلية. احفظ clearanceId وinvoiceHash في قاعدة بياناتك.

وفيما يلي الحد الأدنى من بنية ملف XML داخل الـ payload:

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">

  <cbc:UBLVersionID>2.1</cbc:UBLVersionID>
  <cbc:ProfileID>clearance:1.0</cbc:ProfileID>  <!-- أو reporting:1.0 -->
  <cbc:ID>INV-2026-0042</cbc:ID>
  <cbc:UUID>123e4567-e89b-12d3-a456-426614174000</cbc:UUID>
  <cbc:IssueDate>2026-05-02</cbc:IssueDate>
  <cbc:IssueTime>14:30:00</cbc:IssueTime>
  <cbc:InvoiceTypeCode name="0100000">388</cbc:InvoiceTypeCode>

  <!-- بيانات البائع والمشتري والسطور والضريبة... -->

</Invoice>

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

عند تصميم التكامل، يجب أن يُحدد نظامك تلقائيًا نوع العملية بناءً على نوع العميل:

أبرز أخطاء التكامل وكيفية حلها

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

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

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