ربط منصة فاتورة عبر API: قائمة تحقق للمطورين

يعني الربط مع منصة «فاتورة» التابعة لهيئة الزكاة والضريبة والجمارك (ZATCA) تهيئة كل جهاز أو خادم يصدر الفواتير بوصفه «حلًا لتوليد الفواتير الإلكترونية» (EGS) له معرّف ختم تشفيري خاص به (CSID)، وإنشاء كل فاتورة بصيغة XML وفق معيار UBL 2.1، وإرسالها عبر واجهة API التابعة للهيئة. تُرسل الفواتير الضريبية للاعتماد الفوري قبل أن تصل إلى المشتري، أما الفواتير المبسطة فيختمها نظامك ويُبلغ عنها خلال 24 ساعة. تمر هذه القائمة على كل جزء من ذلك لفريق التطوير الداخلي، أيًا كانت لغة البرمجة المستخدمة.

آخر تحديث: 6 نوفمبر 2026

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

قبل كتابة الكود: النطاق والوثائق المرجعية

تُطبَّق المرحلة الأولى (مرحلة الإصدار) منذ 4 ديسمبر 2021 على جميع المكلفين باستثناء غير المقيمين. وبدأت المرحلة الثانية (مرحلة الربط والتكامل) في 1 يناير 2023 وتُطبَّق على موجات، وتعلن الهيئة عن كل موجة قبل موعدها بستة أشهر على الأقل. ويجب على منشآت الموجة 25، التي تتجاوز إيراداتها الخاضعة للضريبة 187,500 ريال سعودي في أي سنة من 2022 إلى 2025، الربط مع منصة «فاتورة» بحلول 1 فبراير 2027. ويشرح دليلنا عن الموجة 25 الجانب الإداري من هذا الموعد.

قبل أول سطر من الكود، احسم أربعة أمور:

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

تهيئة كل وحدة EGS وإدارة معرّف CSID

يجب أن تصدر الفواتير من حل EGS تمت تهيئته. وتُهيأ كل وحدة عبر بوابة «فاتورة» التي تصدر معرّف CSID الخاص بها، ويمكنها لاحقًا تجديده أو إلغاؤه. وهذا يعني ثلاثة أحداث في دورة الحياة يجب أن تبني لها، لا حدثًا واحدًا:

• الإصدار. احفظ معرّف CSID ومفاتيحه في مخزن آمن للأسرار، وليس في الكود المصدري أو في ملف إعدادات داخل المستودع أو في قاعدة بيانات نظام نقاط البيع.
• التجديد. اجعل التجديد مهمة مجدولة مع تنبيهات، حتى لا تتوقف أي وحدة عن الفوترة في يوم مزدحم.
• الإلغاء. عند فقدان جهاز أو استبداله أو إيقافه، ألغِ معرّف CSID الخاص به وتأكد من أن البرنامج يتوقف فورًا عن الإصدار من تلك الوحدة.
• المتابعة. احتفظ بسجل لكل وحدة EGS وحالة معرّفها وآخر فاتورة أصدرتها، واعرضه في لوحة التحكم.

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

بناء ملف XML للفاتورة

كل ما يُرسل إلى الهيئة يجب أن يكون بصيغة XML عبر واجهة API. ويتبع ملف XML بنية UBL 2.1 مع قواعد تحقق مبنية على المعيار الأوروبي EN 16931، كما يوضحها معيار تطبيق XML الصادر عن الهيئة. ويمكن أن تكون الفاتورة نفسها ملف XML، أو ملف PDF/A-3 مضمَّنًا فيه ملف XML.

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

الاعتماد والإبلاغ: مساران عبر API

في المرحلة الثانية مساران، ويجب أن يوجّه الكود كل مستند إلى مساره الصحيح.

في الفاتورة الضريبية يكون ملف XML المعتمد العائد من الهيئة هو الفاتورة: خزّنه وسلّم المشتري هذه النسخة، لا النسخة التي أرسلتها. وينطبق الاعتماد نفسه على الإشعارات الدائنة والمدينة المرتبطة بالفواتير الضريبية.

وحول هذين الاستدعاءين، ابنِ ما يلي:

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

الختم ورمز QR وضوابط منع التلاعب

عدد من ضوابط الهيئة يقع في نموذج البيانات لديك، لا في استدعاء API:

