API belgeleri

sunucu.com.tr API'si ile hizmetlerinizi listeleyebilir, sunucularınızın durumunu görebilir, başlatıp kapatabilir ve faturalarınızı okuyabilirsiniz. Anahtarı Panel > API sayfasından oluşturursunuz.

İçindekiler

Başlarken
Anahtarlar ve yetkiler
Güvenlik önerileri
Yanıt biçimi
Hatalar
Oran sınırları
Sürümleme
Uçlar
Değişiklik günlüğü

Başlarken

Temel adres: https://sunucu.com.tr/api/v1. Her istekte anahtarı Authorization başlığında gönderin.

curl -H "Authorization: Bearer $SNC_API_KEY" https://sunucu.com.tr/api/v1/services

{ "data": [ { "code": "482913-639201", "name": "Bulut Sunucu", "status": "active", ... } ],
  "meta": { "page": 1, "per_page": 50, "total": 1 } }

Anahtarlar ve yetkiler

Yetki	Ad	Kapsam
services:read	Hizmetleri okuma	Hizmet listesi ve ayrıntısı, sunucu durumu ve işlem günlüğü.
servers:power	Sunucu güç işlemleri	Sunucuları başlatma, kapatma ve yeniden başlatma. Hizmetleri okumayı da içerir.
invoices:read	Faturaları okuma	Fatura listesi, tutarlar ve fatura kalemleri.

Anahtar yalnız oluşturulduğu hesapta geçerlidir.
Anahtar yalnız oluşturulurken bir kez gösterilir; biz de göremeyiz.
IP kısıtı eklerseniz anahtar yalnız o adreslerden çalışır.
Süresi dolan ya da iptal edilen anahtar hemen reddedilir.
Anahtarı yalnız hesap sahibi oluşturur ve iptal eder.

Güvenlik önerileri

Anahtarı kod deposuna koymayın; ortam değişkeninde ya da gizli bilgi kasasında tutun.
Yalnız gereken yetkiyi verin; okuma yeten işe güç yetkisi vermeyin.
Sabit IP'li bir sunucudan kullanıyorsanız IP kısıtı ekleyin.
Sızdığını düşündüğünüz anahtarı hemen iptal edin ve yenisini oluşturun.
Anahtarı adres satırında (sorgu dizesinde) göndermeyin; böyle gelen istek reddedilir.

Yanıt biçimi

Gövde ve yanıt JSON, UTF-8.
Başarılı yanıt { "data": ... }, liste { "data": [...], "meta": { "page", "per_page", "total" } }.
Zaman damgaları ISO 8601 UTC (2026-10-10T09:30:00Z); yalnız tarih alanları (due_date, next_due_date, date) Türkiye günüyle YYYY-MM-DD.
Tutarlar iki ondalıklı metin ("504.00").
Yeni alanlar duyurusuz eklenebilir; yazılımınız bilinmeyen alanları yok saymalı.

Hatalar

{ "error": { "code": "not_found", "message": "Kayıt bulunamadı.", "request_id": "3f9a1c2b7d10" } }

Başka bir hesaba ait kayıt için de 404 döner. Destek talebinde request_id değerini paylaşın.

Kod	HTTP	Açıklama
unauthorized	401	Geçerli bir API anahtarı gönderin.
key_expired	401	Bu API anahtarının süresi dolmuş.
key_revoked	401	Bu API anahtarı iptal edilmiş.
key_in_url	400	API anahtarı adres satırında gönderilemez; Authorization başlığını kullanın.
ip_not_allowed	403	Bu anahtar bu IP adresinden kullanılamaz.
insufficient_scope	403	Bu işlem için anahtarda "yetki adı" yetkisi gerekiyor.
not_found	404	Kayıt bulunamadı.
method_not_allowed	405	Bu adres bu yöntemi desteklemiyor.
invalid_request	400	İstek geçersiz.
payload_too_large	413	İstek gövdesi çok büyük.
unsupported_media_type	415	Content-Type application/json olmalı.
invalid_action	422	Geçersiz işlem. Kullanılabilir: start, shutdown, reboot, stop, reset.
confirm_required	422	Zorla kapatma ve zorla yeniden başlatma için "confirm": true gönderin.
power_not_supported	422	Bu hizmette güç işlemi yapılamaz.
guest_tools_unavailable	422	Güvenli işlem için işletim sisteminin yanıt vermesi gerekiyor, şu an yanıt alınamıyor. stop ya da reset kullanabilirsiniz.
service_not_active	409	Bu hizmet şu an işleme açık değil.
service_provisioning	409	Sunucu hâlâ kuruluyor, lütfen bekleyin.
already_in_state	409	Sunucu zaten bu durumda.
operation_in_progress	409	Bu sunucuda süren bir işlem var. Bitmesini bekleyip tekrar deneyin.
idempotency_key_reused	409	Bu Idempotency-Key başka bir istekte kullanıldı.
rate_limited	429	Çok fazla istek. Retry-After başlığındaki süre kadar bekleyin.
too_many_failed_attempts	429	Bu adresten çok fazla başarısız deneme yapıldı. 10 dakika sonra tekrar deneyin.
api_disabled	503	API şu an geçici olarak kapalı.
infrastructure_error	503	İşlem şu an tamamlanamadı. Birkaç dakika sonra tekrar deneyin; sorun sürerse destek talebi açın.
internal_error	500	Beklenmeyen bir hata oluştu. Sorun sürerse request_id ile destek talebi açın.

