Open API v1 دسترسی شریک B2B

API توسعه‌دهنده

اشتراک‌های VPN کاربرانتان را به‌صورت برنامه‌نویسی مدیریت کنید. یک ایمیل بدهید — یک لینک اشتراک آمادهٔ استفاده بگیرید.

中文 English Русский فارسی

شروع سریع (۳ مرحله)

مرحله 1

🔑

دریافت API Key

از طریق فرم زیر درخواست دهید تا کلید شما را بسازیم

مرحله 2

📡

ارسال درخواست

ارسال POST به /openapi/v1/subscriptions همراه با ایمیل

مرحله 3

✅

تحویل به کاربر

لینک subscription_url را برای کاربرتان بفرستید

نمونه — ایجاد یک اشتراک

curl -s -X POST https://univista.me/openapi/v1/subscriptions \ -H 'X-Api-Key: uk_live_your_key_here' \ -H 'Content-Type: application/json' \ -d '{"email":"[email protected]","plan_id":"30d"}'

# Response 201 { "data": { "subscription_url": "https://univista.me/sub?token=abc123...", "email": "[email protected]", "plan_id": "30d", "expires_at": "2026-05-29T00:00:00Z" } }

احراز هویت

همهٔ درخواست‌ها باید API Key شما را در هدر X-Api-Key قرار دهند.

X-Api-Key: uk_live_a1b2c3d4e5f6...

نکتهٔ امنیتی: API Key شما فقط یک‌بار هنگام ساخت نمایش داده می‌شود. آن را در یک متغیر محیطی نگه دارید، هرگز در کد قرار ندهید. هر ۹۰ روز یک‌بار آن را بچرخانید.

Base URL

https://univista.me/openapi/v1/

اندپوینت‌های API

POST /openapi/v1/subscriptions ایجاد اشتراک

برای ایمیل داده‌شده یک اشتراک جدید می‌سازد. لینک اشتراک را برای تحویل به کاربرتان برمی‌گرداند.

بدنهٔ درخواست (JSON)

فیلد	نوع	الزامی	توضیح
email	string	required	ایمیل مشترک (برای هر اشتراک یکتا)
plan_id	string	optional	7d / 30d / 90d / 365d — پیش‌فرض ۳۰d
memo	string	optional	یادداشت داخلی (به کاربر نمایش داده نمی‌شود، در گزارش حسابرسی ثبت می‌شود)

نمونه درخواست

curl -X POST https://univista.me/openapi/v1/subscriptions \ -H "X-Api-Key: uk_live_..." \ -H "Content-Type: application/json" \ -d '{"email":"[email protected]","plan_id":"30d","memo":"order #123"}'

پاسخ ۲۰۱

{ "data": { "subscription_token": "abc123...", "subscription_url": "https://univista.me/sub?token=abc123...", "email": "[email protected]", "plan_id": "30d", "expires_at": "2026-05-29T00:00:00Z", "created_at": "2026-04-29T10:00:00Z", "memo": "order #123" } }

اگر این ایمیل از قبل اشتراک فعال داشته باشد، کد ۴۰۹ برگردانده می‌شود — برای تمدید از /renew استفاده کنید.

GET /openapi/v1/subscriptions/{email} استعلام اشتراک

وضعیت فعلی اشتراک را با ایمیل دریافت کنید.

curl https://univista.me/openapi/v1/subscriptions/[email protected] \ -H "X-Api-Key: uk_live_..."

پاسخ ۲۰۰

