توثيق الـ API: دليل كل مسارات AdBlock Vip للمطورين
مرجع كامل لـ JSON API بتاع AdBlock Vip: المصادقة، مسارات الحساب والشبكات والاشتراك، مسارات التحكم بالأجهزة، حدود المعدل، وأمثلة curl عملية.

إيه هو الـ API بتاع AdBlock Vip؟
AdBlock Vip بيوفّر JSON API للمطورين وللتطبيقات (زي تطبيق الموبايل الرسمي) عشان يتفاعلوا مع الحساب والشبكات برمجيًا — من غير لوحة التحكم. كل المسارات بترجع application/json، والمصادقة بتيجي من جلسة نفس المتصفح (session cookie) زي ما هي، فمحدش يقدر يوصلك لبياناتك غيرك.
الـ API ده مناسب لو:
- بتطوّر تطبيق أو سكربت يتحكم في شبكتك
- عاوز تقرا بيانات الاشتراك والحدود برمجيًا
- بتبني تكامل مع نظام موجود عندك
مهم: كل المسارات بتشتغل على نفس الدومينhttps://ad-block.vipوتتطلب تسجيل دخول صالح. لو الجلسة انتهت أو غير موجودة، العميل اللي بيطلبAccept: application/json(أو أي مسار تحت/api/) بيحصل على401مع ترويسةWWW-Authenticate— مش redirect. العملاء اللي بتتبع redirect (المتصفحات) هتروح لصفحة الدخول بشكل طبيعي.
المصادقة (Authentication)
الـ API بيستخدم session cookie — نفس الـ cookie اللي بيتبعت من المتصفح بعد تسجيل الدخول (عن طريق الإيميل/كلمة المرور أو حساب جوجل).
Cookie: connect.sid=s%3Axxxxxxxxxxxx.xxxxxxxx
مينفعش تبعت مفتاح API (API key) — النظام مفيهوش مفاتيح، الجلسة هي الأساس. لو بتبني سكربت خادم (server-side)، سجّل دخول مرة واحدة واتبع الـ cookie.
تسجيل الدخول بحساب جوجل من تطبيق
POST /auth/google/mobile
Content-Type: application/json
{ "id_token": "<google_id_token>" }
بيرجع { ok: true } وبيضبط الجلسة. التطبيق بعد كده يبعت نفس الـ cookie في كل طلب.
نقطة النهاية العامة (Public)
معرفة الـ IP الحالي
GET /api/ip
أبسط مسار — مايحتاش تسجيل دخول. بيرجع الـ IP اللي بتطلب منه، وهل هو IP عام (public) ولا داخلي (private). مفيد جدًا لو بتبني أداة تشيك حالة الشبكة.
{
"ip": "197.45.120.8",
"public": true
}
cache-control: no-store — لأن الـ IP بيتغير من شبكة لتانية، فلازم يتطلب كل مرة.
مسارات الحساب (Account)
بيانات المستخدم
GET /api/me
بيرجع بياناتك الأساسية + عدد الشبكات (Profiles) عندك.
{
"id": 1042,
"email": "you@example.com",
"display_name": "أحمد",
"auth_provider": "google",
"profiles_count": 2
}
الشبكات (Profiles)
GET /api/me/profiles
قائمة كل الشبكات بتاعتك مع بيانات الاتصال الخاصة بكل واحدة — تنفعها عشان تضبط DNS على أي جهاز.
{
"profiles": [
{
"configId": "46c7695b54e3",
"name": "شبكة البيت",
"status": "active",
"dohHost": "dns.ad-block.vip",
"dnsIpv4": "169.58.24.201",
"dnsIpv6": "2a02:c207:2274:9303::1"
}
]
}
ملاحظة: الـ configId هو المفتاح اللي بتستخدمه في كل مسارات الأجهزة تحته.
الاشتراك والحدود
GET /api/me/subscription
بيرجع آخر اشتراك نشط + حدود خطتك الحالية (max_profiles و max_links و custom_rules…). لو معندكش اشتراك مدفوع، بيرجع حدود الخطة المجانية.
{
"subscription": {
"id": 88,
"status": "active",
"billing_cycle": "yearly",
"started_at": "2026-09-01T00:00:00.000Z",
"expires_at": "2027-09-01T00:00:00.000Z",
"plan_name": "الاحترافي",
"plan_slug": "pro",
"max_profiles": 5,
"max_links": 10
},
"limits": {
"max_profiles": 5,
"max_links": 10,
"custom_rules": true,
"youtube_ads": true,
"facebook_ads": true
}
}
مسارات الأجهزة (Devices)
قائمة أجهزة شبكة
GET /api/me/devices/:configId
بيرجع كل الأجهزة المرتبطة بالشبكة (:configId من مسار /api/me/profiles) — مع حالة كل جهاز وآخر مرة ظهر فيها.
{
"devices": [
{
"type": "ip",
"value": "192.168.1.15",
"status": "active",
"resolved_ip": "197.45.120.8",
"last_checked_at": "2026-10-07T10:30:00.000Z"
}
]
}
قراءة قواعد الأجهزة
GET /api/me/devices/:configId/rules
بيرجع الجهاز باسمه ونوعه، مع كل القواعد المطبقة عليه (حجب نطاق / سماح نطاق / حجب الإنترنت بالكامل). الجهاز اللي ما اظهرش آخر ٧ أيام بيختفي من القائمة.
{
"devices": [
{
"id": 31,
"ip": "192.168.1.22",
"label": "تابلت الأطفال",
"device_type": "tablet",
"blocked": false,
"rules_count": 2,
"block_all": false
}
],
"rules": [
{ "id": 104, "device_id": 31, "action": "block_domain", "domain": "ads.example.com" }
]
}
إضافة/تعديل قاعدة جهاز
POST /api/me/devices/:configId/rules
Content-Type: application/json
{
"device_id": 31,
"action": "block_domain",
"domain": "ads.example.com"
}
القيم المسموحة لـ action:
| القيمة | المعنى |
|---|---|
block_domain | حجب نطاق واحد عن الجهاز ده بس |
allow_domain | السماح بنطاق محدد رغم قوائم الحجب |
block_all | حجب الإنترنت بالكامل عن الجهاز |
unblock_all | إلغاء كل القواعد على الجهاز |
الاستجابات:
200 { ok: true }— نجح400—device_idأوactionناقصين، أو النطاق غير صالح403— التحكم الفردي بالأجهزة متاح في خطط الاحترافي والأعمال بس (مفتوح فيlimits.custom_rules)404— الجهاز أو الشبكة غير موجودة409— القاعدة موجودة بالفعل
الحدود بتطُبَّق على مستوى DNS نفسه — لو الخطط مش مفعّل فيها الميزة، القاعدة مش هتشتغل حتى لو اتسجلت. شوف دليل القوائم المخصصة.
حذف قاعدة
DELETE /api/me/devices/:configId/rules/:ruleId
بيقول القاعدة بناءً على ruleId (من مسار القراءة فوق). مابيرجعش أي جسم — 200 مع { ok: true }. مينفعش تحذف قاعدة على شبكة تانية بتاعتك.
شكل الاستجابات والأخطاء
كل استجابات الـ API بتتبع نفس الشكل دائمًا — مفيش مسار بيخرج عنه:
- نجاح: جسم الـ JSON الخاص بالمورد (زي
{ profiles: [...] }أو{ ok: true }) مع كود200. - خطأ: نفس الشكل الموحّد في كل مكان:
{
"error": "رسالة الخطأ بالعربي",
"status": 404
}
جدول الحالات اللي ممكن تقابلك:
| الكود | المعنى | إمتى |
|---|---|---|
200 | نجاح | كل المسارات فوق |
400 | بيانات غير صالحة | حقل ناقص أو نطاق مش مظبوط |
401 | تسجيل الدخول مطلوب | الجلسة منتهية أو غير موجودة |
403 | ممنوع | ميزة مش مفعّلة في خطتك، أو فشل التوكن |
404 | غير موجود | الـ configId أو الجهاز غير صحيح |
405 | طريقة غير مسموحة | مثلاً POST على مسار بيقبل GET بس — الترويسة Allow بتقول المسموح |
409 | تعارض | القاعدة موجودة بالفعل |
429 | طلبات كتيرة | شوف قسم حدود المعدل تحت |
500 | خطأ في الخادم | نادر — بيتسجّل تلقائيًا |
في500بس بيظهر حقل إضافيrefId(معرّف قصير). لو واجهت المشكلة بشكل متكرر، ابلّغ الدعم بالـrefIdده وبيوصل للسجل بالظبط. ملاحظة أمان: الـ API مابيتبعتش أي تفاصيل تقنية أو stack trace في الأخطاء — رسالة واضحة بالعربي بس.
حدود المعدل (Rate Limiting)
كل مسارات الـ API (/api/* بتتطلب تسجيل دخول) محمية بـ rate limiter — عدد محدود من الطلبات في الدقيقة لكل IP. لو عدّيت الحد، هتلاقي:
{
"error": "أرسلت طلبات كثيرة في وقت قصير. انتظر 54 ثانية ثم حاول مجددًا.",
"status": 429,
"retryAfter": 54
}
بالإضافة للـ JSON، الترويسات دي بتتبعت دائمًا (معيار IETF الحالي):
Retry-After: 54
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 54
اقرأ retryAfter (أو الترويسة Retry-After) وانتظر القدر ده قبل الطلب اللي بعده — ده الاحترام الصحيح للحدود بدل retry فوري.
الحل: لا تعمل polling سريع. استخدم فاصل دقيق بين الطلبات (مثلاً ٣٠ ثانية لو بتعمل تحديث دوري).
أخطاء شائعة وحلولها
401 بدل JSON
معناها إن الجلسة انتهت أو غير موجودة. سجّل دخول تاني واتبع الـ cookie الجديد. الـ API بيُرسل ترويسة WWW-Authenticate: Bearer realm="ad-block.vip" مع الكود 401 لكل عملاء JSON — دي الإشارة الصحيحة اللي تقدر تبني عليها منطق إعادة المصادقة في التطبيق (مثلاً: اعترض 401 → سجّل دخول → أعد الطلب).
403 على مسارات الأجهزة
التحكم الفردي بالأجهزة ميزة في خطط الاحترافي والأعمال. لو خطتك الأساسية أو المجانية، هتلاقي 403. رقّ خطتك عشان تفعّلها.
404 على /api/me/devices/:configId
تأكد إن الـ configId موجود في رد /api/me/profiles. لو اتبعت NaN أو null بترجع 404 نظيفة بدل خطأ سيرفر — ده مقصود عشان السكربتات ماتكسرش.