Vergilendirme Kuralları

1.7k görüntülenme Markdown

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 'https://panel.ornek.com/api/v1/admin/financial/taxation' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.ornek.com/api/v1/admin/financial/taxation', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$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);
// 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 -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"}'
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();
$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);
// 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 'https://panel.ornek.com/api/v1/admin/financial/taxation/advanced' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.ornek.com/api/v1/admin/financial/taxation/advanced', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$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);
// 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 -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}'
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();
$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);
// 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 'https://panel.ornek.com/api/v1/admin/financial/tax-rules' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.ornek.com/api/v1/admin/financial/tax-rules', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$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);
// 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 -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}]}'
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();
$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);
// 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 -X POST 'https://panel.ornek.com/api/v1/admin/financial/tax-rules/define-all' \
  -H "Authorization: Bearer $API_KEY"
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);
$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);
// 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.

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ı