WP WC Tax ile WooCommerce Vergi Sınıfı ve Oranı Yönetimi

Tarafındankomut
0 Comments

E-ticaret sitelerinde vergi yönetimi, çoğu zaman göz ardı edilen ama yanlış yapıldığında hem müşteri memnuniyetini hem de yasal uyumu doğrudan etkileyen kritik bir konudur. WooCommerce üzerinde onlarca ürün kategorisi, farklı ülkeler veya şehirler için ayrı vergi oranları tanımlamak gerektiğinde, WordPress yönetim paneli üzerinden tek tek işlem yapmak hem zaman alıcı hem de hata yapmaya açık bir süreç haline gelir. İşte tam bu noktada WP-CLI devreye giriyor. Komut satırından WooCommerce vergi sınıflarını ve oranlarını yönetmek, özellikle büyük mağazalarda ya da çoklu site kurulumlarında ciddi verimlilik artışı sağlıyor.

WooCommerce Vergi Yapısını Anlamak

WooCommerce’de vergi yönetimi iki katmanlı bir yapıya dayanır. Birinci katman vergi sınıfları (tax classes), ikinci katman ise vergi oranları (tax rates) olarak tanımlanır.

Vergi sınıfları, ürünleri vergi açısından gruplayan etiketlerdir. WooCommerce varsayılan olarak şu sınıflarla gelir:

  • Standard: Standart vergi oranı, çoğu ürün için geçerlidir
  • Reduced Rate: İndirimli oran, bazı ülkelerde belirli ürünler için uygulanır
  • Zero Rate: Sıfır oranlı vergi, vergiden muaf ürünler için kullanılır

Bir e-ticaret sitesinde örneğin gıda ürünleri için yüzde sekiz, elektronik ürünler için yüzde on sekiz, kitaplar için sıfır vergi uygulamak istiyorsanız, her biri için ayrı bir vergi sınıfı oluşturup o sınıfa ilgili oranları atamanız gerekir.

WP-CLI üzerinden bu işlemleri yapabilmek için öncelikle WooCommerce’in yüklü ve aktif olduğundan emin olun. Ayrıca wp-cli.yml dosyanızı doğru yapılandırdığınızdan emin olun ki her komuta --path parametresi eklemek zorunda kalmayasınız.

WP-CLI ile Mevcut Vergi Yapısını Görüntüleme

Herhangi bir değişiklik yapmadan önce mevcut durumu görmek iyi bir alışkanlıktır. WooCommerce vergi ayarlarını WP-CLI üzerinden sorgulamak için wc komutunu kullanıyoruz.

# Mevcut vergi sınıflarını listele
wp wc tax_class list --user=admin

Bu komut size mevcut tüm vergi sınıflarını döndürür. Çıktı oldukça sade gelir, slug ve name bilgileri görürsünüz.

Vergi oranlarını listelemek içinse:

# Tüm vergi oranlarını listele
wp wc tax list --user=admin

# Belirli bir vergi sınıfına ait oranları listele
wp wc tax list --class="standard" --user=admin

# JSON formatında çıktı al
wp wc tax list --format=json --user=admin

JSON formatı özellikle vergiyi başka bir sisteme aktaracaksanız veya bir script içinde işleyecekseniz oldukça kullanışlıdır. --format=table ile daha okunabilir bir çıktı da alabilirsiniz.

Vergi Sınıfı Oluşturma

Yeni bir vergi sınıfı eklemek oldukça basittir. Türkiye özelinde düşündüğünüzde KDV oranları farklılaştığında ya da özel bir kategori için ayrı vergi sınıfı oluşturmanız gerektiğinde şu komutu kullanırsınız:

# Yeni vergi sınıfı oluştur
wp wc tax_class create --name="Gıda Ürünleri" --user=admin

# Elektronik ürünler için ayrı sınıf
wp wc tax_class create --name="Elektronik" --user=admin

# İndirimli KDV sınıfı
wp wc tax_class create --name="Indirimli KDV" --user=admin

