حدود الطلبات والأخطاء في Zid API: وزّع طلباتك وتعامل مع 429 واقرأ ردود الأخطاء

الحد: 60 طلبًا في الدقيقة لكل تطبيق في كل متجر

تطبّق زد على طلبات الأنظمة الخارجية حدًا قدره 60 طلبًا في الدقيقة لكل تطبيق في كل متجر. ولأن الحد يُحسب لكل متجر على حدة، فطلباتك إلى متجر لا تستهلك من حصة متجر آخر. لكن داخل المتجر الواحد، تتشارك كل مهام تطبيقك الحصة نفسها.

تستخدم زد خوارزمية Leaky Bucket: تدخل الطلبات إلى طابور كأنها تُصبّ في دلو، ويتسرّب الدلو بمعدل ثابت، وعندما يمتلئ تُرفض الطلبات الإضافية. وبحسب سياسة الإبطاء (Throttling)، تُحتجز الطلبات الزائدة ويُعاد تنفيذها بتأخير وعدد محاولات قابلين للضبط، ثم تُرفض نهائيًا إذا لم تنجح.

• يوضح سجل التحديثات أن ردود HTTP 429 تُحتسب ضمن حصتك. فإعادة المحاولة فورًا في حلقة متواصلة تُبقي الدلو ممتلئًا.
• إذا رأيت أن حالتك تحتاج استثناءً، تطلب زد أن ترسل التفاصيل بالبريد لتقييمها.

قراءة ردود زد

يتبع Zid API مبادئ REST ورموز HTTP القياسية. الردود الناجحة تستخدم 200 أو 201 أو 202 (قُبل الطلب ولم تكتمل معالجته) أو 204 (نجح دون محتوى). أما الأخطاء فتأتي بهذا الشكل:

{
  "status": 422,
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "Invalid input data.",
    "fields": {
      "email": ["Email format is invalid."]
    }
  }
}

• 400 bad_request: راجع صيغة الطلب والحقول المطلوبة.
• 401 unauthorized: التوثيق مفقود أو فشل. راجع الـ Tokens.
• 403 forbidden: فُهم الطلب لكنه رُفض. راجع الصلاحيات.
• 404 not_found و405 method_not_allowed و406 not_acceptable (عدّل Header Accept) و410 gone (المورد أُزيل نهائيًا، فنظّف أي إشارة إليه).
• 422 validation_failed: يخبرك Object fields بالمدخلات التي فشلت وسبب فشلها.
• 429 too_many_requests: خفّف الطلبات وأعد المحاولة لاحقًا.
• 500 server_error: أعد المحاولة لاحقًا، وتواصل مع الدعم إذا استمرت المشكلة. و503 service_unavailable: انتظر ثم أعد المحاولة.

ليست كل الأخطاء بالشكل نفسه

اقرأ الأخطاء بحذر. فبعض النقاط وأمثلة مركز المساعدة تُرجع شكلًا مختلفًا، فيه status: "error" و Object message يحتوي type وcode وname وdescription:

{
  "status": "error",
  "message": {
    "type": "error",
    "code": "ERROR_ZID_INVENTORY_ADDRESSES_NOT_FOUND",
    "name": "Sorry",
    "description": "Inventory address not found"
  }
}

ويعرض التوثيق أيضًا أخطاء تحقق باللغة العربية، تظهر فيها حتى قيمة code نفسها بالعربية (خطأ في التحقق). لذا ابنِ منطقك أولًا على رمز HTTP، واعتبر code معلومة مساعدة لا ثابتًا مضمونًا، ولا تعتمد على نص الرسالة. دالة صغيرة توحّد الشكلين:

function readZidError(status, body) {
  if (body && body.error) {
    return { status, code: body.error.code,
             message: body.error.message, fields: body.error.fields || {} };
  }
  if (body && body.message && typeof body.message === 'object') {
    return { status, code: body.message.code,
             message: body.message.description, fields: {} };
  }
  return { status, code: null, message: null, fields: {} };
}

