WooCommerce'e CSV ile Toplu Ürün Yükleme ve Fiyat Güncelleme

Tedarikçiden gelen Excel dosyasında 1.400 satır var. WooCommerce yönetim panelinde Ürünler > İçe Aktar ekranını açtınız, dosyayı seçtiniz, sütunları eşleştirdiniz ve ilerleme çubuğu %38'de donup kaldı. Sayfayı yenilediğinizde 512 ürün eklenmiş, gerisi yok. Üstelik eklenenlerin adları "Kırmızı Tişört" değil "Kırmızı Tişört" olarak görünüyor.

Bu iki sorun — zaman aşımı ve bozuk Türkçe karakterler — WooCommerce'in yerleşik içe aktarıcısıyla çalışan hemen herkesin başına gelir ve ikisi de dosyayı yüklemeden önce çözülebilecek şeylerdir. Üçüncü büyük sorun ise ilk aktarmadan haftalar sonra ortaya çıkar: tedarikçi yeni fiyat listesi gönderdiğinde, 1.400 ürünü silip yeniden yüklemeden yalnızca fiyatları güncellemek gerekir.

Bu rehberde WooCommerce ile birlikte gelen yerleşik içe aktarıcıyı gerçek bir dosya üzerinden kullanacağız: hangi sütunların zorunlu olduğu, varyasyonlu ürünlerde üst/alt satır kurgusunun nasıl yazıldığı, UTF-8 kodlamasının Excel'de nasıl doğru ayarlandığı, mevcut ürünleri ID veya SKU ile eşleyip yalnızca fiyat alanını güncelleme, ve büyük dosyaları zaman aşımı almadan parçalayarak yükleme.

Yerleşik İçe Aktarıcı Ne Yapar, Ne Yapmaz#

WooCommerce 3.1'den beri çekirdekte bir ürün içe/dışa aktarıcı gelir; ek eklenti kurmanıza gerek yoktur. Ürünler > Tüm Ürünler ekranının üstündeki "İçe Aktar" ve "Dışa Aktar" düğmeleriyle erişilir ve arka planda AJAX ile parça parça çalışır.

