انتقل إلى المحتوى
royalproxy
ابدأ الآن

توثيق API للبروكسي

استخدم REST API من RoyalProxy لقراءة رصيدك وبيانات الاتصال، ومعرفة الأسعار، وإنشاء الطلبات من رصيدك، وتكوين أسماء مستخدمي البروكسي من الكود الخاص بك.

أنشئ مفتاح APIعرض نقاط الاتصال

كيف أبدأ؟

  1. 1أنشئ حسابًا وسجّل الدخول إلى لوحة التحكم.
  2. 2افتح Connect وأنشئ مفتاح API. يظهر المفتاح كاملًا مرة واحدة فقط، لذا انسخه إلى مكان آمن.
  3. 3أرسل المفتاح في ترويسة Authorization مع كل طلب يحتاج إليه.
  4. 4استدعِ /account للتأكد من أن المفتاح يعمل، ثم أنشئ الطلبات عبر /orders.

كيف تعمل المصادقة؟

الطلبات الخاصة بحسابك (account وorders وproxy-user) تحتاج إلى مفتاح API. أرسله كرمز Bearer في ترويسة Authorization. الأسعار والدول وحساب الأسعار عامة ولا تحتاج إلى مفتاح.

نحفظ فقط قيمة hash للمفتاح. إذا فقدته، أنشئ مفتاحًا جديدًا في لوحة التحكم ويتوقف المفتاح القديم عن العمل فورًا. لا تضع المفتاح في كود المتصفح أو في المستودعات العامة.

HTTP header
Authorization: Bearer rpk_your_api_key

الرابط الأساسي والتنسيق

عنوان URL الأساسي
https://royalproxy.online/api/v1
محتوى الطلب والاستجابة
application/json
المبالغ
أرقام بالدولار الأمريكي (USD)، مثل 807.90
الوقت
ISO 8601 (UTC)

هل هناك حد لعدد الطلبات؟

يمكن لكل مفتاح API إرسال 60 طلب في الدقيقة كحد أقصى. نقاط الاتصال العامة تسمح بـ 60 طلب في الدقيقة لكل IP. عند تجاوز الحد تحصل على HTTP 429، فانتظر دقيقة وحاول مرة أخرى.

كيف تبدو الأخطاء؟

تستخدم الأخطاء رمز حالة HTTP ومحتوى JSON فيه رمز قصير ورسالة.

مثال
{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance is too low for this order. Top up in the dashboard."
  }
}
code
bad_requestHTTP 400قيمة ناقصة أو غير مسموح بها لهذا المنتج.
unauthorizedHTTP 401مفتاح API غير موجود أو غير صالح.
insufficient_balanceHTTP 402الرصيد أقل من إجمالي الطلب. لم يُخصم أي مبلغ.
not_foundHTTP 404لا يوجد طلب بهذا المعرّف في حسابك.
rate_limitedHTTP 429طلبات كثيرة جدًا في دقيقة واحدة.
server_errorHTTP 500تعذّر إكمال الطلب. لم يُخصم أي مبلغ.

نقاط الاتصال

بيانات الحساب

GET/api/v1/accountمفتاح API

يعيد رصيدك ومضيف البروكسي والمنافذ واسم المستخدم وكلمة المرور وعناوين IP المسموح بها.

الطلب
curl https://royalproxy.online/api/v1/account \
  -H "Authorization: Bearer rpk_your_api_key"
الاستجابة
{
  "username": "royal_user",
  "balance_usd": 1300,
  "proxy": {
    "host": "gate.royalproxy.online",
    "http_port": 6100,
    "socks5_port": 6200,
    "username": "rpexample1",
    "password": "your_password"
  },
  "allowed_ips": [
    "203.0.113.10"
  ]
}

قائمة المنتجات والأسعار

GET/api/v1/productsلا يحتاج إلى مفتاح

يعيد كل منتج مع حدوده ودرجات أسعاره وخصوماته. الأسعار مأخوذة من الجدول نفسه المستخدم في صفحة الأسعار.

الطلب
curl https://royalproxy.online/api/v1/products
الاستجابة
{
  "currency": "USD",
  "prices_as_of": "2026-10-31",
  "products": [
    {
      "id": "unlimited",
      "unit": "day",
      "quantity": {
        "meaning": "days",
        "min": 1,
        "max": 365
      },
      "...": "..."
    },
    {
      "id": "residential",
      "unit": "gb",
      "...": "..."
    }
  ]
}

قائمة الدول والمدن

GET/api/v1/countriesلا يحتاج إلى مفتاح