Oran sınırları

Anahtar başına dakikada 120 istek. Güç işlemleri anahtar başına dakikada 10, aynı sunucuda dakikada 6. Canlı durum anahtar başına dakikada 30. Bir hesabın tüm anahtarları toplamda dakikada 600 istek.

Her yanıtta RateLimit-Limit, RateLimit-Remaining ve RateLimit-Reset başlıkları bulunur; 429 yanıtında Retry-After başlığı kaç saniye beklemeniz gerektiğini söyler. Aynı adresten 10 dakikada 30 başarısız kimlik denemesinden sonra o adres 10 dakika engellenir.

Sürümleme

Sürüm adreste yer alır (/v1). Yeni alan eklemek gibi geriye uyumlu değişiklikler v1 içinde duyurusuz yapılabilir; yazılımınız bilinmeyen alanları yok saymalı. Geriye uyumsuz değişiklikler yeni sürümle gelir; v1 en az 12 ay desteklenir ve kaldırılmadan en az 90 gün önce e-posta ve Duyurular ile bildirilir.

Uçlar

GET/accountherhangi

Anahtarın bağlı olduğu hesap ve anahtarın kendisi.

Örnek istek

curl -H "Authorization: Bearer $SNC_API_KEY" https://sunucu.com.tr/api/v1/account

Örnek yanıt

{ "data": { "account": { "customer_no": 482913, "name": "Örnek Yazılım Ltd.", "currency": "TRY" },
  "key": { "name": "Yedekleme betiği", "prefix": "snc_k3m9q2xa", "scopes": ["services:read"],
           "expires_at": "2027-01-08T09:00:00Z", "ip_restricted": true } } }

GET/servicesservices:read

Hizmet listesi (oluşturulma sırasına göre).

