البدء السريع لـ VPS API: إنشاء مفتاح API وأول خادم

الخطوة 2. المصادقة وأول طلب

تُرسل جميع الطلبات تحت العنوان الأساسي https://helpervps.com/api/v1 مع الترويسة Authorization: Bearer KEY. اجلب قائمة خوادمك كأول طلب. وإذا لم تكن لديك خوادم تعود قائمة فارغة [].

curl -s $HVP/servers -H "Authorization: Bearer $HVP_KEY"

يمكن لكل حساب إرسال ما يصل إلى 300 طلبًا في الدقيقة، وإنشاء الخوادم حتى 10 مرات كل 10 دقائق. وللطلبات المتكررة للتحقق من الحالة يكفي فاصل بضع ثوانٍ. وكل الاستجابات بصيغة JSON، وعند حدوث خطأ تعود مع رمز الحالة بالشكل {"error": "code"}.

الخطوة 3. اختيار المواصفات والمنطقة والصورة

كل القيم التي تضعها عند إنشاء الخادم تأتي من الكتالوج. يُرجع GET /catalog دفعة واحدة المواصفات المعروضة (plans) والمناطق (locations) والصور (images) والخيارات الإضافية (addons). وإذا كان لديك jq يسهل اختيار الأجزاء التي تحتاجها فقط.

curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.plans[] | {code, type, vcpu, ram_mb, disk_gb, monthly}'
curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.locations, .images'

• رمز المواصفات: مثل s1 وs2 يدل على النوع والحجم. وtype هو basic (SSD قياسي) أو fast (NVMe عالي الأداء) أو cpu (CPU مخصص) أو mem (ذاكرة عالية). وmonthly هي الرسوم الشهرية بالدولار الأمريكي.
• رمز المنطقة: اسم المدينة مثل frankfurt وsingapore وseoul.
• رمز الصورة: أنظمة تشغيل مثل ubuntu-24-04 وdebian-13 وalmalinux-10، وتطبيقات مثل app-docker وapp-wordpress.
• الخيارات الإضافية: نسبة النسخ الاحتياطي التلقائي، وأحجام القرص الإضافي ورسومه لكل GB، ورسوم الحماية من DDoS. والخيارات غير المعروضة للبيع تأتي بقيمة null.

إذا لم يكن jq موجودًا فثبّته في Ubuntu عبر apt install -y jq، وفي Mac عبر brew install jq. وهي القائمة نفسها التي تختار منها في الشاشة، فمن المريح الاطلاع معها على الفروق بين المواصفات في صفحة الأسعار.

الخطوة 4. إنشاء الخادم

أرسل الخطة والموقع والصورة والاسم كـ JSON إلى POST /servers. ادفع مقابل الفترة الأولى من الخطة المختارة ويبدأ إنشاء الخادم.

curl -s -X POST $HVP/servers \
  -H "Authorization: Bearer $HVP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"s2","location":"frankfurt","image":"ubuntu-24-04","label":"web-1"}'

عند النجاح تعود معلومات الخادم مع رمز الحالة 201. وقيمة id رمز الخادم بالشكل S-XXXX-XXXX-XXXX، وتستخدم هذا الرمز في كل الطلبات بعدها. وroot_password يأتي مرة واحدة في هذه الاستجابة فاحفظه فورًا. ويمكنك رؤيته أيضًا في صفحة الخادم لمدة 7 أيام.

• label: اسم الخادم. حتى 40 حرفًا من الحروف الإنجليزية والأرقام والنقطة والشرطة، وتُستبدل الحروف الأخرى بشرطة.
• backups: إذا كانت true يُفعَّل النسخ الاحتياطي التلقائي.
• extra_disk_gb: حجم قرص NVMe الكتلي الإضافي. ضع إحدى قيم sizes_gb في الكتالوج (50 أو 100 أو 250 أو 500 أو 1000).
• ddos_protection: إذا كانت true تُفعَّل الحماية من DDoS.

تُضم رسوم الخيارات إلى الرسوم الشهرية للخادم وتظهر في monthly ضمن الاستجابة، وتُجدَّد تلقائيًا بالمبلغ نفسه في كل تاريخ فوترة. ويمكن لكل حساب إنشاء ما يصل إلى 10 خوادم.

الخطوة 5. التحقق من الحالة والاتصال

