هيئة الزكاة والضريبة والجمارك — الفوترة الإلكترونيةZATCA e-invoicing
الفوترة الإلكترونية بمرحلتيها يتولاها تطبيق KSA Compliance مفتوح المصدر (دليل المطور ص10). لا نبرمج التشفير أو XML بأنفسنا. كل مكتب يُسجل وحدته وشهادته.
تصنيف VERIFIED_API هنا يعني أن الفوترة الإلكترونية لها مواصفات ومنصة رسمية ويغطيها تطبيق قائم بحسب الوثائق؛ لم نتحقق في هذه الجلسة من توافق التطبيق مع إصدار ERPNext المختار (OD-01).
1ما المنصة، ومن الجهة المالكة، وما اختصاصها؟
الهيئة المسؤولة عن الضريبة والفوترة الإلكترونية.
2ما الإجراء الذي ينفذه المحامي فيها؟
لا شيء؛ المحاسب.
3متى يحتاج إليها المحامي؟
كل فاتورة.
4ميزات ERPOS المرتبطة بها
B23 الفوترة على المراحل والفوترة الإلكترونية، B25 المحاسبة العامة والأصول والقوائم المالية، B27 المحاسب الآلي للمصروفات، B41 الاشتراكات والخطط والقياس.
5الخدمة المحددة المطلوبة من المنصة
اعتماد الفواتير القياسية (Clearance) والإبلاغ عن المبسطة (Reporting) (الوثيقة المعمارية).
6نوع الحاجة: قراءة أو إرسال أو مزامنة أو إشعارات
إرسال.
7البيانات الداخلة والخارجة وحساسيتها ومصدرها
الفاتورة: المورد والعميل والمبالغ. حساسية متوسطة.
8هل يوجد API رسمي موثق لهذه الخدمة تحديدًا؟
نعم: منصة الهيئة وواجهاتها الرسمية، ويتعامل معها تطبيق KSA Compliance (دليل المطور ص10) (الوثيقة المعمارية).
9المصدر الرسمي وتاريخ التحقق
| المصدر | الرابط | ما تحقّقنا منه | تاريخ التحقق |
|---|---|---|---|
| هيئة الزكاة والضريبة والجمارك | https://zatca.gov.sa | تفتح الصفحة الرئيسية (الزكاة، الجمارك، ضريبة القيمة المضافة). لم نفتح صفحات الفوترة الإلكترونية أو بوابة المطورين | 2026-11-04 |
10حالة التحقق
VERIFIED_API
VERIFIED_API (بالمعنى المذكور في التنبيه).
11ما الذي يثبته المصدر الرسمي وما الذي لا يثبته؟
وجود الفوترة الإلكترونية ومتطلباتها. لا يثبت موعد إلزام موجة المكتب؛ تذكر الوثيقة المعمارية موجة بموعد في 2027 (الوثيقة المعمارية) يحتاج تحققًا أو موافقة رسمية.
12التسجيل والاعتماد والتفويض والمصادقة وبيئة الاختبار
تسجيل وحدة الفوترة (EGS) بـ OTP من بوابة الهيئة لكل مكتب، وشهادة لكل وحدة (الوثيقة المعمارية).
13خطوات الربط من جهة ERPOS
- تثبيت KSA Compliance.
- تسجيل المكتب في بيئة المحاكاة.
- 30 يومًا بلا رفض.
- الإنتاج.
14تصميم Adapter مستقل للمنصة
واجهة ZatcaAdapter مستقلة في legal_erp/integrations/zatca.py ترث النمط الموحد نمط موصل التكامل بعمليات: handled by ksa_compliance. تنفيذان: يدوي (يفتح نموذج إدخال للموظف ويسجل المصدر «يدوي») ورسمي (لا يُكتب قبل استلام توثيق رسمي وموافقة)، ويُختار من الإعداد لكل مكتب اقتراح هندسي.
15تدفق البيانات ومخطط التسلسل
16نموذج الطلب والاستجابة
يتولاه التطبيق؛ لا نكتب نماذج.
17انتهاء المهلة وانقطاع الخدمة والرفض وتضارب الحالة
- انتهاء المهلة ← فشل مؤقت ← إعادة أسية في الطابور.
- انقطاع الخدمة أو أخطاء متتالية ← إيقاف الموصل وتنبيه المدير B43 طبقة التكامل المركزية.
- رفض (صلاحية، تفويض) ← فشل دائم يظهر للمسؤول بلا إعادة.
- تضارب الحالة مع البيانات المحلية ← سجل فرق يقرره إنسان؛ لا كتابة صامتة ولا حذف محلي عند استجابة فارغة.
18منع التكرار وإعادة المحاولة الآمنة
كل عملية صادرة بمفتاح عدم تكرار يُحفظ مع السجل؛ إعادة المحاولة ترسل المفتاح نفسه، وكل حدث وارد يُتجاهل إن تكرر معرّفه أو بصمته B43 طبقة التكامل المركزية.
19حفظ المصدر ووقت الجلب وإيصال الجهة وسجل التدقيق
يُحفظ مع كل قيمة: data_source (يدوي/الجهة)، وقت الجلب، معرّف الاستدعاء أو رقم الإيصال من الجهة إن وُجد، والمستخدم أو المهمة المجدولة. سجل الاستدعاء لا يحفظ جسم الاستجابة ولا بيانات شخصية (خطة ناجز ص14).
20المسار اليدوي المصرح به
عند تعطل الربط: لا إصدار فواتير بديلة يدويًا خارج النظام؛ الانتظار وإعادة الإرسال من التطبيق ضمن المهلة النظامية يحتاج اعتمادًا قانونيًا.
21اختبارات التكامل والفشل والتفويض والتكرار والعزل
| المعرّف | النوع | السيناريو | النتيجة المتوقعة |
|---|---|---|---|
INT-ZTC-01 | تكامل | بيئة وهمية تعيد نجاحًا | تُحفظ القيمة بمصدرها ووقتها. |
INT-ZTC-02 | فشل | مهلة ثم نجاح | إعادة واحدة بلا تكرار. |
INT-ZTC-03 | تفويض | مفتاح أو تفويض غير صالح | فشل دائم وتنبيه، لا إعادة. |
INT-ZTC-04 | تكرار | إرسال الحدث نفسه مرتين | يُعالج مرة. |
INT-ZTC-05 | عزل | مكتبان على الخادم نفسه | لا يرى أحدهما بيانات الآخر ولا مفتاحه. |
22المخاطر والقرارات التي تحتاج موافقة الجهة
التوافق مع v16. موعد الإلزام يحتاج تحققًا أو موافقة رسمية.