کل پنل را با کد خودتان اداره کنید.
هر کاری که در Umiji با کلیک انجام میدهید، یک برنامه هم میتواند از راه HTTPS انجام دهد: کاربرها، نودها، هاستها، اسکوادها، قالبها، صورتحساب و آمار. اینجا میبینید درخواست را چطور امضا کنید، چه جوابی برمیگردد، پنل چه وبهوکهایی میفرستد، و همهی اندپوینتها را با فیلدهایشان.
- 239 اندپوینت
- 29 گروه
- 279 کد خطا
- JSON روی HTTPS
- نسخهی 3.4.7
چطور کار میکند
پنلی که در مرورگر باز میکنید خودش یکی از کلاینتهای همین API است. اسکریپتها، رباتها و سیستمهای فروش شما هم با همین اندپوینتها حرف میزنند، فقط به جای ورود، یک توکن دارند.
- همهی اندپوینتها زیر
/apiروی آدرس پنل شما هستند. - برنامه با یک توکن API خودش را معرفی میکند که در هدر
Authorization: Bearer …فرستاده میشود. هر توکن دامنههای دسترسی خودش را دارد که مشخص میکند چه چیزهایی را میتواند صدا بزند. - درخواست و پاسخ JSON هستند. پاسخ موفق داخل
{"response": …}میآید. - پنل هم شما را صدا میزند: وبهوک برای رویدادهای کاربر، نود و صورتحساب، و در صورت نیاز استریمهای Redis برای ترافیک.
آدرس پایه
همان آدرسی که پنل را با آن باز میکنید، بهعلاوهی /api. آدرس خودتان را در پنل شما در بالای صفحه بنویسید تا همهی نمونههای این صفحه از آن استفاده کنند.
https://panel.example.com/api
HTTPS از پشت ریورس پراکسی لازم است. API درخواستی را که هدرهای X-Forwarded-For و X-Forwarded-Proto: https را نداشته باشد بی هیچ جوابی قطع میکند. ریورس پراکسی شما (Caddy یا Nginx) هر دو را اضافه میکند، پس درخواست به آدرس عمومی بیدردسر کار میکند. curl این حالت را با «Empty reply from server» نشان میدهد.
اسکریپتی که روی خود سرور پنل اجرا میشود میتواند پراکسی را دور بزند و مستقیم پورت 3000 را صدا بزند، به شرطی که خودش هر دو هدر را بفرستد:
curl "http://127.0.0.1:3000/api/system/stats" \
-H "Authorization: Bearer $UMIJI_TOKEN" \
-H "X-Forwarded-For: 127.0.0.1" \
-H "X-Forwarded-Proto: https"
API را از سمت سرور صدا بزنید، نه از یک صفحهی وب. مرورگرها فقط روی دامنهی خود پنل جواب میگیرند، و توکنی که در کد فرانتاند باشد را هر کسی میتواند بخواند.
توکنهای API
توکن کلید بلندی است که نمایندهی یک برنامه است. برای هر ربات یا اسکریپت یک توکن جدا بسازید تا بتوانید یکی را حذف کنید بیآنکه بقیه از کار بیفتند.
- تنظیمات Umiji را باز کنید و کارت توکنهای API را پیدا کنید. روی ساخت توکن API بزنید.
- نام توکن و انقضا پس از (روز) را پر کنید و دامنههای دسترسی را انتخاب کنید: یکی از پیشتنظیمها، یا اندپوینتها را تکتک.
- توکن را کپی کنید. فقط یک بار، درست بعد از ساخته شدن، نشان داده میشود.
- آن را با هر درخواست در هدر
Authorizationبفرستید.
# توکن را در کد ننویسید، در یک متغیر محیطی نگه دارید
export UMIJI_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
curl "https://panel.example.com/api/system/stats" \
-H "Authorization: Bearer $UMIJI_TOKEN"
- حذف توکن فوراً اثر میکند. پنل توکن را در هر درخواست بررسی میکند، پس توکن حذفشده در همان درخواست بعدی 403 میگیرد.
- توکن منقضیشده 401 میگیرد. یک توکن تازه بسازید؛ توکن را نمیشود تمدید کرد.
- ساختن و حذف توکنها کار مالک است، از داخل پنل. یک توکن نمیتواند توکنها را ببیند، بسازد یا حذف کند، و هر تغییر وبهوک
service.api_token_createdیاservice.api_token_deletedرا میفرستد.
ورود خودتان به درد اسکریپت نمیخورد. نشست مالک فقط از داخل پنل و در مرورگر پذیرفته میشود. اگر جای دیگری استفاده شود، 403 با پیام For API requests you must create own API-token in the admin dashboard. برمیگردد. فروشندهها نمیتوانند توکن بسازند و نشست آنها هم فقط در مرورگر کار میکند.
دامنههای دسترسی
دامنههای دسترسی (scopes) میگویند یک توکن چه چیزهایی را میتواند صدا بزند. چهار اندازه دارند، از همهچیز تا فقط یک اندپوینت. اگر حتی یکی از دامنههای توکن اندپوینت را پوشش دهد، درخواست رد نمیشود.
*هر چیزی که توکن API به آن دسترسی دارد. همان کلید دسترسی کامل.users:*همهی اندپوینتهای یک منبع، اینجا کاربرها.users:readهمهی اندپوینتهای خواندنی یک منبع.users:writeهم همهی اندپوینتهای تغییردهنده است.users:createفقط یک اندپوینت. هر اندپوینت در مرجع دامنهی خودش را نشان میدهد؛ برای کپی رویش بزنید.
پنجرهی ساخت توکن سه پیشتنظیم دارد: فقط خواندنی (همهی اندپوینتهای خواندنی)، دسترسی کامل، و صفحه اشتراک، یعنی همان پنج دامنهای که سرور صفحهی اشتراک لازم دارد. میتوانید یک آرایهی JSON از دامنهها را هم از کلیپبورد جایگذاری کنید. فهرست کامل دامنهها، به تفکیک منبع، از GET /api/tokens/scopes میآید.
["subscription-page-configs:list", "subscription-page-configs:get",
"subscriptions:subpage-config", "system:metadata", "users:by-username"]
درخواستی بیرون از دامنههای توکن 403 با Forbidden resource میگیرد. به هر توکن کمترین دسترسی لازم را بدهید: رباتی که فقط کاربر میسازد users:create و users:by-username لازم دارد، نه *.
چه کسی به چه چیزی دسترسی دارد
بیشتر اندپوینتها با توکن کار میکنند. چندتایی مال صفحههای خود پنلاند و توکن را نمیپذیرند. هر اندپوینت در مرجع برچسب دارد، پس قبل از امتحان میدانید.
| اندپوینتها | توکن API | مالک در پنل | فروشنده در پنل |
|---|---|---|---|
| کاربرها، نودها، هاستها، اسکوادها، قالبها، آمار و بقیه (165) | ✓ | ✓ | – |
| کاربرها و اسکوادهایی که فروشنده با آنها کار میکند (28) | ✓ | ✓ | ✓ فقط مال خودش |
| فروشندهها، پیام همگانی، تنظیمات Umiji، passkeyها، توکنهای API (19) | – | ✓ | – |
| ربات فروشگاه خود فروشنده (17) | – | – | ✓ |
| ورود، و لینکهای عمومی اشتراک (10) | توکن لازم نیست | ||
توکن همیشه به جای مالک کار میکند، پس همهی کاربرها را میبیند. برای کار با کاربرهای یک فروشنده، بر اساس brokerUuid کاربر فیلتر کنید.
اولین درخواستها
ده کاربر اول را بگیرید، بعد کاربری با ماهی 50 گیگابایت برای 30 روز بسازید. همین دو درخواست به سه زبان:
# ده کاربر اول
curl "https://panel.example.com/api/users?start=0&size=10" \
-H "Authorization: Bearer $UMIJI_TOKEN"
# کاربر تازه: ماهی 50 گیگابایت، برای 30 روز، در یک اسکواد داخلی
curl -X POST "https://panel.example.com/api/users" \
-H "Authorization: Bearer $UMIJI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"username": "alice",
"expireAt": "2026-12-15T00:00:00.000Z",
"trafficLimitBytes": 53687091200,
"trafficLimitStrategy": "MONTH",
"activeInternalSquads": ["7f3c2a1e-5b4d-4c6e-9f8a-1b2c3d4e5f60"]
}'
// Node.js نسخهی 18 یا بالاتر: fetch داخلش هست
const BASE = 'https://panel.example.com/api'
const headers = {
Authorization: `Bearer ${process.env.UMIJI_TOKEN}`,
'Content-Type': 'application/json',
}
async function umiji(method, path, body) {
const res = await fetch(BASE + path, { method, headers, body: body && JSON.stringify(body) })
if (res.status === 202 || res.status === 204) return null
const json = await res.json()
if (!res.ok) throw new Error(`${json.errorCode ?? res.status}: ${json.message}`)
return json.response
}
const { users, total } = await umiji('GET', '/users?start=0&size=10')
const alice = await umiji('POST', '/users', {
username: 'alice',
expireAt: new Date(Date.now() + 30 * 864e5).toISOString(),
trafficLimitBytes: 50 * 1024 ** 3,
trafficLimitStrategy: 'MONTH',
})
console.log(alice.subscriptionUrl)
import os, datetime, requests
BASE = "https://panel.example.com/api"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['UMIJI_TOKEN']}"
def umiji(method, path, **kw):
r = s.request(method, BASE + path, timeout=30, **kw)
if r.status_code in (202, 204):
return None
data = r.json()
if not r.ok:
raise RuntimeError(f"{data.get('errorCode', r.status_code)}: {data['message']}")
return data["response"]
page = umiji("GET", "/users", params={"start": 0, "size": 10})
alice = umiji("POST", "/users", json={
"username": "alice",
"expireAt": (datetime.datetime.now(datetime.UTC) + datetime.timedelta(days=30)).isoformat(),
"trafficLimitBytes": 50 * 1024**3,
"trafficLimitStrategy": "MONTH",
})
print(alice["subscriptionUrl"])
کاربر تازه کامل برمیگردد، با id و subscriptionUrl: لینکی که به مشتری میدهید. اگر activeInternalSquads را نفرستید، کاربر تا وقتی به یک اسکواد اضافه نشود هیچ سروری نمیگیرد.
درخواست و پاسخ
- بدنه را به صورت JSON و با
Content-Type: application/jsonبفرستید. فیلدهایی که API نمیشناسد کنار گذاشته میشوند، نه اینکه درخواست رد شود. - چیزی که رویش کار میکنید در مسیر میآید (
/api/nodes/{uuid})، جز در ویرایش:PATCHکل تغییر را در بدنه میگیرد وuuidیاidهم داخل همان بدنه است.PATCH /api/usersیاidمیگیرد یاusername. PATCHفقط فیلدهایی را که میفرستید تغییر میدهد.- کارهایی که ویرایش ساده نیستند زیر
/actions/هستند:POST /api/users/{userId}/actions/reset-traffic،…/actions/disableو…/actions/restart.
| وضعیت | یعنی | بدنه |
|---|---|---|
200 OK | انجام شد. | {"response": …} |
201 Created | چیز تازهای ساخته شد. | {"response": …}، همان چیز تازه |
202 Accepted | در صف رفت: تغییرهای گروهی کاربرها و اسکوادها، ریاستارت نود، همگامسازی پلاگین و قطعه کد، قطع اتصالها. کار در پسزمینه انجام میشود و کمی طول میکشد. | ندارد |
204 No Content | حذف شد. | ندارد |
گرفتن اتصالهای زنده مثل نوبت گرفتن است: POST /api/connections/by-user/{userId} فوراً یک jobId برمیگرداند، و GET /api/connections/by-user/{jobId} نتیجه را وقتی نودها جواب دادند میدهد. هر یکی دو ثانیه دوباره بپرسید تا isCompleted برابر true شود.
خطاها
خطا به یکی از سه شکل برمیگردد. اول وضعیت HTTP را ببینید، بعد اگر errorCode بود، آن را: کدها بین نسخهها ثابت میمانند، ولی پیامها شاید عوض شوند.
پنل درخواست را رد کرد
{
"timestamp": "2026-11-15T07:11:48.106Z",
"path": "/api/users",
"message": "User username already exists",
"errorCode": "A019"
}
بدنه از اعتبارسنجی رد نشد (400)
{
"statusCode": 400,
"message": "Validation failed",
"errors": [
{ "code": "too_small", "minimum": 3, "path": ["username"], "message": "Username must be at least 3 characters" },
{ "code": "invalid_type", "expected": "string", "path": ["expireAt"], "message": "Invalid input: expected string, received undefined" }
]
}
توکن پذیرفته نشد (401 و 403)
{ "message": "Unauthorized", "statusCode": 401 }
{ "message": "Forbidden resource", "error": "Forbidden", "statusCode": 403 }
| وضعیت | معمولاً یعنی |
|---|---|
400 | اعتبارسنجی رد شد، یا یکی از قانونهای پنل اجازه نداد؛ errorCode میگوید کدام. |
401 | توکن نیست، خراب است یا منقضی شده. |
403 | توکن دامنهی لازم را ندارد، حذف شده، یا اندپوینت فقط مال پنل است. |
404 | چنین کاربر، نود، هاست… وجود ندارد (مثلاً A063). |
409 | این نام یا تگ قبلاً گرفته شده. |
429 | تلاشهای ورود زیادی پشت سر هم (A286). API محدودیت دیگری ندارد، ولی ملایم باشید. |
500 | پنل نتوانست کار را تمام کند: پایگاه داده یا یک نود خطا داد. errorCode مرحله را مشخص میکند. |
همهی کدها با پیامشان در کدهای خطا هستند، و جستجوی بالای صفحه هم پیدایشان میکند.
صفحهبندی
فهرستهایی که ممکن است بزرگ شوند صفحهصفحه میآیند. دو نوع صفحهبندی هست.
آفست: start و size
GET /api/users، /api/subscriptions، /api/hwid/devices و تاریخچهی درخواستها start (از کجا شروع شود، از 0) و size (تا 1000؛ برای اشتراکها تا 500) میگیرند. پاسخ total دارد، پس میدانید چند صفحه هست. برای جدولی با شمارهی صفحه مناسب است.
کرسر: GET /api/users/stream
برای رفتن روی همهی کاربرها، مثلاً برای همگامسازی یا خروجی گرفتن. هر صفحه nextCursor و hasMore دارد: کرسر را برگردانید تا وقتی hasMore برابر false شود. روی پنلهای بزرگ هم سریع میماند و بر اساس status، tag، telegramId، email، trafficLimitStrategy و externalSquadUuid فیلتر میکند.
let cursor
do {
const q = new URLSearchParams({ size: '1000', status: 'ACTIVE', ...(cursor && { cursor }) })
const page = await umiji('GET', `/users/stream?${q}`)
for (const user of page.users) save(user)
cursor = page.hasMore ? page.nextCursor : undefined
} while (cursor)
پارامترهای جدول (filters، filterModes، globalFilterMode و sorting) برای جدولهای خود پنل ساخته شدهاند و با جستجوی متنی کُند کار میکنند. برای خودکارسازی از فهرست کرسری یا جستجوی مستقیم استفاده کنید: /api/users/by-username/{username}، /by-short-uuid/{shortUuid} و /api/users/{userId}.
تاریخ، بایت و شناسه
| چه چیزی | چه شکلی |
|---|---|
| تاریخها | ISO 8601 به وقت UTC، مثل 2026-11-15T12:00:00.000Z. همینطور هم بفرستید؛ اختلاف ساعت مثل +03:30 هم پذیرفته میشود. |
| ترافیک | بایت، به صورت عدد. هر گیگابایت (GiB) برابر 1073741824 است. محدودیت ترافیک 0 یعنی نامحدود. |
| کاربرها | یک عدد به نام id، در مسیرهایی مثل /api/users/{userId}. با username، با shortUuid (شناسهی داخل لینک اشتراک)، با telegramId و با email هم پیدا میشوند. |
| بقیهی چیزها | یک uuid: نودها، هاستها، اسکوادها، پروفایلها، قالبها و فروشندهها. |
| وضعیت کاربر | ACTIVE، DISABLED، LIMITED (ترافیک تمام شده) و EXPIRED. شما فقط دوتای اول را تنظیم میکنید؛ بقیه را پنل میگذارد. |
| بازنشانی ترافیک | NO_RESET، DAY (هر شب)، WEEK (دوشنبهها)، MONTH (روز اول ماه میلادی) و MONTH_ROLLING (هر ماه در همان روزی که کاربر ساخته شده). زمانها به وقت UTC هستند. |
وبهوکها
به جای اینکه هر دقیقه از پنل بپرسید ترافیک کاربری تمام شده یا نه، بگذارید خودش خبر بدهد. با روشن کردن وبهوک، پنل همان لحظهای که اتفاقی بیفتد یک POST امضاشده به آدرس شما میفرستد.
آن را در فایل .env پنل روشن کنید و پنل را ریاستارت کنید:
WEBHOOK_ENABLED=true
# یک آدرس، یا چند آدرس جدا شده با کاما؛ با http:// یا https://
WEBHOOK_URL=https://bot.example.com/umiji-hook
# کلید امضا: دستکم 32 حرف و رقم لاتین، و هیچ چیز دیگر
WEBHOOK_SECRET_HEADER=vsmu67Kmg6R8FjIOF1WUY8LWBHie4scdEqrfsKmyf4IAf8dY3nFS0wwYHkhh6ZvQ
بهطور پیشفرض همهی رویدادها فرستاده میشوند. برای خاموش کردن بعضیها، یا فرستادن یک رویداد به یک آدرس اضافه، فایل notifications-config.yml را ویرایش کنید (در کانتینر، داخل /var/lib/umiji/configs/notifications/):
events:
user.modified:
telegram: false
webhook: false
user.expired:
telegram: true
webhook: true
additionalWebhookUrls:
- https://crm.example.com/hooks/expired
چه چیزی میرسد
| هدر | مقدار |
|---|---|
Content-Type | application/json |
X-Umiji-Signature | HMAC-SHA256 بدنهی خام با کلید شما، به صورت hex. |
X-Umiji-Timestamp | زمان رویداد به صورت ISO 8601؛ همان timestamp داخل بدنه. |
User-Agent | Umiji |
{
"scope": "user",
"event": "user.expired",
"timestamp": "2026-11-15T12:00:00.000Z",
"data": { "id": 74, "username": "alice", "status": "EXPIRED", "subscriptionUrl": "https://sub.example.com/JRAT-hTGXSqu0xLM" },
"meta": null
}
در رویدادهای کاربر، data کل کاربر است، همان چیزی که GET /api/users/{userId} برمیگرداند. با هر وضعیت 2xx جواب بدهید. اگر سرور شما جواب ندهد، پنل سه بار دیگر با فاصلهی پنج ثانیه امتحان میکند.
بررسی امضا
هر کسی میتواند به آدرس شما درخواست بفرستد. قبل از اینکه به یک وبهوک اعتماد کنید، بدنهی خام را بایتبهبایت با کلیدتان امضا کنید و با X-Umiji-Signature مقایسه کنید. اول JSON را پارس و دوباره سریال نکنید: بایتها عوض میشوند.
import crypto from 'node:crypto'
import express from 'express'
const app = express()
// express.raw بدنه را همانطور که پنل امضا کرده، بایتی نگه میدارد
app.post('/umiji-hook', express.raw({ type: 'application/json' }), (req, res) => {
const expected = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET).update(req.body).digest()
const given = Buffer.from(req.get('X-Umiji-Signature') ?? '', 'hex')
if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
return res.sendStatus(401)
}
const { event, data } = JSON.parse(req.body)
if (event === 'user.expired') remindToRenew(data.username)
res.sendStatus(200)
})
app.listen(8080)
import hashlib, hmac, json, os
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["WEBHOOK_SECRET"].encode()
@app.post("/umiji-hook")
def hook():
body = request.get_data() # بایتهای خام
expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-Umiji-Signature", "")):
abort(401)
event = json.loads(body)
if event["event"] == "user.expired":
remind_to_renew(event["data"]["username"])
return "", 200
<?php
$body = file_get_contents('php://input'); // بایتهای خام
$expected = hash_hmac('sha256', $body, getenv('WEBHOOK_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_UMIJI_SIGNATURE'] ?? '')) {
http_response_code(401);
exit;
}
$event = json_decode($body, true);
if ($event['event'] === 'user.expired') {
remind_to_renew($event['data']['username']);
}
http_response_code(200);
برای جلوگیری از تکرار، وبهوکهایی را که X-Umiji-Timestamp آنها چند دقیقه کهنه است هم کنار بگذارید.
رویدادها
هر رویداد یک scope دارد که مشخص میکند داخل data چه چیزی هست.
| رویداد | کی |
|---|---|
user.created | کاربری ساخته شد. |
user.modified | کاربری تغییر کرد. |
user.deleted | کاربری حذف شد. |
user.revoked | لینک اشتراک کاربر با یک لینک تازه عوض شد. |
user.disabled، user.enabled | خاموش یا دوباره روشن شد. |
user.limited | ترافیکش تمام شد. |
user.expired | تاریخ انقضایش گذشت. |
user.traffic_reset | ترافیکش بازنشانی شد، دستی یا طبق برنامه. |
user.first_connected | کاربر برای اولین بار وصل شد. |
user.bandwidth_usage_threshold_reached | از درصدی از محدودیت، مثلاً 80٪، گذشت. BANDWIDTH_USAGE_NOTIFICATIONS_ENABLED لازم است. |
user.not_connected | چند ساعت بعد از ساخته شدن هنوز وصل نشده؛ meta.notConnectedAfterHours میگوید چند ساعت. NOT_CONNECTED_USERS_NOTIFICATIONS_ENABLED لازم است. |
user.expiration | بهزودی منقضی میشود، یا مدتی پیش منقضی شده؛ meta.expiration تعداد ساعت است (قبل از انقضا منفی). EXPIRATION_NOTIFICATIONS_ENABLED لازم است. |
user_hwid_devices.added، .deleted | دستگاهی اضافه یا حذف شد. data شامل user و hwidUserDevice است. |
node.created، .modified، .deleted | نودی ساخته، تغییر داده یا حذف شد. |
node.enabled، .disabled | نودی روشن یا خاموش شد. |
node.connection_lost، .connection_restored | ارتباط پنل با نودی قطع شد، یا برگشت. |
node.traffic_notify | نودی به هشدار ترافیکش رسید. |
service.panel_started | پنل بالا آمد؛ data.panelVersion. |
service.login_attempt_success، _failed | کسی وارد پنل شد، یا تلاش کرد؛ data.loginAttempt نام کاربری، IP و مرورگر را دارد. |
service.subpage_config_changed | یکی از تنظیمات صفحهی اشتراک ساخته، تغییر داده یا حذف شد. |
service.api_token_created، _deleted | توکن API ساخته یا حذف شد؛ data.apiToken. |
crm.infra_billing_node_payment_in_7_days | صورتحساب یک سرور تا 7 روز دیگر سررسید میشود. همینطور _in_48hrs، _in_24hrs و _due_today، و وقتی دیر شده: _overdue_24hrs، _overdue_48hrs و _overdue_7_days. |
torrent_blocker.report | Torrent Blocker کاربری را گرفت؛ data نود، کاربر و گزارش را دارد. |
errors.bandwidth_usage_threshold_reached_max_notifications | برای کامل بودن در فایل تنظیمات آمده؛ این نسخه هیچوقت آن را نمیفرستد. |
همهی فیلدها، به تفکیک scope
استریمهای خروجی Redis
برای تحلیل در مقیاس بالا، پنل میتواند دادهی خام را در Redis Streams هم بنویسد تا یک سرویس از خودتان، ClickHouse یا Vector آن را بخواند. با EXPORT_TO_STREAM_ENABLED=true روشنش کنید. EXPORT_TO_STREAM_MAXLEN (بهطور پیشفرض 3000) تقریباً تعداد پیامهایی است که هر استریم پیش از دور ریختن قدیمیترها نگه میدارد.
| استریم | هر پیام یعنی |
|---|---|
ioraw:export:user_usage | یک دسته ترافیک کاربرها از یک نود: records جفتهای userId:bytes است که با ; به هم وصل شدهاند. |
ioraw:export:subscription_requests | یک بار گرفتن اشتراک: کاربر، زمان، IP، برنامه و قانون پاسخی که جواب داد. |
ioraw:export:node_connections | چه کسانی همین الان روی یک نود هستند. یک ساعت نگه داشته میشود. |
# پیامهای تازه را با یک consumer group، همانطور که میرسند بخوانید
redis-cli XGROUP CREATE ioraw:export:user_usage billing $ MKSTREAM
redis-cli XREADGROUP GROUP billing worker-1 COUNT 100 BLOCK 5000 STREAMS ioraw:export:user_usage >
لینکهای اشتراک
لینکهایی که برنامههای کلاینت وارد میکنند زیر توکن نیستند: شناسهی کوتاه داخل لینک خودش کلید است. این لینکها از آدرس اشتراک در SUB_PUBLIC_DOMAIN سرو میشوند، که نصب Docker آن را برابر SUB_DOMAIN، یعنی دامنهی صفحهی اشتراک، میگذارد.
| آدرس | چه میدهد |
|---|---|
/api/sub/{shortUuid} | چیزی که برنامه وارد میکند. قوانین پاسخ فرمت را از User-Agent برنامه انتخاب میکنند: لینکهای Base64، Xray JSON، Mihomo، sing-box و بقیه. |
/api/sub/{shortUuid}/{clientType} | فرمتی که خودتان نام میبرید: json، v2ray-json، mihomo، stash، clash یا singbox. |
/api/sub/{shortUuid}/info | JSON برای صفحههای خودتان: کاربر، لینکهای اتصالش و آدرس اشتراک. |
برای رباتها، گروه اشتراکها که با توکن محافظت میشود همین داده را با نام کاربری یا شناسه میدهد، بیآنکه چیزی را پارس کنید.
متریکها و سلامت
پروسهی زمانبند (scheduler) روی METRICS_PORT (یعنی 3001) که روی سرور پنل به 127.0.0.1 بسته شده، با دو اندپوینت بیرون از /api جواب میدهد:
# متریکهای Prometheus، با METRICS_USER و METRICS_PASS از .env
curl -u "$METRICS_USER:$METRICS_PASS" http://127.0.0.1:3001/metrics
# پایگاه داده در دسترس است؟ health check داکر از همین استفاده میکند
curl http://127.0.0.1:3001/health
# prometheus.yml
scrape_configs:
- job_name: umiji
static_configs:
- targets: ['127.0.0.1:3001']
basic_auth:
username: admin
password: your-METRICS_PASS
از خود API هم GET /api/system/health و /api/system/stats همین تصویر را به صورت JSON میدهند.
Scalar و Swagger
پنل شما مرورگرهای زندهی API خودش را دارد که از همان کدی که اجرا میکند ساخته میشوند. تنظیمات Umiji › ابزارهای بکاند را باز کنید و کنار Scalar (مرجع تعاملی و مدرن) یا Swagger (کاوشگر کلاسیک OpenAPI) روی ورود بزنید. ورود یک لینک یکبارمصرف است که دو ساعت اعتبار دارد.
هر دو میتوانند با یک توکن درخواست واقعی بفرستند، و Scalar دکمهای برای دانلود سند OpenAPI دارد. آن را به یک ابزار ساخت کلاینت مثل openapi-generator بدهید تا یک کلاینت تایپشده به زبان خودتان بگیرید.
کدهای خطا
همهی 279 کدی که پنل ممکن است در errorCode بفرستد، با وضعیت HTTP آنها. پیامها همان پیامهای انگلیسی API هستند.
| کد | HTTP | پیام |
|---|
همهی اندپوینتها
به همان ترتیب منوی پنل. هر اندپوینت را باز کنید تا دسترسی، پارامترها، فیلدهای بدنه و پاسخ، یک درخواست آمادهی کپی و یک پاسخ نمونه را ببینید. توضیح اندپوینتها و فیلدها انگلیسی است، همانطور که در خود API آمده.
- GET خواندن
- POST ساختن یا انجام کار
- PATCH تغییر
- PUT جایگزینی
- DELETE حذف
چند مسیر عمداً آورده نشدهاند: نصبکنندهی نود، بلیتهای ترمینال SSH، ورود به ابزارهای بکاند و وبهوک تلگرام رباتهای فروشنده. فقط صفحههای خود پنل و تلگرام آنها را صدا میزنند.