# Vergilendirme Kuralları

https://dev.wisecp.com/tr/vergilendirme-kurallari

Vergi oranlarını, ülke kurallarını ve fatura belgesi ayarlarını yöneten yedi uç.

## Genel Bakış

Vergi üç katmanda kurulur. En altta **temel ayar** vardır: vergilendirme açık mı, varsayılan oran nedir ve vergi tutarın içinde mi yoksa üstünde mi.

Üstünde **ülke ve eyalet kuralları** durur. Bir müşterinin adresine uyan kural varsa oran ondan gelir; eyalet kuralı ülke kuralından, ülke kuralı da varsayılan orandan önceliklidir.

Ayrı bir grup ise **fatura belgesinin kendisiyle** ilgilidir: numaralandırma biçimi, resmileştirme, kurumsal müşteriden istenecek vergi alanları ve basılı fatura gönderimi.

## Referans

### Vergi Ayarlarını Getirme

get/api/v1/admin/financial/taxation

`Financial/GetTaxation` admin

Verginin açık olup olmadığını, oranını ve nasıl hesaplandığını döndürür.

Dönen alanlar data — 4

enabledboolVergilendirmenin açık olup olmadığı.

ratefloatVarsayılan vergi oranı.

taxation_typestringVerginin tutarın içinde mi üstünde mi olduğu.

send_bill_to_addressobjectBasılı fatura gönderimi: açık mı, ücreti ve para birimi.

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/taxation' \
  -H "Authorization: Bearer $API_KEY"
```

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

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

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

```php
// Buradaki oran VARSAYILANDIR; musterinin ulkesine kural tanimliysa o kural once gelir.
$t = Api::Financial()->GetTaxation()['data'];
```

### Vergi Ayarlarını Yazma

put/api/v1/admin/financial/taxation

`Financial/UpdateTaxation` admin

Vergilendirmeyi açar, oranını ve hesaplama biçimini yazar.

Gövde 3

enabledboolVergilendirmeyi açar ya da kapatır.

ratefloatVarsayılan vergi oranı.

taxation_typestringVerginin tutarın içinde mi üstünde mi olacağı.

Dönen alanlar data — 4

dataobjectGüncel vergi ayarları. Getirme ucuyla aynı şekildedir.

Hatalar 1

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/taxation' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"enabled":true,"rate":20,"taxation_type":"exclusive"}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/financial/taxation', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    enabled: true,
    rate: 20,
    taxation_type: 'exclusive',
  }),
});

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

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/taxation');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['enabled' => true, 'rate' => 20]),
]);

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

```php
// Hesaplama bicimini degistirmek AYNI fiyati farkli bir toplama cevirir; ilan ettiginiz
// fiyatlarin hangisini anlattigini bir kez daha dusunun.
Api::Financial()->UpdateTaxation(['taxation_type' => 'inclusive']);
```

### Gelişmiş Ayarları Getirme

get/api/v1/admin/financial/taxation/advanced

`Financial/GetTaxationAdvanced` admin

Fatura numaralandırma ve kurumsal vergi alanlarının ayarlarını döndürür.

Dönen alanlar data — 18

invoice_show_requires_loginboolFaturayı görmek için giriş gerekip gerekmediği.

payment_commission_taxboolÖdeme komisyonunun ve taksit farkının faturanın oranıyla vergilendirilmesi.

delete_invoice_item_aocboolFatura kalemi silmeye izin verilmesi.

invoice_formalization_statusboolResmileştirmenin açık olup olmadığı.

firstly_create_invoiceboolSiparişten önce faturanın kesilmesi.

balance_taxationstringBakiye yüklemesinin nasıl vergilendirileceği.

invoice_special_notestringHer faturaya düşülecek not.

pdf_fontstringBelgede kullanılacak yazı tipi.

invoice_number_formatstringFatura numarasının biçimi. Numaranın geleceği yeri işaretleyen yer tutucuyu taşımalı.

invoice_number_format_statusboolFatura numara biçiminin kullanılıp kullanılmadığı.

paid_invoice_number_formatstringÖdenmiş fatura numarasının biçimi.

paid_invoice_number_format_statusboolÖdenmiş fatura biçiminin kullanılıp kullanılmadığı.

invoice_incrementintFatura numaralarının başlayacağı sayı.

paid_invoice_incrementintÖdenmiş fatura numaralarının başlayacağı sayı.

send_bill_to_addressobjectBasılı fatura gönderimi: açık mı, ücreti ve para birimi.

company_tax_officeobjectVergi dairesi alanı: gösterilip gösterilmediği ve zorunlu olup olmadığı.

company_tax_numberobjectVergi numarası alanı: gösterimi, zorunluluğu ve doğrulanması.

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/taxation/advanced' \
  -H "Authorization: Bearer $API_KEY"
```

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

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/taxation/advanced');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

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

