واجهة برمجة الموزعين: طلب الاستضافة برمجياً

ما الذي تفعله واجهة برمجة الموزعين

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

كل طلب موقّع بـ HMAC-SHA256، محمي من إعادة الإرسال، يُعالَج بشكل عديم الأثر (إلزامي للطلبات)، مُسجَّل في سجل تدقيق محصّن ضد العبث، ويمكن تأكيده اختيارياً عبر Webhook. تُخصم المدفوعات أولاً من رصيدك، ثم من بطاقتك المحفوظة. لا يمكن إضافة بطاقات جديدة إلا في بوابة العملاء (مع تطبيق 3-D Secure 2).

عنوان URL الأساسي

https://www.kernelhost.com/cp/kh_reseller_api/v1

جدول المحتويات

ما يمكنك فعله

تصفّح المنتجات والأسعار (خوادم KVM الجذرية، الخوادم المخصصة، استضافة الويب، Minecraft، VPN، حركة مرور غير محدودة).
إنشاء الطلبات (يحمي Idempotency-Key من الخصم المزدوج عند إعادة محاولات الشبكة).
سرد خدماتك، فحص الحالة، تنفيذ الإجراءات (تشغيل، إيقاف، إعادة تشغيل، إعادة تثبيت، تعليق، إنهاء).
قراءة بيانات اعتماد خدماتك فقط (نطاق منفصل، مُسجَّل في التدقيق، بريد تأكيد اختياري عند كل وصول).
جلب الفواتير، فحص الرصيد، تنزيل ملفات PDF للفواتير.
تسجيل Webhook لكل مفتاح API لاستقبال أحداث الطلبات والخدمات والفواتير (نظام توقيع متوافق مع Stripe).

تصميم بأقصى درجات الأمان

صُمّمت الواجهة بافتراض أن كل طلب له تأثير مالي مباشر وقد يكشف بيانات اعتماد خوادم حساسة. لذلك فإن خط الأساس الأمني يتجاوز كثيراً المعايير المعتادة في REST.

توقيع HMAC-SHA256 للطلب على الطريقة، المسار، الطابع الزمني، الـ Nonce، وتجزئة الجسم. مقارنة بوقت ثابت.
الحماية من إعادة الإرسال: نافذة طابع زمني ±300 ثانية، ذاكرة Nonce أحادي الاستخدام لمدة 600 ثانية.
يُحفظ السر فقط كنص مُشفّر بـ AES-256-GCM. يوجد النص الصريح بشكل عابر في الذاكرة فقط للتحقق من التوقيع. المفتاح الرئيسي يُحفظ خارج قاعدة البيانات.
نطاقات دقيقة لكل مفتاح API. يجب تفعيل النطاقات الخطرة (read:credentials، write:orders) صراحةً. الإعداد الافتراضي للقراءة فقط.
عزل البيانات على مستوى قاعدة البيانات: كل استعلام يُرشّح بصرامة على معرّف حسابك. الوصول بين المستأجرين مستحيل بحكم التصميم.

مثال: استعلام معلومات حسابك

يُوقَّع الطلب بالكامل بسرّك. لا يغادر السر أبداً ذاكرة العميل؛ ينتقل التوقيع وحده.

TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_SHA256=$(printf '' | openssl dgst -sha256 -hex | awk '{print $2}')
SIG_INPUT=$(printf 'GET\n/v1/me\n%s\n%s\n%s' "$TS" "$NONCE" "$BODY_SHA256")
SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $2}')

curl https://www.kernelhost.com/cp/kh_reseller_api/v1/me \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG"

الأسئلة الشائعة

من يمكنه استخدام واجهة برمجة الموزعين؟

يمكن لأي عميل حالي لدى KernelHost إنشاء مفتاح API من "حسابي ← واجهة برمجة الموزعين" بتسمية ونطاقات وقائمة بيضاء لعناوين IP خاصة به. لا يلزم اتفاق موزّع منفصل: كل منتج مُدرَج علناً متاح عبر الواجهة.

كيف تُدفَع الطلبات؟

الترتيب: الرصيد أولاً، ثم طريقة الدفع المحفوظة (بطاقة ائتمان مع 3-D Secure 2). في حال رفض الدفع أو عدم وجود بطاقة محفوظة، تُعيد الواجهة HTTP 402 "Payment Required" بسبب محدد (insufficient_credit_and_no_card، card_declined، card_expired). يبقى الطلب في حالة "pending payment" لمدة 24 ساعة ثم يُلغى تلقائياً.

هل يمكنني قراءة كلمات مرور الخدمات عبر الواجهة؟

نعم، لكن فقط لخدماتك الخاصة وحصراً بالنطاق الصريح read:credentials، الذي يجب تفعيله عند إنشاء مفتاح API. كل وصول يُنتج إدخالاً في سجل التدقيق باسم credentials.read؛ وعند الطلب يمكنك أيضاً استلام بريد تأكيد على عنوان حسابك، بحيث يكون الإساءة الصامتة مستحيلة.

ماذا يحدث إذا اختُرق سرّي؟

تُدوّر السر بنقرة واحدة في بوابة العملاء. يُلغى السر القديم فوراً، وتُبطَل جميع الجلسات الجارية. عند ملاحظة محاولات مصادقة مشبوهة (5 خلال 10 دقائق) يقفل النظام مفتاح API تلقائياً لمدة 15 دقيقة ويُعلمك بالبريد.

جاهز للبدء؟

أنشئ أول مفتاح API لك في بوابة العملاء تحت "واجهة برمجة الموزعين" واتّبع دليل البداية السريعة.