واجهة API للعملاء · V1 تجريبية
واجهة REST API
لخوادم VPS والخوادم المخصصة
أدِر خوادمك من خلال الكود: اطلب خوادم VPS بالساعة واحذفها، ونفّذ إجراءات التشغيل والإيقاف وإعادة التثبيت، والتقط صورك الخاصة وانشر منها، وسدّد الفواتير من الرصيد.
تتيح واجهة API للعملاء من X-ZoneServers (v1، نسخة تجريبية عامة) تنفيذ 92 عملية عبر HTTPS، مع مواصفة OpenAPI 3.0 ومفاتيح API محدّدة الصلاحيات وحدّ افتراضي قدره 1,000 طلب في الساعة لكل مفتاح. وهي مشمولة مع كل حساب دون أي تكلفة إضافية.
92 عملية API1,000 طلب في الساعة لكل مفتاح
طلبك الأول
أنشئ مفتاحًا في لوحة تحكم العميل من Profile → API Keys، ثم اسأل API عن هويتك.
curl https://my.x-zoneservers.com/api/v1/ \
-H "Authorization: Bearer $XZ_API_KEY"
{ "success": true,
"data": {
"version": "1",
"key": { "scopes": ["read", "services"] },
"rate_limit": { "limit": 1000, "remaining": 999 }
} }01الميزات
ما يمكنك أتمتته
تغطي واجهة API دورة حياة الخادم بالكامل، من الطلب حتى الفاتورة، وبالصلاحيات نفسها المتاحة في لوحة تحكم العميل.
النشر والحذف
اطلب خادم VPS بفوترة بالساعة أو شهرية، ومرّر user-data الخاص بـ cloud-init ومفاتيح SSH للإقلاع الأول، ثم احذفه عند انتهاء المهمة. تتوقف الفوترة بالساعة لحظة زوال الخادم.
الطاقة وإعادة التثبيت والإحصاءات
شغّل خادم VPS الخاص بك وأوقفه وأعد تشغيله وأعد تثبيته، وأعد تعيين كلمات مرور root، واقرأ إحصاءات الاستخدام وحركة البيانات من نصوص المراقبة البرمجية الخاصة بك.
الصور المخصصة
التقط صورة من خادم VPS (حتى 3 صور لكل حساب)، أو سجّل صورتك الخاصة بصيغة qcow2 أو raw (يُتحقَّق منها عبر SHA-256) وانشر منها خوادم جديدة.
الفوترة والاستخدام
اطّلع على رصيدك ورسوم الساعات لهذا الشهر، واعرض قائمة الفواتير والفواتير المبدئية وسدّدها من الرصيد — وهذا مفيد للوحات متابعة التكاليف وتنبيهات الميزانية.
الإضافات والترقيات
اشترِ إضافات لخدمة قائمة، مثل عناوين IP إضافية، أو انقلها إلى خطة أكبر دون فتح لوحة التحكم.
المشاريع والمفاتيح محدّدة الصلاحيات
جمّع الخوادم في مشاريع وأصدِر مفاتيح مرتبطة بمشروع واحد، فلا يستطيع مفتاح بيئة staging أبدًا رؤية بيئة الإنتاج أو المساس بها.
02كيف يعمل
مثال: VPS بالساعة لمهمة CI واحدة
أنشئ جهاز بناء نظيفًا، وشغّل خط الأنابيب، ثم احذفه — وادفع مقابل الساعات التي وُجد فيها.
تُحتسب رسوم الخدمات بالساعة من رصيد حسابك بدلًا من إصدار فواتير لها، لذا احرص على إبقاء رصيد في الحساب. أرسل ترويسة Idempotency-Key مع كل طلب شراء: فإذا انتهت مهلة أحد الطلبات أمكن إعادة محاولته دون إنشاء خادم ثانٍ.
1. اختر خطة: اعرض قائمة المنتجات بأسعارها بالساعة والشهرية.
curl https://my.x-zoneservers.com/api/v1/products \
-H "Authorization: Bearer $XZ_API_KEY"2. اطلبه بالفوترة بالساعة، مع نص برمجي للإقلاع الأول ومفتاح SSH الخاص بك.
curl -X POST https://my.x-zoneservers.com/api/v1/orders \
-H "Authorization: Bearer $XZ_API_KEY" \
-H "Idempotency-Key: ci-run-4812" \
-H "Content-Type: application/json" \
-d '{"productId": "<plan-id>", "billingCycle": "hourly",
"hostname": "ci-4812.example.com", "location": "<location>",
"configOptions": {"os_image_id": "<image-id>",
"ssh_keys": ["ssh-ed25519 AAAA... ci@runner"],
"user_data": "#!/bin/sh\n/opt/ci/run-pipeline.sh"}}'3. عند انتهاء المهمة، احذف الخادم. تتوقف الفوترة فورًا.
curl -X DELETE https://my.x-zoneservers.com/api/v1/vps/<vps-id> \
-H "Authorization: Bearer $XZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"immediate": true}'03API
مصممة للنصوص البرمجية ووكلاء الذكاء الاصطناعي
حين يكون من يضغط الأزرار برنامجًا لا إنسانًا، يصبح السلوك المتوقَّع أهم من عدد نقاط النهاية.
مفاتيح محدّدة الصلاحيات
لا يحمل كل مفتاح إلا الصلاحيات التي تمنحها — read, services, orders, billing, destructive — إضافةً إلى قائمة اختيارية بعناوين IP المسموح بها وتاريخ لانتهاء الصلاحية.
حدود معدل طلبات معلنة
افتراضيًا 1,000 طلب في الساعة لكل مفتاح، مع الإبلاغ عن الحد في ترويسات X-RateLimit، وفترات انتظار قصيرة لكل خادم بعد إجراءات التشغيل والإيقاف وإعادة التثبيت.
إعادة محاولة آمنة
تقبل طلبات الشراء ترويسة Idempotency-Key، وكل رفض يعيد رمز خطأ قابلًا للقراءة آليًا، فتستطيع الأتمتة التمييز بين إخفاق يمكن إعادة محاولته وإخفاق حقيقي.
توثيق قابل للقراءة آليًا
مواصفة OpenAPI 3.0 لأدوات توليد مكتبات العملاء، ودليل بصيغة Markdown بسيطة يستطيع مساعدو البرمجة ووكلاء الذكاء الاصطناعي قراءته مباشرة.
04ذو صلة
هل تبيع الخوادم لعملائك؟
تؤتمت واجهة API للعملاء هذه حسابك أنت. ولإعادة البيع تحت علامتك التجارية الخاصة، انضم إلى برنامج إعادة البيع واستخدم بدلًا منها واجهة API لإعادة البيع: أسعار جملة بشرائح حسب الحجم، وطلبات موقّعة بـ HMAC، وwebhooks، ومفاتيح مرتبطة بالعملاء، وروابط وحدة تحكم (console) يفتحها عملاؤك دون حساب لدينا.
05أسئلة
الأسئلة الشائعة حول API
أسئلة شائعة حول أتمتة X-ZoneServers.
هل لدى X-ZoneServers واجهة API؟
نعم. واجهة API للعملاء (v1) هي REST API عبر HTTPS على العنوان https://my.x-zoneservers.com/api/v1 وتضم 92 عملية تغطي خوادم VPS والخوادم المخصصة والطلبات والإضافات والترقيات والفواتير ومفاتيح SSH والصور المخصصة. وهي في مرحلة تجريبية عامة: مستقرة بما يكفي للبناء عليها، لكن نقاط النهاية وبُنى الاستجابات قد تتغير.
هل الوصول إلى API مجاني؟
نعم. الوصول إلى API مشمول مع كل حساب دون أي تكلفة إضافية؛ وتدفع فقط مقابل الخوادم والإضافات التي تطلبها، بالأسعار نفسها المعروضة على الموقع وفي لوحة تحكم العميل.
هل يمكنني إنشاء خوادم VPS بالساعة وحذفها عبر API؟
نعم. قدّم طلب شراء مع ضبط دورة الفوترة على الساعة، مع user-data لـ cloud-init ومفاتيح SSH اختياريًا، ثم احذف الـ VPS حين لا تعود بحاجة إليه. تُحتسب الخدمات بالساعة من رصيد الحساب وتتوقف فوترتها فور حذفها.
هل تعمل واجهة API مع الخوادم المخصصة؟
جزئيًا. بالنسبة إلى الخوادم المخصصة، تغطي واجهة API الطلب والإضافات والفواتير وتفاصيل الخدمة. أما التحكم في التشغيل والإيقاف وإعادة تثبيت نظام التشغيل وإعادة تعيين كلمات المرور فغير متاحة للخوادم المخصصة عبر API ولا عبر لوحة تحكم العميل.
كيف تتم المصادقة؟
أنشئ مفتاح API في لوحة تحكم العميل من Profile → API Keys وأرسله كرمز Bearer. اختر صلاحياته عند إنشائه، ويمكنك اختياريًا تقييده بعناوين IP محددة أو تحديد تاريخ لانتهاء صلاحيته. تُعرض المفاتيح مرة واحدة فقط ويمكن إلغاؤها في أي وقت من لوحة التحكم.
هل توجد مواصفة OpenAPI أو Swagger؟
نعم. المواصفة الكاملة لـ OpenAPI 3.0 منشورة على https://my.x-zoneservers.com/api/v1/openapi.json إلى جانب التوثيق المعروض ودليل استخدام بصيغة Markdown.
ابدأ
أنشئ أول مفتاح API لك
سجّل الدخول إلى لوحة تحكم العميل، وافتح Profile → API Keys، ونفّذ أول طلب لك في أقل من دقيقة. تصل أسئلة API مباشرةً إلى الأشخاص الذين يبنون المنصة.