Sipariş sayısı günde birkaç düzineyi geçtiğinde elle kargo girişi hata üretmeye başlar: yanlış ilçe, eksik telefon, müşteriye hiç gitmeyen takip numarası, hangi siparişe ait olduğu anlaşılmayan iade paketi. Sorun çoğu zaman kargo firmasında değil, WooCommerce ile kargo API’si arasındaki veri akışının hiç tasarlanmamış olmasındadır. Aşağıda desi hesabından iade kabulüne kadar bu akışın her adımını ve sahada en çok takıldığı yerleri sırayla ele alıyoruz.
Kargo entegrasyonunda veri akışı
Bir kargo API entegrasyonu dört ayrı veri alışverişinden oluşur ve her birinin tetikleyicisi farklıdır:
| Adım | Yön | Tetikleyici | Veri |
|---|---|---|---|
| Ücret hesabı | Web içinde veya API | Sepet / ödeme sayfası | Adres, desi, ağırlık |
| Gönderi oluşturma | Web → kargo | Sipariş hazırlandığında | Alıcı, paket, referans |
| Etiket | Kargo → web | Gönderi yanıtı | Barkod, PDF veya ZPL |
| Durum takibi | Kargo → web | Webhook veya periyodik sorgu | Hareket ve teslim bilgisi |
Asıl karar, gönderinin hangi anda açılacağıdır. Ödeme onayında otomatik gönderi açmak, depoda stok sayım farkı çıktığında iptal edilecek gönderiler üretir. Gönderiyi sipariş toplanıp paketlendiğinde açın. Gerçek desi ve paket sayısı ancak o anda bellidir. ERP veya depo yönetim sistemi kullanan işletmelerde gönderi çoğunlukla o sistemden açılır, WooCommerce yalnız takip bilgisini alır. Hangi sistemin hangi alanı yazacağını ERP ile web entegrasyonu desenleri yazısındaki sahiplik ilkesine göre baştan yazılı hale getirin; iki sistemin aynı alanı yazdığı entegrasyonlar er geç birbirinin verisini ezer.
Desi ve ağırlık hesabı
Desi, paket hacmini ağırlık eşdeğerine çeviren birimdir. Türkiye’de yurt içi taşımada yaygın formül, santimetre cinsinden en, boy ve yükseklik çarpımının 3000’e bölünmesidir. Bölen firmaya ve hizmet türüne göre değişebilir; sözleşmenizdeki değeri esas alın. Ücretlendirmede genellikle desi ile kilogram cinsinden gerçek ağırlıktan büyük olanı kullanılır.
Örnek hesap: 40 × 30 × 25 cm ölçülerinde, 6 kg ağırlığındaki koli için desi = 40 × 30 × 25 / 3000 = 10’dur. Ücrete esas değer 10 olur, çünkü 10 desi 6 kg’dan büyüktür. Aynı ürün 40 × 30 × 15 cm koliye sığarsa desi 6’ya düşer ve ağırlıkla eşitlenir. Koli standardı bir maliyet kararıdır.
WooCommerce’ta her ürüne ağırlık ve boyut girilir; birimler WooCommerce → Ayarlar → Ürünler altında tanımlanır. Ancak sepetteki ürün desilerini toplamak gerçek paket desisini vermez; üç küçük ürün tek koliye girer. İki yaklaşım kullanılır:
- Tahmini desi: Sepette ürün desilerinin toplamı veya tanımlı koli tiplerine yerleştirme mantığı kullanılır; ödeme sayfasındaki ücret bir tahmindir.
- Gerçek desi: Gönderi açılırken depoda ölçülen koli ölçüleri girilir. Müşteriden alınan ücret ile kargo faturası arasındaki fark periyodik olarak raporlanır.
Sahada en sık karşılaştığımız tablo şu: ürünlerin yarısında boyut alanı boş, desi hesabı sıfır dönüyor ve ödeme sayfası hacimli ürüne en düşük ücreti gösteriyor. Entegrasyondan önce ürün verisini tamamlayın.
Kargo ücret kuralı modelleri
Müşteriye gösterilen kargo ücreti ile kargo firmasına ödenen tutar aynı şey değildir. Kurumsal e-ticaret sitelerinde ücret modelini seçerken doğruluk, müşteriye açıklanabilirlik ve ödeme sayfasının hızı birlikte tartılır.
| Model | Avantaj | Sınırlama |
|---|---|---|
| Sabit ücret | Basit, hızlı, anlaşılır | Hacimli ürünlerde zarar |
| Belirli tutar üzeri ücretsiz | Sepet tutarını artırır | Maliyet ürün marjına yüklenir |
| Desi/ağırlık bazlı tablo | Maliyete yakın | Ürün ölçüleri eksiksiz olmalı |
| Bölge bazlı | Uzak bölge farkını yansıtır | Bölge tanımlarının bakımı gerekir |
| Canlı API fiyatı | Anlık ve kesin | Ödeme sayfası kargo API’sine bağımlı olur |
WooCommerce’ın yerleşik yapısı kargo bölgeleri, bölge içindeki yöntemler (sabit ücret, ücretsiz kargo, mağazadan teslim) ve kargo sınıflarından oluşur. Sabit ücret yönteminin maliyet alanı basit ifadeleri destekler: [qty] ürün adedini, [cost] sepet tutarını verir; [fee percent="10" min_fee="20"] ise sepet tutarının yüzdesi olarak hesaplanan, alt sınırı olan bir ücret tanımlar. Örneğin 30 + ( 5 * [qty] ) ifadesi 30 birim sabit ücrete ürün başına 5 birim ekler. Hacimli ürünler için ayrı bir kargo sınıfı açıp yalnız o sınıfa ek ücret vermek, desi tablosu kurmadan çoğu sorunu çözer.
Canlı API fiyatı kullanıyorsanız kargo API’si yanıt vermediğinde ödeme sayfası kilitlenmemeli; kısa bir zaman aşımı ve yedek sabit ücret tanımlayın. Dış servis düşerse satış durmamalı. Hesaplanan ücretler WooCommerce’ın kargo oturum önbelleğinde tutulur; adres veya sepet değişmeden API tekrar çağrılmaz.
Gönderi oluşturma ve etiket basımı
Gönderi isteği tipik olarak alıcı adı, telefon, açık adres, il/ilçe, paket sayısı, her paketin desi ve ağırlığı, ödeme tipi (gönderici ödemeli, alıcı ödemeli, kapıda ödeme) ve sizin taraftaki referans numarasını taşır. Referans olarak sipariş numarasını kullanın; kargo panelindeki kaydı siparişe geri bağlamanın en güvenilir yolu budur.
Uygulamada kontrol edilecek noktalar:
- Adres normalizasyonu: İl ve ilçe serbest metin değil, seçim listesinden gelmeli. Kargo API’leri il/ilçe adını veya kodunu kendi listelerine göre doğrular; “Eyüp” ile “Eyüpsultan” farkı gönderi hatası demektir.
- Telefon biçimi: Alıcıya SMS gideceği için telefon tek biçimde (ör. ülke kodu olmadan 10 hane) saklanmalı.
- Tekrar koruması: Gönderi numarası siparişe yazıldıktan sonra düğme pasifleşmeli; API zaman aşımına düşerse yeni istek atmadan önce referansla sorgu yapılmalı. Aksi halde aynı siparişe iki barkod çıkar.
- Çoklu paket: Sipariş birden fazla koliye bölünüyorsa her paketin ayrı barkodu olur; takip bilgisi sipariş düzeyinde liste olarak saklanır.
Etiketler genellikle PDF veya ZPL olarak döner. PDF ofis yazıcısından basılır ama yapışkan etiket için kesme ister. Depoda termal etiket yazıcısı varsa ZPL çıktısı doğrudan yazıcıya gider; etiket boyutu (yaygın olarak 100 × 100 mm veya 100 × 150 mm) kargo firmasının şablonuyla aynı olmalı. Yazıcıda tanımlı etiket boyu şablondan farklıysa barkod kesilir ve şubede okunmaz. Toplu basımda seçilen siparişlere tek seferde gönderi açıp etiketleri tek dosyada birleştirmek paketleme hızını artırır.
Takip numarası ve müşteri bildirimi
Takip numarası siparişe meta veri olarak yazılmalı, hem yönetim ekranında hem müşterinin hesabındaki sipariş detayında görünmelidir. HPOS açık mağazada doğrudan post meta yerine sipariş nesnesi kullanılır:
$order = wc_get_order( $order_id );
$order->update_meta_data( '_kargo_takip_no', $tracking_no );
$order->update_meta_data( '_kargo_firma', 'ornek-kargo' );
$order->save();
// Müşteriye e-posta ile giden sipariş notu (ikinci parametre 1 = müşteri notu)
$order->add_order_note(
sprintf( 'Siparişiniz kargoya verildi. Takip numarası: %s', $tracking_no ),
1
);
$order->update_status( 'completed' );
Müşteri notu olarak eklenen not, WooCommerce’ın “Müşteri notu” e-postasını tetikler. Sipariş aynı anda completed durumuna alınırsa “Sipariş tamamlandı” e-postası da gider. Müşteri iki e-posta alır. Bunu istemiyorsanız takip numarasını yalnız birinde (ör. tamamlandı e-postası şablonuna eklenen alanla) iletin. Bazı işletmeler “Kargoya verildi” adında özel bir sipariş durumu tanımlar ve siparişi teslimattan sonra tamamlandı durumuna alır; bu durumda özel durumun e-posta şablonu ve raporlarda hangi gruba sayılacağı ayrıca ele alınmalıdır.
Durum güncellemesi için iki yöntem var. Kargo firması webhook sağlıyorsa teslim, dağıtımda ve iade gibi olaylar anlık gelir; alıcı tarafın imzayı doğrulaması ve tekrar gelen olayları tanıması gerekir. Webhook yoksa açık gönderiler belirli aralıklarla sorgulanır. Sorgu işi yalnız teslim edilmemiş ve belirli yaştan küçük gönderileri kapsamalı; aksi halde her çalışmada binlerce gereksiz istek gider ve firmanın istek limitine takılırsınız. Webhook alıcısının güvenli tasarımı webhook alıcısı tasarımı rehberinde ayrıca işleniyor.
İade kargo ve depo kontrol listesi
İade akışında müşteriye bir iade kodu verilir, müşteri paketi bu kodla şubeye teslim eder. Kod, iade talebi onaylandığında API ile üretilip siparişe bağlanmalı; böylece depoya gelen paketin hangi siparişe ait olduğu barkoddan anlaşılır. Paket depoya ulaşınca ürün kontrol edilir, ardından ödeme sağlayıcısı üzerinden iade tetiklenir. Ürün görülmeden para iade edilmez. Ödeme tarafındaki iade kuralları WooCommerce sanal POS entegrasyonu yazısında.
Canlıya geçmeden önce ve günlük operasyonda bakılacak liste:
- Tüm ürünlerde ağırlık ve boyut alanları dolu mu, birimler doğru mu?
- Standart koli tipleri ve ölçüleri tanımlı mı?
- Sözleşmedeki desi böleni ve bölge kuralları entegrasyon ayarlarıyla aynı mı?
- İl/ilçe alanları kargo firmasının listesiyle eşleşiyor mu?
- API zaman aşımında ödeme sayfası için yedek ücret tanımlı mı?
- Gönderi oluşturma tekrar korumalı mı, aynı sipariş için ikinci gönderi engelleniyor mu?
- Etiket boyutu ve yazıcı ayarı kargo şablonuyla uyumlu mu?
- Takip numarası müşteri e-postasında ve hesap sayfasında görünüyor mu?
- Hareketsiz gönderi ve teslim edilemeyen paket raporu çalışıyor mu?
- İade kodu siparişe bağlanıyor, depo kabulünden sonra ödeme iadesi tetikleniyor mu?
- Kargo faturası ile müşteriden alınan kargo ücreti aylık karşılaştırılıyor mu?
Kargo, ödeme ve ERP akışlarını tek bir mağaza kurgusunda planlamak için WooCommerce e-ticaret çözümleri sayfasındaki kapsama bakabilirsiniz.
Sık sorulan sorular
Desi hesabında hangi bölen kullanılmalı?
Türkiye’de yurt içi kargoda yaygın bölen 3000’dir; santimetre cinsinden en, boy ve yükseklik çarpımı 3000’e bölünür. Bölen firmaya ve hizmet türüne göre değişebilir, entegrasyonda kargo sözleşmenizdeki değeri kullanın.
Gönderi ödeme alınır alınmaz mı oluşturulmalı?
Genellikle hayır. Gerçek koli ölçüsü ve paket sayısı ancak paketleme sırasında bilinir. Gönderiyi paketleme adımında açmak, iptal edilen gönderileri ve hatalı desi beyanını azaltır.
Kargo firmasında webhook yoksa durum takibi nasıl yapılır?
Teslim edilmemiş gönderiler belirli aralıklarla takip API’sinden sorgulanır. Sorgu kapsamını açık ve belirli yaştan küçük gönderilerle sınırlayın, firmanın istek limitlerine uyun.
Birden fazla kargo firmasıyla çalışmak mümkün mü?
Evet. Her firma için ayrı yöntem veya bölge kuralı tanımlanabilir. Gönderi kaydında firma bilgisini takip numarasıyla birlikte saklayın; müşteriye gösterilen takip bağlantısı firmaya göre üretilmeli.