# Hizmete Bağlı Ek Hizmetler

https://dev.wisecp.com/tr/hizmete-bagli-ek-hizmetler

Bir hizmetin üzerine satılan ek hizmetleri ekleyen, düzenleyen ve durumunu değiştiren sekiz uç.

## Genel Bakış

Ek hizmet, bir hizmetin üzerine satılan şeydir: fazladan disk, yedekleme, kayıt gizliliği. Kendi fiyatı, kendi döngüsü ve kendi durumu vardır; hizmetle birlikte yaşar ama ondan bağımsız askıya alınabilir ve iptal edilebilir.

İki kaynağı vardır. **Katalog** ek hizmetleri ürün tarafında tanımlanır ve kimlikle eklenir. **Alan adı** ek hizmetleri kataloğa girmez; DNS yönetimi, e-posta yönlendirme ve kayıt gizliliğinden ibarettir ve anahtarla eklenir.

## Referans

### Ek Hizmetleri Listeleme

get/api/v1/admin/services/{id}/addons

`Services/GetServiceAddons` admin

Hizmete bağlı ek hizmetlerin tamamını döndürür.

Dönen alanlar data[] — 20

idintEk hizmet kaydının kimliği. Diğer uçlar bunu kullanır.

service_idintBağlı olduğu hizmetin kimliği.

addon_idintKatalogdaki ek hizmet tanımının kimliği. Alan adı ek hizmetlerinde sıfır.

addon_namestringEk hizmetin adı.

option_idintSeçilen seçeneğin kimliği.

option_namestringSeçeneğin adı.

statusstring`waiting`, `inprocess`, `active`, `suspended` ya da `cancelled`.

amountfloatBirim tutar.

total_amountfloatAdetle çarpılmış toplam.

quantityintAdet.

currency_idintPara birimi kimliği.

cyclestringFaturalama döngüsü.

periodstringDönem birimi.

period_timeintDönem çarpanı.

payment_methodstringÖdeme yöntemi.

invoice_idintİlişkili faturanın kimliği.

subscription_idintBağlı aboneliğin kimliği.

created_atstringEklenme tarihi.

due_atstringDönemin bittiği tarih.

renewal_atstringYenileme tarihi.

Hatalar 2

not_found404Hizmet bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/services/529/addons' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/services/529/addons', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/services/529/addons');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$response = Api::Services()->GetServiceAddons(['id' => 529]);
```

### Ek Hizmet Detayı

get/api/v1/admin/services/{id}/addons/{addon_id}

`Services/GetServiceAddon` admin

Tek bir ek hizmeti döndürür. Şema liste öğesiyle aynıdır.

Dönen alanlar data — 20

idintEk hizmet kaydının kimliği. Diğer uçlar bunu kullanır.

service_idintBağlı olduğu hizmetin kimliği.

addon_idintKatalogdaki ek hizmet tanımının kimliği. Alan adı ek hizmetlerinde sıfır.

addon_namestringEk hizmetin adı.

option_idintSeçilen seçeneğin kimliği.

option_namestringSeçeneğin adı.

statusstring`waiting`, `inprocess`, `active`, `suspended` ya da `cancelled`.

amountfloatBirim tutar.

total_amountfloatAdetle çarpılmış toplam.

quantityintAdet.

currency_idintPara birimi kimliği.

cyclestringFaturalama döngüsü.

periodstringDönem birimi.

period_timeintDönem çarpanı.

payment_methodstringÖdeme yöntemi.

invoice_idintİlişkili faturanın kimliği.

subscription_idintBağlı aboneliğin kimliği.

created_atstringEklenme tarihi.

due_atstringDönemin bittiği tarih.

renewal_atstringYenileme tarihi.

Hatalar 2

not_found404Hizmet ya da ek hizmet bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/services/529/addons/44' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/services/529/addons/44', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/services/529/addons/44');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Adresteki kimlik KAYDIN kimligidir, katalogdaki tanimin degil.
$response = Api::Services()->GetServiceAddon(['id' => 529, 'addon_id' => 44]);
```

### Ek Hizmet Ekleme

post/api/v1/admin/services/{id}/addons