Sınıf oluşturduktan sonra WooCommerce otomatik olarak bir slug üretir. Örneğin “Gıda Ürünleri” için gida-urunleri gibi bir slug atanır. Bu slug değerini not edin çünkü vergi oranı eklerken bu slug’ı kullanacaksınız.

Dikkat etmeniz gereken nokta şu: WooCommerce’de vergi sınıfı adları benzersiz olmalıdır. Aynı isimde iki sınıf oluşturamazsınız. Ayrıca standart, reduced-rate ve zero-rate sınıfları sistem tarafından sabit tutulur, bunları silemezsiniz.

Vergi Oranı Ekleme

Vergi sınıflarını oluşturduktan sonra asıl iş vergi oranlarını tanımlamaktır. wp wc tax create komutu bu amaç için kullanılır ve oldukça fazla parametre alır:

Temel parametreler şunlardır:

  • –country: İki harfli ülke kodu (TR, DE, US gibi)
  • –state: Eyalet veya şehir kodu, boş bırakılabilir
  • –city: Şehir adı, opsiyonel
  • –postcode: Posta kodu, opsiyonel
  • –rate: Vergi oranı, ondalık sayı olarak
  • –name: Vergi oranının görünen adı
  • –class: Hangi vergi sınıfına ait olduğu
  • –priority: Aynı sınıfta birden fazla oran varsa öncelik sırası
  • –compound: Bileşik vergi mi, evet/hayır
  • –shipping: Kargo üzerinden de mi hesaplansın
  • –order: Görüntüleme sırası

Türkiye için standart KDV oranı ekleyelim:

# Türkiye için standart KDV (%18) ekle
wp wc tax create 
  --country="TR" 
  --rate="18" 
  --name="KDV %18" 
  --class="standard" 
  --priority="1" 
  --shipping="true" 
  --user=admin

# Gıda ürünleri için indirimli KDV (%8) ekle
wp wc tax create 
  --country="TR" 
  --rate="8" 
  --name="KDV %8 - Gida" 
  --class="gida-urunleri" 
  --priority="1" 
  --shipping="false" 
  --user=admin

# Kitap ve kültürel ürünler için sıfır KDV
wp wc tax create 
  --country="TR" 
  --rate="0" 
  --name="KDV Muaf" 
  --class="zero-rate" 
  --priority="1" 
  --shipping="false" 
  --user=admin

Çoklu Ülke için Vergi Yapılandırması

Uluslararası satış yapan bir mağaza kuruyorsanız durum biraz daha karmaşıklaşır. Her ülke için ayrı vergi oranları tanımlamanız gerekir. Bu işlemi manuel yapmak yerine bir bash script yazarak otomatize edebilirsiniz.

#!/bin/bash
# Avrupa ülkeleri için KDV oranları toplu ekleme scripti

WP_PATH="/var/www/html/wordpress"
ADMIN_USER="admin"

declare -A EU_VAT_RATES
EU_VAT_RATES["DE"]="19"
EU_VAT_RATES["FR"]="20"
EU_VAT_RATES["IT"]="22"
EU_VAT_RATES["ES"]="21"
EU_VAT_RATES["NL"]="21"
EU_VAT_RATES["BE"]="21"
EU_VAT_RATES["AT"]="20"
EU_VAT_RATES["PL"]="23"
EU_VAT_RATES["SE"]="25"

for country in "${!EU_VAT_RATES[@]}"; do
    rate="${EU_VAT_RATES[$country]}"
    echo "Ekleniyor: $country - %$rate KDV"
    
    wp wc tax create 
      --country="$country" 
      --rate="$rate" 
      --name="VAT $rate%" 
      --class="standard" 
      --priority="1" 
      --shipping="true" 
      --user="$ADMIN_USER" 
      --path="$WP_PATH"
    
    if [ $? -eq 0 ]; then
        echo "$country için vergi oranı başarıyla eklendi"
    else
        echo "HATA: $country için vergi oranı eklenemedi"
    fi
