# دليل Partner Open API

تتيح لك **Partner Open API** من QCode إدارة حساب الموزّع الخاص بك برمجيًا — تحقّق من الرصيد والاستخدام، وأنشئ مفاتيح API الفرعية التي تعيد بيعها وتديرها — لتتمكن من دمج التجهيز والتسوية وإصدار المفاتيح في أنظمتك الخاصة بدلًا من استخدام لوحة الويب يدويًا.

> ⚠️ **المتطلب المسبق: يجب أن تكون شريكًا معتمدًا أولًا.**
> لا يتوفر هذا API **إلا لشركاء QCode المعتمدين**. إذا لم تكن شريكًا بعد، [قدّم أولًا](https://qcode.cc/partner-program)؛ وبعد الموافقة يمكنك إنشاء رمز وصول واستدعاء API.

---

## 1. ما الذي يفعله هذا API

بصفتك شريكًا في QCode، لديك حساب موزّع (رصيد مدفوع مسبقًا، ومعامل خصم حسب الفئة) ويمكنك إنشاء عدة **مفاتيح API فرعية** لإعادة بيعها لعملائك أو فريقك، ولكل منها حصتها الخاصة. يكشف Open API عن قدرات اللوحة هذه كنقاط نهاية REST:

- **قراءة** — رصيد الحساب والاستخدام، والإنفاق اليومي خلال آخر 7 / 30 يومًا، وسرد جميع مفاتيح API الفرعية مع تكلفة كل مفتاح.
- **كتابة** — إنشاء مفتاح API فرعي (يُعاد النص العادي مرة واحدة)، وتمكين / تعطيل مفتاح API فرعي، وتحديث حصة مفتاح وعدد الطلبات المتزامنة.

الأنسب للشركاء الذين يريدون ربط إصدار المفاتيح / التسوية بنظام الفوترة الخاص بهم، وتزويد العملاء التابعين بالمفاتيح تلقائيًا، أو سحب الاستخدام لأغراض المراقبة.

---

## 2. كيف تصبح شريكًا (المتطلب المسبق)

لا يمكن استخدام هذا API **إلا بعد الموافقة على وصولك كشريك**.

- **لست شريكًا بعد** → زُر [برنامج الشركاء](https://qcode.cc/partner-program) لمراجعة الفئات والأسعار، ثم قدّم عبر قسم "كيفية التقديم" (البريد الإلكتروني `hi@qcode.cc`). وبعد الموافقة، يُفعَّل حسابك كشريك.
- **شريك بالفعل** → سجّل الدخول إلى [لوحة تحكم الشركاء](https://qcode.cc/reseller/dashboard).

> تتضمن عملية الانضمام شحن الرصيد مسبقًا وفئة شريك (A–E، ولكل منها معامل خصم مختلف)؛ راجع صفحة [برنامج الشركاء](https://qcode.cc/partner-program) للتفاصيل. استدعاء هذا API على حساب غير مفعّل يُرجع `403`.

---
## 3. البدء السريع: الحصول على token وصول

بعد الموافقة:

1. سجّل الدخول إلى [qcode.cc](https://qcode.cc) → افتح **لوحة تحكم الشركاء**.
2. افتح **«Open API / Access Token»**.
3. انقر على **إنشاء token** للحصول على token مثل `rsk_xxxxxxxx`.

> 🔑 **لا يُعرض token كاملًا إلا مرة واحدة، عند الإنشاء / إعادة التعيين** — انسخه واحفظه بأمان (نحن لا نحتفظ إلا بتجزئته). إذا فُقد أو سُرّب، فانقر على **إعادة التعيين** في الصفحة نفسها لتدويره؛ **ويتوقف token القديم عن العمل فورًا**.

> 🆚 **`rsk_` ليس `qot_`.** token الموجود في هذه الصفحة هو **token وصول الشريك (الموزّع)** `rsk_`: يُنشأ في لوحة تحكم الشركاء ضمن «Open API / Access Token»، ويُخوّل الوصول إلى Partner Open API (الرصيد، الاستخدام، إدارة المفاتيح الفرعية). أما token Open API **الشخصي** `qot_` فيأتي من لوحة التحكم ضمن **Open API** (`/dashboard/openapi-token`)؛ وهو للقراءة فقط ولا يعرض إلا انتهاء صلاحية مفاتيحك الخاصة واستخدامها. ولا يمكن استخدام أحدهما بدل الآخر.

---

## 4. المصادقة وBase URL

| العنصر | القيمة |
|---|---|
| Base URL (موصى به) | `https://api.r.qcode.cc` |
| البديل | `https://qcode.cc` (نفس API) |
| المصادقة | الترويسة `Authorization: Bearer rsk_xxxxxxxx` |
| جسم الطلب للكتابة | JSON، مع `Content-Type: application/json` |

```bash
curl https://api.r.qcode.cc/api/v1/reseller/balance \
  -H "Authorization: Bearer rsk_xxxxxxxx"
```

---

## 5. مرجع نقاط النهاية

جميع نقاط النهاية ضمن البادئة `/api/v1/reseller/`.

| الطريقة | المسار | الوصف |
|---|---|---|
| GET | `/api/v1/reseller/me` | ملخص الحساب (المستوى، المنطقة، العملة، الحالة) |
| GET | `/api/v1/reseller/balance` | الرصيد والاستخدام (عملة التسوية الخاصة بك) |
| GET | `/api/v1/reseller/usage?range=7d` | سلسلة الإنفاق اليومي (`range` = `7d` / `30d`) |
| GET | `/api/v1/reseller/keys` | عرض مفاتيح API الفرعية الخاصة بك + تكلفة كل مفتاح |
| GET | `/api/v1/reseller/keys/{id}` | تفاصيل مفتاح واحد |
| POST | `/api/v1/reseller/keys` | إنشاء مفتاح فرعي (**يُعاد النص الصريح مرة واحدة**) |
| POST | `/api/v1/reseller/keys/{id}/enable` | تفعيل مفتاح |
| POST | `/api/v1/reseller/keys/{id}/disable` | تعطيل مفتاح |
| PATCH | `/api/v1/reseller/keys/{id}` | تحديث الحصة / التزامن |

---

## 6. إنشاء مفتاح API فرعي

الحدود بـ **USD (يُحوَّل الاستهلاك وفق أسعار كل نموذج على [/models](https://qcode.cc/models))**. يجب أن يكون كل من `daily_cost_limit_usd` و`total_cost_limit_usd` **أكبر من 0**. مرّر ترويسة `Idempotency-Key` لجعل إعادة المحاولات آمنة (حتى لا تنشئ إعادة المحاولة عند انتهاء المهلة مفتاحين). يُعاد المفتاح `cr_…` كنص صريح **مرة واحدة فقط** — احفظه وسلّمه إلى عميلك.

```bash
curl -X POST https://api.r.qcode.cc/api/v1/reseller/keys \
  -H "Authorization: Bearer rsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-per-create" \
  -d '{"description":"client-a","daily_cost_limit_usd":5,"total_cost_limit_usd":100,"concurrency_limit":5}'

# → {"ok":true,"data":{"id":"...","name":"...","api_key":"cr_...","warnings":[]}}
```

تفعيل / تعطيل، وتحديث الحصة:

```bash
# disable
curl -X POST https://api.r.qcode.cc/api/v1/reseller/keys/{id}/disable \
  -H "Authorization: Bearer rsk_xxxxxxxx"

# change daily limit
curl -X PATCH https://api.r.qcode.cc/api/v1/reseller/keys/{id} \
  -H "Authorization: Bearer rsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"daily_cost_limit_usd":10}'
```

---
## 7. حدود معدل الطلبات

هذه نقاط نهاية إدارية منخفضة التكرار، ومقيّدة بحد معدل الطلبات للحد من تأثير token مسرّب:

- لكل token: **60 / دقيقة**، **1000 / يوم**.
- إنشاء المفاتيح (`POST /keys`): **5 / ساعة** لكل token.
- تجاوز حد يعيد HTTP **429** مع ترويسة `Retry-After` (بالثواني).

---

## 8. الاستجابات والأخطاء

- النجاح: `{"ok": true, "data": { ... }}`
- الخطأ: حالة HTTP المطابقة + `{"detail": "..."}`

| الحالة | المعنى |
|---|---|
| 401 | token غير صالح أو مفقود |
| 403 | الحساب غير نشط (وصول الشريك غير معتمد / موقوف) |
| 404 | المفتاح غير موجود أو لا يخصك |
| 422 | خطأ في التحقق / الحصة |
| 429 | مقيّد بمعدل الطلبات |

---

## 9. الأمان

- تعامل مع token الوصول كما تعامل كلمة المرور: احتفظ به على الخادم، وباستخدام HTTPS فقط، ولا تُدرجه أبدًا في مستودع ولا تكشفه في المتصفح.
- إذا تسرّب token → أعد تعيينه في اللوحة فورًا (يبطل token القديم)، وعطّل المفاتيح الفرعية المتأثرة حسب الحاجة.
- عيّن حدودًا معقولة لـ `total` / `daily` على كل مفتاح فرعي تنشئه لاحتواء الخسارة إذا تسرّب مفتاح واحد.
- المفاتيح الفرعية `cr_…` التي تمنحها تُخصم من رصيد حسابك — أدرها وطابقها بعناية.

---

## 10. المرجع الكامل والدعم

- بعد الاعتماد، تكون صفحة **«API Docs»** داخل لوحة تحكم الشركاء (`/reseller/api-docs`) هي المرجع الموثوق للمطورين والمُدار بالإصدارات.
- لست شريكًا بعد؟ → [تعرّف على برنامج الشركاء وقدّم طلبًا للانضمام إليه](https://qcode.cc/partner-program)
- لديك أسئلة؟ → الدردشة المباشرة داخل الموقع، أو راسلنا عبر البريد الإلكتروني `hi@qcode.cc`.