بداية سريعة

1. أنشئ مفتاح 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 $2}')
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 $2}')

curl https://www.kernelhost.com/cp/kh_reseller_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. عند إعادة المحاولة الشبكية بنفس المفتاح تستعيد نفس الاستجابة، دون طلبية مكررة.

BODY='{"product_id":42,"billing_cycle":"monthly"}'
BODY_SHA256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
IDEM=$(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 $2}')

curl -X POST https://www.kernelhost.com/cp/kh_reseller_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. إعداد Webhook (اختياري)

سجّل عنوان URL بـ HTTPS لكل مفتاح API لتلقي الأحداث بشكل غير متزامن (order.paid، service.provisioned، invoice.created). يتبع توقيع الحمولة نظام Stripe.