Referans Verileri

11 görüntülenme Markdown

Ham numaraları ve kodları okunur etiketlere çeviren yedi başvuru ucu.

Genel Bakış

WISECP API'si ham değer döndürür: durum kodu, ülke numarası, para birimi numarası. Bir arayüz bunları insanın okuyacağı hâle çevirmek zorundadır ve çeviri sözlüğü bu yedi uçta durur.

Bölünme bilinçli. Kaynak uçları ham kalır, çünkü etiket dile ve zamana göre değişir; sözlük ayrı durur, çünkü nadiren değişir ve bir kez çekilip saklanabilir.

Üç uç adres zinciri kurar: ülke, il ve şehir. Zincir tek yönlü çalışır; her adım bir öncekinin numarasını ister.

Referans

Para Birimleri

get/api/v1/admin/reference/currencies
Reference/GetCurrencies admin

Tanımlı para birimlerini numaralarıyla döndürür.

Dönen alanlar data[] — 4
idintPara biriminin numarası. Diğer uçlardaki para birimi alanları bu numarayı taşır.
codestringÜç harfli kodu.
namestringGörünen adı.
is_defaultboolSistemin varsayılan para birimi mi.
Hatalar 1
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/admin/reference/currencies' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://panel.ornek.com/api/v1/admin/reference/currencies', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await res.json();
const byId = Object.fromEntries(data.map((c) => [c.id, c.code]));
$ch = curl_init('https://panel.ornek.com/api/v1/admin/reference/currencies');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Numaralar ISO sayilari DEGILDIR: kurulumun kendi numaralari, kurulumdan kuruluma degisir.
$rows = Api::Reference()->GetCurrencies()['data'];
$code = array_column($rows, 'code', 'id');   // [4 => 'USD']

Ülkeler

get/api/v1/admin/reference/countries
Reference/GetCountries admin

Ülkeleri numara, kod ve çevrilmiş adla döndürür.

Sorgu 1
langstringEtiketlerin döneceği dil. Verilmezse panelin geçerli dili kullanılır.
Dönen alanlar data[] — 3
idintÜlkenin numarası. Diğer uçlardaki ülke alanları bu numarayı taşır.
codestringİki harfli ülke kodu.
namestringÜlkenin adı. İstenen dile çevrilir.
Hatalar 1
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/admin/reference/countries?lang=en' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://panel.ornek.com/api/v1/admin/reference/countries?lang=en', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await res.json();
const name = Object.fromEntries(data.map((c) => [c.id, c.name]));
$ch = curl_init('https://panel.ornek.com/api/v1/admin/reference/countries?lang=en');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Diger uclar ULKE NUMARASI ister, iki harfli kodu degil; esleme burada kurulur.
$rows = Api::Reference()->GetCountries([], ['lang' => 'en'])['data'];
$idOf = array_column($rows, 'id', 'code');   // ['US' => 840]

İller

get/api/v1/admin/reference/states
Reference/GetStates admin

Bir ülkenin illerini döndürür.

Sorgu 1
country_idintreqÜlkenin numarası.
Dönen alanlar data[] — 2
idintİlin numarası.
namestringİlin adı.
Hatalar 2
country_required422Ülke numarası verilmedi.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/admin/reference/states?country_id=840' \
  -H "Authorization: Bearer $API_KEY"
const url = new URL('https://panel.ornek.com/api/v1/admin/reference/states');
url.searchParams.set('country_id', countryId);

const res  = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const { data } = await res.json();
if (! data.length) allowFreeText();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/reference/states?country_id=' . $countryId);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// BOS liste normaldir: her ulkenin il kaydi yoktur, o durumda adres alani serbest metindir.
$states = Api::Reference()->GetStates([], ['country_id' => $countryId])['data'];
$freeText = ! $states;

Şehirler

get/api/v1/admin/reference/cities
Reference/GetCities admin

Bir ilin şehirlerini döndürür.

Sorgu 1
state_idintreqİlin numarası.
Dönen alanlar data[] — 2
idintŞehrin numarası.
namestringŞehrin adı.
Hatalar 2
state_required422İl numarası verilmedi.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/admin/reference/cities?state_id=6' \
  -H "Authorization: Bearer $API_KEY"
const url = new URL('https://panel.ornek.com/api/v1/admin/reference/cities');
url.searchParams.set('state_id', stateId);

const res  = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/reference/cities?state_id=' . $stateId);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Zincir tek yonludur: sehir icin ONCE ulke, sonra il numarasi cozulmelidir.
$states = Api::Reference()->GetStates([], ['country_id' => $countryId])['data'];
$cities = Api::Reference()->GetCities([], ['state_id' => $states[0]['id']])['data'];

Diller

get/api/v1/admin/reference/languages
Reference/GetLanguages admin

Müşteriye açık dilleri sırasıyla döndürür.