```php
// Iki ayri numara dizisi vardir: normal fatura ve ODENMIS fatura icin.
$a = Api::Financial()->GetTaxationAdvanced()['data'];
```

### Gelişmiş Ayarları Yazma

put/api/v1/admin/financial/taxation/advanced

`Financial/UpdateTaxationAdvanced` admin

Gönderdiğiniz gelişmiş vergi ve fatura ayarlarını değiştirir.

Gövde 18

invoice_show_requires_loginboolFaturayı görmek için giriş gerekip gerekmediği.

payment_commission_taxboolÖdeme komisyonunun ve taksit farkının faturanın oranıyla vergilendirilmesi.

delete_invoice_item_aocboolFatura kalemi silmeye izin verilmesi.

invoice_formalization_statusboolResmileştirmenin açık olup olmadığı.

firstly_create_invoiceboolSiparişten önce faturanın kesilmesi.

balance_taxationstringBakiye yüklemesinin nasıl vergilendirileceği.

invoice_special_notestringHer faturaya düşülecek not.

pdf_fontstringBelgede kullanılacak yazı tipi.

invoice_number_formatstringFatura numarasının biçimi. Numaranın geleceği yeri işaretleyen yer tutucuyu taşımalı.

invoice_number_format_statusboolFatura numara biçiminin kullanılıp kullanılmadığı.

paid_invoice_number_formatstringÖdenmiş fatura numarasının biçimi.

paid_invoice_number_format_statusboolÖdenmiş fatura biçiminin kullanılıp kullanılmadığı.

invoice_incrementintFatura numaralarının başlayacağı sayı.

paid_invoice_incrementintÖdenmiş fatura numaralarının başlayacağı sayı.

send_bill_to_addressobjectBasılı fatura gönderimi: açık mı, ücreti ve para birimi.

company_tax_officeobjectVergi dairesi alanı: gösterilip gösterilmediği ve zorunlu olup olmadığı.

company_tax_numberobjectVergi numarası alanı: gösterimi, zorunluluğu ve doğrulanması.

Dönen alanlar data — 18

dataobjectGüncel ayarlar. Getirme ucuyla aynı şekildedir.

Hatalar 2

invalid_number_format422Numara biçiminde yer tutucu yok.

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/taxation/advanced' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"invoice_number_format":"FTR-{NUMBER}","invoice_number_format_status":true}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/financial/taxation/advanced', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    invoice_number_format: 'INV-{NUMBER}',
    invoice_number_format_status: true,
  }),
});

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

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/taxation/advanced');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'invoice_number_format'        => 'INV-{NUMBER}',
        'invoice_number_format_status' => true,
    ]),
]);

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

```php
// Numara BASLANGICINI dusurmek ayni numaranin ikinci kez verilmesine yol acabilir;
// mevcut en yuksek numaradan asagi inmeyin.
Api::Financial()->UpdateTaxationAdvanced(['invoice_increment' => 1000]);
```

### Vergi Kurallarını Listeleme

get/api/v1/admin/financial/tax-rules

`Financial/GetTaxRules` admin

Ülke ve eyalet bazlı vergi oranlarını döndürür.

Dönen alanlar data[] — 7

country_idintÜlkenin numarası.

country_namestringÜlkenin adı.

ccstringÜlkenin iki harfli kodu.

state_idintEyaletin numarası. Sıfır, kuralın ülkenin tamamına uygulandığını söyler.

state_namestringEyaletin adı.

tax_ratefloatToplam vergi oranı. Bileşenlerin toplamıdır.

ratesobject[]Oranı oluşturan bileşenler: her birinin adı ve değeri.

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/tax-rules' \
  -H "Authorization: Bearer $API_KEY"
