راهنمای Partner Open API

پس از تأیید شدن به‌عنوان شریک QCode، حساب نماینده فروش خود را به‌صورت برنامه‌نویسی‌شده با یک توکن دسترسی مدیریت کنید: موجودی و مصرف را بررسی کنید و کلیدهای فرعی API را که می‌فروشید ایجاد و فعال/غیرفعال کنید. پیش‌نیاز، نحوه درخواست، احراز هویت، مرجع نقاط پایانی، محدودیت‌های نرخ درخواست و امنیت را پوشش می‌دهد.

به کلید API نیاز دارید؟ ثبت‌نام ←·نقاط پایانی و Base URL ←

Partner Open API در QCode به شما امکان می‌دهد حساب نماینده فروش خود را به‌صورت برنامه‌نویسی‌شده مدیریت کنید — موجودی و مصرف را بررسی کنید، کلیدهای فرعی API را که می‌فروشید ایجاد و مدیریت کنید — تا بتوانید تأمین، تطبیق و صدور کلید را در سیستم‌های خودتان یکپارچه کنید، به‌جای استفاده دستی از پنل وب.

⚠️ پیش‌نیاز: ابتدا باید شریک تأییدشده باشید. این API فقط برای شرکای تأییدشده QCode در دسترس است. اگر هنوز شریک نیستید، ابتدا درخواست دهید؛ پس از تأیید می‌توانید توکن دسترسی بسازید و API را فراخوانی کنید.

1. این API چه کاری انجام می‌دهد¶

به‌عنوان شریک QCode، شما یک حساب نماینده فروش دارید (موجودی پیش‌پرداخت و ضریب تخفیف مبتنی بر سطح) و می‌توانید چندین کلید فرعی API برای فروش مجدد به مشتریان یا تیم خود ایجاد کنید که هر کدام سهمیه خاص خود را دارند. Open API این قابلیت‌های پنل را به‌صورت نقاط پایانی REST ارائه می‌کند:

• خواندن — موجودی و مصرف حساب کاربری، هزینه روزانه در 7 / 30 روز گذشته، فهرست همه کلیدهای فرعی API همراه با هزینه هر کلید.
• نوشتن — ایجاد یک کلید فرعی API (متن ساده فقط یک بار برگردانده می‌شود)، فعال / غیرفعال کردن یک کلید فرعی API، به‌روزرسانی سهمیه و هم‌زمانی یک کلید.

مناسب برای شرکایی که می‌خواهند صدور کلید / تطبیق را در سیستم صورت‌حساب خود یکپارچه کنند، کلیدها را به‌صورت خودکار برای مشتریان پایین‌دستی تأمین کنند، یا مصرف را برای پایش دریافت کنند.

2. چگونه شریک شوید (پیش‌نیاز)¶

این API فقط پس از تأیید دسترسی شریک شما قابل استفاده است.

• هنوز شریک نیستید → به برنامه شرکا مراجعه کنید تا سطوح و قیمت‌گذاری را بررسی کنید، سپس از طریق بخش «نحوه درخواست» درخواست دهید (ایمیل hi@qcode.cc). پس از تأیید، حساب کاربری شما به‌عنوان شریک فعال می‌شود.
• از قبل شریک هستید → به داشبورد شرکا وارد شوید.

فرایند شروع به کار شامل شارژ حساب پیش‌پرداخت و یک سطح شریک (A–E، هر کدام با ضریب تخفیف متفاوت) است؛ برای جزئیات صفحه برنامه شرکا را ببینید. فراخوانی این API روی حساب کاربری فعال‌نشده 403 برمی‌گرداند.

3. شروع سریع: دریافت توکن دسترسی¶

پس از تأیید:

1. به 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¶

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

5. مرجع نقطه پایانی¶

همه نقاط پایانی زیر پیشوند /api/v1/reseller/ قرار دارند.

6. ایجاد کلید API فرعی¶

محدودیت‌ها بر حسب USD (مصرف با نرخ‌های هر مدل در /models تبدیل می‌شود) هستند. daily_cost_limit_usd و total_cost_limit_usd باید بزرگ‌تر از 0 باشند. یک هدر Idempotency-Key ارسال کنید تا تلاش‌های مجدد ایمن شوند (تا تلاش مجدد پس از پایان مهلت دو کلید ایجاد نکند). کلید cr_… به‌صورت متن ساده فقط یک بار برگردانده می‌شود — آن را ذخیره کنید و به مشتری خود تحویل دهید.

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":[]}}

فعال‌سازی / غیرفعال‌سازی، به‌روزرسانی سهمیه:

# 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": "..."}

9. امنیت¶

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

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

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

سازمانی ←