Para Birimleri ve Kurlar

1.8k görüntülenme Markdown

Para birimlerini, kurlarını ve kur sağlayıcısını yöneten sekiz uç.

Genel Bakış

Kurulumun bir ana para birimi vardır ve diğerlerinin kuru ona göre tutulur. Fiyatlar, faturalar ve raporlar bu noktadan geçerek çevrilir.

Kurlar ya elle yazılır ya da bir sağlayıcı modülünden gelir. Sağlayıcı seçilir, sıklığı belirlenir ve zamanlanmış görev kurları tazeler; ayrıca elle tetikleyen bir uç da vardır.

Bir para birimi ülkelere bağlanabilir: ziyaretçinin ülkesi hangi para birimini göreceğini belirler. Bir ülke aynı anda tek bir para birimine bağlanır.

Referans

Para Birimlerini Listeleme

get/api/v1/admin/financial/currencies
Financial/GetCurrencies admin

Kurulumdaki bütün para birimlerini kurlarıyla döndürür.

Dönen alanlar data[] — 13
idintPara biriminin numarası.
codestringUluslararası kodu.
namestringPara biriminin adı.
statusstringEtkin mi kapalı mı.
localboolKurulumun ana para birimi mi. Bütün çevrimler bunun üzerinden yapılır.
hiddenboolMüşteriye gösterilip gösterilmediği.
ratefloatAna para birimine göre kuru.
formatintSayının nasıl biçimleneceği.
prefixstringTutarın önüne gelen işaret.
suffixstringTutarın arkasına gelen işaret.
countrystringVarsayılan ülkesi.
countriesstring[]Bu para birimine bağlanmış ülkeler. Ziyaretçinin ülkesine göre seçilir.
modulesstring[]Bu para birimiyle çalışan ödeme yöntemleri.
Hatalar 1
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/admin/financial/currencies' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.ornek.com/api/v1/admin/financial/currencies', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();

const base = data.find((c) => c.local);
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/currencies');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Kurlar ANA para birimine goredir; iki yabanci para arasinda cevirim once ondan gecer.
$all  = Api::Financial()->GetCurrencies()['data'];
$base = current(array_filter($all, fn ($c) => $c['local']));

Kur Ayarlarını Getirme

get/api/v1/admin/financial/currency-settings
Financial/GetCurrencySettings admin

Kurları hangi sağlayıcının verdiğini ve ne sıklıkta güncellendiğini döndürür.

Dönen alanlar data — 5
modulestringKurları sağlayan modül.
auto_rate_enabledboolKurların kendiliğinden güncellenip güncellenmediği.
update_periodstringGüncelleme sıklığı: saatlik ya da günlük.
last_run_atstring | nullSon güncelleme anı.
available_modulesstring[]Kurulu kur sağlayıcıları.
Hatalar 1
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/admin/financial/currency-settings' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.ornek.com/api/v1/admin/financial/currency-settings', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/currency-settings');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Son calisma ani ESKIYSE kurlar bayattir; otomatik guncelleme sessizce durmus olabilir.
$s = Api::Financial()->GetCurrencySettings()['data'];

Kur Ayarlarını Yazma

put/api/v1/admin/financial/currency-settings
Financial/UpdateCurrencySettings admin

Kur sağlayıcısını ve güncelleme düzenini değiştirir.

Gövde 4
modulestringKullanılacak kur sağlayıcısı.
auto_rate_enabledboolKurların kendiliğinden güncellenmesini açar.
update_periodstringGüncelleme sıklığı. Öntanımlı olarak günlük.
module_dataobjectSağlayıcının kendi ayarları.
Dönen alanlar data — 5
dataobjectGüncel ayarlar. Getirme ucuyla aynı şekildedir.
Hatalar 2
module_not_found422Sağlayıcı bulunamadı.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl -X PUT 'https://panel.ornek.com/api/v1/admin/financial/currency-settings' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"module":"WAtlas","auto_rate_enabled":true,"update_period":"day"}'
const res = await fetch('https://panel.ornek.com/api/v1/admin/financial/currency-settings', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    module: 'WAtlas',
    auto_rate_enabled: true,
    update_period: 'day',
  }),
});

const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/currency-settings');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'module'            => 'WAtlas',
        'auto_rate_enabled' => true,
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Saglayiciyi degistirmeden ONCE sinama ucundan gecirin; yanlis anahtar sessiz bayatlik uretir.
Api::Financial()->TestCurrencyModule(['module' => 'WAtlas']);
Api::Financial()->UpdateCurrencySettings(['module' => 'WAtlas']);

Sağlayıcıyı Sınama

