مرجع API
استخدم عمليات API وفسّر نتائجها
اقرأ النقاط النهائية المتاحة وقواعد العزل واستجابات الإجراءات المصفوفة والحدود الحالية لتتبع العمليات.
في هذه الصفحة
قبل أن تبدأ
- جلسة صالحة، وللتغييرات المحمية، رمز CSRF الخاص بها.
- معرفات مأخوذة من الكتالوج الحالي أو استجابات API الموثقة.
- مفتاح Idempotency-Key فريد لكل طلب أو سحب أو إجراء عتادي.
اقرأ الحساب قبل تغييره
استخدم نقاط نهاية القراءة لتأكيد الحساب والرصيد والمورد المستهدف. يُرجع GET /api/v1/me اسم المستخدم وbalanceUsd ورمز csrfToken الخاص بالجلسة. معرفات الموارد خاصة بالحساب؛ استخدم معرف الخادم أو الشبكة المُعاد للحساب الحالي بدلاً من نسخ قيمة من بيئة أخرى.
API الحالي هو واجهة حساب مدمجة، وليس منصة مهام غير متزامنة كاملة. احفظ المراجع من الكتابات الناجحة في سجلاتك الخاصة. لا يوجد نقطة نهاية لسرد كل طلب، أو فحص إجراء محدد في قائمة الانتظار، أو استرداد أحدث حالة مراجعة للسحب.
| نقطة نهاية القراءة | البيانات المُعادة |
|---|---|
| GET /api/v1/ledger | أحدث إدخالات سجل 100، الأحدث أولاً؛ لا يوجد عقد ترقيم صفحات. |
| GET /api/v1/servers | الخوادم غير المنتهية، الحالة، المنطقة، paidThrough، graceUntil وautoRenew. |
| GET /api/v1/network | العناوين المعينة وأطوال البادئات وقيم PTR ومعرفات الخادم ذات الصلة. |
| GET /api/health | أعداد الخدمة الأساسية والكتالوج؛ لا يوجد ضمان لصحة الحساب أو الخادم الفعلي. |
استخدم نقطة نهاية التغيير المطابقة
إجراءات الخادم المدعومة هي إعادة التشغيل و power_off وإعادة التثبيت و mount_iso و kvm و rotate_root_password. يجب أن يستخدم عنوان URL المخصص لـ ISO بروتوكول HTTPS عامًا بدون بيانات اعتماد مضمّنة. مدة الطلب أسبوعية أو شهرية، تمثل سبعة أو ثلاثين يومًا. يتم فحص السعر والخصومات والأموال والسعة بواسطة الخدمة؛ لا ترسل سعرًا محسوبًا من العميل كمرجع.
| نقطة النهاية | حقول الطلب والنتيجة |
|---|---|
| POST /api/v1/orders | configId وregionId وosId والمدة والكمية؛ اختياري sshPublicKey. يعيد معرف الطلب وACCEPTED. |
| POST /api/v1/deposit-addresses | أصل. يعيد العنوان والأصل والشبكة وconfirmationsRequired والوضع، أو خطأ عدم توفر التسوية. |
| POST /api/v1/withdrawals | الأصل، الوجهة، الدولار الأمريكي. يعيد id وPENDING_REVIEW؛ الرصيد محتجز. |
| POST /api/v1/servers/{id}/actions | إجراء؛ isoUrl لـ mount_iso. يُرجع معرف الإجراء وQUEUED. |
| PUT /api/v1/servers/{id}/ddos | الوضع: BASELINE أو ADVANCED. يُرجع QUEUED أو UNCHANGED و quoteRequired. |
| PUT /api/v1/network/{id}/rdns | ptr، أو قيمة فارغة لمسحها. تُرجع قيمة PTR المخزنة. |
اجعل إعادة المحاولة متعمدة
الطلبات والسحوبات وإجراءات الخادم وطلبات DDoS تتطلب مفتاح Idempotency-Key. استخدم 8–100 أحرفًا وأرقامًا وواصلات أو شرطات سفلية، وخصص مفتاحًا جديدًا لكل عملية مقصودة مميزة. احتفظ بالمفتاح الأصلي والمورد والحمولة قبل الإرسال حتى يمكن التحقيق في استجابة غير مؤكدة.
يمكن للطلبات إعادة النتيجة الحالية لنفس المفتاح والطلب المطبع؛ تفاصيل الطلب المتغيرة تنتج تعارضًا. إعادة إجراءات الخادم تعيد الإجراء الحالي عندما يكون متوافقًا. حافظ على مفاتيح الإجراءات فريدة عبر جميع الخوادم في الحساب. تُبلغ السحوبات عن تعارض عند تسجيلها بالفعل بدلاً من إرجاع الطلب الأصلي كنجاح.
POST /api/v1/servers/{serverId}/actions HTTP/1.1
Content-Type: application/json
x-csrf-token: <current-session-token>
Idempotency-Key: <unique-operation-key>
Cookie: <current-session-cookies>
{"action":"reboot"}ميّز بين القبول والإكمال
استجابة QUEUED من 202 تؤكد تسجيل طلب عتاد. لا تحتوي على رابط KVM يعمل، أو كلمة مرور جذر بديلة، أو إثبات إعادة تشغيل الجهاز. وبالمثل، تسجّل ACCEPTED دخول طلب إلى مرحلة التجهيز؛ وتسجّل PENDING_REVIEW سحبًا بانتظار مراجعة المشغّل. احتفظ بالمعرّف المُعاد عند السؤال عن التنفيذ.
لا يوجد مسار لاستطلاع حالة الإجراء في هذا الإصدار. أعد قراءة بيانات الخادم أو الشبكة عند الاقتضاء، واحصل على تأكيد المشغّل للتأثيرات المادية. تفضيل PTR أو DDoS المخزن وحده ليس قياسًا لنظام DNS العام أو حماية الشبكة المباشرة.
استجب للفشل دون تكرار العمل
- خطأ تحقق من 400: صحّح الحقول الموثقة قبل إعادة الإرسال.
- 401 أو 403: أصلح مصادقة الجلسة أو التحقق من CSRF قبل إعادة المحاولة.
- 404: تحقق من أن معرف المورد ينتمي إلى الحساب المسجل الدخول.
- 409: افحص رمز الخطأ؛ الرصيد غير الكافي، السعة المستنفدة، وتعارضات العجز عن التكرار تتطلب استجابات مختلفة.
- 502 أو 503 على الإيداعات: لم يتم إرجاع عنوان جديد قابل للاستخدام؛ لا تبدأ تحويلاً.
- انتهاء المهلة أو استجابة غير قابلة للقراءة: تحقق من سجلات الحساب المتاحة واحتفظ بتفاصيل الطلب الأصلية. لا تنشئ مفتاح تشغيل جديدًا بشكل أعمى.