Umiji

کل پنل را با کد خودتان اداره کنید.

هر کاری که در 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

توکن کلید بلندی است که نماینده‌ی یک برنامه است. برای هر ربات یا اسکریپت یک توکن جدا بسازید تا بتوانید یکی را حذف کنید بی‌آنکه بقیه از کار بیفتند.

  1. تنظیمات Umiji را باز کنید و کارت توکن‌های API را پیدا کنید. روی ساخت توکن API بزنید.
  2. نام توکن و انقضا پس از (روز) را پر کنید و دامنه‌های دسترسی را انتخاب کنید: یکی از پیش‌تنظیم‌ها، یا اندپوینت‌ها را تک‌تک.
  3. توکن را کپی کنید. فقط یک بار، درست بعد از ساخته شدن، نشان داده می‌شود.
  4. آن را با هر درخواست در هدر 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) می‌گویند یک توکن چه چیزهایی را می‌تواند صدا بزند. چهار اندازه دارند، از همه‌چیز تا فقط یک اندپوینت. اگر حتی یکی از دامنه‌های توکن اندپوینت را پوشش دهد، درخواست رد نمی‌شود.

  1. *هر چیزی که توکن API به آن دسترسی دارد. همان کلید دسترسی کامل.
  2. users:*همه‌ی اندپوینت‌های یک منبع، این‌جا کاربرها.
  3. users:readهمه‌ی اندپوینت‌های خواندنی یک منبع. users:write هم همه‌ی اندپوینت‌های تغییردهنده است.
  4. 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-Typeapplication/json
X-Umiji-SignatureHMAC-SHA256 بدنه‌ی خام با کلید شما، به صورت hex.
X-Umiji-Timestampزمان رویداد به صورت ISO 8601؛ همان timestamp داخل بدنه.
User-AgentUmiji
{
  "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.reportTorrent 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 >

متریک‌ها و سلامت

پروسه‌ی زمان‌بند (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، ورود به ابزارهای بک‌اند و وب‌هوک تلگرام ربات‌های فروشنده. فقط صفحه‌های خود پنل و تلگرام آن‌ها را صدا می‌زنند.