وثائق بروكسي API: استلام قائمة البروكسي عبر REST API

ما الذي يمكن فعله باستخدام API؟

استخدم API عندما تريد أن يحصل البرنامج الذي يستخدم البروكسي على أحدث القوائم تلقائيًا. يمكن للزاحف الحصول على القائمة عند كل بداية، أو يمكن للخادم تغيير القائمة تلقائيًا عند شراء خطة جديدة أو انتهاء الفترة. القوائم التي يتم تنزيلها من لوحة التحكم وتلك التي يتم الحصول عليها عبر API هي نفس البيانات.

API للقراءة فقط. يدعم التحقق من الرصيد، قائمة الخطط، واستعراض قوائم الوكيل، بينما يتم الدفع والشراء من لوحة التحكم. جميع الاستجابات هي UTF-8 والتواريخ بتنسيق ISO 8601 UTC.

كيف يمكن إنشاء وإرسال مفتاح API؟

قم بإنشاء مفتاح API في شاشة مفاتيح API في لوحة التحكم. المفتاح يبدأ بـ spx_ ويتكون من 44 حرفًا، وسيظهر مرة واحدة فقط عند الإنشاء. يتم تخزين بصمة المفتاح (hash) فقط على الخادم، لذا إذا فقدته، يمكنك إنشاء مفتاح جديد، وسيتم تعطيل المفتاح القديم على الفور.

أضف مفتاح API باستخدام طريقة Bearer في رأس Authorization لكل طلب. لا نقبل إضافة المفتاح في استعلام العنوان. إذا كان المفتاح مفقودًا أو خاطئًا، سيتم الرد بـ 401 unauthorized.

curl -H "Authorization: Bearer spx_your_api_key" https://socks5proxy.io/api/v1/account

استعلام عن الرصيد ومعلومات الحساب: GET /account

يتم إرجاع رمز الحساب، الرصيد، عدد الخطط المستخدمة، وعدد البروكسي. الرصيد حتى منزلتين عشريتين (USD).

curl -H "Authorization: Bearer spx_your_api_key" https://socks5proxy.io/api/v1/account

{
  "code": "S5-7KQ2-M8PX-4HDA",
  "balance": "125.40",
  "currency": "USD",
  "active_plans": 2,
  "proxies": 125,
  "created_at": "2026-10-22T08:15:02.114Z"
}

استعلام قائمة الخطط: GET /plans

تُرجع الخطط المشتراة من الأحدث إلى الأقدم. الحالة تكون إما active (قيد الاستخدام)، expired (انتهت المدة)، أو canceled (ملغاة). المعرف هو كود الخطة (يبدأ بـ P-) ويمكن استخدامه كقيمة plan في /proxies.

{
  "plans": [
    {
      "id": "P-8WQ4C-NM2KT",
      "product": "dc-private",
      "product_name": "Private Datacenter Proxy",
      "ips": 100,
      "months": 1,
      "country": "us",
      "status": "active",
      "amount": "49.40",
      "created_at": "2026-10-22T08:20:11.002Z",
      "expires_at": "2026-11-22T08:20:11.002Z"
    }
  ]
}

استعلام قائمة البروكسي: GET /proxies

تُرجع الوكيل المستخدم في الخطة الحالية بتنسيق JSON. يتضمن كل وكيل العنوان، منفذ HTTP، منفذ SOCKS5، اسم المستخدم، كلمة المرور، الدولة، المدينة، رمز الخطة، ووقت الانتهاء.

يمكن التصفية باستخدام country (رمز الدولة المكون من حرفين) وplan (رمز الخطة). يتم عرض البروتوكول في الاستجابة.

curl -H "Authorization: Bearer spx_your_api_key" \
  "https://socks5proxy.io/api/v1/proxies?country=us&protocol=socks5"

{
  "count": 1,
  "protocol": "socks5",
  "proxies": [
    {
      "host": "198.51.100.23",
      "http_port": 8231,
      "socks5_port": 1080,
      "username": "spx_k2m8qa",
      "password": "q7rbx2wd9n",
      "country": "us",
      "city": "New York",
      "plan": "P-8WQ4C-NM2KT",
      "product": "dc-private",
      "product_name": "Private Datacenter Proxy",
      "expires_at": "2026-11-22T08:20:11.002Z"
    }
  ]
}

تنزيل القائمة: GET /proxies/download

تُرجع القائمة بروكسي واحدًا في كل سطر لتسهيل القراءة المباشرة من البرامج. إذا كان البروتوكول socks5، يتم تضمين منفذ SOCKS5، وإذا كان http، يتم تضمين منفذ HTTP. format=url يضيف بادئة العنوان المناسبة للبروتوكول (socks5:// أو http://).

على الخوادم التي تم تمكين تفويض IP المسموح به، يمكنك الاتصال مباشرة بتنسيق ip:port دون اسم مستخدم. يحتوي ملف csv على أسماء الأعمدة في السطر الأول ويشمل كلا المنفذين.

curl -H "Authorization: Bearer spx_your_api_key" \
  "https://socks5proxy.io/api/v1/proxies/download?format=url&protocol=socks5" -o proxies.txt

أمثلة التعليمات البرمجية: Python، Node.js، PHP

في المثال التالي، يتم استلام القائمة وإرسال الطلب إلى البروكسي الأول. لاستخدام SOCKS5 في Python، تحتاج إلى حزمة requests[socks]. إذا كنت تستخدم socks5h، فسيتم أيضًا حل اسم النطاق من جانب البروكسي.

import requests

API = "https://socks5proxy.io/api/v1"
H = {"Authorization": "Bearer spx_your_api_key"}

proxies = requests.get(f"{API}/proxies", headers=H, params={"country": "us"}).json()["proxies"]
p = proxies[0]
url = f"socks5h://{p['username']}:{p['password']}@{p['host']}:{p['socks5_port']}"
r = requests.get("https://api.ipify.org?format=json", proxies={"http": url, "https": url}, timeout=30)
print(r.json())

import { ProxyAgent, fetch } from "undici";

const API = "https://socks5proxy.io/api/v1";
const H = { Authorization: "Bearer spx_your_api_key" };

const { proxies } = await (await fetch(`${API}/proxies?country=us`, { headers: H })).json();
const p = proxies[0];
const agent = new ProxyAgent(`http://${p.username}:${p.password}@${p.host}:${p.http_port}`);
const r = await fetch("https://api.ipify.org?format=json", { dispatcher: agent });
console.log(await r.json());

<?php
$ch = curl_init("https://socks5proxy.io/api/v1/proxies/download?format=ip:port:user:pass&protocol=http");
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spx_your_api_key"],
  CURLOPT_RETURNTRANSFER => true,
]);
$lines = explode("\n", trim(curl_exec($ch)));
[$host, $port, $user, $pass] = explode(":", $lines[0]);
echo "$host:$port\n";

رموز الأخطاء وحدود الاستدعاء

يتم إرجاع الأخطاء برمز حالة HTTP وبصيغة { "error": { "code", "message" } }. يمكنك استدعاء كل مفتاح حتى 300 مرة في الدقيقة، وإذا تجاوزت ذلك، ستتلقى ردًا 429 لمدة دقيقة. نظرًا لأن القوائم تتغير فقط عند الشراء أو الانتهاء، نوصي بجلبها كل بضع دقائق وإعادة استخدامها داخل البرنامج.

استدعاءات API لا تكلف شيئًا. يتم خصم المبلغ من الرصيد فقط عند شراء الخطط من لوحة التحكم.