يبدأ الخادم الجديد بحالة creating، وعند اكتمال التجهيز يصبح running وتُملأ قيمة ipv4. الحلقة أدناه تتحقق من الحالة كل 10 ثوانٍ وتعرض IP عندما تصبح running. واستبدل رمز الخادم برمز خادمك.

ID=S-XXXX-XXXX-XXXX
until [ "$(curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .state)" = "running" ]; do sleep 10; done
curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .ipv4

الحالة هي واحدة من creating أو running أو stopped أو rebooting أو installing أو suspended أو check. suspended تعني أن الخادم تم إيقافه لأنه لم يتم تجديده في تاريخ الفوترة، وcheck تعني أننا نتحقق من نتيجة إعداد الخادم. بمجرد ظهور IP، اتصل عبر ssh root@IP. طريقة الاتصال موجودة في دليل أول تسجيل دخول.

الخطوة 6. التشغيل والتجديد والحذف

curl -s -X POST $HVP/servers/$ID/stop   -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/start  -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/reboot -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/renew  -H "Authorization: Bearer $HVP_KEY"
curl -s -X DELETE $HVP/servers/$ID     -H "Authorization: Bearer $HVP_KEY"

• start: يشغّل الخادم المتوقف (stopped).
• stop وreboot: يوقفان الخادم العامل (running) أو يعيدان تشغيله.
• renew: يدفع الآن لفترة إضافية مدتها 1، 3، 6 أو 12 شهرًا. الخادم المعلق يعود للعمل أيضًا بهذا الطلب.
• DELETE: يحذف الخادم وأقراصه ويُرجع {"state": "deleted"}. ولا تُسترد المدة المتبقية من الشهر المدفوع.

إذا أرسلت عملية لا يمكن تنفيذها في الحالة الحالية يعود 409 wrong_state. مثلًا عند إرسال start إلى خادم يعمل بالفعل. وإعادة التثبيت وإنشاء كلمة مرور root جديدة تتم من صفحة الخادم. والخطوات في دليل إعادة التثبيت.

تنفيذ الخطوات نفسها بـ Python

إذا كتبت التدفق نفسه كسكربت Python يصبح هكذا. يستخدم مكتبة requests (pip install requests).

import os, time, requests

API = "https://helpervps.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['HVP_KEY']}"}

r = requests.post(f"{API}/servers", headers=H, json={
    "plan": "s2", "location": "frankfurt",
    "image": "ubuntu-24-04", "label": "web-1",
})
r.raise_for_status()
server = r.json()
print("id:", server["id"], "root password:", server["root_password"])

while True:
    s = requests.get(f"{API}/servers/{server['id']}", headers=H).json()
    if s["state"] == "running" and s["ipv4"]:
        print("ready:", s["ipv4"])
        break
    time.sleep(10)

رموز الأخطاء الشائعة

• 401 unauthorized: المفتاح مفقود أو خاطئ. تحقق من أن الترويسة بالشكل Authorization: Bearer hvp_....
• 403 not_allowed: تُفتح بعد تأكيد أول دفعة.
• 400 bad_request: اسم الحقل أو قيمته خاطئة. استخدم الرموز كما هي في الكتالوج.
• 402 not_enough_balance: مبلغ الدفع أقل من $25. أرسل مرة أخرى بمبلغ لا يقل عن $25.
• 409 limit: وصلت إلى عدد الخوادم المسموح بإنشائها في الحساب.
• 409 not_created: تعذر إنشاء الخادم، وتذهب الرسوم إلى رصيد حسابك.
• 202 checking: نحن نتحقق من نتيجة إعداد الخادم. لا ترسل نفس الطلب مرة أخرى؛ تحقق من قائمة الخوادم الخاصة بك. سيتم إكمال الخادم أو إعادة الرسوم إلى رصيد حسابك.
• 404 not_found: رمز خادم أو عنوان غير موجود في حسابك.
• 409 wrong_state: عملية لا يمكن تنفيذها في الحالة الحالية.
• 429 rate_limited: وصلت إلى حد الطلبات في الدقيقة. انتظر قليلًا ثم أرسل.

جمعنا كل نقاط النهاية وحقول الاستجابة والأمثلة في توثيق API. وترى ما يمكنك فعله عبر API واستخداماته في صفحة VPS API.