نمای کلی API

API اویرا یک رابط HTTP با خروجی JSON به پنل است. با آن می‌توانید ربات فروش یا پشتیبانی بسازید، ابزار نمایندگی بنویسید، ترافیک و اتصال‌ها را از سامانهٔ دیگری ببینید، یا کارهایی را که در پنل تکرار می‌کنید با اسکریپت انجام دهید. این صفحه آدرس پایه، ورود، شکل درخواست و خطا، و کارهایی را که یک توکن نمی‌تواند انجام دهد توضیح می‌دهد.

توکن‌های API از اویرا v0.9.9-beta.6 در دسترس‌اند. این قابلیت بتاست؛ نسخهٔ پایدار v0.9.8 و بتاهای قبلی v0.9.9 زبانهٔ تنظیمات → API را ندارند.

چه چیزی می‌توانید بسازید

• ربات فروشی که برای هر سفارش کاربر می‌سازد، لینک اشتراک و کد QR را می‌فرستد، بعداً تمدید می‌کند و در پایان سفارش کاربر را خاموش یا حذف می‌کند.
• ابزار نمایندگی که فقط در حساب یک نماینده و سهمیهٔ ترافیک آن کار می‌کند.
• پایشی که کاربران، اتصال‌های زنده، وضعیت نودها و تاریخچهٔ ترافیک را می‌خواند.
• اسکریپتی که کاربران را گروهی می‌سازد، به گروه‌ها می‌افزاید، یا CRM بیرونی را هم‌گام نگه می‌دارد.

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

آدرس پایه

API زیر آدرس پنل، مسیر مخفی آن و api/ قرار دارد:

https://panel.example.com/<secret-path>/api/

آدرس دقیق در تنظیمات → API و در آدرس پایه API است و دکمهٔ کپی دارد. همان را پایه بگذارید و پیشوند /api را که در مرجع می‌آید حذف کنید؛ $BASE پایین از قبل آن را دارد. مثال‌ها آن را با $BASE کوتاه می‌کنند:

export BASE="https://panel.example.com/ovira-7f3c/api"
export OVIRA_TOKEN="ovk_..."

پراکسی معکوس جلوی پنل، scheme و host عمومی را عوض می‌کند، نه بخش بعد از <secret-path> را. اگر پنل پشت پراکسی است، آدرس HTTPS عمومی پراکسی را بگذارید.

ورود با توکن

توکن را در تنظیمات → API بسازید. کلید آن را در هدر Authorization بفرستید:

curl -sS \
  -H "Authorization: Bearer $OVIRA_TOKEN" \
  "$BASE/auth/me"

درخواست با توکن به هدر CSRF نیاز ندارد. وقتی این هدر حاضر باشد، پنل کوکی مرورگر را نادیده می‌گیرد؛ توکن اشتباه نمی‌تواند به نشست واردشده تکیه کند.

توکن مانند حسابی عمل می‌کند که آن را ساخته. توکن دسترسی کامل حقوق حساب را همان‌طور که در آن لحظه هست به کار می‌برد. توکن سفارشی فقط دسترسی‌هایی را دارد که هنگام ساخت انتخاب شده‌اند و هرگز بیش از دسترسی فعلی حساب نیست. اگر حساب بعداً دسترسی‌ای را از دست بدهد، توکن هم آن را از دست می‌دهد.

توکن سفارشی هرگز مالک حساب نیست، حتی اگر مالک آن را ساخته باشد، و نمی‌تواند مسیرهای مخصوص مالک را صدا بزند. توکن کاملِ مالک حقوق مالک را نگه می‌دارد، جز کارهای مخصوص نشست که در ادامه آمده.

درخواست و پاسخ

JSON بفرستید و JSON بگیرید. هنگام فرستادن بدنه Content-Type: application/json بگذارید. مسیرها و نام فیلدها به بزرگی و کوچکی حرف حساس‌اند.

دو واحد همه‌جا تکرار می‌شوند:

• ترافیک با بایت: trafficLimit، usedUp، usedDown، bytes.
• زمان با ثانیهٔ یونیکس: expireAt، createdAt، lastOnlineAt، from، to، t.

سقف ترافیک 0 یعنی بدون محدودیت. تاریخ پایان 0 یعنی بدون تاریخ پایان.

خطاها

درخواست ناموفق یک شیء JSON برمی‌گرداند:

{
  "error": "a client with this name already exists",
  "field": "name"
}

error یک جمله برای اپراتور است. field فیلد اشتباه درخواست را می‌گوید. code وقتی می‌آید که برنامه بتواند بر اساس آن تصمیم بگیرد، و params جزئیات آن را دارد:

