Zenix API

Temel adres

https://api.zenix.net.tr/v1

Tüm uçlar bu adrese göredir. Düz HTTP istekleri reddedilir.

Kimlik doğrulama

Anahtarları hesap sahibi müşteri panelindeki API anahtarları bölümünden, şifresi ve iki adımlı doğrulama koduyla onaylayarak oluşturur. Anahtar yalnızca bir kez gösterilir; şifre gibi saklayın ve her istekte gönderin:

Authorization: Bearer zxc_live_...

Anahtarı hiçbir zaman URL'ye koymayın. Geçerli anahtar olmadan gelen istekler 401 alır; aynı adresten tekrarlanan hatalı denemeler sınırlandırılır. Bir anahtar oluşturulduğunda ya da iptal edildiğinde hesap sahibine e-posta gider; hesap sahibi anahtarı istediği an iptal edebilir.

Kapsamlar

Anahtar yalnızca oluşturulduğu kapsamlarla çalışır. Kapsam ve hizmetler değiştirilemez: değiştirmek için anahtarı iptal edip yenisini oluşturun. İzinli IP adresleri müşteri panelinden istediğiniz zaman düzenlenebilir.

Hizmet ve IP kısıtları

Anahtar seçili hizmetlerle sınırlandırılabilir: listeler yalnızca o hizmetleri içerir ve hesap geneli kapsamlar (fatura, destek talebi, BGP) verilemez. Anahtar ayrıca IP adresleri ya da CIDR bloklarıyla sınırlandırılabilir; başka adreslerden gelen istekler 403 ip_not_allowed alır. Anahtarların süresi 30, 90 ya da 365 gün sonra dolabilir ya da süresiz olabilir.

Hız sınırları

Anahtar başına dakikada 120 okuma ve 20 yazma isteği. Bir hesabın tüm anahtarları birlikte dakikada 300 okuma ve 40 yazma isteği. Yanıtlar X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarını taşır; sınır aşılırsa Retry-After ile 429 döner.

Sunucu durumu, özeti ve güç işlemleri diğer müşterilerle ortak bir kapasiteyi de kullanır ve 429 server_rate_limited dönebilir. Durum 10 saniye, sunucu özeti 60 saniye önbelleklenir; daha sık sorgulamak daha güncel veri vermez.

İstekler ve yanıtlar

• Yanıtlar JSON'dur: başarılı yanıtlarda success, data ve meta.request_id; hatalarda success false, error.code, error.message ve gerektiğinde error.details bulunur. Desteğe başvururken request_id değerini iletin.
• Listeler limit (1-100, varsayılan 25) ve offset alır; meta.pagination içinde limit, offset, total ve has_more döner. Bilinmeyen ya da tekrarlanan sorgu parametreleri 422 ile reddedilir.
• Tutarlar ve diğer ondalık değerler metin olarak gelir (örneğin 24.00), hiçbir zaman kayan noktalı sayı olarak değil. Tutarların para birimi ayrı bir alandadır.
• Zamanlar ofsetli ISO 8601 biçimindedir (UTC için Z; randevu saatleri +03:00). Takvim günleri YYYY-MM-DD biçimindedir. Enerji günleri ve ayları UTC'dir.
• Alan adları snake_case'tir. Durum alanlarına v1 içinde yeni değerler eklenebilir; bilinmeyen değerleri tolere edin.

{
  "success": true,
  "data": [ { "id": 123, "product_name": "VDS 4", "status": "active", "recurring_amount": "24.00", "currency": "USD" } ],
  "meta": {
    "request_id": "7f3c9a2e-…",
    "pagination": { "limit": 10, "offset": 0, "total": 1, "has_more": false }
  }
}

Tekrar deneme ve idempotency

Yazma uçları Idempotency-Key başlığını kabul eder (1-64 karakter: harf, rakam, '.', '_', ':' ya da '-'). Aynı anahtarla 24 saat içinde tekrarlanan istek işlemi yinelemez; ilk yanıtı Idempotent-Replayed: true başlığıyla döner. Aynı anahtar farklı bir gövdeyle kullanılırsa 422 idempotency_key_reused döner. Zaman aşımından (504) sonra işlem yine de tamamlanmış olabilir: yeni bir anahtarla değil, aynı anahtarla tekrar deneyin.

Uçlar

Örnekler

İlk on hizmeti listeleme:

curl https://api.zenix.net.tr/v1/services?limit=10 \
  -H "Authorization: Bearer $ZENIX_API_KEY"

Sunucuyu yeniden başlatma (güvenle tekrarlanabilir):

curl -X POST https://api.zenix.net.tr/v1/services/123/server/power \
  -H "Authorization: Bearer $ZENIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: restart-123-20261020" \
  -d '{"action":"restart"}'

Hatalar

Her hatanın değişmeyen, makinece okunabilir bir kodu vardır. Mesajlar sabit İngilizce metindir ve değişebilir; mantığınızı koda dayandırın.

{
  "success": false,
  "error": { "code": "insufficient_scope", "message": "…", "details": { "required_scope": "servers:power" } },
  "meta": { "request_id": "7f3c9a2e-…" }
}

Sürümleme

v1 içinde yeni alanlar ve durum değerleri eklenebilir; tanımadığınız alanları yok sayın. Geriye uyumsuz değişiklikler yeni bir sürüm yolunda yayımlanır.