توثيق الواجهة البرمجية (API)

واجهة REST آمنة تُمكّن أنظمة إدارة المساحات والوصول من إنشاء حسابات الإنترنت والتحكم بجلساتها الحيّة وقراءة استهلاكها على شبكة يديرها RadiusX — بمفتاح واحد لكل شبكة، بصيغة JSON عبر HTTPS.

BASE https://radiusx.link/api/v1
FORMAT JSON / HTTPS
AUTH Bearer rxk_…

المصادقة

كل طلب يحمل مفتاح الشبكة كـ Bearer token. المفتاح وحده يحدّد الشبكة — لا تُمرّر أي معرّف شبكة. صاحب كل شبكة ينسخ مفتاحه من لوحته لدى RadiusX ويُدخله في نظامك، والمفتاح لا يرى ولا يتحكّم إلا ببيانات تلك الشبكة.

# header on every request
Authorization: Bearer rxk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
الضابطالسلوك
البيئاتSandbox والإنتاج يتشاركان نفس الـ Base URL؛ المفتاح يحدّد البيئة (مفتاح Sandbox يعمل على بيانات تجريبية معزولة).
قائمة السماح (IP)اختيارية لكل شبكة. عند ضبطها تُرفض الطلبات من عناوين أخرى بـ 403 ip_not_allowed.
توقيع الطلبHMAC اختياري (مرحلة 2): أرسل X-Signature: sha256=<hmac of raw body>.
حد الاستخدام120 طلب/دقيقة لكل مفتاح؛ التجاوز يُرجع 429 rate_limited.

الأساسيات

الموضوعالقاعدة
حجم البياناتبالبايت، مجموع التنزيل + الرفع.
السرعةميجابت/ثانية (Mbps).
التواريخISO 8601 مع الإزاحة، مثل 2026-08-31T23:59:59+03:00. نخزّن اللحظة الدقيقة.
منع التكرارأرسل external_ref (معرّف بطاقتك) عند الإنشاء؛ تكرار نفس المرجع يُرجع الحساب القائم لا نسخة مكررة. ويُقبل أيضاً ترويسة Idempotency-Key.
العنونةكل مسار /subscribers/{id} يقبل subscriber_id الرقمي لدينا أو external_ref الخاص بك.
شكل النجاح{ "status":"success", … }
شكل الخطأ{ "status":"error", "code":"…", "message":"…" }

الكوتا والصلاحية

يُقيَّد الحساب بـ كوتا بيانات و/أو تاريخ صلاحية — اضبط أيّهما أو كليهما أو لا شيء. كلاهما يُفرض تلقائياً من طرفنا؛ لا حاجة لأن تراقب وتقطع بنفسك.

كوتا البيانات — quota_bytes

سقف إجمالي عبر كل الجلسات (رفع + تنزيل). الجلسة الحيّة مقيّدة بالمتبقي، وعند بلوغ السقف يُمنع الحساب عند إعادة المصادقة — لا يُصفَّر بإعادة الاتصال. القيمة 0 أو تركها = بلا حد.

الصلاحية — expires_at

تاريخ انتهاء زمني يُفرض فوراً: عند بلوغه يُمنع الدخول وتُقطع الجلسة الجارية. اتركه ليرث نافذة الباقة، أو أرسل null لبلا انتهاء.

النقاط (Endpoints)

GET/profiles
باقات الشبكة لمطابقتها مع خططك — السرعة، حدود البيانات والوقت، الصلاحية والسعر.
Response 200
{
  "status": "success",
  "profiles": [{
    "id": 70, "name": "Day pass — 10 Mbps / 5 GB",
    "download_mbps": "10", "upload_mbps": "10", "rate_limit": "10/10",
    "quota_bytes": 5368709120, "time_limit_seconds": null,
    "validity": "30 days", "price": 0
  }]
}
POST/subscribers
إنشاء وتفعيل حساب. أنت تزوّد بيانات الدخول التي يكتبها الزبون في صفحة الهوتسبوت. منع التكرار عبر external_ref.
Body
الحقلالنوعملاحظات
usernamestringاسم الدخول (معرّف بطاقتك). required
passwordstringكلمة المرور. required
profile_idintegerمن GET /profiles. required
quota_bytesintegerيتجاوز كوتا الباقة. 0 = بلا حد. optional
expires_atstringISO 8601. null = بلا انتهاء؛ الحذف = افتراضي الباقة. optional
external_refstringمرجعك — يفعّل منع التكرار والعنونة. optional
simultaneous_useintegerأقصى أجهزة متزامنة. optional
Request
curl -X POST https://radiusx.link/api/v1/subscribers \
  -H "Authorization: Bearer rxk_…" \
  -H "Content-Type: application/json" \
  -d '{ "username": "u-1001", "password": "s3cret",
        "profile_id": 70, "quota_bytes": 1073741824,
        "expires_at": "2026-08-31T23:59:59+03:00",
        "external_ref": "CARD-001" }'
