# الحصص

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

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

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

حدود الواجهة البرمجية وحدها

هذه الحصص تحتسب نداءات الواجهة البرمجية المُرسَلة بمفتاح إلى `https://api.dzbuild.app/v1`. أما واجهة متجرك وصفحة إتمام الطلب ولوحة التحكم فلا تُقيَّد بها أبدًا ولا تستهلك منها شيئًا. انظر [حدود المعدل](https://dzbuild.com/ar/ar/api-docs/rate-limits.md).

## حدود الخطط[​](#حدود-الخطط "رابط مباشر إلى حدود الخطط")

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

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

## `GET /v1/quotas`[​](#get-v1quotas "رابط مباشر إلى get-v1quotas")

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

### الطلب[​](#الطلب "رابط مباشر إلى الطلب")

```
curl https://api.dzbuild.app/v1/quotas \

  -H "Authorization: Bearer $DZ_KEY"
```

### الاستجابة 200[​](#الاستجابة-200 "رابط مباشر إلى الاستجابة 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--غير-محدود "رابط مباشر إلى -1--غير-محدود")

أي حقل قيمته `-1` يعني بلا حد. وخطة `enterprise` تجعل الحقول **الشهرية** الثلاثة `-1` افتراضيًا؛ أما `requests_per_minute` فهو دائمًا قيمة حقيقية (وليس `-1` أبدًا) حتى لا يستطيع تكامل واحد أن يُثقل الخوادم التي تخدم كذلك واجهات متاجر التجار. انظر [حدود المعدل](https://dzbuild.com/ar/ar/api-docs/rate-limits.md).

## متى تصطدم بحصة[​](#متى-تصطدم-بحصة "رابط مباشر إلى متى تصطدم بحصة")

* **اندفاع في الدقيقة** → `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 نفسها فلا تُوقَف أبدًا، وتظل الأحداث الجديدة تُدرَج في الطابور من أجلها.

انظر [الأخطاء](https://dzbuild.com/ar/ar/api-docs/errors.md) و[حدود المعدل](https://dzbuild.com/ar/ar/api-docs/rate-limits.md) لاستراتيجيات إعادة المحاولة.