{
  "error": "this API token is not allowed from your address",
  "code": "token_ip",
  "params": { "ip": "203.0.113.9" }
}

وضعیت	معنی
200	درخواست انجام شد.
201	چیزی ساخته شد.
202	کاری شروع شد؛ نتیجه را از همان منبع یا فهرست بخوانید.
204	درخواست انجام شد و بدنه ندارد.
400	بدنه یا یکی از فیلدها معتبر نیست. field را ببینید.
401	نشست یا توکن معتبر نیست.
402	لایسنس، سهمیهٔ ترافیک یا محدودیت حساب تغییر را رد می‌کند.
403	حساب یا توکن اجازهٔ این کار را ندارد.
404	چنین رکوردی نیست، یا خارج از دسترس حساب است.
409	تعارض، مثل نام تکراری یا برگشت نسخهٔ پشتیبانی‌نشده.
429	تلاش‌های ناموفق زیاد بوده؛ صبر کنید و دوباره بفرستید.
500	پنل نتوانست درخواست را تمام کند.
502	در درخواست پشتیبان، Telegram در دسترس نبود.

کدهای خطای توکن

code	معنی	کار شما
token_invalid	هدر Bearer ندارد، کلید با ovk_ شروع نمی‌شود، یا توکنی با آن پیدا نشد.	کلید را بررسی کنید و ببینید توکن لغو نشده باشد.
token_expired	تاریخ انقضای توکن گذشته.	توکن تازه بسازید.
token_ip	درخواست از آدرسی خارج از آی‌پی‌های مجاز آمده. params.ip آدرسی است که پنل دیده.	از آدرس مجاز بفرستید، یا توکن تازه با فهرست درست بسازید.
token_forbidden	این مسیر مخصوص نشست است.	در پنل وارد شوید و از برنامهٔ وب استفاده کنید.
account_blocked	حساب پشت توکن خاموش، منقضی یا بدون ترافیک است. params.reason می‌گوید کدام.	از مالک پنل بخواهید حساب را شارژ یا تمدید کند.
token_limit	حساب هم‌اکنون ۲۵ توکن API دارد.	اول یک توکن را لغو کنید.

درخواست با توکنی که حساب دیگر آن دسترسی را ندارد، 403 بدون code می‌گیرد. توکن سفارشی که آن دسترسی را ندارد هم همین پاسخ را می‌گیرد.

توکن چه کاری نمی‌تواند بکند

این مسیرها روی خود پنل یا مرورگر واردشده کار می‌کنند و هر توکنی را با 403 و token_forbidden رد می‌کنند:

• خروج از پنل (POST auth/logout).
• همهٔ account/: رمز عبور، راه‌اندازی و بازیابی ورود دومرحله‌ای، نشست‌های واردشده و توکن‌های خودتان.
• اینکه مالک توکن‌های حساب دیگری را ببیند یا لغو کند، رمز حساب دیگری را بگذارد، یا ورود دومرحله‌ای او را بازنشانی کند.
• حذف بستهٔ یک پروتکل از نود (DELETE nodes/{id}/protocols/{kind}).
• تغییر آدرس شنود، مسیر مخفی یا فایل‌های TLS پنل، و تغییر گواهی آن.
• بازگردانی پشتیبان، از فایل آپلودی یا از Telegram.

توکن سفارشی به مسیرهای مخصوص مالک هم نمی‌رسد: تنظیمات، حساب‌ها، نقش‌ها، دانلود پشتیبان و بقیهٔ مدیریت خود پنل. فقط توکن کاملِ مالک این حقوق را نگه می‌دارد.

از HTTPS استفاده کنید

توکن را روی HTTPS بفرستید. توکن رمز حساب است: هر کس آن را در مسیر بخواند تا وقتی لغو یا منقضی شود می‌تواند از آن استفاده کند. اگر پنل روی HTTP ساده است، پیش از وصل کردن رباتی از بیرون سرور، آن را پشت پراکسی معکوس HTTPS بگذارید.

سند OpenAPI

همین API در یک سند OpenAPI 3.1 توصیف شده:

• نسخه‌ای که همراه این مستندات است: openapi.json.
• نسخهٔ دقیق یک پنل در حال اجرا: <base>/api/openapi.json، که <base> آدرس پنل و مسیر مخفی آن است.

برای آوردن آن در Postman، Insomnia یا Bruno و ساختن کلاینت، سند OpenAPI را ببینید.

صفحه‌های مرتبط

• توکن‌های API: ساخت، محدود کردن، انقضا و لغو توکن.
• شروع سریع: اولین درخواست‌ها با curl، Python و Node.
• ربات فروش: دستور کامل یک ربات فروش.
• مرجع API: همهٔ مسیرها، دسترسی و بدنهٔ آن‌ها.