واجهة API للشركاء

تتيح لك واجهة API للشركاء أن تبني موقعك الخاص أو لوحتك الخاصة أو روبوت Telegram فوق CreateYourVPN.

تغطي الواجهة العملاء والاشتراكات والباقات وإعدادات المتجر. أما البنية التحتية، مثل الخوادم والعُقد واللوحات وبيانات اعتماد SSH، فهي خارج العقد العام.

الحصول على مفتاح

يمكن لكل شريك أن يملك حتى 5 مفاتيح نشطة. ولتدوير مفتاح، أصدر مفتاحاً جديداً، وحدّث التكامل، ثم ألغِ المفتاح القديم.

المصادقة

أرسل المفتاح كرمز bearer:

curl https://api.createyourvpn.com/api/v1/partner-api/me \
  -H "Authorization: Bearer cyv_live_<key_id>_<secret>"

X-API-Key: cyv_live_… يعمل أيضاً، للحالات التي يشغل فيها وسيط (proxy) الترويسة Authorization.

يبدو المفتاح هكذا: cyv_live_<key_id>_<secret>. النصف الأول (key_id) علني: هو ما تراه في لوحة التحكم، ويمكنك ذكره للدعم بأمان. والنصف الثاني هو السر.

الصلاحيات (scopes)

config:read يكفي للتكاملات التي تقرأ بيانات المتجر فقط. أضف users:read أو users:write فقط عندما يحتاج التكامل إلى العمليات المقابلة على العملاء.

عقد API والأمثلة

يوجد العقد الكامل القابل للتشغيل في مجموعة Postman العامة. وهي تضم كل نقطة نهاية وصلاحية ومعامل وجسم طلب ومثال استجابة ورمز خطأ ثابت. وتُولَّد المجموعة من عقد الواجهة الخلفية، وهي المصدر الحالي لمخططات الطلبات والاستجابات.

حدود المعدّل

تُحسب الحدود لكل مفتاح على حدة، بصرف النظر عن عنوان IP الذي يأتي منه الطلب.

• 120 طلباً في الدقيقة لكل مفتاح إجمالاً.
• 10 طلبات في الدقيقة لـ GET /users تحديداً.

لـ GET /users حد مستقل لأن كل طلب يحمّل قائمة العملاء كاملة. وللاستعلامات المنتظمة استخدم GET /users/{id} أو البحث عبر externalId.

منع التكرار (Idempotency)

تتطلب ثلاث عمليات الترويسة Idempotency-Key: منح باقة، وإعادة تعيين رابط الاشتراك، وحذف عميل.

curl -X POST .../users/u_9f3a…/grant \
  -H "Authorization: Bearer $CYV_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariffId":"monthly"}'

تكرار الطلب بالمفتاح نفسه خلال 24 ساعة يعيد الاستجابة المحفوظة بدلاً من تنفيذ العملية مرة أخرى. وهذا يمنع التغييرات المكررة عندما يعيد التكامل المحاولة بعد انتهاء المهلة.

أنشئ مفتاحاً واحداً لكل حدث تجاري (مثلاً دفعة واحدة أو إجراء واحد) وأعد استخدامه في كل محاولة لهذا الحدث.

إذا كانت المحاولة الأولى ما تزال قيد التنفيذ، أو كانت نتيجتها غير معروفة مؤقتاً، تعيد الواجهة 409 conflict دون تنفيذ العملية مرة أخرى. تحقّق من الحالة الحالية للعميل قبل أن تقرّر إعادة المحاولة.

استخدم مجموعة Postman العامة أعلاه مرجعاً لمخططات الطلبات والاستجابات.