يعيد الدول المتاحة لمنتج معين، مع قيم المدن التي يمكنك وضعها في اسم مستخدم البروكسي.

الحقلالمعنى
productاختياريunlimited أو residential أو isp أو datacenter. الافتراضي residential.
الطلب
curl "https://royalproxy.online/api/v1/countries?product=datacenter"
الاستجابة
{
  "product": "datacenter",
  "countries": [
    {
      "code": "us",
      "name": "United States",
      "region": "americas",
      "datacenter": true,
      "cities": [
        {
          "name": "New York",
          "value": "new_york"
        },
        {
          "name": "Los Angeles",
          "value": "los_angeles"
        }
      ]
    }
  ]
}

حساب سعر الطلب

POST/api/v1/quoteلا يحتاج إلى مفتاح

يحسب إجمالي الطلب دون خصم أي مبلغ. استخدم المحتوى نفسه المستخدم عند إنشاء الطلب.

الحقلالمعنى
productمطلوبunlimited أو residential أو isp أو datacenter.
quantityمطلوبالأيام لـ unlimited (1~365)، وGB لـ residential (5~5,000)، وعدد عناوين IP لـ isp (1~1,000) أو datacenter (5~5,000).
concurrencyاختياريلـ unlimited فقط: 200 أو 500 أو 1000 أو 2000.
bandwidthاختياريلـ unlimited فقط، بوحدة Mbps: 100 أو 200 أو 500 أو 1000.
monthsاختياريلـ isp وdatacenter فقط: 1 أو 3 أو 6 أو 12.
countryاختياريلـ isp وdatacenter فقط: رمز الدولة من حرفين، مثل jp. راجع /countries.
الطلب
curl -X POST https://royalproxy.online/api/v1/quote \
  -H "Content-Type: application/json" \
  -d '{"product":"unlimited","quantity":30,"concurrency":1000,"bandwidth":200}'
الاستجابة
{
  "product": "unlimited",
  "quantity": 30,
  "unit_price_usd": 8.97,
  "unit": "day",
  "total_usd": 269.1
}

تنفيذ طلب

POST/api/v1/ordersمفتاح API

يخصم الإجمالي من رصيدك وينشئ الطلب. تبدأ الطلبات الجديدة بحالة pending (قيد التفعيل) وتتحول إلى active عندما تصبح جاهزة. إذا تعذّر تفعيل الطلب يصبح refunded ويعود المبلغ كاملًا إلى رصيدك. يعيد 402 عندما يكون الرصيد غير كافٍ.

الحقلالمعنى
productمطلوبunlimited أو residential أو isp أو datacenter.
quantityمطلوبالأيام لـ unlimited (1~365)، وGB لـ residential (5~5,000)، وعدد عناوين IP لـ isp (1~1,000) أو datacenter (5~5,000).
concurrencyاختياريلـ unlimited فقط: 200 أو 500 أو 1000 أو 2000.
bandwidthاختياريلـ unlimited فقط، بوحدة Mbps: 100 أو 200 أو 500 أو 1000.
monthsاختياريلـ isp وdatacenter فقط: 1 أو 3 أو 6 أو 12.
countryاختياريلـ isp وdatacenter فقط: رمز الدولة من حرفين، مثل jp. راجع /countries.
الطلب
curl -X POST https://royalproxy.online/api/v1/orders \
  -H "Authorization: Bearer rpk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"product":"unlimited","quantity":30,"concurrency":1000,"bandwidth":200}'
الاستجابة
{
  "order": {
    "id": "RP-7KQ2M-X4HTD",
    "product": "unlimited",
    "quantity": 30,
    "months": null,
    "concurrency": 1000,
    "bandwidth_mbps": 200,
    "country": null,
    "unit_price_usd": 8.97,
    "total_usd": 269.1,
    "status": "pending",
    "created_at": "2026-10-31T09:12:44.120Z",
    "updated_at": "2026-10-31T09:12:44.120Z"
  },
  "balance_usd": 1030.9
}

قائمة طلباتك

GET/api/v1/ordersمفتاح API

يعيد آخر 100 طلب، الأحدث أولًا.

الحقلالمعنى
statusاختياريpending أو active أو refunded. اتركه فارغًا للحصول على الكل.
الطلب
curl "https://royalproxy.online/api/v1/orders?status=pending" \
  -H "Authorization: Bearer rpk_your_api_key"
