API شرکا
API شرکا برای ارتباط سرور با سرور: کلید صادر کنید، پیکربندی ویترین و موقعیت‌ها را بخوانید، مشتری بسازید، طرح اختصاص دهید و لینک‌های اشتراک را از سایت یا ربات تلگرام خودتان مدیریت کنید.
API شرکا به شما امکان می‌دهد سایت خودتان، پنل خودتان یا یک ربات تلگرام را روی CreateYourVPN بسازید.
این API مشتریان، اشتراک‌ها، طرح‌ها و پیکربندی ویترین را پوشش می‌دهد. زیرساخت، یعنی سرورها، نودها، پنل‌ها و اطلاعات ورود SSH، خارج از قرارداد عمومی است.
فقط ارتباط سرور با سرور. کلیدهای API را روی سرور خودتان نگه دارید و آن‌ها را در کد frontend قرار ندهید. درخواست‌هایی که هدرهای مرورگر دارند با 403 browser_forbidden رد می‌شوند.
دریافت کلید
داشبورد را باز کنید ← منوی حساب ← «API»، زبانهٔ «کلیدها».
برای کلید نامی بگذارید (ربات تلگرام، لندینگ) و فقط دسترسی‌هایی را که لازم دارد انتخاب کنید.
روی «صدور کلید» بزنید و مقدار کامل را کپی کنید. بخش محرمانه فقط یک‌بار نمایش داده می‌شود، چون فقط هش آن ذخیره می‌شود.
هر شریک می‌تواند تا ۵ کلید فعال داشته باشد. برای چرخش کلید، کلید تازه‌ای صادر کنید، یکپارچه‌سازی را به‌روز کنید و سپس کلید قدیمی را باطل کنید.
احراز هویت
کلید را به‌صورت توکن bearer بفرستید:
curl https://api.createyourvpn.com/api/v1/partner-api/me \
-H "Authorization: Bearer cyv_live_<key_id>_<secret>"X-API-Key: cyv_live_… هم کار می‌کند، برای وقتی که Authorization را یک پراکسی اشغال کرده است.
کلید این شکل را دارد: cyv_live_<key_id>_<secret>. نیمهٔ اول (key_id) عمومی است: همان چیزی است که در داشبورد می‌بینید و می‌توانید بی‌خطر به پشتیبانی بگویید. نیمهٔ دوم بخش محرمانه است.
دسترسی‌ها (scopes)
| دسترسی | چه اجازه‌ای می‌دهد |
|---|---|
config:read | خواندن پیکربندی ویترین، طرح‌ها، موقعیت‌ها و /me. |
users:read | خواندن مشتریان، اشتراک‌ها و ترافیک آن‌ها. |
users:write | ساخت مشتری، اختصاص طرح، بازنشانی لینک‌های اشتراک و حذف مشتری. |
config:read برای یکپارچه‌سازی‌هایی که فقط داده‌های ویترین را می‌خوانند کافی است. users:read یا users:write را فقط وقتی اضافه کنید که یکپارچه‌سازی به عملیات مربوط به مشتریان نیاز دارد.
قرارداد API و نمونه‌ها
قرارداد کامل و قابل اجرا در مجموعهٔ عمومی Postman است. این مجموعه همهٔ endpointها، دسترسی‌ها، پارامترها، bodyهای درخواست، نمونه‌های پاسخ و کدهای خطای پایدار را در بر دارد. مجموعه از قرارداد backend تولید می‌شود و مرجع فعلی ساختار درخواست‌ها و پاسخ‌هاست.
محدودیت‌های نرخ
محدودیت‌ها برای هر کلید جداگانه شمرده می‌شوند و به نشانی IP درخواست بستگی ندارند.
- ۱۲۰ درخواست در دقیقه برای هر کلید در مجموع.
- ۱۰ درخواست در دقیقه به‌طور خاص برای
GET /users.
GET /users محدودیت جداگانه دارد، چون هر درخواست فهرست کامل مشتریان را بار می‌کند. برای بررسی‌های منظم از GET /users/{id} یا جست‌وجو با externalId استفاده کنید.
الگوی پیشنهادی. شناسهٔ مشتری در CreateYourVPN را که هنگام ساخت برگردانده می‌شود ذخیره کنید و برای درخواست‌های بعدی از 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"}'تکرار درخواست با همان کلید ظرف ۲۴ ساعت پاسخ ذخیره‌شده را برمی‌گرداند و عملیات دوباره اجرا نمی‌شود. این کار جلوی تغییرات تکراری را می‌گیرد، وقتی یکپارچه‌سازی پس از timeout دوباره تلاش می‌کند.
برای هر رویداد کسب‌وکار (مثلاً یک پرداخت یا یک اقدام) یک کلید بسازید و در همهٔ تلاش‌های دوبارهٔ همان رویداد از آن استفاده کنید.
اگر تلاش اول هنوز در حال اجراست یا نتیجه‌اش موقتاً معلوم نیست، API پاسخ 409 conflict می‌دهد و عملیات را دوباره اجرا نمی‌کند. پیش از تصمیم به تلاش دوباره، وضعیت فعلی مشتری را بررسی کنید.
مجموعهٔ عمومی Postman بالا را مرجع ساختار درخواست‌ها و پاسخ‌ها بدانید.
بازیابی از یک پشتیبان
دو راه برای بازگرداندن کاربران: بازیابی یک‌کلیکی درون داشبورد که آن‌ها را به‌صورت خودتوان دوباره وارد می‌کند، یا بازیابی دستی در یک Marzban خام، چون فایل در قالب بومی کاربر Marzban است.
دسترسی اضطراری
راهی پشتیبان برای اتصال وقتی شبکه از فهرست سفید استفاده می‌کند و اتصال اصلی مسدود است: یک تماس تصویری بسازید، پیوند آن را از حساب خود یا با ایمیل به ما بدهید و اتصالی آمادهٔ استفاده بگیرید.