بداية سريعة

1. أنشئ مفتاح API

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

2. احفظ بيانات الاعتماد

احفظ مفتاح API والسر كمتغيرات بيئة. لا تضعهما في الشيفرة، ولا في أي مستودع.

# ملف .env أو ملف تعريف الصدفة
export KH_KEY="kh_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
export KH_SECRET="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. أرسل طلبك الأول

اسرد المنتجات المتاحة. يُبنى التوقيع على الطريقة، المسار، الطابع الزمني، الـ Nonce، وتجزئة الجسم.

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

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

4. أنشئ طلبية

مهم: يتطلب POST /v1/orders ترويسة Idempotency-Key واسم مضيف. وإذا أعدت إرسال الطلب بعد خطأ في الشبكة بقيمة Idempotency-Key نفسها، فستتلقى الاستجابة ذاتها بدلًا من طلبية ثانية. أما خيارات التكوين التي لا تحددها (مثل الموقع أو نظام التشغيل) فتأخذ أول قيمة معروضة في المتجر.

BODY='{"product_id":42,"billing_cycle":"monthly","hostname":"web01.example.com"}'
IDEM="order-web01-$(date +%Y%m%d)"
BODY_SHA256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
SIG_INPUT=$(printf 'POST\n/v1/orders\n%s\n%s\n%s' "$TS" "$NONCE" "$BODY_SHA256")
SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $NF}')

curl -X POST https://www.kernelhost.com/cp/kernelhost_api/v1/orders \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  --data "$BODY"

5. تحقّق من الحالة واجلب بيانات الاعتماد

تُدرج استجابة الطلبية معرّفات الخدمات في الحقل service_ids. كرّر الاستعلام عبر GET /v1/services/{id} إلى أن تصبح قيمة status هي active ويُعيَّن عنوان IP؛ ويستغرق الإعداد عادةً ما بين بضع ثوانٍ وبضع دقائق. بعد ذلك يُعيد GET /v1/services/{id}/credentials (يتطلب النطاق read:credentials) اسم المضيف وعناوين IP واسم المستخدم وكلمة المرور، لتستخدمها مثلًا في قائمة المضيفين (inventory) لديك في Ansible.

kh_get() {
  TS=$(date +%s)
  NONCE=$(openssl rand -hex 16)
  BODY_SHA256=$(printf '' | openssl dgst -sha256 -hex | awk '{print $NF}')
  SIG_INPUT=$(printf 'GET\n%s\n%s\n%s\n%s' "$1" "$TS" "$NONCE" "$BODY_SHA256")
  SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $NF}')
  curl -s "https://www.kernelhost.com/cp/kernelhost_api$1" \
    -H "KH-Key: $KH_KEY" \
    -H "KH-Timestamp: $TS" \
    -H "KH-Nonce: $NONCE" \
    -H "KH-Signature: $SIG"
}

kh_get /v1/services/1234
kh_get /v1/services/1234/credentials

6. احفظ عنوان Webhook (اختياري)

يمكنك منذ الآن حفظ عنوان URL بصيغة HTTPS لكل مفتاح. أما إرسال الأحداث فهو قيد التحضير؛ وحتى ذلك الحين، استخدم استعلامات الحالة الواردة في الخطوة 5.