• معرّف UUID. تحمل كل فاتورة معرّف UUID بطول 128 بت. أنشئه مرة واحدة عند إنشاء الفاتورة، ولا تُعِد إنشاءه عند إعادة المحاولة.
• قيمة تجزئة الفاتورة السابقة. تتضمن كل فاتورة قيمة تجزئة الفاتورة التي قبلها، فتتكون سلسلة واحدة لكل وحدة EGS. وإذا كتبت عمليتان في السلسلة نفسها في الوقت نفسه فستنكسر، لذا أنشئ الفواتير واحدة تلو الأخرى في كل وحدة.
• العداد. لا يمكن إعادة ضبط عداد الفواتير. خطط لكيفية بقاء العداد والسلسلة سليمين بعد إعادة التثبيت أو استبدال الجهاز أو استعادة قاعدة البيانات.
• تاريخ النظام. يجب ألا يتمكن المستخدمون من تغيير تاريخ النظام.
• ملفات XML المخزنة. لا يمكن للمستخدمين حذف ملفات XML المخزنة أو تعديلها، فلا تضف إجراء تعديل أو حذف للفواتير الصادرة في أي صلاحية.
• السجلات. تكون السجلات مختومة بالوقت، ويجب أن تكون محاولات التلاعب قابلة للكشف. والسجلات التي تقبل الإضافة فقط تسهّل ذلك كثيرًا.
• رمز QR. في الفواتير المبسطة تضيف وحدة EGS رمز QR الخاص بالمرحلة الثانية، ويحتوي على 9 وسوم بصيغة TLV مرمّزة بـ base64. اختبر طباعته وقراءته على طابعات الإيصالات المستخدمة فعلًا في فروعك.

لهذه الضوابط وزن حقيقي. ففي الغرامات التي نشرتها الهيئة في 16 نوفمبر 2021، تبدأ غرامة عدم إصدار الفواتير الإلكترونية من 5,000 ريال سعودي، وغرامة حذف الفاتورة الإلكترونية أو تعديلها بعد إصدارها من 10,000 ريال سعودي، بينما يؤدي غياب رمز QR إلى إنذار في المرة الأولى. ثم تتحدد الغرامات بحسب نوع المخالفة وعدد مرات تكرارها.

العمل دون اتصال ومهلة 24 ساعة

ينقطع اتصال المحلات بالإنترنت أحيانًا، وقد يتعذر الوصول إلى منصة «فاتورة». والفواتير المبسطة مصممة للتعامل مع ذلك: تختم وحدة EGS الفاتورة محليًا، ويستلم العميل النسخة المطبوعة، وينتظر ملف XML في قائمة انتظار يجب أن يصل منها إلى المنصة خلال 24 ساعة.

• احفظ قبل أن تطبع. خزّن كل فاتورة مبسطة في قائمة انتظار محلية دائمة قبل طباعة الإيصال، حتى لا يضيّعها أي توقف مفاجئ للنظام.
• أرسل بترتيب الإصدار. حافظ على سلامة السلسلة، ولا تُعِد بناءها لسد أي فجوة.
• نبّه مبكرًا. أطلق تنبيهًا عندما يمر على أقدم فاتورة لم يُبلغ عنها بضع ساعات، لا عندما تكاد الـ 24 ساعة تنتهي. وإذا انقضت المهلة، فبحسب دليل الهيئة يُبلَّغ عن ذلك عبر النموذج المخصص على موقعها.
• اجعل قائمة الانتظار مرئية. اعرض حجمها وعمر أقدم عنصر فيها على نقطة البيع وفي لوحة التحكم.

أما الفواتير الضريبية فمختلفة، إذ يجب في الأصل اعتمادها قبل أن يستلمها المشتري. وللانقطاعات يصف الدليل التفصيلي للهيئة مسارًا بديلًا: استمر في إعادة المحاولة، وإذا ظل الوصول إلى الهيئة متعذرًا فشارك الفاتورة غير المعتمدة واحتفظ بالسجلات، ثم أرسل الفاتورة المعتمدة بعد نجاح الاعتماد. وإذا كان الخلل من جهتك، فأبلغ الهيئة عبر نموذجها الإلكتروني. ابنِ ذلك مسارًا صريحًا ومسجّلًا.

قائمة الاختبار والإطلاق

1. حصر كل أنواع المستندات التي تصدرها، مع مسار كل منها: الاعتماد أو الإبلاغ.
2. تحديد وحدات EGS، وكيف تبقى سلسلة كل وحدة وعدادها سليمين بعد الاستعادة أو استبدال الجهاز.
3. توليد ملفات XML من بيانات منظمة، واجتياز أدوات الاختبار التي توفرها الهيئة لكل نوع من المستندات.
4. بناء إصدار معرّف CSID وتجديده وإلغائه، مع إبقاء المفاتيح خارج الكود.
5. تخزين ملف XML المرسل والرد المستلم لكل مستند.
6. بناء قائمة الانتظار دون اتصال، مع تنبيهات قبل نهاية مهلة 24 ساعة بوقت كافٍ.
7. قفل تاريخ النظام وملفات XML الصادرة والسجلات أمام أي تعديل.
8. مراجعة الفاتورة العربية ورمز QR المطبوع على طابعات حقيقية.
9. تجربة انقطاع الاتصال ورفض مستند وإلغاء معرّف CSID قبل الإطلاق.