post/api/v1/admin/financial/currency-modules/test
Financial/TestCurrencyModule admin kaydetmez

Bir kur sağlayıcısından örnek kur çekerek bağlantıyı sınar.

Gövde 2
modulestringreqSınanacak sağlayıcı.
module_dataobjectSınama için kullanılacak geçici ayarlar. Kaydedilmez, yalnız bu çağrıda kullanılır.
Dönen alanlar data — 2
localstringAna para biriminin kodu.
ratesobjectSağlayıcıdan gelen örnek kurlar.
Hatalar 6
module_required422Sağlayıcı adı verilmedi.
module_not_found422Sağlayıcı bulunamadı.
not_supported422Sağlayıcı kur vermiyor.
no_local422Ana para birimi tanımlı değil.
test_failed422Sağlayıcı hiç kur döndürmedi.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl -X POST 'https://panel.ornek.com/api/v1/admin/financial/currency-modules/test' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"module":"WAtlas"}'
const res = await fetch('https://panel.ornek.com/api/v1/admin/financial/currency-modules/test', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ module: 'WAtlas' }),
});

const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/currency-modules/test');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['module' => 'WAtlas']),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Sinama CANLI baglanti kurar ve hicbir sey kaydetmez; henuz secilmemis saglayici da sinanir.
$r = Api::Financial()->TestCurrencyModule([
    'module'      => 'WAtlas',
    'module_data' => ['WAtlas' => ['api_key' => $key]],
])['data'];

Kurları Güncelleme

post/api/v1/admin/financial/currencies/sync
Financial/SyncCurrencyRates admin anında çalışır

Kurları sağlayıcıdan elle çeker.

Gövde —
——Gövde gerekmez. Sağlayıcı ve periyot çağrıdan değil para birimi ayarlarından gelir; boş gövde gönderin.
Dönen alanlar data — 3
rates_changedboolKurlar değişti mi.
reasonstringDeğişmediyse neden. Yalnız güncelleme atlandığında gelir.
last_run_atstring | nullGüncellemenin anı.
Hatalar 2
sync_failed422Kurlar çekilemedi. message kur modülünün kendi hata mesajını taşır; modül mesaj vermediyse sabit bir "kullanılabilir kur yok" cümlesi döner.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl -X POST 'https://panel.ornek.com/api/v1/admin/financial/currencies/sync' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch('https://panel.ornek.com/api/v1/admin/financial/currencies/sync', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await res.json();
if (! data.rates_changed) console.warn(data.reason);
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/currencies/sync');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Basarili bir cagri kurlarin DEGISTIGI anlamina gelmez; sebep alanini okuyun.
$r = Api::Financial()->SyncCurrencyRates()['data'];
if (! $r['rates_changed']) error_log($r['reason'] ?? 'skipped');

Para Birimi Detayı

get/api/v1/admin/financial/currencies/{id}
Financial/GetCurrency admin

Tek bir para birimini döndürür.

Dönen alanlar data — 13
idintPara biriminin numarası.
codestringUluslararası kodu.
namestringPara biriminin adı.
statusstringEtkin mi kapalı mı.
localboolKurulumun ana para birimi mi. Bütün çevrimler bunun üzerinden yapılır.
hiddenboolMüşteriye gösterilip gösterilmediği.
ratefloatAna para birimine göre kuru.
formatintSayının nasıl biçimleneceği.
prefixstringTutarın önüne gelen işaret.
suffixstringTutarın arkasına gelen işaret.
countrystringVarsayılan ülkesi.
countriesstring[]Bu para birimine bağlanmış ülkeler. Ziyaretçinin ülkesine göre seçilir.
modulesstring[]Bu para birimiyle çalışan ödeme yöntemleri.
Hatalar 2
not_found404Para birimi bulunamadı.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl 'https://panel.ornek.com/api/v1/admin/financial/currencies/4' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch(`https://panel.ornek.com/api/v1/admin/financial/currencies/${id}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/currencies/' . $id);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Ana para biriminin kuru DAIMA birdir; onu degistirmeye calismak anlamsizdir.
$c = Api::Financial()->GetCurrency(['id' => $id])['data'];

Para Birimini Güncelleme

patch/api/v1/admin/financial/currencies/{id}
Financial/UpdateCurrency admin ana para birimi değiştirilebilir

Para biriminin görünümünü, kurunu ve bağlarını değiştirir.

Gövde 9
namestringPara biriminin adı.
prefixstringTutarın önüne gelen işaret.
suffixstringTutarın arkasına gelen işaret.
formatintSayının nasıl biçimleneceği.
ratefloatAna para birimine göre kuru. Otomatik güncelleme açıksa bir sonraki koşuda üzerine yazılır.
hiddenboolMüşteriden gizler.
countriesstring[]Bu para birimine bağlanacak ülkeler. Bir ülke tek bir para birimine bağlanabilir.
modulesstring[]Bu para birimiyle çalışacak ödeme yöntemleri.
localboolBu para birimini kurulumun ana para birimi yapar. Bütün çevrimlerin dayandığı nokta değişir.
Dönen alanlar data — 13
dataobjectGüncel para birimi. Detay ucuyla aynı şekildedir.
Hatalar 4
not_found404Para birimi bulunamadı.
country_conflict422Ülke başka bir para birimine bağlı.
currency_save_failed422Kayıt yazılamadı.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl -X PATCH 'https://panel.ornek.com/api/v1/admin/financial/currencies/4' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"US Dollar","prefix":"$","hidden":false}'
const res = await fetch(`https://panel.ornek.com/api/v1/admin/financial/currencies/${id}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'US Dollar', prefix: '$', hidden: false }),
});

