# REST API — Giriş

Onoxsoft Panel REST API'si, panel işlevlerinin tamamını programatik olarak yönetmenize olanak tanır. WHMCS, özel faturalandırma sistemleri, otomasyon betikleri ve çoklu sunucu yönetimi için tasarlanmıştır.

## Temel Bilgiler

| Özellik | Değer |
|---------|-------|
| Base URL | `https://panel.yourdomain.com/api/v1` |
| Protokol | HTTPS (HTTP desteklenmez) |
| Format | JSON |
| Kimlik Doğrulama | Bearer Token veya HMAC-SHA256 |
| Rate Limit | 120 istek / dakika (varsayılan) |
| API Versiyonu | `v1` |

## İlk API Token Oluşturma

### Panel Üzerinden

1. Admin panele giriş yapın
2. **Sistem > API Tokenları > Yeni Token** tıklayın
3. Token adı, kapsam ve isteğe bağlı IP kısıtlaması girin
4. **Oluştur** butonuna tıklayın
5. Token bir kez gösterilir — not alın

### CLI Üzerinden

```bash
php artisan onox:create-api-token \
  --name="WHMCS Integration" \
  --scopes="accounts:read,accounts:write,domains:*,dns:*" \
  --user-id=1
```

## Kimlik Doğrulama

Tüm API isteklerinde `Authorization` başlığı zorunludur.

### Bearer Token (Önerilen)

```http
GET /api/v1/accounts HTTP/1.1
Host: panel.yourdomain.com
Authorization: Bearer onox_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json
Content-Type: application/json
```

### HMAC-SHA256 İmzası (Cluster / Servis-Servis)

Sunucular arası iletişimde daha güvenli olan HMAC imzası kullanılır:

```http
POST /api/v1/accounts HTTP/1.1
Host: panel.yourdomain.com
X-Onox-Key-Id: key_abc123
X-Onox-Timestamp: 1748808000
X-Onox-Signature: sha256=<hmac>
Content-Type: application/json
```

İmza hesaplama:

```php
$payload = $timestamp . "\n" . $method . "\n" . $path . "\n" . $body;
$signature = hash_hmac('sha256', $payload, $secret);
```

```python
import hmac, hashlib, time

def sign_request(method, path, body, secret):
    ts = str(int(time.time()))
    payload = f"{ts}\n{method}\n{path}\n{body}"
    sig = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
    return ts, f"sha256={sig}"
```

## İstek Formatı

Tüm isteklerde `Content-Type: application/json` başlığı gönderilmelidir.

```bash
curl -X POST https://panel.yourdomain.com/api/v1/accounts \
  -H "Authorization: Bearer onox_live_xxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "username": "ornek",
    "email": "ornek@firma.com",
    "password": "güçlü_şifre",
    "package_id": 2,
    "domain": "ornek.com"
  }'
```

## Yanıt Formatı

### Başarılı Yanıt (2xx)

```json
{
    "success": true,
    "data": {
        "id": 42,
        "username": "ornek",
        "email": "ornek@firma.com",
        "status": "active",
        "created_at": "2026-05-13T10:30:00Z"
    },
    "meta": {
        "request_id": "req_01HX..."
    }
}
```

### Liste Yanıtı (Sayfalama)

```json
{
    "success": true,
    "data": [ ... ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 187,
        "last_page": 8
    },
    "links": {
        "first": "/api/v1/accounts?page=1",
        "next": "/api/v1/accounts?page=2",
        "last": "/api/v1/accounts?page=8"
    }
}
```

### Hata Yanıtı (4xx / 5xx)

```json
{
    "success": false,
    "error": {
        "code": "ACCOUNT_LIMIT_EXCEEDED",
        "message": "Paketinizdeki maksimum hesap sayısına ulaşıldı.",
        "details": {
            "limit": 100,
            "current": 100
        }
    },
    "meta": {
        "request_id": "req_01HX..."
    }
}
```

## HTTP Durum Kodları

| Kod | Anlam |
|-----|-------|
| 200 | Başarılı GET/PUT/PATCH |
| 201 | Kaynak oluşturuldu (POST) |
| 204 | İçerik yok (DELETE başarılı) |
| 400 | Geçersiz istek / validasyon hatası |
| 401 | Kimlik doğrulama hatası |
| 403 | Yetki hatası |
| 404 | Kaynak bulunamadı |
| 409 | Çakışma (zaten var) |
| 422 | Validasyon hataları |
| 429 | Rate limit aşıldı |
| 500 | Sunucu hatası |
| 503 | Servis geçici olarak kullanılamıyor |

## Sayfalama

Listeleme endpoint'leri `page` ve `per_page` parametrelerini destekler:

```bash
GET /api/v1/accounts?page=2&per_page=50
```

Maksimum `per_page`: **100**

## Filtreleme ve Sıralama

```bash
# Durum filtreleme
GET /api/v1/accounts?status=active

# Arama
GET /api/v1/accounts?search=ahmet

# Sıralama
GET /api/v1/accounts?sort=created_at&direction=desc

# Birden fazla filtre
GET /api/v1/accounts?status=active&package_id=2&sort=username
```

## Zaman Damgaları

Tüm tarih/saat alanları **ISO 8601 UTC** formatında döner:

```
"created_at": "2026-05-13T10:30:00Z"
```

İsteklerde de UTC veya timezone offset kabul edilir:

```json
{
    "expires_at": "2027-05-13T00:00:00+03:00"
}
```

## Webhooks

Onoxsoft Panel, belirli olaylar gerçekleştiğinde tanımlı URL'lere POST isteği gönderebilir.

Webhook ayarları: **Admin > Sistem > Webhooks**

Desteklenen olaylar:
- `account.created`
- `account.suspended`
- `account.terminated`
- `ssl.issued`
- `ssl.expiring`
- `backup.completed`
- `backup.failed`

Detaylar için [Events & Webhooks](/tr/developers/events-webhooks) sayfasına bakın.

## SDK'lar ve İstemciler

Resmi PHP SDK:

```bash
composer require onoxsoft/panel-sdk
```

```php
use Onox\PanelSdk\OnoxClient;

$client = new OnoxClient(
    baseUrl: 'https://panel.yourdomain.com',
    token: 'onox_live_xxxxx'
);

$accounts = $client->accounts()->list(page: 1, perPage: 25);
foreach ($accounts as $account) {
    echo $account->username . PHP_EOL;
}
```

## Postman Koleksiyonu

Koleksiyonu Postman'e aktarmak için:

1. [GitHub Releases](https://github.com/onoxsoft/panel/releases) sayfasından `onox-api.postman_collection.json` indirin
2. Postman'de **Import > File** ile açın
3. Environment değişkenlerine `base_url` ve `api_token` ekleyin

## Sonraki Adımlar

- [Kimlik Doğrulama Detayları](/tr/api/auth)
- [Accounts API](/tr/api/accounts)
- [Domains API](/tr/api/domains)
- [Rate Limiting](/tr/api/ratelimit)
- [Hata Kodları Referansı](/tr/api/errors)
