DEVELOPER DOCUMENTATION

مستندات فنی

راهنمای کامل یکپارچه‌سازی و استفاده از API، WebSocket و SDKهای FreedomNet

آخرین نسخه: v2.4.0

بروزرسانی: ۱۵ فوریه ۲۰۲۴

وضعیت: پایدار

شروع سریع

در ۵ دقیقه شروع کنید

مرجع API

اندپوینت‌ها و پارامترها

SDKها

پایتون، Node.js، جاوا، Go

مثال‌ها

کدهای آماده

فهرست مطالب

دانلود مستندات:

شروع سریع

در ۵ دقیقه API FreedomNet را یکپارچه کنید

۱. دریافت API Key

ابتدا وارد پنل کاربری شوید و از بخش توسعه‌دهندگان یک API Key جدید بسازید.

تولید API Key

# با استفاده از CLI
curl -X POST https://api.relifemc.ir/v1/keys \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "scopes": ["servers.read", "configs.write"]}'

۲. احراز هویت

تمام درخواست‌ها باید با هدر Authorization ارسال شوند.

مثال درخواست

GET /v1/servers HTTP/1.1
Host: api.relifemc.ir
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

احراز هویت

روش‌های تأیید هویت در API

Bearer Token

توکن خود را در هدر Authorization به این شکل ارسال کنید:

Authorization: Bearer fn_xxxxxxxxxxxxxxxxxxxx

محدوده دسترسی (Scopes)

Scope	دسترسی
servers.read	مشاهده لیست سرورها
configs.read	مشاهده کانفیگ‌ها
configs.write	ایجاد و ویرایش کانفیگ

مرجع API

لیست کامل اندپوینت‌ها

GET /v1/servers

دریافت لیست تمام سرورهای فعال

پارامترها: بدون پارامتر

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "آمریکا شرقی",
      "flag": "🇺🇸",
      "ping": 45,
      "load": "low"
    }
  ]
}

POST /v1/configs

ایجاد کانفیگ VPN جدید

پارامترها: protocol, server_id, name

{
  "name": "My Config",
  "protocol": "wireguard",
  "server_id": 1
}

GET /v1/user/profile

دریافت اطلاعات کاربری

{
  "username": "john_doe",
  "email": "john@example.com",
  "subscription": {
    "plan": "professional",
    "expires_at": "2024-12-31",
    "status": "active"
  }
}

WebSocket

اتصال بلادرنگ و رویدادهای زنده

اتصال WebSocket

const ws = new WebSocket('wss://api.relifemc.ir/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'YOUR_API_KEY'
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('📩', data);
};

رویدادهای پشتیبانی شده:

رویداد	توضیحات	Payload
server.status	تغییر وضعیت سرور	{ id, status, load }
config.used	استفاده از کانفیگ	{ config_id, user, timestamp }
user.connected	اتصال کاربر	{ user_id, server, ip }

SDKهای رسمی

کتابخانه‌های رسمی برای زبان‌های محبوب

Python SDK

v2.4.0

pip install freedomnet-sdk

from freedomnet import Client

client = Client(api_key="YOUR_KEY")
servers = client.servers.list()

مستندات

Node.js SDK

v2.4.0

npm install freedomnet-sdk

const { Client } = require('freedomnet-sdk');
const client = new Client('YOUR_KEY');
const servers = await client.servers.list();

مستندات

Java SDK

v2.4.0

implementation 'com.freedomnet:sdk:2.4.0'

FreedomNetClient client = 
  new FreedomNetClient("YOUR_KEY");
List servers = 
  client.getServers();

مستندات

Go SDK

v2.4.0

go get github.com/freedomnet/sdk

client := freedomnet.NewClient("YOUR_KEY")
servers, err := client.ListServers()

مستندات

کدهای خطا

لیست کامل خطاهای API

کد	پیام	توضیحات	راه‌حل
400	bad_request	درخواست نامعتبر	پارامترها را بررسی کنید
401	unauthorized	توکن نامعتبر یا منقضی	API Key جدید بسازید
403	forbidden	دسترسی غیرمجاز	Scopeها را بررسی کنید
404	not_found	منبع یافت نشد	آیدی منبع را بررسی کنید
429	too_many_requests	تعداد درخواست بیش از حد	صبر کنید و دوباره تلاش کنید
500	internal_error	خطای داخلی سرور	به پشتیبانی گزارش دهید

محدودیت نرخ

محدودیت درخواست‌ها در API

پلن رایگان

۶۰

درخواست در دقیقه

۱,۰۰۰ درخواست روزانه

پلن حرفه‌ای

۳۰۰

درخواست در دقیقه

۱۰,۰۰۰ درخواست روزانه

هدرهای محدودیت نرخ

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1708456789

Webhooks

دریافت رویدادهای لحظه‌ای

نمونه payload webhook

{
  "event": "config.created",
  "timestamp": "2024-02-15T12:00:00Z",
  "data": {
    "id": 123,
    "name": "My Config",
    "user_id": 456
  }
}

تنظیم Webhook

مثال‌ها

کدهای آماده برای استفاده

Python

import requests

API_KEY = "your_key"
headers = {
    "Authorization": f"Bearer {API_KEY}"
}

response = requests.get(
    "https://api.relifemc.ir/v1/servers",
    headers=headers
)
servers = response.json()

JavaScript

const API_KEY = 'your_key';

fetch('https://api.relifemc.ir/v1/servers', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
})
.then(res => res.json())
.then(data => console.log(data));

تغییرات نسخه

تاریخچه بروزرسانی‌های API

نسخه ۲.۴.۰

۱۵ فوریه ۲۰۲۴

اضافه شدن WebSocket برای رویدادهای بلادرنگ
بهبود performance در اندپوینت /servers
رفع باگ احراز هویت در درخواست‌های همزمان

نسخه ۲.۳.۰

۲۰ ژانویه ۲۰۲۴

اضافه شدن پشتیبانی از IPv6
اندپوینت جدید /v1/analytics
بهبود مستندات و مثال‌ها

به راهنمایی بیشتری نیاز دارید؟

تیم پشتیبانی فنی ما ۲۴/۷ آماده پاسخگویی است

تماس با پشتیبانی انجمن توسعه‌دهندگان