`Services/CreateServiceAddon` admin iki kaynak

Hizmete ek hizmet bağlar. Katalogdan ya da alan adına özgü olabilir.

Gövde — hangi ek hizmet 2

addon_idintKatalogdaki ek hizmet tanımının kimliği. Alan adı dışındaki hizmetlerde gerekir.

addon_keystringAlan adı ek hizmeti: `dns-manage`, `forwarding` ya da `whois-privacy`. Yalnız alan adı hizmetlerinde ve `addon_id` yerine.

Gövde — fiyat ve dönem 5

option_idintSeçilecek ek hizmet seçeneğinin kimliği.

override_amountfloatFiyatı elle belirler. Vermezseniz seçeneğin ya da alan adı ek hizmetinin kendi fiyatı kullanılır.

override_currencystringElle belirlenen fiyatın para birimi kodu.

quantityintAdet. En az bir; varsayılan bir.

cyclestringFaturalama döngüsü. Alan adı ek hizmeti her zaman fiyatının dönemini (yıllık) alır, gönderilen döngü yok sayılır. Döngüsüz gönderilen katalog ek hizmeti seçilen seçeneğin dönemini alır.

Gövde — tarih, durum ve fatura 6

start_datedatetimeBaşlangıç tarihi. Varsayılan şimdi.

end_datedatetimeBitiş tarihi, ek hizmetin bir sonraki yenileme vadesi. Verilmezse alan adı ek hizmeti hizmetle birlikte biter. Ürün Döngüsüne Göre Sun işaretli katalog ek hizmeti de öyle. Diğerleri başlangıçtan bir dönem sonra biter.

statusstringBaşlangıç durumu: `waiting`, `inprocess` ya da `active`. Varsayılan `waiting`. Bekleyen ek hizmet yenilenmez; mevcut hizmetlere faturasız ek hizmet bağlarken `active` gönderin.

generate_invoiceboolEk hizmet için fatura üretir.

invoice_statusstringÜretilen faturanın durumu: `unpaid` ya da `paid`. Varsayılan `unpaid`.

requirementsobjectEk hizmetin sorduğu alanlara verilen yanıtlar. Gereksinim kimliğinden değere eşleme.

Dönen alanlar 201 — data

dataobjectOluşan ek hizmet. Detay ucuyla aynı şekildedir.

Hatalar 6

not_found404Hizmet bulunamadı.

addon_id_required422Katalog ek hizmetinde kimlik verilmedi.

addon_invalid422Alan adı ek hizmet anahtarı üç değerden biri değil.

addon_not_found422Ek hizmet tanımı bulunamadı.

addon_add_failed500Ek hizmet eklenemedi.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/services/529/addons' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"addon_id":9,"option_id":3,"quantity":1,"cycle":"monthly","generate_invoice":true}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/services/529/addons', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    addon_id: 9,
    option_id: 3,
    quantity: 1,
    cycle: 'monthly',
    generate_invoice: true,
  }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/services/529/addons');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'addon_id'         => 9,
        'option_id'        => 3,
        'quantity'         => 1,
        'cycle'            => 'monthly',
        'generate_invoice' => true,
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Alan adi hizmetinde addon_id DEGIL addon_key gonderilir.
$service = Api::Services()->GetService(['id' => 529])['data'];

$body = $service['type'] === 'domain'
    ? ['addon_key' => 'whois-privacy']
    : ['addon_id' => 9, 'option_id' => 3];