Dönen alanlar data[] — 2
codestringDilin anahtarı. Diğer uçların dil parametresine bu değer verilir.
namestringDilin görünen adı.
Hatalar 1
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/admin/reference/languages' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://panel.ornek.com/api/v1/admin/reference/languages', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await res.json();
renderLanguagePicker(data);
$ch = curl_init('https://panel.ornek.com/api/v1/admin/reference/languages');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Yalniz ACIK diller gelir; kapali dilleri de gormek icin dil yonetim ucunu kullanin.
$open = Api::Reference()->GetLanguages()['data'];
$all  = Api::Languages()->GetLanguages()['data'];

Ödeme Döngüleri

get/api/v1/admin/reference/cycles
Reference/GetCycles admin

Faturalama döngüsü kodlarını okunur etiketleriyle eşler.

Sorgu 1
langstringEtiketlerin döneceği dil. Verilmezse panelin geçerli dili kullanılır.
Dönen alanlar data[] — 2
codestringDöngünün kodu. Sipariş ve hizmet uçları bu kodu kullanır.
labelstringÇevrilmiş etiketi.
Hatalar 1
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/admin/reference/cycles?lang=en' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://panel.ornek.com/api/v1/admin/reference/cycles?lang=en', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await res.json();
const label = Object.fromEntries(data.map((c) => [c.code, c.label]));
$ch = curl_init('https://panel.ornek.com/api/v1/admin/reference/cycles?lang=en');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Liste ETIKET kaynagidir, gecerlilik kapisi degil: bir urunun hangi donguleri sattigi ayri sorudur.
$labels = array_column(Api::Reference()->GetCycles()['data'], 'label', 'code');
$sold   = Api::Products()->GetProduct(['id' => $pid])['data']['prices'] ?? [];

Durum Kodları

get/api/v1/admin/reference/statuses
Reference/GetStatuses admin

Bir varlık türünün durum kodlarını etiketleriyle eşler.

Sorgu 2
entitystringDurumları istenen tür: client ya da product. Verilmezse müşteri alınır.
langstringEtiketlerin döneceği dil. Verilmezse panelin geçerli dili kullanılır.
Dönen alanlar data — 2
entitystringİstenen tür.
statusesobject[]Kod ve etiket çiftleri.
valuestringDurumun kodu.
labelstringÇevrilmiş etiketi.
Hatalar 2
entity_invalid422Bilinmeyen tür. Yanıtın ayrıntısı desteklenen listeyi verir.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/admin/reference/statuses?entity=client&lang=en' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://panel.ornek.com/api/v1/admin/reference/statuses?entity=client', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await res.json();
const label = Object.fromEntries(data.statuses.map((s) => [s.value, s.label]));
$ch = curl_init('https://panel.ornek.com/api/v1/admin/reference/statuses?entity=client');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Yalniz IKI tur vardir: fatura, siparis ve talep durumlari bu ucta YOK, kendi makalelerinde.
$out = Api::Reference()->GetStatuses([], ['entity' => 'client'])['data'];
$map = array_column($out['statuses'], 'label', 'value');

Tuzaklar

Numaralar kuruluma ait, evrensel değil

Para birimi numarası kurulumun kendi kaydını gösterir; iki kurulumda aynı para birimi farklı numara taşıyabilir. Numarayı koda gömmeyin, bu listeden çözün. Ülke numaraları da aynı kuralı izler; taşınabilir olan kod, numara değil.

Boş il listesi hata anlamına gelmez

Her ülkenin il kaydı yoktur; böyle bir ülkede il ucu boş liste döner ve bu beklenen davranış. Adres formu o durumda seçim yerine serbest metin sunmalı. Boş listeyi hata sayan bir arayüz o ülkelerde adres kaydını tümüyle engeller.

Durum listesi yalnız iki türü kapsar

Durum ucu müşteri ve ürün durumlarını verir. Fatura, sipariş, hizmet ve destek talebi durumları burada bulunmaz; onların kod listeleri kendi makalelerinde durur. Bilinmeyen bir tür istemek hata döndürür ve yanıtın ayrıntısı desteklenen listeyi gösterir.

Etiket dili istekle gelir, anahtarla değil

Dil parametresi verilmezse etiketler panelin geçerli diliyle döner. Bir arka plan işi ya da rapor üreticisi için bu dil öngörülemez olabilir. Sonucu saklayacaksanız dili her zaman açıkça yazın.

Bir kez çekin, saklayın, nadiren tazeleyin

Bu listeler her istekte çekilmek için değildir. Ülke ve şehir verisi neredeyse hiç değişmez, para birimi ve dil ise ayar değiştiğinde değişir. Uygulama açılışında bir kez çekip bellekte tutmak hem hızlı hem de kotanızı boşa harcamaz.

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ı