done

echo "Tüm AB ülke vergi oranları tamamlandı"

Bu scripti çalıştırmadan önce execute izni vermeyi unutmayın:

chmod +x eu_vat_setup.sh
./eu_vat_setup.sh

Vergi Oranı Güncelleme

Mevcut bir vergi oranını güncellemek için önce o oranın ID’sini bulmanız gerekir. ID’yi listelemeden alabilirsiniz:

# Önce mevcut oranları ve ID'leri gör
wp wc tax list --fields=id,name,rate,country,class --user=admin

# ID'si 5 olan vergi oranını güncelle
wp wc tax update 5 
  --rate="20" 
  --name="KDV %20" 
  --user=admin

# Vergi oranının kargo hesaplamasını kapat
wp wc tax update 5 
  --shipping="false" 
  --user=admin

Gerçek dünya senaryosunda bu çok işe yarar. Örneğin hükümet bir vergi oranı değişikliği yaptı ve siz onlarca farklı vergi kaydını güncellemeniz gerekiyor. Şöyle bir script yazabilirsiniz:

#!/bin/bash
# Belirli bir ülkenin tüm vergi oranlarını toplu güncelle

WP_USER="admin"
TARGET_COUNTRY="TR"
NEW_RATE="20"

# Hedef ülkenin tüm vergi ID'lerini al
TAX_IDS=$(wp wc tax list 
  --country="$TARGET_COUNTRY" 
  --fields=id 
  --format=csv 
  --user="$WP_USER" | tail -n +2)

# Her ID için güncelleme yap
for tax_id in $TAX_IDS; do
    echo "Güncelleniyor: Vergi ID $tax_id"
    wp wc tax update "$tax_id" 
      --rate="$NEW_RATE" 
      --user="$WP_USER"
done

echo "Güncelleme tamamlandı. Etkilenen kayıt sayısı: $(echo "$TAX_IDS" | wc -l)"

Vergi Oranı Silme ve Temizleme

Test ortamında oluşturulan gereksiz vergi kayıtlarını temizlemek veya artık geçerli olmayan ülke oranlarını kaldırmak gerekebilir.

# Tek bir vergi oranını sil
wp wc tax delete 12 --user=admin

# Silme işlemini onay sormadan yap
wp wc tax delete 12 --force --user=admin

# Belirli bir sınıfa ait tüm oranları temizle
for id in $(wp wc tax list --class="test-sinif" --fields=id --format=csv --user=admin | tail -n +2); do
    wp wc tax delete "$id" --force --user=admin
    echo "Silindi: ID $id"
done

Silme işlemlerinde dikkatli olun. Production ortamında silmeden önce mutlaka yedek alın ve silmek istediğiniz kayıtları önce listeleyerek kontrol edin. --force parametresi onay istemeksizin silme yapar, yanlışlıkla önemli vergi kayıtlarını silebilirsiniz.

Vergi Ayarlarını Dışa Aktarma ve Yedekleme

WooCommerce vergi ayarlarını başka bir siteye taşımak veya yedeklemek istediğinizde JSON formatındaki export oldukça işe yarar:

# Tüm vergi oranlarını JSON olarak dışa aktar
wp wc tax list 
  --format=json 
  --user=admin 
  > /backup/wc_tax_rates_$(date +%Y%m%d).json

# Belirli bir sınıfı dışa aktar
wp wc tax list 
  --class="standard" 
  --format=json 
  --user=admin 
  > /backup/wc_standard_taxes_$(date +%Y%m%d).json

echo "Vergi yedekleme tamamlandı"

Bu JSON dosyasını başka bir siteye aktarmak için küçük bir Python veya bash scripti yazabilirsiniz. Alternatif olarak WP-CLI’ın eval komutuyla JSON’ı okuyup yeni siteye yazabilirsiniz:

#!/bin/bash
# Yedek dosyasından vergi oranlarını yeni siteye aktar

