# Adres Defteri

https://dev.wisecp.com/tr/adres-defteri

Hesabın fatura profillerini yöneten altı uç.

## Genel Bakış

Adres defteri hesabın **fatura profillerini** tutar. Her kayıt bir kişiyi, bir adresi ve o adrese düşen vergi oranını taşır; faturalar buradan kesilir.

Bir profil her zaman **varsayılan olur** ve hesap asla varsayılansız kalmaz: ilk eklenen kendiliğinden varsayılan olur, varsayılan silinirse sıradaki terfi eder.

Konum alanları başvuru zincirinden doldurulur: ülke kodu, il numarası, şehir numarası. Platformda veri bulunmayan yerde aynı alanlara serbest metin yazılır.

## Referans

### Adresleri Listeleme

get/api/v1/client/addresses

`Addresses/GetAddresses` anahtarın sahibi

Hesabın fatura profillerini döndürür.

Dönen alanlar data[] — 18

idintAdresin numarası.

labelstringSerbest etiket.

full_namestringİlgili kişinin tam adı.

namestringAdı.

surnamestringSoyadı.

kindstringKişi türü: bireysel ya da kurumsal.

emailstringKişinin e-postası.

phonestringKişinin telefonu.

identitystringKimlik numarası.

companyobjectŞirket bilgileri. Ad, vergi numarası ve vergi dairesi taşır.

countrystringÜlke kodu.

stateobjectİl. Numara ve ad taşır; serbest metinle girilmişse numara sıfırdır.

cityobjectŞehir. Numara ve ad taşır; serbest metinle girilmişse numara sıfırdır.

addressstringAçık adres.

zipcodestringPosta kodu.

tax_ratefloatBu adrese düşen vergi oranı. Sunucu adresten hesaplar.

is_defaultboolVarsayılan fatura profili mi.

notificationsarrayKişi başına bildirim kanalları. Altı kategorinin her biri için e-posta ve kısa mesaj.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

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

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

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

const { data } = await res.json();
const billing = data.find((a) => a.is_default);
```

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

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

```php
// Varsayilan kisi HER ZAMAN ilk siradadir; ayrica aramak yerine ilk kaydi alabilirsiniz.
$rows = Kernel::internal('client:Addresses/GetAddresses', ['owner_id' => $uid])['data'];
$default = $rows[0] ?? null;
```

### Tek Adresi Okuma

get/api/v1/client/addresses/{id}

`Addresses/GetAddress` anahtarın sahibi

Hesabın adreslerinden birini döndürür.

Dönen alanlar data — 18

dataobjectAdres kaydı. Listedeki öğeyle aynı şekildedir.

Hatalar 2

not_found404Böyle bir adres yok ya da başka bir müşteriye ait.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

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

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

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

if (res.status === 404) return notYours();

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

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

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

```php
// Baskasinin adresi de BULUNAMADI doner: var olup olmadigini bu uctan ogrenemezsiniz.
$a = Kernel::internal('client:Addresses/GetAddress', ['owner_id' => $uid, 'id' => $id]);
```

### Adres Ekleme

post/api/v1/client/addresses

`Addresses/CreateAddress` fatura profili

Hesaba yeni bir fatura profili ekler.

Gövde 16

namestringreqİlgili kişinin adı.

surnamestringreqSoyadı.

emailstringreqGeçerli bir e-posta.

countrystringreqÜlke kodu. Başvuru ucundan alınır.

statestringreqİl. Listeden numara, liste boşsa serbest metin.

citystringreqŞehir. Listeden numara, liste boşsa serbest metin.

addressstringreqAçık adres.

zipcodestringreqPosta kodu. En çok yirmi karakter.

kindstringKişi türü. Öntanımlı olarak bireysel.

companyobjectŞirket bilgileri. Kurumsal kişide ad zorunludur.

labelstringSerbest etiket.

phonestringKişinin telefonu.

identitystringKimlik numarası.

notificationsobjectKanal matrisi. Tam değiştirmedir; hiç gönderilmezse hepsi açılır.

is_defaultboolBunu varsayılan profil yap.

overwrite_invoicesboolAçık faturaları bu adrese yeniden yaz.

Dönen alanlar data — 18

dataobjectOluşan adres. Okuma ucuyla aynı şekildedir.

Hatalar 6

name_required422Zorunlu bir alan eksik ya da geçersiz. Soyad, e-posta, ülke, il, şehir, adres ve posta kodu aynı biçimde reddedilir.

company_name_required422Kurumsal kişide şirket adı boş.

notifications_invalid422Bildirim matrisi bozuk ya da bilinmeyen kategori taşıyor.

contact_rejected422Bir kanca kaydı reddetti.

address_add_failed500Adres 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/client/addresses' \
  -H "Authorization: Bearer $CLIENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Jane","surname":"Cooper","email":"jane@example.com","country":"TR","state":"34","city":"1441","address":"Sample St 42","zipcode":"34710"}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/client/addresses', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${clientKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Jane', surname: 'Cooper', email: 'jane@example.com',
    country: 'TR', state: String(stateId), city: String(cityId),
    address: 'Sample St 42', zipcode: '34710',
  }),
});

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

```php
$ch = curl_init('https://panel.ornek.com/api/v1/client/addresses');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $clientKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($contact),
]);

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