{ "data": { "email": "[email protected]", "status": "active", // active | expired | rate_limited "plan_id": "30d", "expires_at": "2026-05-29T00:00:00Z", "days_remaining": 30, "subscription_url": "https://univista.me/sub?token=..." } }

POST /openapi/v1/subscriptions/{email}/renew تمدید اشتراک

یک اشتراک موجود را تمدید کنید. دو حالت: extend (روزها را به انقضای فعلی اضافه می‌کند) یا reset (از امروز از نو شروع می‌کند).

فیلد	نوع	الزامی	توضیح
plan_id	string	required	7d / 30d / 90d / 365d
mode	string	optional	extend (پیش‌فرض) یا reset

curl -X POST https://univista.me/openapi/v1/subscriptions/[email protected]/renew \ -H "X-Api-Key: uk_live_..." \ -H "Content-Type: application/json" \ -d '{"plan_id":"30d","mode":"extend"}'

پاسخ ۲۰۰

{ "data": { "email": "[email protected]", "new_expires_at": "2026-06-29T00:00:00Z", "subscription_url": "https://univista.me/sub?token=..." } }

DELETE /openapi/v1/subscriptions/{email} لغو اشتراک

اشتراک این ایمیل را غیرفعال (لغو نرم) می‌کند. رکورد اشتراک حفظ می‌شود اما وضعیت آن به revokedتغییر می‌کند و دسترسی در همگام‌سازی بعدی حذف می‌شود. فقط روی اشتراک‌های ساخته‌شده با API Key شما اثر می‌گذارد.

curl -X DELETE https://univista.me/openapi/v1/subscriptions/[email protected] \ -H "X-Api-Key: uk_live_..."

پاسخ ۲۰۰

{ "data": { "email": "[email protected]", "status": "revoked", "revoked_at": "2026-06-22T10:00:00Z" } }

GET /openapi/v1/subscriptions فهرست اشتراک‌ها

فهرست صفحه‌بندی‌شدهٔ اشتراک‌های ساخته‌شده با API Key شما. فقط اشتراک‌های خودتان برگردانده می‌شود — داده‌های سایر مستأجرها هرگز فاش نمی‌شود.

فیلد	نوع	الزامی	توضیح
page	int	optional	شمارهٔ صفحه، از ۱ شروع می‌شود. پیش‌فرض ۱.
per_page	int	optional	تعداد در هر صفحه. پیش‌فرض ۲۰، حداکثر ۱۰۰ (مازاد به ۱۰۰ محدود می‌شود).
status	string	optional	فیلتر: `active` / `expired` / `all` (پیش‌فرض all).

curl "https://univista.me/openapi/v1/subscriptions?page=1&per_page=20" \
  -H "X-Api-Key: uk_live_..."

پاسخ ۲۰۰

{ "data": [ { "email": "[email protected]", "status": "active", "plan_id": "30d", "expires_at": "2026-07-22T00:00:00Z", "days_remaining": 30, "subscription_url": "https://univista.me/sub?token=..." } ], "meta": { "page": 1, "per_page": 20, "total": 156, "total_pages": 8 } }

GET /openapi/v1/me اطلاعات کلید

اطلاعات API Key فعلی و مصرف امروز را دریافت کنید.

curl https://univista.me/openapi/v1/me \
  -H "X-Api-Key: uk_live_..."

{ "data": { "name": "Partner A", "owner_email": "[email protected]", "created_at": "2026-04-01T00:00:00Z", "rate_limit": { "per_minute": 60, "per_day": 1000, "remaining_today": 847 } } }

کدهای خطا

همهٔ خطاها قالب یکسانی دارند:

{ "error": { "code": "invalid_email", "message": "..." } }

HTTP	error.code	توضیح
400	invalid_email	قالب ایمیل نامعتبر است
400	invalid_plan_id	plan_id شناخته نشد
401	missing_api_key	هدر X-Api-Key وجود ندارد
401	invalid_api_key	API Key نامعتبر یا باطل‌شده است
403	ip_not_whitelisted	آی‌پی مبدأ در فهرست سفید نیست
404	subscription_not_found	برای این ایمیل اشتراکی وجود ندارد
409	email_already_exists	اشتراک فعال موجود است — از renew استفاده کنید
429	rate_limit_exceeded	از محدودیت نرخ عبور کردید — هدر Retry-After را ببینید
500	internal_error	خطای سرور

محدودیت نرخ

req/min

برای هر کلید، در دقیقه

1,000

req/day

برای هر کلید، در روز

هنگام عبور از محدودیت، پاسخ 429 همراه با هدر Retry-After است که تعداد ثانیهٔ انتظار را نشان می‌دهد. محدودیت‌ها قابل افزایش‌اند — با ما تماس بگیرید.

درخواست دسترسی به API

فرم زیر را پر کنید. پس از بررسی درخواست شما، با شما تماس می‌گیریم و API Key را تحویل می‌دهیم.

از قبل کلید دارید؟ به بخش «شروع سریع» در بالا بروید. تماس با پشتیبانی