مقدمة

واجهة برمجية لعرض الباقات، واستعراض الاشتراكات، وشراء بروكسيات جديدة، وتجديد الاشتراكات النشطة، وضبط التدوير التلقائي لعناوين IP.

تستخدم الواجهة نقطة دخول واحدة: /api/proxy. في عمليات GET يتم تمرير op ضمن query string، وفي عمليات POST يتم تمرير op ضمن JSON body.

البدء السريع

أنشئ مفتاح API في Dashboard -> API Keys وأرسله في ترويسة كل طلب.

BASE="https://makeadsafe.com"
API_KEY="rk_your_long_lived_api_key"

جميع المعرّفات تتكون من أحرف وأرقام صغيرة فقط.

إصدار النسخة التجريبية عبر POST /api/proxy مع {"op":"trial","planId":"..."} متاح فقط لبعض مفاتيح API المحددة. تواصل مع الدعم لتفعيل هذه الميزة لمفتاحك. تتم مراقبة استخدام النسخة التجريبية وقد يتم تقييده أو تعطيله في حال إساءة الاستخدام.

الباقات المتاحة

تعيد الباقات النشطة المتاحة لمالك مفتاح API.

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=plans"

{
  "ok": true,
  "plans": [
    {
      "id": "k17m3q5v7n9p1r2t4w6y8z0a",
      "connectionType": "private",
      "durationMs": 2592000000,
      "priceAmountCents": 1200,
      "popular": true,
      "remainingProxies": 20,
      "network": {
        "name": "NL-AMS",
        "city": "Amsterdam",
        "country": "NL",
        "networkType": "mobile"
      }
    }
  ]
}

الاشتراكات النشطة

تعيد اشتراكاتك، بما في ذلك بيانات الاعتماد وروابط البروتوكولات وبيانات تدوير IP.

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=subscriptions"

{
  "ok": true,
  "subscriptions": [
    {
      "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
      "status": "active",
      "activeUntil": 1762592000000,
      "userNote": "Client A",
      "rotationPolicy": 10,
      "label": "12001 - NL - Private",
      "networkLabel": "NL-AMS Amsterdam",
      "credentials": {
        "username": "u_6k8s9d",
        "password": "p_2n4m6q"
      },
      "protocols": {
        "http": "http://u_6k8s9d:[email protected]:12001",
        "socks5": "socks5://u_6k8s9d:[email protected]:12001",
        "vless": "vless://...",
        "shadowsocks": "ss://..."
      },
      "rotate": {
        "rotatePath": "/r/abcd1234",
        "available": true
      }
    }
  ]
}

باقات التجديد

تعيد الباقات المؤهلة لتجديد اشتراك محدد.

SUB_ID="j97b2f6m1k4n8p3r5t7v9x0z"

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=renewal-plans&subscriptionId=$SUB_ID"

{
  "ok": true,
  "renewalPlans": [
    {
      "id": "k17m3q5v7n9p1r2t4w6y8z0a",
      "connectionType": "private",
      "durationMs": 2592000000,
      "priceAmountCents": 1200
    }
  ]
}

الشبكات المتاحة

تعيد الشبكات المتاحة لتبديل اشتراك محدد.

SUB_ID="j97b2f6m1k4n8p3r5t7v9x0z"

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=available-networks&subscriptionId=$SUB_ID"

{
  "ok": true,
  "networks": [
    {
      "id": "b1c2d3e4f5g6h7j8k9m0n1p2",
      "networkLabel": "DE-BER Berlin",
      "country": "DE"
    }
  ]
}

استخدم networks[].id كقيمة targetNetwork في طلب switch-network.

شراء اشتراك

ينشئ اشتراكًا واحدًا أو عدة اشتراكات جديدة من رصيدك باستخدام الباقة المحددة.

حقول اختيارية:

• couponCode: يطبّق كوبونًا صالحًا على عملية الشراء.
• repeatCount: عدد صحيح موجب، والقيمة الافتراضية 1؛ يضاعف المدة والسعر لكل اشتراك يتم إنشاؤه.
• quantity: عدد صحيح موجب، والقيمة الافتراضية 1؛ ينشئ عدة اشتراكات في طلب واحد.
• os: بصمة نظام التشغيل السلبية المطبقة على جميع البروكسيات المنشأة؛ إحدى القيم ios أو macos أو android أو win10 أو win11. غير متاح لخطط multi.

{
  "op": "purchase",
  "planId": "k17m3q5v7n9p1r2t4w6y8z0a",
  "couponCode": "MYCODE",
  "repeatCount": 3,
  "os": "ios",
  "quantity": 2
}

curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"purchase","planId":"k17m3q5v7n9p1r2t4w6y8z0a","repeatCount":3,"os":"ios","quantity":2}' 
  "$BASE/api/proxy"