```php
// ILK adres kendiliginden VARSAYILAN olur; bayrak gondermeseniz de hesap profilsiz kalmaz.
$a = Kernel::internal('client:Addresses/CreateAddress', ['owner_id' => $uid] + $contact)['data'];
$isFirst = $a['is_default'];
```

### Adresi Güncelleme

put/api/v1/client/addresses/{id}

`Addresses/UpdateAddress` tam gövde

Adresin tamamını yeniden yazar.

Gövde 16

namestringreqİlgili kişinin adı.

surnamestringreqSoyadı.

emailstringreqGeçerli bir e-posta.

countrystringreqÜlke kodu. Başvuru ucundan alınır.

statestringreqİl. Listeden numara, liste boşsa serbest metin.

citystringreqŞehir. Listeden numara, liste boşsa serbest metin.

addressstringreqAçık adres.

zipcodestringreqPosta kodu. En çok yirmi karakter.

kindstringKişi türü. Öntanımlı olarak bireysel.

companyobjectŞirket bilgileri. Kurumsal kişide ad zorunludur.

labelstringSerbest etiket.

phonestringKişinin telefonu.

identitystringKimlik numarası.

notificationsobjectKanal matrisi. Tam değiştirmedir; hiç gönderilmezse hepsi açılır.

is_defaultboolBunu varsayılan profil yap.

overwrite_invoicesboolAçık faturaları bu adrese yeniden yaz.

Dönen alanlar data — 18

dataobjectGüncel adres. Okuma ucuyla aynı şekildedir.

Hatalar 5

not_found404Böyle bir adres yok ya da başka bir müşteriye ait.

name_required422Zorunlu bir alan eksik ya da geçersiz.

company_name_required422Kurumsal kişide şirket adı boş.

contact_rejected422Bir kanca kaydı reddetti.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

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

```bash
curl -X PUT 'https://panel.ornek.com/api/v1/client/addresses/12' \
  -H "Authorization: Bearer $CLIENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Jane","surname":"Cooper","email":"jane@example.com","country":"TR","state":"34","city":"1441","address":"New St 7","zipcode":"34710"}'
```

```javascript
const cur = await fetch(`https://panel.ornek.com/api/v1/client/addresses/${id}`, {
  headers: { Authorization: `Bearer ${clientKey}` },
}).then((r) => r.json());

const body = {
  ...cur.data,
  state: String(cur.data.state.id || cur.data.state.name),
  city:  String(cur.data.city.id  || cur.data.city.name),
  address: 'New St 7',
};

await fetch(`https://panel.ornek.com/api/v1/client/addresses/${id}`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${clientKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
});
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/client/addresses/' . $id);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $clientKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($contact),
]);

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

```php
// Okunan il/sehir NESNEDIR, gonderilen ise DUZ DEGER: geri yazmadan once numarayi cikarin.
$a = Kernel::internal('client:Addresses/GetAddress', ['owner_id' => $uid, 'id' => $id])['data'];
$a['state'] = (string) ($a['state']['id'] ?: $a['state']['name']);
$a['city']  = (string) ($a['city']['id']  ?: $a['city']['name']);

Kernel::internal('client:Addresses/UpdateAddress', ['owner_id' => $uid, 'id' => $id] + $a);
```

### Varsayılanı Taşıma