ملاحظة عن المورّدين والشارات: الهيئة لا تعتمد البرامج. فدليل مزودي الحلول لديها قائمة استرشادية «لا تُعد اعتمادًا من الهيئة»، ويحق للمكلفين استخدام أي حل متوافق، بما في ذلك الحلول المطورة داخليًا. احكم على أي حل ربط بما يفعله في الاختبار، لا بشعار يحمله.

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

دور KF Tech Solutions. نبني واجهات API والأنظمة الخلفية من خلال خدمة تطوير API والأنظمة الخلفية، وقد ربطنا نظام نقاط بيع مع منظومة الإيصال الإلكتروني لمصلحة الضرائب المصرية، وهي منصة حكومية أخرى تقوم على فواتير موقّعة يجري التحقق منها (كيف يعمل ذلك الربط). نعمل مع المنشآت في مصر والخليج (انظر صفحة السعودية)، ويمكننا بناء حل الربط مع فريقك أو مراجعة حل قائم وفق هذه القائمة.

أسئلة شائعة

هل تعتمد الهيئة برامج الربط أو توافق عليها؟

لا. دليل مزودي الحلول لدى الهيئة قائمة استرشادية غير ملزمة قانونيًا للمكلفين، وبحسب نص الهيئة «لا يُعد اعتمادًا منها». ويحق للمكلفين استخدام أي حل متوافق.

هل يمكن بناء الربط بلغة C# أو بإطار Laravel أو بغيرهما؟

نعم. تحدد الهيئة صيغة XML والختم التشفيري ورمز QR وواجهة API، ولا تحدد لغة برمجة. وأي بيئة تستطيع بناء ملفات UBL 2.1 والتحقق منها، وحساب قيم التجزئة، وتوقيع المستندات، واستدعاء واجهة API عبر HTTPS تؤدي المهمة، ومنها C#/.NET وPHP/Laravel. اختر البيئة التي يصونها فريقك بالفعل.

هل يحتاج كل جهاز إلى معرّف CSID خاص به؟

تُهيأ كل وحدة EGS على حدة، ولها معرّف CSID خاص وسلسلة تجزئة فواتير خاصة. أما تحديد الوحدة، هل هي كل نقطة بيع أم خادم واحد لكل فرع، فهو قرار تصميمي يُحسم وفق أدلة الهيئة قبل تهيئة أي وحدة.

هل يمكن إرسال الفواتير إلى الهيئة بصيغة PDF؟

لا. ما يُرسل إلى الهيئة يجب أن يكون XML عبر واجهة API. أما نسخة المشتري فيمكن أن تكون ملف XML أو ملف PDF/A-3 مضمَّنًا فيه ملف XML، ويجب أن يكون محتواها المقروء بالعربية.

ماذا يحدث للفواتير المبسطة عند انقطاع الإنترنت؟

يستمر نظامك في ختمها وطباعتها، ويحفظ ملفات XML في قائمة انتظار ويبلغ عنها بعد عودة الاتصال، خلال 24 ساعة، فإن تعذّر ذلك فأبلغ الهيئة. وللفواتير الضريبية راجع المسار البديل عند الانقطاع الموضح أعلاه.

هل يبني فريقك هذا الربط داخليًا وتريد رأيًا ثانيًا في التصميم؟ احجز مكالمة أو أرسل لنا تفاصيل نظامك الحالي، وسنخبرك بوضوح بما نقترح تغييره.

المصادر

• هيئة الزكاة والضريبة والجمارك: ما هي الفوترة الإلكترونية
• هيئة الزكاة والضريبة والجمارك: مراحل التطبيق
• هيئة الزكاة والضريبة والجمارك: الدليل التفصيلي للفوترة الإلكترونية (PDF)
• هيئة الزكاة والضريبة والجمارك: معيار تطبيق XML للفاتورة الإلكترونية (PDF)
• هيئة الزكاة والضريبة والجمارك: الموجة 25 من الربط والتكامل
• هيئة الزكاة والضريبة والجمارك: دليل مزودي الحلول
• هيئة الزكاة والضريبة والجمارك: مخالفات الفوترة الإلكترونية وغراماتها (16 نوفمبر 2021)