Api::Services()->CreateServiceAddon(['id' => 529] + $body);
```

### Ek Hizmeti Güncelleme

patch/api/v1/admin/services/{id}/addons/{addon_id}

`Services/UpdateServiceAddon` admin

Ek hizmetin fiyatını, adetini, döngüsünü ve tarihlerini değiştirir.

Gövde 11

addon_namestringEk hizmetin görünen adı.

option_namestringSeçeneğin görünen adı.

amountfloatBirim tutar. Toplam yeniden hesaplanır.

quantityintAdet. En az bir.

currency_idintPara birimi kimliği.

cyclestringFaturalama döngüsü. Alan adı ek hizmetlerinde geçmez.

payment_methodstringÖdeme yöntemi.

subscription_identifierstringAboneliğe eşlenen abonelik tanımlayıcısı. Boş değer ya da eşleşmeyen değer bağı temizler.

start_datedatetimeBaşlangıç tarihi.

end_datedatetimeBitiş tarihi. Boş göndermek tarihi temizler.

renewal_datedatetimeYenileme tarihi. Boş göndermek tarihi temizler.

Dönen alanlar data

dataobjectGüncel ek hizmet. Detay ucuyla aynı şekildedir.

Hatalar 2

not_found404Hizmet ya da ek hizmet bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X PATCH 'https://panel.ornek.com/api/v1/admin/services/529/addons/44' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"amount":15,"quantity":2}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/services/529/addons/44', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ amount: 15, quantity: 2 }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/services/529/addons/44');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['amount' => 15, 'quantity' => 2]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Hizmetin donem bitisini otelemek ayni gundeki ek hizmetleri de kaydirir; bu uc TEK ek hizmeti tasir.
$response = Api::Services()->UpdateServiceAddon([
    'id'       => 529,
    'addon_id' => 44,
    'end_date' => '2026-09-01 00:00:00',
]);
```

### Ek Hizmeti Silme

delete/api/v1/admin/services/{id}/addons/{addon_id}

`Services/DeleteServiceAddon` admin geri alınamaz

Ek hizmet kaydını siler.

Dönen alanlar data — 2

deletedboolSilme başarılı mı.

idintSilinen kaydın kimliği.

Hatalar 2

not_found404Hizmet ya da ek hizmet bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X DELETE 'https://panel.ornek.com/api/v1/admin/services/529/addons/44' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/services/529/addons/44', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/services/529/addons/44');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Silmek modulde bir sey KAPATMAZ; saglayici tarafi icin once iptal ucunu cagirin.
Api::Services()->CancelServiceAddon([
    'id'              => 529,
    'addon_id'        => 44,
    'apply_on_module' => true,
]);

Api::Services()->DeleteServiceAddon(['id' => 529, 'addon_id' => 44]);
```

### Ek Hizmeti Askıya Alma

post/api/v1/admin/services/{id}/addons/{addon_id}/suspend

`Services/SuspendServiceAddon` admin modüle iner

Ek hizmeti durdurur. Hizmetin kendisine dokunmaz.

Gövde 3

reasonstringAskıya alma nedeni.

notifyboolMüşteriye bildirim gönderir.

apply_on_moduleboolİşlemi sağlayıcıya da uygular. Vermezseniz hizmetin modülü olup olmadığına bakılır.

Dönen alanlar data — 3

statusstringİşlem sonrası durum.

idintEk hizmet kaydının kimliği.

applied_on_moduleboolSağlayıcıya uygulandı mı.

Hatalar 4

not_found404Hizmet ya da ek hizmet bulunamadı.

module_error422Hizmetin modülü değişikliği reddetti. Mesaj gerekçesini taşır; ek hizmetin durumu değişmez.

status_change_failed500Durum değiştirilemedi.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/services/529/addons/44/suspend' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Awaiting payment","notify":true}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/services/529/addons/44/suspend', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ reason: 'Awaiting payment', notify: true }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/services/529/addons/44/suspend');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['reason' => 'Awaiting payment']),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$response = Api::Services()->SuspendServiceAddon([
    'id'       => 529,
    'addon_id' => 44,
    'reason'   => 'Awaiting payment',
]);

// Durum degisti ama module inmediyse ozellik CALISMAYA devam eder.
$reached = $response['data']['applied_on_module'] ?? false;
```

### Ek Hizmet Askısını Kaldırma

post/api/v1/admin/services/{id}/addons/{addon_id}/unsuspend

`Services/UnsuspendServiceAddon` admin modüle iner

Askıdaki ek hizmeti yeniden çalıştırır.

Gövde 2

notifyboolMüşteriye bildirim gönderir.

apply_on_moduleboolİşlemi sağlayıcıya da uygular. Vermezseniz hizmetin modülü olup olmadığına bakılır.

Dönen alanlar data — 3