{
  "ok": true,
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "subscriptionIds": [
    "j97b2f6m1k4n8p3r5t7v9x0z",
    "n38k2f6m1k4n8p3r5t7v9x0z"
  ],
  "subscriptions": [
    {
      "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
      "status": "active",
      "activeUntil": 1767776000000,
      "label": "12001 - NL - Private",
      "networkLabel": "NL-AMS Amsterdam"
    },
    {
      "subscriptionId": "n38k2f6m1k4n8p3r5t7v9x0z",
      "status": "active",
      "activeUntil": 1767776000000,
      "label": "12002 - NL - Private",
      "networkLabel": "NL-AMS Amsterdam"
    }
  ]
}

إذا تم إنشاء اشتراك واحد فقط، فقد تعيد البوابة subscription بدلًا من subscriptions. تستخدم العناصر داخل subscription/subscriptions البنية نفسها الخاصة بـ GET /api/proxy?op=subscriptions.

تجديد الاشتراك

يجدد اشتراكًا موجودًا باستخدام باقة تجديد مؤهلة.

حقول اختيارية:

• couponCode: يطبّق كوبونًا صالحًا على التجديد.
• repeatCount: عدد صحيح موجب، والقيمة الافتراضية 1؛ يضاعف مدة التجديد وسعره.

{
  "op": "renew",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "planId": "q2w4e6r8t0y2u4i6o8p0a2s4",
  "couponCode": "MYCODE",
  "repeatCount": 3
}

curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"renew","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z","planId":"q2w4e6r8t0y2u4i6o8p0a2s4","repeatCount":3}' 
  "$BASE/api/proxy"

{
  "ok": true,
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "endAt": 1770368000000
}

تغيير بيانات الاتصال

يعيد توليد بيانات الاتصال لاشتراك نشط يخص المستخدم الموثق (JWT) أو مالك مفتاح API.

{
  "op": "change-credentials",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z"
}

curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"change-credentials","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z"}' 
  "$BASE/api/proxy"

{
  "ok": true,
  "password": "q7N3x9Lp",
  "vpn": "7f3d9d4a-8b9f-4a93-9f55-2d5e3b7f1c24"
}

ضبط سياسة التدوير التلقائي

يضبط التدوير التلقائي لعناوين IP لاشتراك نشط. الإعداد متاح فقط للاتصالات التي تحتوي على "rotate": { "available": true }.

القيم المسموح بها لـ rotationPolicy هي: 0 و5 و10 و15 و30 و60 دقيقة. استخدم 0 لتعطيل التدوير التلقائي.

{
  "op": "set-rotation-policy",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "rotationPolicy": 10
}

curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"set-rotation-policy","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z","rotationPolicy":10}' 
  "$BASE/api/proxy"

{
  "ok": true
}

تغيير شبكة الاتصال

ينقل اشتراكًا نشطًا إلى شبكة أخرى متاحة.

{
  "op": "switch-network",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "targetNetwork": "b1c2d3e4f5g6h7j8k9m0n1p2"
}

curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"switch-network","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z","targetNetwork":"b1c2d3e4f5g6h7j8k9m0n1p2"}' 
  "$BASE/api/proxy"

{
  "ok": true,
  "subscription": {
    "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
    "status": "active",
    "activeUntil": 1762592000000,
    "userNote": "Client A",
    "rotationPolicy": 10,
    "label": "12001 - DE - Private",
    "networkLabel": "DE-BER Berlin",
    "credentials": {
      "username": "u_6k8s9d",
      "password": "p_2n4m6q"
    },
    "protocols": {
      "http": "http://u_6k8s9d:[email protected]:12001",
      "socks5": "socks5://u_6k8s9d:[email protected]:12001",
      "vless": "vless://...",
      "shadowsocks": "ss://..."
    },
    "rotate": {
      "rotatePath": "/r/abcd1234",
      "available": true
    }
  }
}

أخطاء البوابة

• 400 JSON غير صالح في body
• 400 يجب أن يكون body كائنًا
• 400 قيمة op مفقودة أو غير معروفة
• 400 الحقل planId/subscriptionId/targetNetwork/rotationPolicy مفقود أو غير صالح
• 400 القيمة repeatCount أو quantity غير صالحة
• 400 القيمة os غير صالحة
• 401 Unauthorized
• 402 الرصيد غير كافٍ
• 403 Forbidden
• 404 الاشتراك غير موجود
• 409 سياسة التدوير غير متاحة لهذا الاشتراك
• 409 لا توجد موارد متاحة، أو أن الباقة/الشبكة غير نشطة، أو أن حالة الاشتراك غير صالحة
• 409 اختيار نظام التشغيل غير متاح لخطط multi
• 429 Rate limited
• 500 Internal error