دليل 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. البدء السريع: الحصول على token وصول¶

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

1. سجّل الدخول إلى 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¶

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. حدود معدل الطلبات¶

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

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

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

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

9. الأمان¶

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

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

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

المؤسسات ←