Adres Defteri

1.7k görüntülenme Markdown

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 'https://panel.ornek.com/api/v1/client/addresses' \
  -H "Authorization: Bearer $CLIENT_KEY"
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);
$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);
// 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 'https://panel.ornek.com/api/v1/client/addresses/12' \
  -H "Authorization: Bearer $CLIENT_KEY"
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();
$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);
// 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 -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":"[email protected]","country":"TR","state":"34","city":"1441","address":"Sample St 42","zipcode":"34710"}'
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: '[email protected]',
    country: 'TR', state: String(stateId), city: String(cityId),
    address: 'Sample St 42', zipcode: '34710',
  }),
});

const { data } = await res.json();
$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);
// 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 -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":"[email protected]","country":"TR","state":"34","city":"1441","address":"New St 7","zipcode":"34710"}'
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),
});
$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);
// 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 -X POST 'https://panel.ornek.com/api/v1/client/addresses/12/default' \
  -H "Authorization: Bearer $CLIENT_KEY"
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();
$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);
// 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 -X DELETE 'https://panel.ornek.com/api/v1/client/addresses/12' \
  -H "Authorization: Bearer $CLIENT_KEY"
const res = await fetch(`https://panel.ornek.com/api/v1/client/addresses/${id}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${clientKey}` },
});

const body = await res.json();
$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);
// 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.

Faydalı oldu mu?

Geri bildiriminiz için teşekkürler!

Hâlâ Yardıma mı İhtiyacınız Var?

Yukarıda bulamadığınız her şey için destek ekibimiz her zaman yanınızda.

Bize Ulaşın Destek Talebi Oluştur

Oturumunuzu açık tutmak, dil ve para birimi tercihinizi hatırlamak ve siteyi geliştirmek için çerez kullanıyoruz. Çerez Politikası