APIمطورينJSONتكامل

توثيق الـ API: دليل كل مسارات AdBlock Vip للمطورين

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

توثيق الـ API: دليل كل مسارات AdBlock Vip للمطورين — دليل AdBlock Vip

إيه هو الـ 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 نظيفة بدل خطأ سيرفر — ده مقصود عشان السكربتات ماتكسرش.