# Hizmet Uçları

https://dev.wisecp.com/tr/hizmet-uclari

Müşteri hizmetlerini listeleyen, okuyan, düzenleyen ve silen dört uç.

## Genel Bakış

Hizmet, bir müşterinin satın aldığı ve süren şeydir: barındırma hesabı, alan adı, sunucu, yazılım lisansı. Bu dört uç hizmetin kendisini okur, düzenler ve siler.

Yanıtlar **ham** gelir: durumlar ve döngüler kod olarak, tarihler standart biçimde, tutarlar sembolsüz sayı olarak. İnsan okuyacak etiketler `reference` uçlarından alınır.

Detaydaki `capabilities` bloğu, bu hizmete hangi işlemin uygulanabileceğini söyler. Değerler modülden türetilir, yani sabit değildir.

## Referans

### Hizmetleri Listeleme

get/api/v1/admin/services

`Services/GetServices` admin sayfalı

Müşteri hizmetlerini süzgeçlerle döndürür.

Sorgu parametreleri 9

searchstringHizmet adında, müşteride, e-postada ve adreste arar.

statusstringDuruma göre süzer: `waiting`, `inprocess`, `active`, `suspended`, `expired`, `cancelled` ya da `completed`.

typestringTipe göre süzer: `domain`, `hosting`, `server`, `software`, `sms`, `ssl` ya da `special`. Özel gruplarda tipe kimlik eklenir.

client_idintHizmet sahibine göre süzer.

product_idintÜrüne göre süzer.

server_idintSunucuya göre süzer. Sıfır, sunucusuz hizmetleri verir.

cyclestringFaturalama döngüsüne göre süzer.

pageintVarsayılan 1.

limitintVarsayılan 25, en çok 100.

Dönen alanlar data[] — 16

idintHizmet kimliği.

namestringHizmet adı.

typestringHizmet tipi.

type_idintÖzel gruplarda alt tip kimliği.

product_idintBağlı ürünün kimliği.

domainstring | nullHizmete bağlı alan adı.

statusstringHizmet durumu.

amountfloatDönem başına tutar. Ham sayı; biçimlendirme sizde.

currency_idintTutarın para birimi kimliği.

cyclestringFaturalama döngüsü.

qtyintAdet.

modulestring | nullHizmeti yürüten modül.

clientobject 4 alanHizmetin sahibi.

idintMüşteri kimliği.

full_namestringAd ve soyad.

company_namestringFirma adı.

emailstringE-posta adresi.

created_atdatetimeHizmetin açıldığı tarih.

due_atdatetimeDönemin bittiği tarih.

renewal_atdatetimeYenileme tarihi.

Sayfalama 4

totalintSüzgece uyan toplam kayıt.

pageintBulunduğunuz sayfa.

limitintSayfa boyutu.

next_pageintSonraki sayfa. Sıfır son sayfada olduğunuz anlamına gelir.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

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

```bash
curl -G 'https://panel.ornek.com/api/v1/admin/services' \
  -H "Authorization: Bearer $API_KEY" \
  -d status=active \
  -d type=hosting
```

```javascript
const url = new URL('https://panel.ornek.com/api/v1/admin/services');
url.searchParams.set('status', 'active');
url.searchParams.set('type', 'hosting');

const res  = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
```

```php
$url = 'https://panel.ornek.com/api/v1/admin/services?' . http_build_query(['status' => 'active', 'type' => 'hosting']);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

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

```php
// Sayfalama alanlari KOK seviyededir, 'meta' altinda degil.
$page = 1;
$all  = [];