statusstringİşlem sonrası durum.

idintEk hizmet kaydının kimliği.

applied_on_moduleboolSağlayıcıya uygulandı mı.

Hatalar 4

not_found404Hizmet ya da ek hizmet bulunamadı.

module_error422Hizmetin modülü değişikliği reddetti. Mesaj gerekçesini taşır; ek hizmetin durumu değişmez.

status_change_failed500Durum değiştirilemedi.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/services/529/addons/44/unsuspend' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/services/529/addons/44/unsuspend', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/services/529/addons/44/unsuspend');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$response = Api::Services()->UnsuspendServiceAddon(['id' => 529, 'addon_id' => 44]);
```

### Ek Hizmeti İptal Etme

post/api/v1/admin/services/{id}/addons/{addon_id}/cancel

`Services/CancelServiceAddon` admin geri alınamaz

Ek hizmeti iptal eder ve isterseniz sağlayıcıdaki karşılığını kapatır.

Gövde 3

reasonstringİptal nedeni.

notifyboolMüşteriye bildirim gönderir.

apply_on_moduleboolSağlayıcıdaki karşılığını da kapatır. Burada varsayılan kapalıdır; askıya almadan farklı olarak açıkça istemeniz gerekir.

Dönen alanlar data — 3

statusstringİşlem sonrası durum.

idintEk hizmet kaydının kimliği.

applied_on_moduleboolSağlayıcıya uygulandı mı.

Hatalar 4

not_found404Hizmet ya da ek hizmet bulunamadı.

module_error422Hizmetin modülü değişikliği reddetti. Mesaj gerekçesini taşır; ek hizmetin durumu değişmez.

status_change_failed500Durum değiştirilemedi.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/services/529/addons/44/cancel' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"apply_on_module":true,"notify":true}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/services/529/addons/44/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ apply_on_module: true, notify: true }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/services/529/addons/44/cancel');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['apply_on_module' => true]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Iptalde bayrak VARSAYILAN OLARAK KAPALI: vermezseniz ozellik sunucuda acik kalir.
$response = Api::Services()->CancelServiceAddon([
    'id'              => 529,
    'addon_id'        => 44,
    'apply_on_module' => true,
]);
```

## Tuzaklar

> **Alan adı ek hizmeti farklı alanla eklenir**
> 
> Katalog ek hizmeti `addon_id` ile, alan adı ek hizmeti `addon_key` ile eklenir; ikisi birbirinin yerine geçmez. Alan adı hizmetine kimlik göndermek `addon_not_found`, başka bir hizmete anahtar göndermek `addon_id_required` döndürür. Ekleme yapmadan önce hizmetin tipine bakın.

> **İptalde modül seçeneği kapalı gelir**
> 
> Askıya alma ve açma uçlarında sağlayıcıya uygulama varsayılan olarak hizmetin modülüne bakar; **iptal ucunda ise kapalıdır**. Seçeneği vermeden iptal ettiğinizde kayıt kapanır ama özellik sunucuda açık kalmaya devam eder. Bu asimetri kolayca gözden kaçar.

> **Silmek sunucuda hiçbir şeyi kapatmaz**
> 
> Silme ucu yalnız kaydı kaldırır ve sağlayıcıya hiç dokunmaz; modül seçeneğini bile almaz. Ek hizmetin sunucudaki karşılığı da kapanacaksa önce iptal ucunu o seçenekle çağırın, sonra silin.

> **Adresteki kimlik kaydın kimliğidir**
> 
> Alt uçlardaki kimlik, hizmete eklenmiş **kaydın** kimliğidir; katalogdaki tanımın kimliği değil. İkisi listede yan yana döner: `id` kayda, `addon_id` tanıma aittir. Ekleme yaparken tanımın kimliğini, sonraki her işlemde kaydın kimliğini kullanırsınız.

## İlgili Makaleler

- [Add-on Tanımları](https://dev.wisecp.com/tr/addon-tanimlari)
- [Yenileme ve İptal](https://dev.wisecp.com/tr/yenileme-ve-iptal)
- [Hizmet Uçları](https://dev.wisecp.com/tr/hizmet-uclari)