KernelHost API

ما الذي تفعله KernelHost API (Reseller API)

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

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

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

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

• بداية سريعة في 5 دقائق
• المصادقة (HMAC-SHA256)
• مرجع نقاط النهاية
• رموز الأخطاء (RFC 7807)
• حزم SDK وأمثلة برمجية
• الأمان وأفضل الممارسات
• سجل التغييرات

ما يمكنك فعله

• تصفّح المنتجات والأسعار (خوادم KVM الجذرية، الخوادم المخصصة، استضافة الويب، Minecraft، VPN، حركة مرور غير محدودة).
• إنشاء الطلبات (يحمي Idempotency-Key من الخصم المزدوج عند إعادة محاولات الشبكة).
• عرض قائمة بخدماتك الخاصة، والتحقق من حالتها، وتنفيذ الإجراءات: start وstop وreboot، إضافة إلى الإلغاء في نهاية فترة الفوترة والتراجع عن هذا الإلغاء.
• قراءة بيانات اعتماد خدماتك فقط (نطاق منفصل، مُسجَّل في التدقيق، بريد تأكيد اختياري عند كل وصول).
• جلب الفواتير، فحص الرصيد، تنزيل ملفات PDF للفواتير.
• حفظ عنوان Webhook لكل مفتاح API. أما إرسال الأحداث (أحداث الطلبيات والخدمات والفواتير) فهو قيد التحضير؛ وحتى ذلك الحين، استعلم عن الحالة عبر GET /v1/orders/{id} وGET /v1/services/{id}.

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

صُمّمت الواجهة بافتراض أن كل طلب له تأثير مالي مباشر وقد يكشف بيانات اعتماد خوادم حساسة. لذلك فإن خط الأساس الأمني يتجاوز كثيراً المعايير المعتادة في 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/kernelhost_api/v1/me \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG"

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

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

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

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

ترتيب الدفع: رصيدك أولًا، ثم طريقة الدفع المحفوظة لديك. وإذا فشل الدفع أو لم تكن هناك بطاقة محفوظة، تُعيد الواجهة HTTP 402 "Payment Required" مع سبب دقيق (insufficient_credit_and_no_card أو card_declined أو credit_apply_failed) وتُلغي الطلبية فورًا، فلا تبقى أي طلبية غير مدفوعة.

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

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

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

يمكنك تدوير الـ secret بنقرة واحدة في منطقة العملاء، ويصبح الـ secret القديم غير صالح فورًا. تُسجَّل محاولات المصادقة الفاشلة وتُقيَّد لكل عنوان IP مصدر، لكنها لا تقفل مفتاحك أبدًا، فلا يستطيع أحد تعطيل تكاملك لمجرد معرفته بالمعرّف العام لمفتاحك.