Geliştirici Portalı

WHost ile entegrasyon için tek giriş noktası burasıdır. Yapmak istediğinize uyan yolu seçin:

Hızlı Başlangıç

Her WHost API isteği dört HMAC header'ı gerektirir. Aşağıda kanonik payload biçimi ve tek seferlik bir cURL probe'u yer alır — 200 döndüğünde çalışan bir entegrasyon temeliniz olur.

API panelin kendi adresi altında sunulur: https://<panel-adresi>/api/v1/…. Agent'ın kendisi yalnız 127.0.0.1:2000 üzerinde dinler; panelin web sunucusu /api/v1/ isteklerini ona iletir.

1. Kimlik bilgilerini al

Yönetici panelinde:

Ayarlar (üst çubuktaki dişli simgesi) → API Erişimi → API Anahtarı Oluştur

Genel bir entegrasyon için Tam Erişim kapsamını seçin — Sadece Denetim Okuma kapsamlı bir anahtar yalnız /api/v1/audit-logs'a ulaşır. API Anahtarı VE API Gizli Anahtarı'nı hemen kopyalayın — gizli anahtar yalnızca bir kez gösterilir. Tüketen sunucunun sabit bir adresi varsa anahtarı İzin Verilen IP'ler alanıyla (her satıra bir IP veya CIDR) kısıtlayın.

2. v2 HMAC imzasını hesapla

Kanonik payload — her bileşen newline ile ayrılır:

METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY

• METHOD — büyük harfli HTTP fiili (GET, POST, …)
• PATH — istek yolunun gönderildiği hâli, /api/v1/... öneki dahil: URL-decode edilmez; istekte sorgu dizesi varsa ardından ? ve sorgu dizesi gelir (/api/v1/accounts?limit=10)
• TIMESTAMP — geçerli Unix zamanı, saniye cinsinden (string); sunucu saatinden en fazla 300 sn sapabilir
• NONCE — 16–256 karakter, istek başına benzersiz (örnekler 32 hex karakter kullanır); son 11 dakikada görülmüş bir nonce reddedilir
• BODY — isteğin gövde baytlarının kendisi (gövdesiz istekte boş)

X-WHost-Signature, bu payload'ın API gizli anahtarıyla anahtarlanmış HMAC-SHA256 değerini küçük harfli hex olarak taşır.

Beş dilde çalışan imzalayıcılar — her biri GET /api/v1/system/info isteğini imzalar:

3. İlk istek

# Yukarıdaki tablodaki Bash imzalayıcısını kullanarak:
export WHOST_BASE_URL="https://panel.example.com"   # panel adresi
export WHOST_API_KEY="..."
export WHOST_API_SECRET="..."
bash hmac-example.sh
# Beklenen: system/info zarfı — {"status":"success","data":{…}}

İstek reddedilirse yanıt gövdesindeki error_code hangi kontrolün reddettiğini söyler (Bash imzalayıcı curl'ü gövdeyi gizleyen -f ile çalıştırır — PHP, Node.js, Go ve Ruby imzalayıcıları durum kodunu ve gövdeyi yazdırır):

• 401 AUTH_EXPIRED — saat kayması (clock drift): X-WHost-Timestamp sunucu saatinden 300 sn'den fazla uzak. Çağıran host'ta timedatectl status çalıştırın.
• 401 AUTH_FAILED — anahtar, imza veya nonce reddedildi. En yaygın sebepler:
  • Gövde bayt uyumsuzluğu — tam olarak gönderdiğiniz baytları imzalayın; sizin tarafınızda istek gövdesini yeniden sıkıştıran veya yeniden kodlayan bir proxy imzayı bozar.
  • Yanlış PATH — /api/v1 ile başlamalı, büyük/küçük harfi ve varsa yüzde kodlamasını (percent-encoding) korumalı, sorgu dizesi varsa onu da içermelidir.
  • 16 karakterden kısa ya da daha önce kullanılmış bir nonce.
  • İmzanın büyük harfli hex olarak gönderilmesi.
• 403 IP_NOT_ALLOWED — çağıran adres anahtarın İzin Verilen IP'ler listesinde değil.
• 403 SCOPE_DENIED — anahtarın kapsamı bu yolu kapsamıyor.
• 429 AUTH_RATE_LIMITED — tek bir adresten 5 dakika içinde 30 başarısız doğrulama o adresi bir saat engeller.

4. Idempotent hale getir

Her mutasyon yapan çağrı (POST / PUT / PATCH / DELETE) isteğe bağlı bir X-Idempotency-Key header'ı kabul eder — A–Z a–z 0–9 _ - karakterlerinden 8–64 karakter (aksi hâlde 400 IDEMPOTENCY_KEY_INVALID). Mantıksal operasyon başına bir UUID v4 kullanın:

curl -X POST … \
     -H "X-Idempotency-Key: $(uuidgen)" \
     -d '{"username":"alice","password":"<hesap parolası>","domain":"alice.example.com","email":"[email protected]","plan_id":"starter"}' \
     "$WHOST_BASE_URL/api/v1/accounts"

(…, -H "Content-Type: application/json" ile 2. adımdaki dört X-WHost-* header'ının yerini tutar; imza gövde string'inin tam hâli üzerinden hesaplanır.)

24 saat içinde aynı key + aynı body → saklanan yanıt tekrar oynatılır (X-Idempotent-Replay: true). 2xx ve 4xx yanıtlar saklanır; 5xx yanıt saklanmaz, bu yüzden 5xx sonrası tekrar deneme çağrıyı yeniden çalıştırır. Aynı key + farklı metot, yol ya da body → 409 IDEMPOTENCY_KEY_REUSED (çağıran tarafta bug). Anahtar, onu gönderen API anahtarına (ya da oturuma) aittir: aynı anahtarı başka bir kimlik gönderirse yeni istek çalışır ve sizin saklanan yanıtınızı asla almaz.

Tam semantik: api-reference.md → Idempotensi.

5. Yaşam döngüsü olaylarına abone ol

Durum değişiklikleri için polling mi yapıyorsunuz? Yapmayın — bir webhook kaydedin:

curl -X POST … \
     -d '{
       "url": "https://your-system.example.com/whost-hook",
       "events": ["account.created","account.suspended","account.terminated","ssl.failed"],
       "description": "billing platform"
     }' \
     "$WHOST_BASE_URL/api/v1/system/webhooks"