Response 201
{
  "status": "success", "idempotent": false,
  "subscriber": {
    "subscriber_id": 33, "external_ref": "CARD-001",
    "username": "u-1001", "profile_id": 70, "status": "active",
    "online": false, "download_bytes": 0, "upload_bytes": 0,
    "used_bytes": 0, "quota_bytes": 1073741824, "remaining_bytes": 1073741824,
    "session_time": 0, "last_seen": null, "expires_at": "2026-08-31T20:59:59+00:00"
  }
}
GET/subscribers/{id}
الحالة والاستهلاك الحيّ. {id} هو subscriber_id لدينا أو external_ref الخاص بك.
حقول الاستجابة
الحقلالمعنى
statusactive · suspended · expired
onlineلديه جلسة حيّة الآن.
download_bytesمجموع ما أُرسل للمستخدم (تنزيل).
upload_bytesمجموع ما استُقبل من المستخدم (رفع).
used_bytesالمجموع الكلي (تنزيل + رفع).
remaining_bytesالكوتا − المستهلك، أو null عند اللامحدود.
session_timeمجموع ثواني الاتصال.
last_seenآخر تحديث محاسبة (ISO 8601) أو null.
expires_atنهاية الصلاحية أو null.

يتحدّث الاستهلاك على فترة محاسبة ~5 دقائق ولحظياً عند انتهاء الجلسة.

PATCH/subscribers/{id}
إيقاف / إعادة تفعيل، أو تغيير الباقة أو الكوتا أو الصلاحية أو كلمة المرور. الإيقاف يقطع الجلسة الحيّة فوراً.
الحقلملاحظات
statusactive أو suspended — الإيقاف = منع + فصل فوري.
profile_idتبديل الباقة (سرعة/كوتا/صلاحية).
quota_bytesسقف إجمالي جديد (0 = بلا حد).
expires_atصلاحية جديدة (null = بلا انتهاء).
passwordتغيير كلمة المرور.
Request
curl -X PATCH https://radiusx.link/api/v1/subscribers/CARD-001 \
  -H "Authorization: Bearer rxk_…" -H "Content-Type: application/json" \
  -d '{ "status": "suspended" }'
DELETE/subscribers/{id}
حذف الحساب نهائياً وفصل أي جلسة حيّة.
Response 200
{ "status": "success", "message": "Subscriber deleted." }
POST/subscribers/{id}/disconnect
فصل الجلسة الحيّة الآن عبر CoA / Disconnect (RFC 5176) دون تغيير الحساب.
Response 200
{ "status": "success", "disconnected": true }
// disconnected:false = no live session

الإشعارات (Webhooks) — مرحلة 2

زوّدنا برابط callback وسرّ مشترك، فنرسل أحداث دورة الحياة لحظياً. كل تسليم موقّع ويُعاد عند الفشل (5 محاولات، تراجع 10ث ← 15د).

الحدثيُطلق عند
subscriber.createdتجهيز الحساب.
subscriber.onlineبدء جلسة.
subscriber.offlineانتهاء جلسة.
subscriber.quota_exhaustedبلوغ الاستهلاك للسقف.
subscriber.expiredانقضاء الصلاحية.
subscriber.suspendedإيقاف الحساب عبر الـ API.
subscriber.deletedحذف الحساب.
Delivery
# headers
X-RadiusX-Event: subscriber.quota_exhausted
X-RadiusX-Signature: sha256=<hmac-sha256 of raw body, keyed by your secret>

# body
{ "event": "subscriber.quota_exhausted", "sent_at": "2026-07-23T12:30:15+00:00",
  "data": { "subscriber_id": 33, "external_ref": "CARD-001",
    "username": "u-1001", "used_bytes": 1073741824, "quota_bytes": 1073741824 } }
تحقّق من صحة التسليم بإعادة حساب HMAC-SHA256(secret, rawBody) ومقارنته بترويسة X-RadiusX-Signature قبل الوثوق به.

الأخطاء

الاستجابات غير الناجحة تستخدم code ثابتاً قابلاً للقراءة آلياً؛ وmessage نصّي مكمّل. أخطاء التحقق تُضيف خريطة errors بالحقل.

HTTPcodeالمعنى
401unauthorizedمفتاح مفقود أو غير صالح.
401invalid_signatureفشل توقيع HMAC (عند تفعيله).
403ip_not_allowedالعنوان خارج قائمة السماح.
403network_suspendedالشبكة موقوفة.
404not_foundلا مشترك بهذا المعرّف لهذه الشبكة.
409username_takenاسم المستخدم مستخدَم مسبقاً.
422validation_failedحقول ناقصة/خاطئة — راجع errors.
429rate_limitedتجاوز 120 طلب/دقيقة.
500server_errorخطأ غير متوقع — آمن لإعادة المحاولة.
{
  "status": "error", "code": "validation_failed",
  "message": "The given data was invalid.",
  "errors": { "profile_id": ["The profile id field is required."] }
}

بيئة الاختبار (Sandbox)

مفتاح Sandbox يشير إلى شبكة اختبار معزولة — أنشئ وأوقف واقرأ واحذف بحرية دون أي أثر حقيقي. نفس الـ Base URL؛ المفتاح يحدّد البيئة.

# list sandbox profiles, then create a test account
curl https://radiusx.link/api/v1/profiles -H "Authorization: Bearer <sandbox key>"
curl -X POST https://radiusx.link/api/v1/subscribers -H "Authorization: Bearer <sandbox key>" \
  -H "Content-Type: application/json" \
  -d '{"username":"test-1","password":"pw","profile_id":<id>,"external_ref":"T-1"}'
شرط الإنتاج: راوتر كل مشغّل شبكة يجب أن يكون مربوطاً بخادم RADIUS لدينا (يحصل على مفتاحه وإعداد الراوتر من لوحته). نظامك يستدعي هذه الواجهة؛ وربط الراوتر يُجهَّز لكل مشغّل ولا يمرّ عبر خوادمك.