الاستجابة
{
  "orders": [
    {
      "id": "RP-7KQ2M-X4HTD",
      "product": "unlimited",
      "quantity": 30,
      "months": null,
      "concurrency": 1000,
      "bandwidth_mbps": 200,
      "country": null,
      "unit_price_usd": 8.97,
      "total_usd": 269.1,
      "status": "pending",
      "created_at": "2026-10-31T09:12:44.120Z",
      "updated_at": "2026-10-31T09:12:44.120Z"
    }
  ]
}

طلب واحد

GET/api/v1/orders/{id}مفتاح API

يعيد طلبًا واحدًا حسب معرّفه، مثلًا للتحقق مما إذا كان مفعّلًا.

الحقلالمعنى
idمطلوبمعرّف الطلب، مثل RP-7KQ2M-X4HTD.
الطلب
curl https://royalproxy.online/api/v1/orders/RP-7KQ2M-X4HTD \
  -H "Authorization: Bearer rpk_your_api_key"
الاستجابة
{
  "order": {
    "id": "RP-7KQ2M-X4HTD",
    "product": "unlimited",
    "quantity": 30,
    "months": null,
    "concurrency": 1000,
    "bandwidth_mbps": 200,
    "country": null,
    "unit_price_usd": 8.97,
    "total_usd": 269.1,
    "status": "active",
    "created_at": "2026-10-31T09:12:44.120Z",
    "updated_at": "2026-10-31T09:40:02.511Z"
  }
}

تكوين اسم مستخدم البروكسي

GET/api/v1/proxy-userمفتاح API

يعيد اسم مستخدم بروكسي بخياراتك مع روابط بروكسي HTTP وSOCKS5 جاهزة. دون session يتغيّر IP مع كل طلب.

الحقلالمعنى
productاختياريunlimited أو residential أو isp أو datacenter. الافتراضي unlimited.
countryاختياريرمز الدولة من حرفين، مثل jp.
cityاختياريقيمة المدينة من /countries، مثل tokyo. تتطلب country.
sessionاختياريمن 1 إلى 32 حرفًا أو رقمًا. الطلبات التي تحمل session نفسها تحتفظ بنفس IP.
ttlاختياريعدد دقائق الاحتفاظ بعنوان IP الجلسة، 1~60. الافتراضي 30.
الطلب
curl "https://royalproxy.online/api/v1/proxy-user?product=residential&country=jp&city=tokyo&session=job42&ttl=30" \
  -H "Authorization: Bearer rpk_your_api_key"
الاستجابة
{
  "username": "rpexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30",
  "password": "your_password",
  "http": "http://rpexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30:your_password@gate.royalproxy.online:6100",
  "socks5": "socks5h://rpexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30:your_password@gate.royalproxy.online:6200"
}

أمثلة كاملة

تحسب هذه الأمثلة السعر، وتطلب من الرصيد، وتتصل عبر IP ياباني.

Python (requests)
import requests

API = "https://royalproxy.online/api/v1"
HEAD = {"Authorization": "Bearer rpk_your_api_key"}

# 1) Check the price first
plan = {"product": "residential", "quantity": 100}
print(requests.post(f"{API}/quote", json=plan).json())

# 2) Order from your balance
r = requests.post(f"{API}/orders", json=plan, headers=HEAD)
order = r.json()["order"]
print(order["id"], order["status"])

# 3) Get a username for Japanese IPs
u = requests.get(f"{API}/proxy-user", headers=HEAD,
                 params={"product": "residential", "country": "jp"}).json()
proxies = {"http": u["http"], "https": u["http"]}
print(requests.get("https://ipinfo.io/json", proxies=proxies, timeout=30).json())
Node.js 18+
const API = "https://royalproxy.online/api/v1";
const HEAD = { Authorization: "Bearer rpk_your_api_key", "Content-Type": "application/json" };

// Check the balance
const acc = await fetch(`${API}/account`, { headers: HEAD }).then((r) => r.json());
console.log(acc.balance_usd);

// Order 7 days of unlimited
const res = await fetch(`${API}/orders`, {
  method: "POST",
  headers: HEAD,
  body: JSON.stringify({ product: "unlimited", quantity: 7, concurrency: 500, bandwidth: 100 }),
});
if (res.status === 402) console.log("Top up first");
else console.log((await res.json()).order.id);

الطلبات المنشأة عبر API مثل الطلبات من لوحة التحكم وتظهر في History. ضع مفتاحك مكان rpk_your_api_key.

اربط RoyalProxy بنظامك الخاص

أنشئ حسابًا، ثم أنشئ مفتاح API في لوحة التحكم.

إنشاء حسابدليل الإعداد