نقطة /v1/quotas تُظهر ثلاثة أمور:

حدود الخطة الأساسية (الواجهة البرمجية حصرية لخطة Enterprise، لذا الخطة هنا دائمًا enterprise).
أي تجاوزات ضبطها الدعم لمتجرك (صفقات مخصصة، تكاملات شركاء).
الحدود الفعّالة — التجاوز يفوز، ويعود إلى افتراضيات الخطة عند غيابه.

الوصول إلى الواجهة البرمجية بالمفاتيح التي تُنشئها أنت يتطلب خطة Enterprise سارية. ومغادرة Enterprise، بتخفيض الخطة أو بانتهاء صلاحية الاشتراك، لا تغيّر الحدود المُبلَّغ عنها؛ بل تُزيل الوصول كليًا (403 forbidden في كل نداء، بما فيه هذه النقطة) إلى أن يعود المتجر إلى Enterprise. ولن تحتاج أبدًا إلى إعادة إصدار مفتاح.

ℹ️ معلومة — حدود الواجهة البرمجية وحدها

هذه الحصص تحتسب نداءات الواجهة البرمجية المُرسَلة بمفتاح إلى https://api.dzbuild.app/v1. أما واجهة متجرك وصفحة إتمام الطلب ولوحة التحكم فلا تُقيَّد بها أبدًا ولا تستهلك منها شيئًا. انظر حدود المعدل.

حدود الخطط

الخطة	طلبات / شهر	تسجيلات / شهر	Webhooks / شهر	طلبات / دقيقة
`enterprise`	`-1`	`-1`	`-1`	600

خطط Free / Pro / Unlimited القديمة أُلغيت في أوت 2026 حين صارت الواجهة البرمجية حصرية لخطة Enterprise. والقيمة المُبلَّغ عنها تحت effective هي القيمة المطبَّقة فعلًا، مع استثناء واحد: النداءات إلى https://api.dzbuild.app/v1 لا تتعدّى أبدًا 600 طلب في الدقيقة لكل متجر، حتى لو ضبط تجاوزٌ قيمة requests_per_minute أعلى من ذلك.

GET /v1/quotas

المصادقة: مفتاح منصة بصلاحية usage:read (وهذه الصلاحية مطبَّقة فعلًا هنا).

الطلب

curl https://api.dzbuild.app/v1/quotas \
  -H "Authorization: Bearer $DZ_KEY"

الاستجابة 200

{
  "data": {
    "tier": "enterprise",
    "tier_limits": {
      "requests_per_month":  -1,
      "signups_per_month":   -1,
      "webhooks_per_month":  -1,
      "requests_per_minute": 600
    },
    "overrides": null,
    "effective": {
      "requests_per_month":  -1,
      "signups_per_month":   -1,
      "webhooks_per_month":  -1,
      "requests_per_minute": 600
    }
  }
}

عند وجود تجاوز:

{
  "data": {
    "tier": "enterprise",
    "tier_limits": {
      "requests_per_month":  -1,
      "signups_per_month":   -1,
      "webhooks_per_month":  -1,
      "requests_per_minute": 600
    },
    "overrides": {
      "store_id":            13,
      "requests_per_month":  null,       // not overridden, falls back to tier
      "signups_per_month":   null,
      "webhooks_per_month":  null,
      "requests_per_minute": 1200,       // override
      "notes": "Partner integration — Q2 2026",
      "set_by_user_id":      1,
      "updated_at":          "2026-04-30 19:27:55"
    },
    "effective": {
      "requests_per_month":  -1,         // from tier
      "signups_per_month":   -1,
      "webhooks_per_month":  -1,
      "requests_per_minute": 1200        // from override
    }
  }
}

متى تطلب تجاوزًا

ذروة موسمية بدون ترقية الشهر كاملًا (عيد، بلاك فرايدي).
تكامل شركاء — خدمة شبيهة بـ Zapier تتصل نيابة عنك وتحتاج RPS أعلى.
عقد مخصص — صفقات Enterprise.

تواصل مع الدعم بمعرّف متجرك لإعداد ذلك. التجاوز يحلّ محلّ قيمة الخطة لأي حقول مضبوطة؛ والحقول null تعود إلى افتراضي الخطة. وقد يكون التجاوز أدنى من افتراضي الخطة — عمليًا لا يرفعها الدعم إلا رفعًا، لكن اعتبر effective هو المرجع بدل افتراض أنها مساوية لـ tier_limits أو أعلى منها.

وoverrides يُعاد كما هو، لذا قد تظهر حقول إضافية مع الوقت. ويكون null عند عدم وجود تجاوز للمتجر.

-1 = غير محدود

أي حقل قيمته -1 يعني بلا حد. وخطة enterprise تجعل الحقول الشهرية الثلاثة -1 افتراضيًا؛ أما requests_per_minute فهو دائمًا قيمة حقيقية (وليس -1 أبدًا) حتى لا يستطيع تكامل واحد أن يُثقل الخوادم التي تخدم كذلك واجهات متاجر التجار. انظر حدود المعدل.

متى تصطدم بحصة

اندفاع في الدقيقة → 429 مع Retry-After. يُطبَّق لكل متجر: جميع مفاتيح المتجر تتشارك الميزانية، بما فيها المفاتيح التي يستعملها Copilot أو مساعد ذكاء اصطناعي متصل (Claude أو ChatGPT) أو تطبيق مثبّت. والعدّادات متّسقة تدريجيًا، فقد يُسمح لك وجيزًا بأكثر من الحد أثناء اندفاع حاد، أو ترى 429 أبكر قليلًا مما يوحي به عدّك الخاص.
حصة الطلبات الشهرية → 402 quota_exceeded حتى أول الشهر القادم. تُطبَّق لكل متجر، مجموعةً عبر كل مفاتيحه، ويُرفض الطلب قبل معالجته.
حصة الاشتراكات — يُبلَّغ عنها لكنها غير مطبَّقة في v1. تجاوز signups_per_month لا يحجب /v1/signups؛ والعدّاد معلوماتي فقط (GET /v1/usage) إلى أن تُطلَق الفوترة بالاستهلاك.
حصة تسليم Webhook: غير مطبَّقة وغير مُقاسة في v1. التسليمات لا تُحسب أبدًا ولا تتوقف بسبب حصة؛ والحماية التلقائية الوحيدة تعمل على مستوى كل عملية تسليم على حدة: الإخفاق الذي لا يُعاد (أي 4xx غير 408 و429، أو 3xx) يُنهي تلك العملية من المحاولة الأولى، أما الإخفاق القابل للإعادة (انتهاء المهلة أو خطأ الشبكة، أو 5xx، أو 408، أو 429) فيتوقف بعد المحاولة الفاشلة الخامسة. أما نقطة نهاية الـ webhook نفسها فلا تُوقَف أبدًا، وتظل الأحداث الجديدة تُدرَج في الطابور من أجلها.

انظر الأخطاء وحدود المعدل لاستراتيجيات إعادة المحاولة.

المقالات ذات الصلة