ZATCA-API-429 ⚡ الربط وبوابة زاتكا والـ API error

خطأ 429: تجاوز الحد الأقصى لمعدل الطلبات في بوابة زاتكا

ZATCA API 429: Too Many Requests / Rate Limit Exceeded

المواصفة التقنية المعتمدة من زاتكا:

ترجع بوابة زاتكا رمز الحالة 429 عند تجاوز عدد الطلبات المسموح بها في الثانية الواحدة لكل جهاز EGS.

XPath Context: HTTP Response Status Code: 429 Too Many Requests

📌 نبذة عن القاعدة وسبب التدقيق

تفرض منصة فاتورة حداً أقصى لمعدل إرسال الفواتير في الثانية، ويؤدي إرسال طلبات متزامنة بكثافة إلى إرجاع خطأ HTTP 429.

English Description: ZATCA Fatoora clearance & compliance endpoints enforce throttling limits. Rapid concurrent requests trigger HTTP 429 rate limit errors.

⚠️ الأسباب الشائعة لظهور الخطأ ورفض الفاتورة

  • ✕ إرسال فواتير بالجملة في حلقة تكرارية سريعة دون جدولة أو فواصل زمنية
  • ✕ ضغط عمليات البيع في نقاط البيع (POS) دون استخدام طابور معالجة (Message Queue)
  • ✕ استخدام خيوط معالجة متعددة (Multithreading) بنفس شهادة الجهاز في نفس اللحظة
  • ✕ إعادة المحاولة الفورية دون احترام ترويسة Retry-After

✅ خطوات الحل وتصحيح الفاتورة

1

تطبيق التراجع الأسي (Exponential Backoff)

عند استلام رمز 429، انتظر مدة زمنية متضاعفة (500ms ثم 1s ثم 2s) قبل إعادة إرسال الطلب.

2

استخدام طوابير المعالجة في الخلفية (Queues)

استخدم طوابير معالجة مثل Redis/BullMQ لتحديد سقف الإرسال بمعدل 5 إلى 10 فواتير في الثانية.

3

الاستفادة من مهلة الـ 24 ساعة للفواتير المبسطة

في نقاط البيع B2C، يتم توقيع الفاتورة وإعطاؤها للعميل فوراً دون انتظار، ويتم إرسالها لزاتكا في الخلفية خلال 24 ساعة.

💻 نموذج برمجي لمقارنة ملف XML (قبل وبعد التصحيح)

❌ النموذج الخاطئ (مرفوض من زاتكا) Invalid XML 
// Anti-pattern: Synchronous loop firing 100 requests in parallel
await Promise.all(invoices.map(inv => zatcaApi.post('/invoices/clearance', inv)));
✓ النموذج الصحيح (المعتمد رسمياً) Valid UBL 2.1 
// Best practice: Rate-limited queue with exponential backoff
const queue = new PQueue({ concurrency: 3, interval: 1000, intervalCap: 5 });
for (const invoice of invoices) {
  await queue.add(() => sendWithRetry(invoice));
}

تحقق من صحة ملف الفاتورة الآن مجاناً

استخدم أدوات قيمة لفحص بنية XML والتأكد من عدم وجود أخطاء قبل إرسال الفواتير لمنصة زاتكا.

فحص XML والهاش ← محلل رمز QR ←

❓ الأسئلة الشائعة حول ZATCA-API-429

هل يعني خطأ 429 أن الفاتورة تم رفضها نهائياً؟

لا، خطأ 429 يعني أن الخادم مشغول بتنظيم حركة المرور ولم تتم معالجة الفاتورة بعد، ويمكنك إعادة المحاولة بأمان.

🔗 قواعد وأخطاء زاتكا ذات صلة

INVALID-INVOICE-HASH

خطأ هاش الفاتورة غير صالح: عدم تطابق بصمة الفاتورة الرقمية

بصمة SHA-256 المحتسبة لملف XML لا تطابق البصمة المستخرجة بواسطة مدقق زاتكا نتيجة أخطاء في التحويل المعياري C14N.

BR-KSA-26

BR-KSA-26: خطأ في احتساب هاش الفاتورة السابقة (PIH / KSA-13)

يجب أن يكون هاش الفاتورة السابقة (KSA-13) مشفراً بـ Base64 لترميز SHA-256 للفاتورة السابقة، أو الهاش المبدئي الصفري للفاتورة الأولى.

BR-KSA-27

BR-KSA-27: رمز الاستجابة السريعة (QR Code / KSA-14) مفقود أو غير مطابق

يجب أن تحتوي الفاتورة على رمز QR مشفر بنظام Base64 ومبني بترميز TLV وفق متطلبات المرحلة الثانية من هيئة الزكاة.

ودّع مشاكل الربط وأخطاء الفوترة مع برنامج قيمة

يتكفل نظام قيمة بكافة متطلبات هيئة الزكاة والضريبة والجمارك تلقائياً في الخلفية: اعتماد فوري للفواتير، توقيع رقمي، وربط كامل مع منصة فاتورة.

ابدأ تجربتك المجانية الآن ← تصفح باقي قواعد أخطاء زاتكا