Dönen secret'ı saklayın — gelen payload'ları HMAC ile doğrulamak için kullanılır. Tam abone reçetesi (PHP SDK helper, imza formülü, tekrar deneme semantiği, SSRF korumaları): webhooks.md.

Referans dokümanlar

Yaygın entegrasyon kalıpları

Kalıp A — faturalama platformu sağlama hook'u

WISECP, WHMCS, Blesta ve özel faturalama sistemleri içindir. Plain-PHP referansı: SDK arşivindeki examples/03-billing-integration-pattern.php.

order_activated  → POST   /api/v1/accounts                     (idempotency key: "order-create-$id")
order_suspended  → POST   /api/v1/accounts/{u}/suspend         (key: "order-suspend-$id")
order_resumed    → POST   /api/v1/accounts/{u}/unsuspend       (key: "order-resume-$id")
order_cancelled  → DELETE /api/v1/accounts/{u}                 (key: "order-terminate-$id")
package_changed  → POST   /api/v1/accounts/{u}/change-package  (key: "pkg-change-$changeId")

Idempotensi anahtarları, timeout sonrası ağ tekrar denemelerinin güvenli olması anlamına gelir — aynı mantıksal sipariş iki kez sağlama yapmaz.

Kalıp B — bant dışı (out-of-band) faturalama mutabakatı

account. olaylarına abone olun (her birini adıyla yazın — events filtresi joker karakter değil, tam olay adı alır); bir operatör panelden manuel olarak askıya alma / yeniden etkinleştirme yaptığında faturalama sisteminiz senkron kalır.

account.suspended         → faturalamada siparişi "suspended" olarak işaretle
account.unsuspended       → tekrar "active" duruma çevir
account.terminated        → iptali mutabık kıl
account.package_changed   → fiyatlandırmayı yeniden hesapla
account.password_changed  → yalnızca denetim logu kaydı

Kalıp C — SSL sertifika olayları

ssl.failed   → nöbetçiyi ara + destek bileti aç
ssl.renewed  → açık bileti sustur (varsa)
ssl.issued   → yeni geçerlilik penceresini kaydet (data.extra.valid_to)

Bu olaylar panel ya da API üzerinden yapılan sertifika istek ve yüklemelerinden doğar. certbot'un kendi zamanlamasıyla yaptığı yenilemeler olay göndermez; her otomatik sertifika isteği de olay göndermez (bkz. olay kataloğu). Süre bitimini izlemek için GET /api/v1/accounts/{username}/ssl/{domain} (valid_to) çağrısını poll edin.

Kalıp D — yedek doğrulama

backup.completed → başarı + boyut + zamanlamayı kaydet (data.extra.size_mb)
backup.failed    → nöbetçiyi ara (operatörün sorumluluğu, müşterinin değil)

Arşivi oluşturulmuş ama uzak hedefe yüklemesi başarısız olmuş bir yedek, data.extra.remote_upload_error dolu olarak backup.completed şeklinde gelir.

Kalıp E — metrikler üzerinden kapasite planlama

/api/v1/system/info endpoint'i CPU / bellek / disk kullanımı döndürür. 5 dakikalık aralıkla poll edin (okuma katmanı hız sınırı içinde) ve kendi gözlemlenebilirlik yığınınızda trend takibi yapın; GET /api/v1/system/metrics?period=24h (24h, 7d veya 30d) agent'ın 15 dakikada bir örneklediği geçmişi döndürür. WHost şu anda kendisi Prometheus metrikleri yayımlamaz.

Kararlılık & deprecation

/api/v1/* kararlıdır — bu önek altında bozucu değişiklik yayımlanmaz. Geriye dönük uyumsuz çalışmalar /api/v2/ üzerinden gider ve v1 ile paralel sunulur: v2 duyurusu ile v1'in kaldırılması arasında en az 15 ay geçer (3 aylık beta artı en az 12 aylık deprecation penceresi).

Bu, bugün v1'e karşı yazılmış bir entegrasyonun v1 için duyurulan sunset tarihine kadar değişmeden çalışmaya devam edeceği anlamına gelir. Tam deprecation zaman çizelgesi, header kuralları ve v2 tanıtıldığında Sunset header'larının nasıl görüneceği için versioning-policy.md dosyasını okuyun.

Destek

Bir entegrasyon hatasını raporlarken lütfen şunları ekleyin:

1. Tam istek (header'lar + body, secret'lar maskelenmiş)
2. Tam yanıt (status, header'lar, body)
3. Agent sürümü (GET /api/v1/system/update/status → data.current_version)
4. SDK sürümü, kullanılıyorsa