ZATCA API · Fatoora integration
واجهة زاتكا API وتكامل فاتورة — دون تعقيد تقني
يبحث المطوّرون عن واجهة زاتكا لأن المرحلة الثانية تتطلب ربطاً مباشراً بمنصة فاتورة: تسجيل EGS، وشهادة CSID للإنتاج، وتوقيع UBL 2.1، وسلسلة PIH، وإخلاء B2B، وإبلاغ B2C. إسناد طبقة وسيطة — ترسل JSON ونُعيد فاتورة مُخلّاة أو مُبلَّغاً عنها مع UUID ورمز QR.
لماذا يبحث الفريق عن تكامل واجهة فاتورة
- ✓المرحلة الثانية (التكامل) إلزامية على موجات — الموجة 25 يجب ربطها بفاتورة في 1 فبراير 2027 إذا تجاوزت الإيرادات الخاضعة 187,500 ريال في أي من 2022–2025؛ والغرامات بعد المواعيد.
- ✓التكامل المباشر يعني مفاتيح ECDSA وCSR بمعرّفات زاتكا، وCSID للامتثال والإنتاج، وفواتير اختبار قبل التشغيل.
- ✓كل فاتورة تحتاج UBL 2.1 وتوقيع XAdES وPIH لكل EGS وQR TLV (B2C) وإخلاء (B2B) أو إبلاغ خلال 24 ساعة (B2C).
- ✓البناء الداخلي يستغرق أسابيع؛ الطبقة الوسيطة تتيح الإطلاق خلال أيام.
ما الذي تتولاه واجهة إسناد لزاتكا
EGS وCSID
تسجيل بيئة التجربة والإنتاج، وOTP، وتنبيهات تجديد الشهادة، والتجديد عبر API.
UBL 2.1 والتوقيع
XML بالملف السعودي، هاش، سلسلة PIH، وختم ECDSA — من JSON.
إخلاء وإبلاغ فاتورة
فواتير B2B تُخلَّى قبل التسليم؛ B2C تُبلَّغ خلال 24 ساعة.
إعادة محاولة وWebhooks
قائمة انتظار عند بطء زاتكا؛ webhooks موقّعة HMAC.
تكامل فاتورة بنفسك مقابل واجهة إسناد
الاتصال المباشر بـ gw-fatoora.zatca.gov.sa يمنحك تحكماً كاملاً لكن يربط فريقك بتحديثات المواصفات وتدوير الشهادات إلى الأبد. إسناد تُبقي واجهة تكاملك ثابتة بينما نحن نستوعب تحديثات زاتكا.
أسئلة شائعة عن تكامل API زاتكا
- هل توجد واجهة رسمية من زاتكا؟
- نعم — منصة فاتورة توفّر واجهات REST للتسجيل (CSID) والإخلاء (B2B) والإبلاغ (B2C). إسناد تلفّها بواجهة JSON واحدة.
- ما تكامل واجهة فاتورة؟
- ربط نظام الفوترة أو ERP بمنصة فاتورة لدى زاتكا لتوقيع الفواتير وإرسالها لحظياً، بدلاً من الحفظ المحلي فقط كما في المرحلة الأولى.
- هل أحتاج مسارين B2B وB2C؟
- نعم. الفواتير الضريبية (B2B/B2G) تُخلَّى قبل وصولها للمشتري. الفواتير المبسّطة (B2C) تُصدر أولاً ثم تُبلَّغ خلال 24 ساعة.
- هل يمكن التجربة قبل الإنتاج؟
- نعم. إسناد توفّر بيئة تجربة بمفاتيح zatca_test_*. اطلب تجربة ونجهّز لوحة التحكم خلال 24 ساعة.
- هل تغطي إسناد الموجة 25 (1 فبراير 2027)؟
- نعم. ربط المرحلة الثانية للموجة 25 (إيرادات خاضعة فوق 187,500 ريال في أي من 2022–2025) يستخدم نفس واجهات الإخلاء والإبلاغ في فاتورة. عقد JSON لدى إسناد يبقى كما هو؛ ما زلت تكمل OTP فاتورة لـ EGS/CSID قبل 1 فبراير 2027.