Yapabildikleri: yeni ürün oluşturma, mevcut ürünü güncelleme, basit ve varyasyonlu ürünler, kategori ve etiket atama, görsel indirme (URL'den), stok, ağırlık/boyut, öznitelikler ve Meta: önekiyle özel alanlar.

Yapamadıkları da net bilinmeli, çünkü bu sınırlar çoğu "import çalışmıyor" şikâyetinin gerçek sebebidir:

• Ürün silmez. CSV'den bir satırı çıkarmak o ürünü mağazadan kaldırmaz.
• Tanımadığı sütunu içe aktarmaz. Şema dışında kalan sütunlar, Meta: önekiyle eşleştirilmedikçe sessizce yok sayılır.
• Sipariş, müşteri veya kupon aktarmaz. Yalnızca ürünlerle ilgilenir.
• Geri alma düğmesi yoktur. Yanlış bir dosyayla 800 ürünün fiyatını sıfırladıysanız, geri dönüş yolunuz veritabanı yedeğidir.

Son madde nedeniyle her toplu aktarmadan önce yedek alın. Bunu nasıl otomatikleştireceğinizi WordPress yedekleme yazısında ele aldık; en azından wp-content ve veritabanının o günkü kopyası elinizde olsun.

CSV Dosyasında Hangi Sütunlar Gerekli#

En sık yapılan hata, tedarikçinin gönderdiği Excel'i olduğu gibi yüklemeye çalışmaktır. İçe aktarıcı sütun adlarını kendi şemasıyla eşleştirmeye çalışır; eşleşmeyeni size sorar, siz de elle seçersiniz. Ama sütun adlarını baştan doğru yazarsanız eşleme adımı neredeyse otomatik geçer.

Aşağıdaki tablo, çalışan bir dosya için gerçekten anlamlı olan sütunları toplar:

İki nokta hemen dikkat çeker. Birincisi ondalık ayırıcı noktadır: 249,90 yazarsanız içe aktarıcı bunu ya sıfırlar ya da 24990 olarak yorumlar. Excel'de Türkçe yerel ayarla çalışıyorsanız fiyat sütununu metin formatına çevirip noktalı yazmak en güvenli yoldur.

İkincisi SKU benzersizliğidir. Dosyanızda aynı SKU iki satırda geçiyorsa içe aktarma o satırda hata verir. Yüklemeden önce kontrol etmek beş saniye sürer:

# Dosyada tekrar eden SKU var mı? (SKU'nun 2. sütun olduğunu varsayıyoruz)
cut -d',' -f2 urunler.csv | sort | uniq -d

# Toplam satır sayısı (başlık dahil)
wc -l urunler.csv

Doğru sütun adlarını ezberlemenin en pratik yolu şudur: mağazanıza elle bir tane örnek ürün girin, sonra Ürünler > Dışa Aktar ile onu CSV olarak indirin. Elinizde WooCommerce'in kendi sürümünüzde beklediği başlık satırı olur; tedarikçi verisini bu şablona doldurursunuz.

Türkçe Karakterler Bozuk Geliyorsa: UTF-8 ve Ayırıcı#

"Kırmızı" görüntüsü tek bir şey anlamına gelir: dosya UTF-8 değil, muhtemelen Windows-1254 veya ISO-8859-9 kodlamasıyla kaydedilmiş, WordPress ise UTF-8 olarak okuyor.

Excel'de "Farklı Kaydet" yaparken CSV (virgülle ayrılmış) ile CSV UTF-8 (virgülle ayrılmış) iki ayrı seçenektir ve ilki Türkçe karakterleri bozar. Her zaman ikincisini seçin. LibreOffice Calc kullanıyorsanız kaydetme sırasında açılan diyalogda karakter kümesini Unicode (UTF-8) ve alan ayırıcısını , yapın.

Dosyanın gerçekten hangi kodlamada olduğunu tahmin etmek yerine ölçün:

# Dosyanın karakter kümesini öğren
file -I urunler.csv

# Windows-1254'ten UTF-8'e çevir
iconv -f WINDOWS-1254 -t UTF-8 urunler.csv > urunler-utf8.csv

# Excel'in eklediği BOM işaretini kaldır (ilk sütun adını bozar)
sed -i '1s/^\xEF\xBB\xBF//' urunler-utf8.csv

BOM meselesi ayrı bir tuzaktır: Excel'in "CSV UTF-8" çıktısı dosyanın başına görünmez üç bayt ekler. Bu baytlar ilk sütun adına yapışır, SKU sütunu SKU olur ve içe aktarıcı onu tanımaz — eşleme ekranında ilk sütun "Eşleme yok" olarak gelir. Yukarıdaki sed satırı bunu temizler.

Ayırıcı karakter de sık sorun çıkarır. Türkçe Windows kurulumlarında Excel varsayılan olarak noktalı virgül (;) ile kaydeder. WooCommerce içe aktarıcısı varsayılan olarak virgül bekler, ama yükleme ekranındaki "Gelişmiş seçenekleri göster" bağlantısına tıkladığınızda çıkan CSV Ayırıcı alanına ; yazabilirsiniz. Dosyayı düzenlemekten daha hızlıdır.

Varyasyonlu Ürünleri CSV ile Aktarmak#

Varyasyonlu ürünler dosyanın en çok yanlış yazılan kısmıdır, çünkü tek bir ürün birden fazla satıra yayılır: bir üst satır (variable) ve her varyasyon için bir alt satır (variation). Ürün tipleri arasındaki farkı ve hangi durumda değişken ürün kullanacağınızı WooCommerce ürün tipleri yazısında ayrıntılı anlattık.

Kuralları şunlardır:

• Üst satırın Type değeri variable, alt satırların variation olur.
• Alt satırın Parent sütununa üst ürünün SKU'su veya id:812 biçiminde ID'si yazılır. Yeni bir dosyada üst ürünün henüz ID'si olmadığı için SKU kullanmak daha güvenlidir.
• Üst satır dosyada alt satırlarından önce gelmelidir.
• Üst satırın fiyat sütunları boş bırakılır (sıfır değil, boş). Fiyat varyasyon satırlarında durur.
• Üst satırın Attribute 1 value(s) alanında tüm seçenekler virgülle listelenir; alt satırda o varyasyona ait tek değer bulunur.
• Her satırın SKU'su benzersiz olmalıdır.

Örnek bir dosyanın ilgili sütunları şöyle görünür:

Type,SKU,Name,Parent,Regular price,Stock,Attribute 1 name,Attribute 1 value(s),Attribute 1 visible,Attribute 1 global
variable,TS-KRM,Kırmızı Tişört,,,,Beden,"S, M, L",1,1
variation,TS-KRM-S,,TS-KRM,249.90,12,Beden,S,1,1
variation,TS-KRM-M,,TS-KRM,249.90,25,Beden,M,1,1
variation,TS-KRM-L,,TS-KRM,269.90,8,Beden,L,1,1

Dikkat edilecek üç ayrıntı var. Değer listesinde virgül olduğu için "S, M, L" tırnak içine alınmıştır — bu CSV'nin kendi kuralıdır ve atlanırsa satır kayar. Varyasyon satırlarında Name boş bırakılabilir; WooCommerce adı üst üründen türetir. Attribute 1 global sütunu 1 ise öznitelik Ürünler > Öznitelikler ekranında önceden tanımlı olmalıdır; tanımlı değilse 0 yazın, WooCommerce onu o ürüne özel yerel öznitelik olarak oluşturur.

İki öznitelikli varyasyonlarda (örneğin Beden + Renk) Attribute 2 name ve Attribute 2 value(s) sütunlarını ekleyip aynı mantığı sürdürürsünüz. Varyasyon sayısı bedenlerin renklerle çarpımı kadar olur; 5 beden × 4 renk 20 alt satır demektir ve bunları elle yazmak yerine Excel'de formülle üretmek hem hızlı hem hatasızdır.

Varyasyon bazlı stok takibinin nasıl kurulacağı ayrı bir konudur; alt satırlardaki Stock değerlerinin gerçekten devreye girmesi için ürün düzeyinde stok yönetiminin açık olması gerekir. Ayrıntılar WooCommerce stok yönetimi yazısında.

Mevcut Ürünleri Güncelleme: ID mi SKU mu?#

İçe aktarıcının en değerli özelliği, var olan ürünleri güncelleyebilmesidir. Yükleme ekranının ilk adımında "Mevcut ürünler güncellensin" kutucuğunu işaretlediğinizde davranış tamamen değişir.

Eşleme iki anahtarla yapılır ve sıra önemlidir:

Pratikte hangisini kullanmalısınız? SKU daha okunaklı ve tedarikçi listeleriyle uyumludur; ürün kodu zaten elinizdedir. ID ise kesin eşleşme sağlar ve SKU'ları değiştirmeniz gereken durumlarda tek seçenektir. En sağlam yöntem, güncellenecek ürünleri önce dışa aktarıp ID'leriyle birlikte almaktır:

# WooCommerce CLI çağrıları bir kullanıcı bağlamı ister
wp wc product list --fields=id,sku,name,regular_price --per_page=100 --user=1

# Tek bir ürünü aktarmadan sonra doğrula
wp wc product get 812 --fields=id,sku,regular_price,sale_price --user=1

WP-CLI'ye erişiminiz yoksa yönetim panelindeki Dışa Aktar ekranı da ID sütununu içeren bir CSV üretir; onu şablon olarak kullanabilirsiniz. WP-CLI'yi hiç kullanmadıysanız WP-CLI kullanımı yazısı komut yapısını anlatıyor.

Yalnızca Fiyat Güncellemek İçin En Küçük CSV#

İçe aktarıcının çok bilinmeyen ama en faydalı davranışı şudur: dosyada olmayan sütunlara dokunmaz. Yani yalnızca SKU ve fiyat sütunu içeren bir dosya yüklerseniz, ürünün açıklaması, görselleri, kategorileri ve stoğu olduğu gibi kalır.

Bu, tedarikçi zam listesi geldiğinde işinizi üç sütuna indirir:

SKU,Regular price,Sale price
TS-KRM-S,279.90,
TS-KRM-M,279.90,249.90
TS-KRM-L,299.90,

Sale price sütununun boş bırakıldığı satırlarda indirimli fiyat temizlenir; indirimi bitirmek için de aynı yöntemi kullanabilirsiniz. Yükleme sırasında "Mevcut ürünler güncellensin" kutucuğunu işaretlemeyi unutmayın — işaretlemezseniz WooCommerce bu satırları yeni ürün sanır ve mağazanıza adsız, fiyatlı kopyalar ekler. Bu, tek bir kutucuğun sebep olduğu en yaygın kazadır.

Fiyat güncellemesi yaptıktan sonra vitrinde eski fiyatları görüyorsanız sorun aktarmada değil, önbellektedir; sayfa önbelleğini temizleyip sert yenileme yapın. Fiyatların KDV dahil mi hariç mi yorumlanacağı da ayrı bir katmandır ve WooCommerce KDV ayarları tarafında belirlenir — aynı 249.90 değeri, o ayara göre farklı bir raf fiyatı üretir.

Büyük Dosyalarda Zaman Aşımı ve Parçalayarak Yükleme#

İçe aktarıcı dosyayı tek seferde işlemez; varsayılan olarak 30 satırlık partiler hâlinde AJAX istekleriyle ilerler. Her istek PHP'nin çalışma süresi sınırına tabidir. Görsel indiren satırlarda (Images sütunu dolu olduğunda) her ürün için ayrıca bir HTTP isteği yapıldığı için parti süresi kolayca 30 saniyeyi aşar ve süreç sessizce durur.

Üç ayarı birlikte düşünmek gerekir. Önce PHP tarafı:

; php.ini — paylaşımlı hostingte panelden değiştirilir
max_execution_time = 300
memory_limit = 512M
upload_max_filesize = 64M
post_max_size = 64M

upload_max_filesize ve post_max_size yalnızca dosyayı yükleyebilmek içindir; bu ikisini büyütmezseniz büyük dosya sunucuya hiç ulaşmaz. Bu limitlerin nerede tanımlandığı ve hangisinin diğerini ezdiği konusunda PHP upload_max_filesize ayarı yazısına bakabilirsiniz.

İkinci ayar parti boyutudur. Sezgiye aykırı biçimde, zaman aşımı alıyorsanız bu sayıyı düşürmeniz gerekir; her istek daha az iş yapar ve süre sınırına takılmaz:

add_filter( 'woocommerce_product_import_batch_size', function ( $size ) {
    return 10; // varsayılan 30; görselli aktarmalarda düşürün
} );

Üçüncüsü ise dosyayı bölmektir. 5.000 satırlık tek dosya yerine 500'er satırlık on dosya yüklemek her zaman daha güvenlidir: bir parça hata verirse yalnızca onu tekrarlarsınız, sıfırdan başlamazsınız.

# Başlık satırını ayır
head -n 1 urunler.csv > baslik.csv

# Gövdeyi 500'er satırlık parçalara böl
tail -n +2 urunler.csv | split -l 500 - parca_

# Her parçanın başına başlık satırını ekle
for f in parca_*; do
  cat baslik.csv "$f" > "urunler_${f}.csv"
  rm "$f"
done

Yükleme ekranındaki "Gelişmiş seçenekler" altında sunucudaki bir dosya yolunu doğrudan verebileceğinizi de unutmayın. Dosyayı FTP/SSH ile wp-content/uploads/ altına koyup yolunu yazmak, tarayıcıdan yükleme adımını ve onun tüm boyut sınırlarını tamamen atlar. Çok büyük dosyalarda önerilen yol budur.

Aktarma sırasında 504 hatası alıyorsanız sorun PHP'den önce web sunucusunun zaman aşımı ayarında olabilir; 504 Gateway Timeout hatası yazısı nginx ve Apache tarafındaki karşılıklarını anlatıyor.

Sık Karşılaşılan İçe Aktarma Hataları#

Aşağıdaki tablo, gerçek hata mesajlarını sebep ve çözümle eşleştirir:

Görsel sorunları ayrıca dikkat ister: içe aktarıcı görselleri indirir, yani URL'lerin aktarma sırasında dışarıdan erişilebilir olması gerekir. Yerel ağdaki bir adres veya şifre korumalı bir dizin işe yaramaz. 1.400 görselin indirilmesi de dakikalar sürer; bu yüzden büyük katalogları önce görselsiz yükleyip, görselleri ikinci bir güncelleme turunda eklemek çoğu zaman daha hızlı ve daha güvenlidir.

Aktarma Öncesi ve Sonrası Kontrol Listesi#

Toplu aktarmayı bir rutine bağladığınızda sürprizler biter. Sıra şudur:

1. Yedek alın. Veritabanı ve wp-content kopyası, aktarmadan hemen önce.
2. Şablonu dışa aktarımla üretin. Bir örnek ürünü dışa aktarıp başlık satırını oradan alın.
3. Küçük bir örnekle deneyin. 1.400 satırlık dosyanın ilk 10 satırını ayrı bir dosyaya alıp önce onu yükleyin.
4. Sonucu gözle doğrulayın. Fiyat, stok, kategori, varyasyon sayısı ve görsel — beş alanı bir üründe kontrol edin.
5. Kalan parçaları yükleyin. Örnek doğruysa bölünmüş dosyaları sırayla aktarın.
6. Sayıları karşılaştırın. Beklenen ürün sayısı ile mağazadaki sayı tutuyor mu?

Son adım için hızlı bir doğrulama:

# Yayınlanmış ürün sayısı
wp post list --post_type=product --post_status=publish --format=count

# SKU'su boş kalan ürünler (eşleme hatasının işareti)
wp db query "SELECT COUNT(*) FROM wp_postmeta WHERE meta_key='_sku' AND meta_value=''"

Bir toplu aktarma işi, dosyayı hazırlarken harcanan on dakikayı geri ödeyecek kadar zaman kazandırır — yeter ki kodlama, ayırıcı ve eşleme anahtarı üçlüsü dosyayı yüklemeden önce netleşmiş olsun. Zaman aşımı ve kopya ürün gibi sorunların tamamı bu üç karara bağlıdır, ve üçü de tarayıcıda değil masaüstünde çözülür.

Sıkça Sorulan Sorular#

WooCommerce'e ürün aktarmak için eklenti kurmam gerekir mi?#

Gerekmez. WooCommerce 3.1'den beri ürün içe/dışa aktarıcı çekirdekte gelir ve Ürünler ekranının üstündeki düğmelerden erişilir. Basit ve varyasyonlu ürünleri, kategorileri, öznitelikleri, stoğu ve görselleri aktarabilir. Ek eklentiler genellikle zamanlanmış aktarma, XML desteği veya sipariş/müşteri aktarımı gibi çekirdekte olmayan özellikler için gerekir.

CSV'de Türkçe karakterler neden bozuk çıkıyor?#

Dosya UTF-8 değil, büyük ihtimalle Windows-1254 kodlamasıyla kaydedilmiştir. Excel'de "Farklı Kaydet" yaparken "CSV (virgülle ayrılmış)" yerine "CSV UTF-8 (virgülle ayrılmış)" seçeneğini kullanın. Dosya elinizdeyse iconv -f WINDOWS-1254 -t UTF-8 komutuyla dönüştürebilirsiniz. Dönüştürdükten sonra dosya başındaki BOM işaretini de temizlemeniz gerekebilir.

Sadece fiyatları güncellemek için tüm ürün bilgilerini yazmam gerekir mi?#

Hayır. İçe aktarıcı, dosyanızda bulunmayan sütunlara dokunmaz. Yalnızca SKU ve fiyat sütunu içeren üç sütunluk bir dosya yükleyip "Mevcut ürünler güncellensin" kutucuğunu işaretlerseniz, açıklama, görsel, kategori ve stok bilgileri olduğu gibi kalır. Bu kutucuğu işaretlemeyi unutursanız aynı ürünlerin kopyaları oluşur.

Varyasyonlu ürünlerde Parent sütununa ne yazılır?#

Üst ürünün SKU'su veya id:812 biçiminde ürün ID'si yazılır. Yeni bir katalog aktarıyorsanız üst ürünün henüz ID'si olmadığı için SKU kullanmak zorunludur. Üst satırın dosyada varyasyon satırlarından önce gelmesi ve üst satırın fiyat alanlarının boş bırakılması da gerekir; fiyat bilgisi yalnızca varyasyon satırlarında bulunur.

İçe aktarma yarıda kalıyor, ne yapmalıyım?#

Parti boyutunu düşürün ve dosyayı bölün. İçe aktarıcı varsayılan olarak 30 satırlık partiler hâlinde çalışır; woocommerce_product_import_batch_size filtresiyle bunu 10'a indirmek, her isteğin PHP çalışma süresi sınırına takılmasını engeller. Ayrıca max_execution_time değerini artırın ve 5.000 satırlık tek dosya yerine 500'er satırlık parçalar yükleyin.

İçe aktarma ile yanlış veri yükledim, geri alabilir miyim?#

İçe aktarıcının geri alma özelliği yoktur. Tek güvenilir dönüş yolu, aktarmadan önce alınmış veritabanı yedeğidir. Yedek yoksa zararı sınırlamak için doğru değerleri içeren yeni bir CSV hazırlayıp aynı SKU'lar üzerinden güncelleme yapmanız gerekir; yanlışlıkla oluşan kopya ürünleri ise ürün listesinden toplu seçip çöp kutusuna taşıyabilirsiniz.