post/api/v1/client/addresses/{id}/default

`Addresses/SetDefaultAddress` hesabın ülkesi izler

Bu adresi varsayılan fatura profili yapar.

Gövde —

——Gövde gerekmez, boş gönderin. Adresi adresteki kimlik belirler.

Dönen alanlar data — 18

dataobjectArtık varsayılan olan adres.

Hatalar 2

not_found404Böyle bir adres yok ya da başka bir müşteriye ait.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

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

```bash
curl -X POST 'https://panel.ornek.com/api/v1/client/addresses/12/default' \
  -H "Authorization: Bearer $CLIENT_KEY"
```

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

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

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

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

```php
// Varsayilani DUSURMEK diye bir islem yok: baska bir adresi varsayilan yapmak tek yoldur.
Kernel::internal('client:Addresses/SetDefaultAddress', ['owner_id' => $uid, 'id' => $other]);
```

### Adresi Silme

delete/api/v1/client/addresses/{id}

`Addresses/DeleteAddress` anahtarın sahibi

Adresi siler ve gerekiyorsa varsayılanı devreder.

Dönen alanlar data — 2

deletedboolSilme çalıştı mı.

idintSilinen adresin numarası.

Hatalar 2

not_found404Böyle bir adres yok ya da başka bir müşteriye ait.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

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

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

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

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

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

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

```php
// Varsayilani silmek yasak DEGIL: siradaki adres kendiliginden varsayilana terfi eder.
Kernel::internal('client:Addresses/DeleteAddress', ['owner_id' => $uid, 'id' => $id]);
$now = Kernel::internal('client:Addresses/GetAddresses', ['owner_id' => $uid])['data'][0] ?? null;
```

## Tuzaklar

> **İl ve şehir okumada nesne, yazmada düz değerdir**
> 
> Okuma uçları il ve şehri **numara ve ad taşıyan bir nesne** olarak döndürür; yazma uçları ise düz bir değer bekler. Okuduğunuz kaydı doğrudan geri göndermek bu iki alanda doğrulama hatası verir. Yazmadan önce numarayı çıkarın, numara sıfırsa adı gönderin.

> **Güncelleme kaydın tamamını ister**
> 
> Güncelleme gövdesi **adresin tamamını** ister: oluşturmadaki zorunlu alanlar burada da geçerli. Yalnız posta kodunu değiştirmek için bile tam kaydı göndermelisiniz. Tek kolaylık bildirim matrisinde: gönderilmezse kayıtlı değerini korur.

> **Varsayılanı taşımak hesabın ülkesini değiştirir**
> 
> Bir adresi varsayılan yapmak hesabın ülkesini **o adresin ülkesine** çeker. Ülke ise vergi oranını ve bazı ürünlerin görünürlüğünü belirler, yani basit görünen bu işlem fiyatları etkileyebilir. Farklı ülkedeki bir profili varsayılan yapmadan önce sonucu düşünün.

> **Açık faturaları yeniden yazma isteğe bağlıdır**
> 
> Yeni bir adres eklerken açık faturaların bu adrese taşınmasını isteyebilirsiniz. İstemezseniz **eski adresle kesilmiş** faturalar öyle kalır ve müşteri iki farklı adres görür. Vergi numarası değişikliği gibi durumlarda bu bayrağı düşünün.

> **Yabancı adres bulunamadı der**
> 
> Başka bir müşterinin adres numarasını sormak `404` döndürür, yetki hatası değil. Bu bilinçli bir seçim; yanıt **o numaranın var olup olmadığını** da açığa vurmaz. Bulunamadı yanıtını "silinmiş" diye yorumlamayın.

> **Her kişi kendi bildirim matrisini taşır**
> 
> Bildirim tercihleri hem hesap düzeyinde hem **kişi düzeyinde** tutulur: faturalar bir kişiye, destek başka birine gidebilir. Adres yazarken matris gönderilmezse oluşturmada hepsi açılır, güncellemede ise kayıtlı hâli korunur.

## İlgili Makaleler

- [Anahtarın Hesabı](https://dev.wisecp.com/tr/anahtarin-hesabi)
- [Client API İlk Çağrılar](https://dev.wisecp.com/tr/client-api-ilk-cagrilar)
- [Fatura Ödeme](https://dev.wisecp.com/tr/fatura-odeme-api)