const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/currencies/' . $id);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['name' => 'US Dollar', 'prefix' => '$']),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Ana para birimi alanini TEK BASINA bir bayrak sanmayin: kurulumun para tabani degisir
// ve butun kurlar yeniden hesaplanir.
Api::Financial()->UpdateCurrency(['id' => $id, 'prefix' => '$']);

Para Birimini Açma ve Kapatma

put/api/v1/admin/financial/currencies/{id}/status
Financial/SetCurrencyStatus admin

Para biriminin kullanılabilir olup olmadığını belirler.

Gövde 1
statusboolreqPara birimini açar ya da kapatır.
Dönen alanlar data — 13
dataobjectGüncel para birimi. Detay ucuyla aynı şekildedir.
Hatalar 4
not_found404Para birimi bulunamadı.
local_currency422Ana para birimi kapatılamaz.
blocked_by_gate422Bir kanca değişimi reddetti.
insufficient_scope403Anahtar gerekli kapsamı taşımıyor.
İstek 
curl -X PUT 'https://panel.ornek.com/api/v1/admin/financial/currencies/4/status' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status":true}'
const res = await fetch(`https://panel.ornek.com/api/v1/admin/financial/currencies/${id}/status`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ status: true }),
});

const body = await res.json();
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/currencies/' . $id . '/status');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['status' => true]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Kapatmak o para birimindeki GECMIS faturalari bozmaz; yalniz yeni secimleri engeller.
Api::Financial()->SetCurrencyStatus(['id' => $id, 'status' => false]);

Tuzaklar

Ana para birimini değiştirmek her şeyi kaydırır

Güncelleme gövdesindeki ana para birimi alanı sıradan bir seçenek değildir: kurulumun para tabanını taşır, ayar dosyasına yazar ve bütün kurları yeniden hesaplattırır. Fiyatlar aynı sayıda kalır ama artık başka bir birimi anlatır. Bu alanı yanlışlıkla göndermek en pahalı hatalardan biridir.

Elle yazılan kur bir sonraki güncellemede silinir

Otomatik güncelleme açıkken bir kuru elle yazmak geçici bir düzeltmedir: sağlayıcı bir sonraki koşuda üzerine yazar. Kalıcı bir kur istiyorsanız önce otomatik güncellemeyi kapatın. Elle yazdıktan sonra "kur geri döndü" durumunun sebebi budur.

Başarılı güncelleme kurların değiştiği anlamına gelmez

Güncelleme ucu, kurları çekmeden döndüğü durumları da başarılı sayar ve sebebi ayrı bir alanda yazar. Sağlayıcı yanıt vermemiş, süre dolmamış ya da ayar kapalı olabilir. Yalnız yanıt koduna bakan bir izleme, kurların aylardır bayat olduğunu göremez.

Bir ülke tek bir para birimine bağlanır

Bir ülkeyi bir para birimine bağlarken o ülke başka bir para biriminde duruyorsa çağrı reddedilir. Ülke listesi gönderildiğinde yerine geçer, yani eksik gönderilen bir ülke bağdan düşer. Ülkeleri değiştirirken mevcut listeyi okuyup üzerine ekleyin.

Sağlayıcıyı seçmeden önce sınayın

Sınama ucu canlı bir bağlantı kurar ve hiçbir şey kaydetmez; henüz seçilmemiş bir sağlayıcıyı geçici ayarlarla deneyebilirsiniz. Sınamadan geçirmeden sağlayıcı değiştirmek, kurların sessizce güncellenmemesine yol açar: hata görünmez, yalnız son güncelleme anı yerinde kalır.

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ı