# Client API İlk Çağrılar

https://dev.wisecp.com/tr/client-api-ilk-cagrilar

Müşteri tarafına bağlanırken çağrılan beş uç: sağlık, anahtar ve adres listeleri.

## Genel Bakış

Müşteri API'si, bir müşterinin kendi hesabını bir tümleştirmeden yönetmesi içindir. Yönetim API'sinden ayrı bir arayüzdür: **ayrı adres, ayrı anahtar türü** ve her çağrı tek bir müşteriyle sınırlı.

Bu makale ilk üç soruyu yanıtlar: API ayakta mı, anahtarım ne yapabiliyor ve adres alanlarını hangi değerlerle dolduracağım.

Adres zinciri tek yönlü çalışır: önce ülke kodu, sonra il numarası, sonra şehir numarası. Her adım bir öncekini ister ve herhangi biri boş dönebilir.

## Referans

### Sağlık Kontrolü

get/api/v1/admin/client/ping

`System/Ping` kimlik gerekmez

Müşteri tarafının ayakta olduğunu ve sunucu saatini döndürür.

Dönen alanlar data — 3

pongboolAPI ayakta mı.

versionstringAPI sürümü.

timestringSunucunun saati. Sunucunun kendi saat diliminde gelir.

Hatalar —

——Bu uç herkese açık, hata döndürmez.

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

```bash
curl 'https://panel.ornek.com/api/v1/client/ping'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/client/ping');
const { data } = await res.json();

if (! data.pong) reportOutage();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/client/ping');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

```php
// Yonetim tarafinin ayni adli ucundan AYRIDIR; biri ayaktayken digeri kapali olabilir.
$up = Kernel::internal('client:System/Ping')['data']['pong'] ?? false;
```

### Anahtar Bilgisi

get/api/v1/admin/client/whoami

`System/Whoami` kapsam gerekmez

Anahtarın kimliğini, yetkilerini ve bağlı olduğu müşteriyi döndürür.

Dönen alanlar data — 6

idintAnahtarın numarası.

typestringAnahtarın türü. Bu tarafta her zaman müşteri anahtarıdır.

namestringAnahtara verilen ad.

permissionsstring[]Anahtarın taşıdığı kapsamlar.

last_accessstringSon kullanıldığı an.

owner_idintAnahtarın bağlı olduğu müşterinin numarası. Bütün çağrılar bu müşteriyle sınırlıdır.

Hatalar 4

missing_token401Anahtar gönderilmemiş ya da tanınmıyor.

key_revoked401Anahtar iptal edilmiş.

audience_mismatch403Müşteri tarafında yönetim anahtarı kullanılmış.

ip_not_allowed403İstek izin verilen adreslerin dışından geldi.

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

```bash
curl 'https://panel.ornek.com/api/v1/client/whoami' \
  -H "Authorization: Bearer $CLIENT_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/client/whoami', {
  headers: { Authorization: `Bearer ${clientKey}` },
});

if (res.status === 403) return showWrongSurface();

const { data } = await res.json();
console.log(data.owner_id, data.permissions);
```

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

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

```php
// owner_id CAGRILARDA GECMEZ: musteri anahtardan cozulur, govdeye yazmak bir sey degistirmez.
$me = Kernel::internal('client:System/Whoami', ['owner_id' => $ownerId])['data'];
```

### Ülkeler

get/api/v1/admin/client/reference/countries

`Reference/GetCountries` kapsam gerekmez

Profil ve adres uçlarının kabul ettiği ülke kodlarını döndürür.

Dönen alanlar data[] — 2

codestringİki harfli ülke kodu. Profil ve adres uçları bu değeri ister, numarayı değil.

namestringÜlke adı. Sitenin dilinde gelir.

Hatalar 3

missing_token401Anahtar gönderilmemiş ya da tanınmıyor.

key_revoked401Anahtar iptal edilmiş.

audience_mismatch403Müşteri tarafında yönetim anahtarı kullanılmış.

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

```bash
curl 'https://panel.ornek.com/api/v1/client/reference/countries' \
  -H "Authorization: Bearer $CLIENT_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/client/reference/countries', {
  headers: { Authorization: `Bearer ${clientKey}` },
});

const { data } = await res.json();
renderCountryPicker(data);
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/client/reference/countries');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $clientKey],
]);

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

```php
// Musteri tarafi ULKE KODUYLA konusur; yonetim tarafindaki ulke NUMARASI burada gecmez.
$rows = Kernel::internal('client:Reference/GetCountries', ['owner_id' => $uid])['data'];
$codes = array_column($rows, 'code');
```

### Bir Ülkenin İlleri

get/api/v1/admin/client/reference/countries/{code}/states

`Reference/GetStates` kapsam gerekmez

