# راهنمای 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. شروع سریع: دریافت توکن دسترسی

پس از تأیید:

1. به [qcode.cc](https://qcode.cc) وارد شوید → **داشبورد شرکا** را باز کنید.
2. **«Open API / Access Token»** را باز کنید.
3. روی **تولید توکن** کلیک کنید تا توکنی مانند `rsk_xxxxxxxx` دریافت کنید.

> 🔑 **توکن فقط یک بار و به‌صورت کامل، هنگام تولید / بازنشانی نمایش داده می‌شود** — آن را کپی و به‌صورت امن ذخیره کنید (ما فقط هش آن را نگه می‌داریم). اگر گم شد یا افشا شد، روی **بازنشانی** در همان صفحه کلیک کنید تا توکن جایگزین شود؛ **توکن قدیمی بلافاصله از کار می‌افتد**.

> 🆚 **`rsk_` معادل `qot_` نیست.** توکن این صفحه **توکن دسترسی شریک (نماینده فروش)** `rsk_` است: در داشبورد شرکا و در بخش «Open API / Access Token» تولید می‌شود و Open API شرکا (موجودی، مصرف، مدیریت کلیدهای فرعی) را مجاز می‌کند. توکن 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. محدودیت نرخ درخواست

اینها نقاط پایانی مدیریتی با فراوانی پایین هستند و محدودیت نرخ درخواست دارند تا اثر توکن افشاشده کاهش یابد:

- به‌ازای هر توکن: **60 / دقیقه**، **1000 / روز**.
- ساخت کلیدها (`POST /keys`): **5 / ساعت** به‌ازای هر توکن.
- در صورت عبور از محدودیت، HTTP **429** همراه با هدر `Retry-After` (ثانیه) بازگردانده می‌شود.

---

## 8. پاسخ‌ها و خطاها

- موفقیت: `{"ok": true, "data": { ... }}`
- خطا: کد وضعیت HTTP متناظر + `{"detail": "..."}`

| وضعیت | معنا |
|---|---|
| 401 | توکن نامعتبر یا ناموجود |
| 403 | حساب کاربری فعال نیست (دسترسی شریک تأیید نشده / معلق شده است) |
| 404 | کلید یافت نشد یا متعلق به شما نیست |
| 422 | خطای اعتبارسنجی / سهمیه |
| 429 | محدودیت نرخ درخواست |

---

## 9. امنیت

- توکن دسترسی را مانند گذرواژه بدانید: آن را در سمت سرور نگه دارید، فقط از HTTPS استفاده کنید، **هرگز** آن را در مخزن کد کامیت نکنید یا در مرورگر افشا نکنید.
- اگر توکنی افشا شد → بلافاصله آن را در پنل **بازنشانی** کنید (توکن قدیمی از کار می‌افتد) و کلیدهای فرعی متأثر را در صورت نیاز غیرفعال کنید.
- روی هر کلید فرعی که می‌سازید، محدودیت‌های معقول `total` / `daily` تعیین کنید تا در صورت افشای یک کلید، دامنه خسارت محدود بماند.
- کلیدهای فرعی `cr_…` که در اختیار دیگران می‌گذارید از موجودی حساب کاربری شما برداشت می‌کنند — آن‌ها را با دقت مدیریت و تطبیق کنید.

---

## 10. مرجع کامل و پشتیبانی

- پس از تأیید، صفحه **«API Docs»** در داشبورد شرکا (`/reseller/api-docs`) مرجع رسمی و نسخه‌بندی‌شده توسعه‌دهندگان است.
- هنوز شریک نیستید؟ → [با برنامه شرکا آشنا شوید و درخواست دهید](https://qcode.cc/partner-program)
- پرسشی دارید؟ → چت زنده درون‌سایت، یا ایمیل به `hi@qcode.cc`.