do {
    $response = Api::Services()->GetServices([], [
        'status' => 'active',
        'page'   => $page,
        'limit'  => 100,
    ]);

    $all  = array_merge($all, $response['data']);
    $page = $response['next_page'];
} while ($page > 0);
```

Yanıt 200

```json
{
  "data": [
    {
      "id": 510,
      "name": "Mail Hosting",
      "type": "hosting",
      "type_id": 0,
      "product_id": 15,
      "domain": "example.com",
      "status": "active",
      "amount": 10.0,
      "currency_id": 1,
      "cycle": "monthly",
      "qty": 1,
      "module": "Mailcow",
      "client": {
        "id": 50,
        "full_name": "John Doe",
        "company_name": "",
        "email": "john@example.com"
      },
      "created_at": "2026-06-18 12:00:00",
      "due_at": "2026-07-18 12:00:00",
      "renewal_at": "2026-07-18 12:00:00"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 25,
  "next_page": 2
}
```

### Hizmet Detayı

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

`Services/GetService` admin yetenekler dahil

Bir hizmetin tüm ayrıntısını, ilişkilerini ve neler yapılabileceğini döndürür.

Dönen alanlar data — 29

idintHizmet kimliği.

namestringHizmet adı.

typestringHizmet tipi.

type_idintÖzel gruplarda alt tip kimliği.

product_idintBağlı ürünün kimliği.

order_idintHizmeti doğuran siparişin kimliği. Sipariş yoksa sıfır.

invoice_idintİlk faturanın kimliği.

statusstringHizmet durumu.

amountfloatDönem başına tutar.

total_amountfloatAdetle çarpılmış toplam.

currency_idintPara birimi kimliği.

qtyintAdet.

periodstringDönem birimi.

period_timeintDönem çarpanı.

cyclestringFaturalama döngüsü.

is_overdueboolVadesi geçmiş mi.

created_atdatetimeHizmetin açıldığı tarih.

due_atdatetimeDönemin bittiği tarih.

renewal_atdatetimeYenileme tarihi.

suspend_datedate | nullPlanlı askının yapılacağı gün. Planlı askı yoksa boş.

cancel_datedate | nullPlanlı iptalin yapılacağı gün. Planlı iptal yoksa boş.

process_exemption_datedate | nullOtomatik işlemlerden muaf tutulduğu son gün. Muafiyet yoksa boş.

payment_methodstringHizmeti tahsil eden ödeme modülü. Modül atanmamışsa `none`.

subscription_idintBağlı ağ geçidi aboneliğinin kimliği. Abonelik yoksa sıfır.

subscription_identifierstringO aboneliğin ağ geçidindeki kendi kimliği. Abonelik yoksa boş.

modulestring | nullHizmeti yürüten modül.

clientobject 4 alanHizmetin sahibi.

idintMüşteri kimliği.

full_namestringAd ve soyad.

company_namestringFirma adı.

emailstringE-posta adresi.

productobjectBağlı ürünün özeti: kimlik, başlık, tip ve modül.

serverobject | nullHizmetin kurulu olduğu sunucu: kimlik, ad, adres, kullanıcı ve durum.

orderobject | nullSiparişin özeti: kimlik, numara ve durum.

optionsobjectHizmetin ham ayarları. Şifre alanları çıkarılır; alanlar modüle göre değişir.

capabilitiesobject 6 alanBu hizmete hangi işlemlerin uygulanabileceği.

has_moduleboolHizmete bir modül bağlı mı.

can_suspendboolAskıya alınabilir mi.

can_unsuspendboolAskıdan çıkarılabilir mi.

can_cancelboolİptal edilebilir mi.

can_reinstallboolYeniden kurulabilir mi.

can_change_passwordboolŞifresi değiştirilebilir mi.

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/506' \
  -H "Authorization: Bearer $API_KEY"
```

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

// Islemi denemeden once yetenegi okuyun.
if (body.data.capabilities.can_reinstall) {
  // ...
}
```

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

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

```php
$service = Api::Services()->GetService(['id' => 506])['data'];

// Yetenekler modulden turetilir: modulsuz hizmette cogu kapalidir.
if ($service['capabilities']['can_suspend'] ?? false) {
    Api::Services()->SuspendService(['id' => 506]);
}
```

### Hizmeti Güncelleme

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

`Services/UpdateService` admin geçmişe yazılır

Hizmetin veri alanlarını değiştirir. Durum geçişleri buradan yapılmaz.

Gövde 23

namestringHizmet adı.

notesstringYönetici notu. Müşteriye gösterilmez.

payment_methodstringÖdeme yöntemi. Boş göndermek yöntemi kaldırır.

modulestringHizmeti yürütecek modül. Yalnız alan adı hizmetlerinde değiştirilebilir.

client_idintHizmetin sahibini değiştirir.

product_idintBağlı ürünü değiştirir.

product_groupstringÜrün değişiminde tipi çözmek için. Ürün kimliğiyle birlikte gönderilir.

subscription_identifierstringAbonelik tanımlayıcısı. Boş göndermek bağı koparır.

created_atdatetimeAçılış tarihi. Dakika hassasiyetinde karşılaştırılır: kayıtlı dakikaya düşen değer değişiklik sayılmaz, kayıtlı saniye korunur.

renewal_atdatetimeYenileme tarihi. Açılış tarihi gibi dakika hassasiyetinde karşılaştırılır.

due_atdatetimeDönem bitiş tarihi. Dakika hassasiyetinde karşılaştırılır. Boş göndermek hizmeti tarihsiz yapar.

suspend_datedatePlanlı askı tarihi. Boş göndermek planı iptal eder.

cancel_datedatePlanlı iptal tarihi.

process_exemption_datedateOtomatik işlemlerden muaf tutulacağı tarih.

amountfloatDönem başına tutar. Düz sayı olarak; ekrandaki biçimiyle değil.

currency_idintTutarın para birimi.

cyclestringFaturalama döngüsü. Alan adı hizmetlerinde yok sayılır.

qtyintAdet. Toplam tutar yeniden hesaplanır.

auto_payboolYenilemede otomatik tahsilat.

block_accessboolMüşterinin hizmete erişimini keser.

skip_renewal_invoiceboolYenileme faturası üretilmesini durdurur.

billing_profile_idintFaturanın kesileceği profil. Sıfır varsayılana döner.

discountobject 6 alanBu hizmetin yenileme faturalarına uygulanan indirim. Boş nesne göndermek indirimi kaldırır.

typestring`percent` ya da `amount`.

valuefloatYüzde ya da tutar. Sıfırdan büyük olmalı; yüzde yüzden küçük.

cidintSabit tutarın para birimi. Yüzdede yok sayılır.

ends_atstringİndirimin son geçerli günü. Boş bırakırsanız süresizdir.

cycles_limitintKaç yenilemeyi kapsayacağı. Sıfır sınırsız demektir.

notestringİndirimin gerekçesini anlatan iç not.

Dönen alanlar data — 29

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

Hatalar 5

not_found404Hizmet bulunamadı.

owner_not_found422Hedef müşteri bulunamadı.

invalid_date422Gönderilen tarih çözümlenemedi.

discount_invalid422İndirim reddedildi. Değer aralık dışında, bitiş tarihi geçmiş ya da hizmet bir aboneliğe bağlı.

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/506' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Mail Hosting Pro","amount":29.9,"qty":2,"auto_pay":true}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/services/506', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Mail Hosting Pro',
    amount: 29.9,
    qty: 2,
    auto_pay: true,
  }),
});

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

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/services/506');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name'   => 'Mail Hosting Pro',
        'amount' => 29.9,
        'qty'    => 2,
    ]),
]);

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

```php
// Donem bitisini oteleyen bir guncelleme, ayni gune denk gelen ek hizmetleri de kaydirir.
$response = Api::Services()->UpdateService([
    'id'     => 506,
    'due_at' => '2026-08-18 12:00:00',
]);
```

### Hizmeti Silme

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

`Services/DeleteService` admin geri alınamaz

Hizmet kaydını siler. İsterseniz sağlayıcıdaki hesabı da aynı istekte kapatır.

Gövde 1

apply_on_moduleboolSağlayıcıdaki hesabı da iptal eder. Varsayılan kapalı: kayıt gider, hesap sunucuda kalır.

Dönen alanlar data — 2

deletedboolSilme başarılı mı.

idintSilinen hizmetin kimliği.

Hatalar 2

not_found404Hizmet 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/510' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"apply_on_module":true}'
```

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

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

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/services/510');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    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
// Bayragi vermezseniz sunucudaki hesap AYAKTA kalir ve kaynak tuketmeye devam eder.
$response = Api::Services()->DeleteService([
    'id'              => 510,
    'apply_on_module' => true,
]);
```

## Tuzaklar

> **Silmek sunucudaki hesabı kapatmaz**
> 
> Silme ucu varsayılan olarak yalnız **kaydı** siler; sağlayıcıdaki hesap ayakta kalır ve kaynak tüketmeye devam eder. Hesabın da kapanması için isteğe o bayrağı koymanız gerekir. Kayıt gittikten sonra bunu API üzerinden yapmanın yolu kalmaz.

> **Durum değişimi bu uçta değil**
> 
> Güncelleme ucu `status` alanı kabul etmez: askıya alma, iptal ve yeniden aktifleştirme kendi uçlarındadır. Bunun sebebi bu geçişlerin modüle iş yaptırmasıdır; düz bir alan yazımı sunucuda hiçbir şeyi değiştirmezdi.

> **Sayfalama kökte, meta altında değil**
> 
> Hizmet listesi `total`, `page`, `limit` ve `next_page` alanlarını **kök seviyede** döndürür. Diğer birçok listede bunlar `meta` altındadır; ortak bir sayfalama yardımcısı yazıyorsanız bu farkı gözetin.

> **Bitiş tarihi ek hizmetleri de kaydırır**
> 
> Dönem bitişini değiştirmek, aynı güne denk gelen ek hizmetlerin bitişini de birlikte taşır. Bu genelde istenen davranıştır ama sessizdir: yalnız hizmetin tarihini değiştirdiğinizi sanırken faturalanacak başka kalemler de kaymış olur.

## İlgili Makaleler

- [Hizmet Yaşam Döngüsü](https://dev.wisecp.com/tr/hizmet-yasam-dongusu)
- [Hizmet Ayarları ve Sunucu](https://dev.wisecp.com/tr/hizmet-ayarlari-ve-sunucu)
- [Hizmete Bağlı Ek Hizmetler](https://dev.wisecp.com/tr/hizmete-bagli-ek-hizmetler)