وی‌پی‌ان را با برند خودتان بفروشید
خرید پلن، تحویل کانفیگ و تمدید سرویس را با یک REST API ساده خودکار کنید. هزینه‌ها را از کیف پول بپردازید، کانفیگ‌ها را با نام برند خودتان بسازید و تنها در چند دقیقه API را به سامانه‌تان متصل کنید.
- REST · JSON
- Bearer tvp_…
- API v1.1.0
$ کانفیگ با برند شما
پیشوند برندتان را یک‌بار تنظیم کنید تا نام همه کانفیگ‌های جدید با برند شما آغاز شود.
اتوماسیون کامل
خرید پلن، دانلود کانفیگ، تمدید، ساخت دوباره کلیدها و بایگانی سرویس‌ها؛ همه از طریق HTTP.
پرداخت از کیف پول
هزینه هر خرید مستقیماً از موجودی کیف پول تومانی یا USDT شما کسر می‌شود.
توکن‌های امن
برای توکن Bearer تاریخ انقضا و محدودیت IP تعیین کنید و هر زمان لازم بود آن را باطل کنید.
شروع سریع
با سه درخواست، اولین کانفیگ وی‌پی‌ان خود را بسازید.
- ۱
ساخت توکن API
در پنل کاربری ← توسعه‌دهندگان یک توکن بسازید. توکن فقط یک‌بار نمایش داده می‌شود؛ همان موقع آن را کپی کنید و در متغیر محیطی سرورتان نگه دارید.
دریافت کلید APITerminalexport TAKVPN_TOKEN="tvp_your_token_here" - ۲
بررسی حساب
مسیر /me را فراخوانی کنید تا از معتبر بودن توکن مطمئن شوید و موجودی کیف پولتان را ببینید.
curl -sS -X GET "https://api.takvpn.com/api/open/v1/me" \ -H "Authorization: Bearer $TAKVPN_TOKEN" - ۳
خرید پلن
درخواست POST /orders هزینه را از کیف پول کسر می‌کند و ساخت سرویس را آغاز می‌کند. وضعیت سرویس را از مسیر /vpn پیگیری کنید و پس از فعال‌شدن، کانفیگ را دریافت کنید.
curl -sS -X POST "https://api.takvpn.com/api/open/v1/orders" \ -H "Authorization: Bearer $TAKVPN_TOKEN" \ -H "Content-Type: application/json" \ -d '{"plan_id":1,"currency":"IRT"}'
احراز هویت
توکن را در هدر Authorization همه درخواست‌ها بفرستید. توکن به حساب کاربری شما دسترسی دارد و می‌تواند عملیات مربوط به سرویس‌ها و سفارش‌ها را از طرف شما انجام دهد.
Authorization: Bearer tvp_…
Accept: application/jsonنشانی پایه
https://api.takvpn.com/api/open/v1محدودیت IP
توکن را فقط روی سرور نگه دارید
امنیت
با سازوکارهای امنیتی API و نکاتی که برای محافظت از حساب خود باید رعایت کنید آشنا شوید.
توکن فقط در هدر Bearer
توکن فقط از طریق هدر Authorization پذیرفته می‌شود. درخواست‌هایی که توکن را در پارامتر ?token= یا کوکی نشست بفرستند رد می‌شوند؛ بنابراین توکن در گزارش‌ها یا تاریخچه مرورگر باقی نمی‌ماند.
ذخیره امن و نمایش یک‌باره
از هر توکن فقط هش SHA-256 ذخیره می‌شود و مقایسه آن در زمان ثابت انجام می‌گیرد. مقدار کامل توکن نیز فقط هنگام ساخت نمایش داده می‌شود.
محدودیت IP امن
دسترسی توکن را به IPها یا بازه‌های CIDR سرورهای خود محدود کنید. IP واقعی درخواست از پراکسی لبه TakVPN دریافت می‌شود و هدرهای ارسالی کاربر برای جعل IP نادیده گرفته می‌شوند. درخواست از سایر IPها پاسخ 403 با خطای ip not allowed می‌گیرد.
تاریخ انقضا و ابطال فوری
برای هر توکن تاریخ انقضا تعیین کنید و هر زمان لازم بود آن را از پنل باطل کنید. توکن‌های باطل‌شده یا منقضی و توکن‌های متعلق به حساب‌های تعلیق‌شده، بلافاصله پاسخ 401 دریافت می‌کنند.
پاسخ‌های خصوصی و ذخیره‌نشدنی
همه پاسخ‌ها با هدر Cache-Control: no-store و یک X-Request-ID یکتا ارسال می‌شوند. هنگام تماس با پشتیبانی، شناسه درخواست را در اختیار ما بگذارید.
ارتباط فقط از سرور
Open API از CORS پشتیبانی نمی‌کند و باید از بک‌اند شما فراخوانی شود. توکن را در متغیر محیطی یا مخزن امن اسرار نگه دارید؛ هرگز آن را در وب‌سایت، اپلیکیشن موبایل یا مخزن عمومی قرار ندهید.
توکن افشا شده است؟
پیشوند برند
نام هر کانفیگ با یک پیشوند آغاز می‌شود. برند خود را در پنل تنظیم کنید تا نام سرویس‌های جدید با پیشوند دلخواه شما ساخته شود. نام سرویس‌های قبلی تغییر نخواهد کرد.
پیش‌فرض
takvpn-starter-30d12345
با برند شما
mybrand-starter-30d12345
پیشوند باید ۲ تا ۲۴ نویسه داشته باشد، با یک حرف کوچک انگلیسی آغاز شود و فقط شامل حروف کوچک انگلیسی، عدد و خط تیره باشد.
تنظیم برندکیف پول و پرداخت
هزینه ساخت و تمدید سرویس از کیف پول حساب شما کسر می‌شود. در هر درخواست می‌توانید تومان یا USDT را انتخاب کنید. پیش از ثبت سفارش‌های گروهی، از کافی‌بودن موجودی مطمئن شوید.
HTTP 402 — موجودی ناکافی
قیمت نمایندگی
مرجع API
مشخصات 22 مسیر به‌صورت خودکار از سند OpenAPI نمایش داده می‌شود.
حساب1
پلن‌ها3
سفارش‌ها3
سرویس‌های وی‌پی‌ان15
خطاها
API از کدهای استاندارد وضعیت HTTP استفاده می‌کند. جزئیات هر خطا در بدنه پاسخ و با فرمت JSON برگردانده می‌شود.
- 400
400 — درخواست نامعتبر
ساختار بدنه JSON درست نیست یا یکی از فیلدها مقدار نامعتبری دارد؛ برای نمونه currency باید USDT یا IRT باشد.
- 401
401 — احراز هویت ناموفق
توکن ارسال نشده یا نامعتبر، منقضی یا باطل شده است. در صورت نیاز، از پنل توکن جدیدی بسازید.
- 402
402 — موجودی ناکافی
موجودی کیف پول برای خرید یا تمدید کافی نیست. کیف پول را شارژ کنید و درخواست را دوباره بفرستید.
- 403
403 — دسترسی ممنوع
درخواست از IP مجاز توکن ارسال نشده است (ip not allowed) یا حساب شما اجازه دسترسی به این مسیر را ندارد.
- 404
404 — یافت نشد
پلن یا سرویس موردنظر وجود ندارد یا به حساب شما تعلق ندارد.
- 409
409 — تعارض
وضعیت فعلی سرویس اجازه این عملیات را نمی‌دهد؛ ممکن است سرویس شرایط لازم را نداشته باشد، عملیات دیگری روی آن در حال انجام باشد یا مدیر آن را مسدود کرده باشد.
- 429
429 — درخواست‌های بیش از حد
تعداد درخواست‌ها از حد مجاز گذشته است. به‌اندازه زمان اعلام‌شده در Retry-After صبر کنید و سپس درخواست را دوباره بفرستید.
- 5XX
502 / 503 — اختلال سرور وی‌پی‌ان یا توقف موقت فروش
سرور وی‌پی‌ان با خطا روبه‌رو شده و مبلغی کسر نشده است، یا فروش پلن موقتاً غیرفعال است. کمی بعد دوباره تلاش کنید.
HTTP/1.1 402 Payment Required
X-Request-ID: api-7f3c9b/ZkGq8VtqKx-000043
{
"error": "insufficient balance"
}منطق برنامه را بر اساس مقدار error در بدنه پاسخ، مانند insufficient balance یا ip not allowed، پیاده‌سازی کنید؛ زیرا چند خطای متفاوت ممکن است کد وضعیت HTTP یکسانی داشته باشند. خطاهای احتمالی هر مسیر همراه نمونه در مرجع API آمده‌اند.
محدودیت‌ها
محدودیت‌ها جداگانه برای IP، توکن و حساب اعمال می‌شوند. همه توکن‌های یک حساب، سقف درخواست‌های آن حساب را به‌صورت مشترک استفاده می‌کنند. مقادیر پیش‌فرض در ادامه آمده‌اند.
| محدودیت | سقف مجاز | اعمال روی |
|---|---|---|
| به ازای هر IP | 60 در دقیقه | همه درخواست‌های Open API، پیش از احراز هویت |
| به ازای هر توکن | 60 در دقیقه | همه درخواست‌های احراز هویت‌شده |
| خرید به ازای هر حساب | 10 در دقیقه | POST /orders, POST /orders/bulk |
| عملیات سرویس به ازای هر حساب | 10 در دقیقه | فعال‌سازی، غیرفعال‌سازی، عملیات گروهی، حذف، تلاش دوباره، تمدید و ساخت دوباره کلیدها |
| دانلود کانفیگ به ازای هر حساب | 20 در ساعت | GET /vpn/{id}/download |
| ساخت دوباره کلید به ازای هر سرویس | یک بار در هر 7 روز | POST /vpn/{id}/regenerate |
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1767225660
X-Request-ID: api-7f3c9b/ZkGq8VtqKx-000042
{ "error": "rate limited" }مدیریت درست پاسخ 429
سایر محدودیت‌ها
- حداکثر 5 توکن فعال برای هر حساب
- حداکثر 20 کانفیگ در هر سفارش گروهی
- حداکثر 100 شناسه سرویس در هر درخواست فعال‌سازی یا غیرفعال‌سازی گروهی
- حداکثر 512 نویسه برای هر یادداشت
پرسش‌های متداول
چه کسانی می‌توانند از API استفاده کنند؟
همه کاربران TakVPN می‌توانند بدون نیاز به تأیید جداگانه، از پنل کاربری ← توسعه‌دهندگان توکن بسازند.
اگر موجودی کیف پول تمام شود چه می‌شود؟
درخواست خرید یا تمدید با پاسخ 402 (insufficient balance) رد می‌شود و مبلغی از کیف پول کسر نخواهد شد. پس از شارژ کیف پول، درخواست را دوباره بفرستید.
آیا بعداً می‌توانم پیشوند برند را تغییر دهم؟
بله. پیشوند جدید فقط روی کانفیگ‌هایی اعمال می‌شود که پس از تغییر ساخته شوند و نام سرویس‌های قبلی بدون تغییر می‌ماند.
توکنم را گم کرده‌ام. می‌توانم دوباره ببینمش؟
خیر. هر توکن فقط یک‌بار، هنگام ساخت، نمایش داده می‌شود. توکن قبلی را باطل کنید و توکن جدیدی بسازید.
کانفیگ سرویس جدید را چطور دریافت کنم؟
پس از ارسال POST /orders، وضعیت سرویس را با GET /vpn پیگیری کنید. وقتی سرویس فعال شد، کانفیگ را از GET /vpn/{id}/download دانلود کنید.
در چند دقیقه شروع کنید
توکن بسازید، پیشوند برندتان را تنظیم کنید و همین امروز اولین درخواست خود را بفرستید.
دریافت کلید API