Parametre	Açıklama
state	current (varsayılan, süren hizmetler), ended (biten) ya da all.
category	server, hosting, domain, email, storage, app ya da other.
page, per_page	Sayfa (1'den) ve sayfa boyu (1-100, varsayılan 50).

Örnek istek

curl -H "Authorization: Bearer $SNC_API_KEY" "https://sunucu.com.tr/api/v1/services?state=current"

Örnek yanıt

{ "data": [ {
    "code": "482913-639201",
    "name": "Bulut Sunucu",
    "category": "server",
    "status": "active",
    "hostname": "web01.ornek.com",
    "domain": null,
    "ipv4": "203.0.113.10",
    "additional_ips": ["203.0.113.11"],
    "location": "Türkiye",
    "os": "Ubuntu 24.04",
    "specs": { "vcpu": 2, "ram_gb": 4, "disk_gb": 80 },
    "power_state": "running",
    "power_actions": true,
    "billing": { "cycle": "monthly", "amount": "420.00", "currency": "TRY", "vat_included": true, "next_due_date": "2026-11-01" },
    "created_at": "2026-03-14T08:12:00Z"
  } ],
  "meta": { "page": 1, "per_page": 50, "total": 1 } }

GET/services/{code}services:read

Tek hizmet. {code}, paneldeki hizmet kodudur (müşteri no ve hizmet no, ör. 482913-639201).

Örnek istek

curl -H "Authorization: Bearer $SNC_API_KEY" https://sunucu.com.tr/api/v1/services/482913-639201

Örnek yanıt

{ "data": {
    "code": "482913-639201",
    "name": "Bulut Sunucu",
    "category": "server",
    "status": "active",
    "hostname": "web01.ornek.com",
    "domain": null,
    "ipv4": "203.0.113.10",
    "additional_ips": ["203.0.113.11"],
    "location": "Türkiye",
    "os": "Ubuntu 24.04",
    "specs": { "vcpu": 2, "ram_gb": 4, "disk_gb": 80 },
    "power_state": "running",
    "power_actions": true,
    "billing": { "cycle": "monthly", "amount": "420.00", "currency": "TRY", "vat_included": true, "next_due_date": "2026-11-01" },
    "created_at": "2026-03-14T08:12:00Z"
  } }

GET/services/{code}/statusservices:read

Sunucunun canlı durumu. Güç işlemi desteklenmeyen hizmette 422 power_not_supported.

Örnek istek

curl -H "Authorization: Bearer $SNC_API_KEY" https://sunucu.com.tr/api/v1/services/482913-639201/status

Örnek yanıt

{ "data": { "power": "running", "uptime_seconds": 273600, "guest_tools": true,
  "operation_in_progress": null, "checked_at": "2026-10-10T09:30:12Z" } }

POST/services/{code}/powerservers:power

Sunucuyu başlatır, kapatır ya da yeniden başlatır.

Parametre	Açıklama
action	start, shutdown, reboot, stop ya da reset (gövdede).
confirm	stop ve reset için true olmalı (gövdede).
Idempotency-Key	İsteğe bağlı başlık, 8-48 karakter harf, rakam ve tire.

action	İşlem
start	Başlat
shutdown	Güvenli kapat (işletim sistemine kapanma sinyali)
reboot	Güvenli yeniden başlat
stop	Zorla kapat ("confirm": true gerekir)
reset	Zorla yeniden başlat ("confirm": true gerekir)

Güvenli işlemler sunucudaki işletim sisteminin yanıt vermesini gerektirir. Aynı isteği güvenle tekrarlamak için Idempotency-Key başlığı gönderin; aynı anahtarla gelen tekrar duplicate: true döner. Yeniden kurulum, iptal ve silme gibi geri alınamaz işlemler API'de yoktur; panelden yapılır.

Örnek istek

curl -X POST -H "Authorization: Bearer $SNC_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: yeniden-baslat-0001" \
  -d '{"action":"reboot"}' https://sunucu.com.tr/api/v1/services/482913-639201/power

Örnek yanıt

{ "data": { "operation": { "id": 9812, "action": "reboot", "status": "completed",
  "expected_power": "running", "created_at": "2026-10-10T09:31:02Z", "finished_at": "2026-10-10T09:31:05Z" },
  "duplicate": false } }

GET/services/{code}/operationsservices:read

Sunucunun işlem günlüğü (yeniden eskiye).

Parametre	Açıklama
limit	1-100, varsayılan 50.

Örnek istek

curl -H "Authorization: Bearer $SNC_API_KEY" "https://sunucu.com.tr/api/v1/services/482913-639201/operations?limit=20"

Örnek yanıt

{ "data": [ { "id": 9812, "action": "reboot", "label": "Yeniden başlatıldı", "status": "completed",
  "actor": "api_key", "actor_name": "Yedekleme betiği",
  "created_at": "2026-10-10T09:31:02Z", "finished_at": "2026-10-10T09:31:05Z" } ] }

GET/invoicesinvoices:read

Fatura listesi (yeniden eskiye); panelde gördüğünüz faturalar.

Parametre	Açıklama
status	unpaid, paid, cancelled, refunded ya da all (varsayılan).
page, per_page	Sayfa ve sayfa boyu (1-100, varsayılan 50).

Örnek istek

curl -H "Authorization: Bearer $SNC_API_KEY" "https://sunucu.com.tr/api/v1/invoices?status=unpaid"

Örnek yanıt

{ "data": [ {
    "id": 1234, "number": "S-1234", "status": "unpaid", "type": "standard",
    "date": "2026-10-01", "due_date": "2026-10-08", "paid_date": null,
    "currency": "TRY", "total": "504.00", "amount_paid": "0.00", "balance_due": "504.00",
    "vat_included": true, "items_count": 3,
    "url": "https://sunucu.com.tr/panel/faturalar/1234"
  } ],
  "meta": { "page": 1, "per_page": 50, "total": 1 } }

GET/invoices/{id}invoices:read

Tek fatura ve kalemleri.

Örnek istek

curl -H "Authorization: Bearer $SNC_API_KEY" https://sunucu.com.tr/api/v1/invoices/1234

Örnek yanıt

{ "data": { "id": 1234, "number": "S-1234", "status": "unpaid", "total": "504.00",
  "subtotal": "420.00", "vat": "84.00",
  "items": [ { "description": "Bulut Sunucu (01.10.2026 - 31.10.2026)", "amount": "420.00", "group": null } ] } }

Değişiklik günlüğü

10 Ekim 2026 · v1 yayında.

Sorularınız için panelden destek talebi açın.