Bir ülkenin illerini adres alanlarında kullanılan numaralarla döndürür.

Dönen alanlar data[] — 2

idintİlin numarası. Adres uçlarındaki il alanı ve şehir aramasının girdisi budur.

namestringİlin adı.

Hatalar 4

not_found404Böyle bir ülke kodu yok.

missing_token401Anahtar gönderilmemiş ya da tanınmıyor.

key_revoked401Anahtar iptal edilmiş.

audience_mismatch403Müşteri tarafında yönetim anahtarı kullanılmış.

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

```bash
curl 'https://panel.ornek.com/api/v1/client/reference/countries/TR/states' \
  -H "Authorization: Bearer $CLIENT_KEY"
```

```javascript
const res = await fetch(`https://panel.ornek.com/api/v1/client/reference/countries/${code}/states`, {
  headers: { Authorization: `Bearer ${clientKey}` },
});

const { data } = await res.json();
if (! data.length) useFreeTextState();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/client/reference/countries/' . $code . '/states');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $clientKey],
]);

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

```php
// BOS liste normaldir: o ulkede il kaydi yoksa adres alanina serbest metin gonderilir.
$states = Kernel::internal('client:Reference/GetStates', ['owner_id' => $uid, 'code' => $code])['data'];
$free   = ! $states;
```

### Bir İlin Şehirleri

get/api/v1/admin/client/reference/states/{id}/cities

`Reference/GetCities` kapsam gerekmez

Bir ilin şehirlerini adres alanlarında kullanılan numaralarla döndürür.

Dönen alanlar data[] — 2

idintŞehrin numarası. Adres uçlarındaki şehir alanı budur.

namestringŞehrin adı.

Hatalar 4

not_found404Böyle bir il yok.

missing_token401Anahtar gönderilmemiş ya da tanınmıyor.

key_revoked401Anahtar iptal edilmiş.

audience_mismatch403Müşteri tarafında yönetim anahtarı kullanılmış.

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

```bash
curl 'https://panel.ornek.com/api/v1/client/reference/states/34/cities' \
  -H "Authorization: Bearer $CLIENT_KEY"
```

```javascript
const res = await fetch(`https://panel.ornek.com/api/v1/client/reference/states/${stateId}/cities`, {
  headers: { Authorization: `Bearer ${clientKey}` },
});

const { data } = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/client/reference/states/' . $stateId . '/cities');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $clientKey],
]);

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

```php
// Sehir listesi bos gelse bile adreste SEHIR ZORUNLUDUR: serbest metin yazilir, bos birakilamaz.
$cities = Kernel::internal('client:Reference/GetCities', ['owner_id' => $uid, 'id' => $stateId])['data'];
```

## Tuzaklar

> **Yönetim anahtarı bu tarafta çalışmaz**
> 
> Müşteri tarafı yalnız müşteri anahtarı kabul eder; yönetim anahtarıyla çağırmak `audience_mismatch` verir. Hata kod olarak yetki değil **yanlış taraf** anlamına gelir; anahtarı değiştirmek yerine adresi düzeltmeye çalışmak zaman kaybıdır.

> **Müşteri anahtardan gelir, istekten değil**
> 
> Bütün müşteri uçları anahtarın sahibiyle sınırlıdır. Gövdeye bir müşteri numarası yazmak **hiçbir şeyi değiştirmez**; başkasının kaydını istemek bulunamadı yanıtı verir. Birden çok müşteriye erişmek gerekiyorsa yönetim tarafını kullanın.

> **Ülke kodla, il ve şehir numarayla konuşur**
> 
> Müşteri tarafında ülke **iki harfli kodla** verilir; yönetim tarafındaki ülke numarası burada geçmez. İl ve şehir ise numara ister. Üç alanı aynı biçimde doldurmaya çalışmak sessiz bir doğrulama hatasına yol açar.

> **Boş liste hata değil, serbest metin işaretidir**
> 
> İl ya da şehir listesi boş dönebilir: platformda o ülke ya da il için veri yoktur. Bu durumda adres alanına **serbest metin** yazılır. Şehir alanı boş liste gelse bile zorunlu kalır; adres kaydı şehirsiz geçmez.

> **Sağlık kontrolü anahtarı doğrulamaz**
> 
> Sağlık ucu kimlik istemez, yani **başarılı yanıtı** anahtarınızın çalıştığı anlamına gelmez. Bir tümleştirmeyi bağlarken ikisini birlikte çağırın: sağlık ucu sunucuyu, anahtar bilgisi kimliği doğrular.

## İlgili Makaleler

- [Hesap Bilgileri](https://dev.wisecp.com/tr/anahtarin-hesabi)
- [Adres Defteri](https://dev.wisecp.com/tr/adres-defteri)