```

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

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/tax-rules');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

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

```php
// Eyalet kurali ULKE kuralindan once gelir; ikisi de yoksa varsayilan oran uygulanir.
$rules = Api::Financial()->GetTaxRules()['data'];
```

### Vergi Kuralı Yazma

put/api/v1/admin/financial/tax-rules

`Financial/UpdateTaxRule` admin

Bir ülke ya da eyalet için vergi oranını yazar.

Gövde 4

country_idintreqKuralın uygulanacağı ülke.

state_idintKuralın uygulanacağı eyalet. Sıfır, ülkenin tamamı demektir.

state_namestringYeni bir eyalet adı. Verilirse eyalet önce oluşturulur.

ratesobject[]Oranı oluşturan bileşenler: her birinin adı ve değeri.

Dönen alanlar data — 3

country_idintKuralın ülkesi.

state_idintKuralın eyaleti. Yeni eyalet açıldıysa numarası burada döner.

ratefloatHesaplanan toplam oran.

Hatalar 5

invalid_country422Ülke geçersiz.

state_insert_failed422Yeni eyalet açılamadı.

tax_rule_failed422Kural yazılamadı.

blocked_by_gate422Bir 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/admin/financial/tax-rules' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"country_id":792,"state_id":0,"rates":[{"name":"KDV","value":20}]}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/financial/tax-rules', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    country_id: 840,
    state_id: 0,
    rates: [{ name: 'VAT', value: 20 }],
  }),
});

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

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/tax-rules');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'country_id' => 840,
        'rates'      => [['name' => 'VAT', 'value' => 20]],
    ]),
]);

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

```php
// Bilesenler YERINE GECER: gonderdiginiz liste eskisini siler, uzerine eklemez.
Api::Financial()->UpdateTaxRule([
    'country_id' => 840,
    'rates'      => [['name' => 'VAT', 'value' => 20]],
]);
```

### Avrupa Oranlarını Tanımlama

post/api/v1/admin/financial/tax-rules/define-all

`Financial/DefineAllTaxRates` admin mevcut kuralları ezer

Avrupa Birliği ülkelerinin katma değer vergisi oranlarını toplu tanımlar.

Gövde —

——Gövde gerekmez, boş gönderin. Oran kümesi gönderilmez, gömülü gelir; seçilecek bir şey yoktur.

Dönen alanlar data — 1

definedintTanımlanan oran sayısı.

Hatalar 1

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/tax-rules/define-all' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/financial/tax-rules/define-all', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});

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

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/tax-rules/define-all');
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
// Kurulumun ulkesi de listedeyse VARSAYILAN oran degisir; once mevcut kurallari kaydedin.
$before = Api::Financial()->GetTaxRules()['data'];
Api::Financial()->DefineAllTaxRates();
```

## Tuzaklar

> **Oran üç yerden gelebilir**
> 
> Bir faturaya uygulanan oran önce müşterinin **eyalet kuralından**, o yoksa **ülke kuralından**, o da yoksa varsayılan orandan alınır. Varsayılanı değiştirmek, kuralı olan ülkelerdeki müşterilerde hiçbir şeyi değiştirmez. "Oran güncellemesi işe yaramadı" durumlarının sebebi çoğunlukla budur.

> **Kural bileşenleri yerine geçer**
> 
> Vergi kuralı yazarken gönderdiğiniz bileşen listesi **eskisinin yerine geçer**; üzerine eklenmez. Bir ülkeye ikinci bir bileşen eklemek istiyorsanız önce mevcut listeyi okuyup ikisini birlikte gönderin. Tek bileşen göndermek diğerlerini sessizce düşürür.

> **Toplu tanımlama mevcut kuralları ezer**
> 
> Avrupa oranlarını toplu tanımlamak, o ülkeler için **elle girdiğiniz kuralların üzerine yazar**. Kurulumun kendi ülkesi de listedeyse varsayılan oran da değişir. Çalıştırmadan önce mevcut kuralları okuyup saklayın; geri almanın başka yolu yoktur.

> **Numara başlangıcını düşürmek çakışma üretir**
> 
> Fatura numarası başlangıcını mevcut en yüksek numaranın **altına indirmek**, aynı numaranın ikinci kez verilmesine yol açar. Muhasebede iki belgenin aynı numarayı taşıması ciddi bir sorundur ve sonradan düzeltmek zordur. Başlangıcı yalnız yukarı taşıyın.

> **Hesaplama biçimi aynı fiyatı farklı toplama çevirir**
> 
> Verginin tutarın içinde mi üstünde mi olduğu ayarı, **ilan ettiğiniz fiyatların ne anlattığını** değiştirir. İçinde olduğunda yüz liralık ürün yüz liraya satılır ve vergi içinden çıkar; üstünde olduğunda müşteri yüz yirmi lira öder. Bu ayarı kurulum yayına girdikten sonra değiştirmek bütün fiyat listesini yeniden gözden geçirmeyi gerektirir.

## İlgili Makaleler

- [Para Birimleri ve Kurlar](https://dev.wisecp.com/tr/para-birimleri-ve-kurlar)
- [İndirim Kuponları](https://dev.wisecp.com/tr/indirim-kuponlari)
- [Fatura Yönetimi](https://dev.wisecp.com/tr/fatura-yonetimi)