# توثيق الـ API: دليل كل مسارات AdBlock Vip للمطورين
> مرجع كامل لـ JSON API بتاع AdBlock Vip: المصادقة، مسارات الحساب والشبكات والاشتراك، مسارات التحكم بالأجهزة، حدود المعدل، وأمثلة curl عملية.
- النوع: توثيق
- الكاتب: AdBlock Vip
- النشر: 2026-10-07
- الوسوم: API, مطورين, JSON, تكامل
- الرابط الأصلي: https://ad-block.vip/docs/api-reference

![توثيق الـ API: دليل كل مسارات AdBlock Vip للمطورين — دليل AdBlock Vip](/assets/docs/api-reference/cover.jpg)

## إيه هو الـ 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). مفيد جدًا لو بتبني أداة تشيك حالة الشبكة.

```json
{
  "ip": "197.45.120.8",
  "public": true
}
```

`cache-control: no-store` — لأن الـ IP بيتغير من شبكة لتانية، فلازم يتطلب كل مرة.

## مسارات الحساب (Account)

### بيانات المستخدم

```
GET /api/me
```

بيرجع بياناتك الأساسية + عدد الشبكات (Profiles) عندك.

```json
{
  "id": 1042,
  "email": "you@example.com",
  "display_name": "أحمد",
  "auth_provider": "google",
  "profiles_count": 2
}
```

### الشبكات (Profiles)

```
GET /api/me/profiles
```

قائمة كل الشبكات بتاعتك مع بيانات الاتصال الخاصة بكل واحدة — تنفعها عشان تضبط DNS على أي جهاز.

```json
{
  "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`…). لو معندكش اشتراك مدفوع، بيرجع حدود الخطة المجانية.

```json
{
  "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`) — مع حالة كل جهاز وآخر مرة ظهر فيها.

```json
{
  "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
```

بيرجع الجهاز باسمه ونوعه، مع كل القواعد المطبقة عليه (حجب نطاق / سماح نطاق / حجب الإنترنت بالكامل). الجهاز اللي ما اظهرش آخر ٧ أيام بيختفي من القائمة.

```json
{
  "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 نفسه** — لو الخطط مش مفعّل فيها الميزة، القاعدة مش هتشتغل حتى لو اتسجلت. شوف [دليل القوائم المخصصة](/docs/allowlist-denylist-guide).

### حذف قاعدة

```
DELETE /api/me/devices/:configId/rules/:ruleId
```

بيقول القاعدة بناءً على `ruleId` (من مسار القراءة فوق). مابيرجعش أي جسم — `200` مع `{ ok: true }`. مينفعش تحذف قاعدة على شبكة تانية بتاعتك.

## شكل الاستجابات والأخطاء

كل استجابات الـ API بتتبع نفس الشكل دائمًا — مفيش مسار بيخرج عنه:

- **نجاح:** جسم الـ JSON الخاص بالمورد (زي `{ profiles: [...] }` أو `{ ok: true }`) مع كود `200`.
- **خطأ:** نفس الشكل الموحّد في كل مكان:

```json
{
  "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. لو عدّيت الحد، هتلاقي:

```json
{
  "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`. [رقّ خطتك](/pricing) عشان تفعّلها.

### 404 على `/api/me/devices/:configId`

تأكد إن الـ `configId` موجود في رد `/api/me/profiles`. لو اتبعت `NaN` أو `null` بترجع `404` نظيفة بدل خطأ سيرفر — ده مقصود عشان السكربتات ماتكسرش.

## الأسئلة الشائعة
### هل في مفتاح API (API key)؟
لا — المصادقة بالجلسة (session cookie) بس. ده أكثر أمانًا لأنه مفيش مفتاح ثابت ممكن يتسرب، والجلسة بتنتهي تلقائيًا.
### هل الـ API مجاني؟
ايوه، كل مسارات الـ API متاحة لكل المستخدمين (الحدود بتختلف حسب الخطة). مفيش تكلفة إضافية على استخدام الـ API.
### هل يدعم CORS عشان أستخدمه من المتصفح؟
مسارات الـ API بتتطلب نفس أصل الموقع (same-origin) — مينفعش تطلبها من دومين تاني من JS في المتصفح. استخدمها من سكربت خادم (server-side) أو من تطبيق.
### فين أرصد الطلبات عشان أتأكد بتشتغل؟
استخدم أداة زي `curl`: ```bash **احفظ الجلسة في ملف cookie** curl -c cookies.txt -X POST https://ad-block.vip/login \ -d "email=you@example.com" -d "password=..." **استخدمها في كل طلب بعد كده** curl -b cookies.txt https://ad-block.vip/api/me/profiles ``` **الخطوة التالية** [دليل لوحة التحكم والـ Profiles](/docs/dashboard-profiles-guide) — فهم الـ Profiles والقوائم ، [دليل القوائم المخصصة](/docs/allowlist-denylist-guide) — Allowlist و Denylist ، [التحكم الفردي بالأجهزة](/docs/device-level-controls-guide) — حجب الإنترنت عن جهاز واحد ، [استكشاف الأخطاء وإصلاحها](/docs/troubleshooting) — لو الطلب رجع غريب