SOURCE_FILE="/backup/wc_tax_rates_20240115.json"
WP_PATH_NEW="/var/www/yeni-site/wordpress"
ADMIN_USER="admin"

# JSON'dan her kaydı oku ve yeni siteye ekle
wp eval '
$taxes = json_decode(file_get_contents("'"$SOURCE_FILE"'"), true);
foreach ($taxes as $tax) {
    $result = WC_Tax::_insert_tax_rate([
        "tax_rate_country"  => $tax["country"],
        "tax_rate_state"    => $tax["state"],
        "tax_rate"          => $tax["rate"],
        "tax_rate_name"     => $tax["name"],
        "tax_rate_priority" => $tax["priority"],
        "tax_rate_compound" => $tax["compound"],
        "tax_rate_shipping" => $tax["shipping"],
        "tax_rate_order"    => $tax["order"],
        "tax_rate_class"    => $tax["class"],
    ]);
    if ($result) {
        WP_CLI::success("Eklendi: " . $tax["name"] . " - ID: " . $result);
    } else {
        WP_CLI::error("Eklenemedi: " . $tax["name"], false);
    }
}
' --path="$WP_PATH_NEW" --user="$ADMIN_USER"

WooCommerce Genel Vergi Ayarlarını Yapılandırma

Vergi oranları dışında WooCommerce’in genel vergi davranışını da WP-CLI üzerinden ayarlayabilirsiniz. Bu ayarlar wp option ve wp wc setting komutları aracılığıyla yapılır:

# Vergi hesaplamasını aktif et
wp option update woocommerce_calc_taxes "yes"

# Fiyatları vergisiz mi vergili mi göster
wp option update woocommerce_prices_include_tax "no"

# Vergiyi fatura adresine göre mi teslimat adresine göre mi hesapla
wp option update woocommerce_tax_based_on "shipping"

# Kargo vergisini yönet
wp option update woocommerce_shipping_tax_class "inherit"

# Yuvarlama yöntemini ayarla
wp option update woocommerce_tax_round_at_subtotal "no"

# Vergi görüntüleme ayarları (incl veya excl)
wp option update woocommerce_tax_display_shop "excl"
wp option update woocommerce_tax_display_cart "incl"

# Vergi ayarlarını doğrula
wp option get woocommerce_calc_taxes
wp option get woocommerce_tax_based_on

Bu ayarlar WooCommerce’in temel vergi davranışını belirler. Özellikle woocommerce_prices_include_tax ayarı kritik öneme sahiptir. Türkiye’de KDV dahil fiyat göstermek yaygın bir pratik olduğundan bu ayarı doğru yapılandırmak önemlidir.

Gerçek Dünya Senaryosu: Site Taşıma ve Vergi Migrasyonu

Bir müşterinin mağazasını eski bir sunucudan yeni bir sunucuya taşıdığınızı düşünün. Veritabanını taşıdınız ama vergi yapısını doğrulamak ve gerekirse yeniden yapılandırmak istiyorsunuz. İşte bu tür bir migration script örneği:

#!/bin/bash
# WooCommerce Vergi Migration ve Doğrulama Scripti

NEW_SITE="/var/www/yeni-magaza"
ADMIN="admin"
LOG_FILE="/var/log/wc_tax_migration.log"

echo "=== WC Vergi Migration Başlıyor ===" | tee -a $LOG_FILE
echo "Tarih: $(date)" | tee -a $LOG_FILE

# Mevcut vergi sınıflarını kontrol et
echo "Mevcut vergi sınıfları:" | tee -a $LOG_FILE
wp wc tax_class list 
  --user="$ADMIN" 
  --path="$NEW_SITE" | tee -a $LOG_FILE

# Mevcut vergi oranlarını say
RATE_COUNT=$(wp wc tax list 
  --user="$ADMIN" 
  --path="$NEW_SITE" 
  --format=count)

echo "Toplam vergi oranı sayısı: $RATE_COUNT" | tee -a $LOG_FILE

