# Para Birimleri ve Kurlar

https://dev.wisecp.com/tr/para-birimleri-ve-kurlar

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 JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/financial/currencies' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
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);
```

```php
$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);
```

```php
// 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 JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/financial/currency-settings' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/financial/currency-settings', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$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);
```

```php
// 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 JavaScript PHP (HTTP) PHP (Dahili)

```bash
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"}'
```

```javascript
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();
```

```php
$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);
```

```php
// 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 JavaScript PHP (HTTP) PHP (Dahili)

```bash
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"}'
```

```javascript
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();
```

```php
$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);
```

```php
// 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 JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/financial/currencies/sync' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
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);
```

```php
$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);
```

```php
// 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 JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/financial/currencies/4' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch(`https://panel.ornek.com/api/v1/admin/financial/currencies/${id}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$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);
```

```php
// 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 JavaScript PHP (HTTP) PHP (Dahili)

```bash
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}'
```

```javascript
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();
```

```php
$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);
```

```php
// 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 JavaScript PHP (HTTP) PHP (Dahili)

```bash
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}'
```

```javascript
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();
```

```php
$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);
```

```php
// 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.

## İlgili Makaleler

- [Vergilendirme Kuralları](https://dev.wisecp.com/tr/vergilendirme-kurallari)
- [İndirim Kuponları](https://dev.wisecp.com/tr/indirim-kuponlari)
- [Fatura Yönetimi](https://dev.wisecp.com/tr/fatura-yonetimi)