التعامل مع 429 و5xx بالتراجع التدريجي

يوصي التوثيق بالتراجع الأُسّي (exponential backoff) عند 429 Too Many Requests. ولا تنشر زد قيم تأخير محددة، فالأرقام أدناه نقطة بداية وليست قاعدة من زد:

async function callZid(doRequest, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const res = await doRequest();
    const retryable = [429, 500, 503].includes(res.status);
    if (!retryable) return res;
    const cap = Math.min(60000, 1000 * 2 ** attempt); // 1s, 2s, 4s ... max 60s
    const wait = cap / 2 + Math.random() * (cap / 2);  // add jitter
    await new Promise(r => setTimeout(r, wait));
  }
  throw new Error('Zid API still failing after retries');
}

• أعد المحاولة فقط لما يمكن تكراره بأمان. إعادة GET لا ضرر فيها، أما إعادة طلب إنشاء فقد تنتج نسخًا مكررة ما لم تتحقق أولًا.
• لا تُعِد إرسال 400 أو 401 أو 403 أو 404 أو 422 دون تغيير، فلن تنجح حتى تصلح الطلب أو الـ Token أو الصلاحية.
• اعتبر 401 إشارة لفحص الـ Token لا لإعادة المحاولة. وتجد التجديد في دليل OAuth.

ونصيحة مركز المساعدة لرسالة «Too Many Attempts, Please slow down for few seconds !» تسير في الاتجاه نفسه: قسّم الطلبات أو جدولها.

استخدم الصفحات واطلب بيانات أقل

نقاط القوائم مقسّمة إلى صفحات، وأسماء الـ Parameters تختلف من نقطة لأخرى، فراجع كل واحدة. أمثلة:

• List Orders (GET /v1/managers/store/orders): المعاملان page وper_page مطلوبان، وأقصى عدد في الصفحة 100 سجل. ويتحكم payload_type في حجم الرد: simple (الافتراضي) دون المنتجات، وtiny بالـ IDs الأساسية فقط، وdefault يتضمن المنتجات وهو الأبطأ.
• List Customers (GET /v1/managers/store/customers): المعاملان page وper_page اختياريان.
• نقاط المدونة (مثل /v2/blogs/categories/): المعاملان page وpage_size.

إذا انتهت مهلة طلب كبير برمز 504، ينصح مركز المساعدة باستخدام الصفحات مع حجم أصغر، مثل 50 في الصفحة. وللمزامنة الدورية، تقبل List Orders الـ Parameters date_from وdate_to وdate_attribute (created_at أو updated_at)، فتجلب ما تغيّر منذ آخر تشغيل بدل السجل كاملًا:

GET /v1/managers/store/orders?page=1&per_page=50&payload_type=simple&date_attribute=updated_at&date_from=2026-09-01T00:00:00.000%2B0000

توقّف عن الاستعلام المتكرر: الـ Webhooks والتخزين المؤقت

تطلب زد صراحة ألا تستعلم مرارًا عن تحديثات الحالة. لمتابعة حالة الطلب والدفع استخدم الـ Webhooks: الحدثان order.status.update وorder.payment_status.update يدفعان التغيير إليك، فلا تستهلك أي طلب في الانتظار. ويمكنك تضييق الإرسال أكثر بالشروط (conditions) على order.create وorder.status.update، كما يشرح دليل الـ Webhooks.

• من الممارسات الجيدة تخزين البيانات التي نادرًا ما تتغير مؤقتًا، مثل تفاصيل المتجر وإعداداته، وتحديثها على جدول أو عند وصول webhook متعلق بها.
• شغّل طابورًا لكل متجر حتى لا تستهلك عملية استيراد كبيرة لتاجر ما حصة العمل الفوري لمتجره، وقدّم الطلبات التفاعلية على المهام الخلفية.
• سجّل كل طلب ورد أثناء التطوير، كما توصي صفحة Responses، لترى أين تذهب حصتك.
• اختبر تكاملك في المتجر التجريبي قبل الإطلاق.