# Türkiye için standart oranların varlığını kontrol et
TR_STANDARD=$(wp wc tax list 
  --country="TR" 
  --class="standard" 
  --user="$ADMIN" 
  --path="$NEW_SITE" 
  --format=count)

if [ "$TR_STANDARD" -eq 0 ]; then
    echo "UYARI: Türkiye standart vergi oranı bulunamadı, ekleniyor..." | tee -a $LOG_FILE
    wp wc tax create 
      --country="TR" 
      --rate="18" 
      --name="KDV %18" 
      --class="standard" 
      --priority="1" 
      --shipping="true" 
      --user="$ADMIN" 
      --path="$NEW_SITE"
    echo "Türkiye KDV %18 eklendi" | tee -a $LOG_FILE
else
    echo "Türkiye standart vergi oranı mevcut, atlanıyor" | tee -a $LOG_FILE
fi

# WooCommerce vergi ayarlarını kontrol et ve yapılandır
CALC_TAXES=$(wp option get woocommerce_calc_taxes --path="$NEW_SITE")
if [ "$CALC_TAXES" != "yes" ]; then
    echo "Vergi hesaplama kapalı, aktif ediliyor..." | tee -a $LOG_FILE
    wp option update woocommerce_calc_taxes "yes" --path="$NEW_SITE"
fi

echo "=== Migration Tamamlandı ===" | tee -a $LOG_FILE

Yaygın Hatalar ve Çözümleri

WP-CLI ile vergi yönetimi yaparken karşılaşılan bazı yaygın sorunlar ve çözümleri:

Yetki hatası: --user parametresini atlayınca Error: Sorry, you cannot do that. gibi bir hata alırsınız. Her wc komutuna admin yetkisine sahip bir kullanıcı adı vermeyi unutmayın.

Sınıf slug uyuşmazlığı: Türkçe karakterli sınıf isimleri oluştururken slug otomatik üretilir ve Türkçe karakterler slug’da düzleştirilir. “Gıda Ürünleri” için slug gida-urunleri olabilir. Rate eklerken doğru slug’ı kullandığınızdan emin olmak için önce wp wc tax_class list ile sınıfları kontrol edin.

Ondalık ayırıcı sorunu: Bazı sistemlerde vergi oranını 18.5 yerine 18,5 yazdığınızda hata alabilirsiniz. Her zaman nokta kullanın.

WooCommerce versiyon uyumsuzluğu: WP-CLI WooCommerce eklentisi, WooCommerce versiyonuyla uyumlu olmalıdır. wp plugin list ile WooCommerce versiyonunu kontrol edin ve WP-CLI WC eklentisini güncel tutun.

Sonuç

WP-CLI üzerinden WooCommerce vergi sınıfı ve oranı yönetimi, başlangıçta karmaşık görünse de birkaç temel komutu kavradıktan sonra son derece güçlü bir araç haline gelir. Özellikle onlarca ülke için vergi tanımlaması yapmanız, bir sunucudan diğerine geçiş yapmanız ya da periyodik vergi güncellemelerini otomatize etmeniz gerektiğinde bu yaklaşım size inanılmaz esneklik sağlar.

Panel üzerinden tıklamak yerine komut satırından iş yaparken hem hız kazanırsınız hem de yaptığınız her şeyi script haline getirerek tekrarlanabilir ve denetlenebilir süreçler oluşturursunuz. Vergi oranı değişikliklerini versiyon kontrol sistemine aldığınızda kimin ne zaman hangi oranı değiştirdiğini takip etmek de mümkün hale gelir.

Bir sonraki adım olarak bu scriptleri cron job’lara bağlamayı ya da CI/CD pipeline’ınıza entegre etmeyi düşünebilirsiniz. Vergi oranı güncellemelerini otomatik bir şekilde production’a yayan, ama önce staging ortamında test eden bir yapı kurmak hem güvenli hem de profesyonel bir yaklaşım olur.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir