Trendyol API entegrasyonu, WooCommerce ile Trendyol Partner Programı arasında kategori/öznitelik, ürün, stok-fiyat ve sipariş servisleri üzerinden çalışan bağımsız modüllerden oluşur; hepsini birden değil, sırayla kurmak daha sağlıklıdır.
En çok zaman alan kısım kod yazmak değil, kendi kategori yapınızla Trendyol’un kategori ağacı ve zorunlu özniteliklerini eşlemektir; bu eşleme yanlış kurulduğunda ürünler sessizce reddedilir.
Barkod her varyasyonda benzersiz ve sabit olmalı, senkronizasyon gerçek bir sunucu cron’una bağlanmalı; WP-Cron’a güvenmek, trafiği düşük sitelerde gecikmeli güncellemeye yol açar.
Ürünleri Trendyol paneline elle girmek, birkaç düzine ürüne kadar sürdürülebilir bir yöntem. Ürün sayısı arttığında ve aynı stok hem kendi siteniz hem pazaryeri tarafından tüketilmeye başladığında elle yönetim çöker. Trendyol API tam olarak bu noktada devreye girer.
Bu yazı teknik tarafı ele alıyor. Entegrasyonun mimarisi, hangi servis grubunun ne işe yaradığı, senkronizasyonun nerede kırıldığı ve WooCommerce tarafında nelerin hazırlanması gerektiği anlatılıyor.
Hangi yöntemin işletmeniz için daha mantıklı olduğu, maliyetler ve entegratör karşılaştırması ayrı bir konu. Onu pazaryeri entegrasyonu yazısında ele aldım.
API entegrasyonu neyi çözer
Kısaca: tek bir stok gerçeğini tüm kanallara yansıtır, böylece kendi sitenizde satılan bir ürün pazaryerinde satılmaya devam etmez. Bunun neden bu kadar kritik olduğunu ve iş tarafındaki maliyetini pazaryeri entegrasyonu yazısında ayrıntılı anlattım; burada doğrudan teknik çözüme giriyorum.
Entegrasyonla birlikte otomatikleşen işler:
- Ürün ve varyasyonların pazaryerine aktarılması
- Fiyat değişikliklerinin tek noktadan yayılması
- Siparişlerin kendi sisteminize düşmesi
- Kargo ve iade süreçlerinin takip edilmesi
- Fatura bilgilerinin gönderilmesi
Erişim ve kimlik doğrulama
Trendyol, entegrasyon servislerini Partner Programı üzerinden sunuyor. Satıcı panelinizde entegrasyon bilgileri bölümünden erişim anahtarlarınızı oluşturuyorsunuz.
Entegrasyon çalışmaya başlamadan önce elinizde şunlar olmalı:
- Satıcı kimlik numaranız
- Panel üzerinden üretilen erişim anahtarı ve gizli anahtar çifti
- Test ortamı bilgileri
Kimlik doğrulama yöntemi, başlık yapısı ve servis adresleri Trendyol’un geliştirici dokümantasyonunda tanımlı. Bu değerler zaman içinde güncellenebildiği için entegrasyona başlamadan önce resmi dokümantasyondaki güncel yapıyı esas almanızı öneririm. Eski blog yazılarından kopyalanan başlık ve adres bilgileri, entegrasyonun ilk kırılma noktasıdır.
Test ortamında başlayın
Canlı ortamda yapılan ilk denemeler gerçek ürün listelerini bozar. Yanlış eşlenmiş bir kategori, yüzlerce ürünün hatalı yayınlanmasına yol açabilir.
Test ortamı bu riski ortadan kaldırır. Ürün aktarımı, stok güncellemesi ve sipariş akışı doğrulanmadan canlıya geçilmemeli.
Servis grupları ve ne işe yaradıkları
Trendyol api entegrasyonu tek bir servis değil, birbirinden bağımsız çalışan servis gruplarından oluşur. Entegrasyonu parça parça kurmak, hepsini birden kurmaya çalışmaktan daha sağlıklıdır.
| Servis grubu | Ne yapar | Kurulum sırası |
|---|---|---|
| Kategori ve öznitelik | Pazaryerinin kategori ağacını ve zorunlu alanlarını okur | 1, her şeyin temeli |
| Ürün | Ürün oluşturur ve günceller | 2 |
| Stok ve fiyat | Mevcut ürünlerin stok ve fiyatını günceller | 3, en sık çalışan servis |
| Sipariş | Gelen siparişleri çeker, durum günceller | 4 |
| Kargo ve iade | Gönderi ve iade süreçlerini yönetir | 5 |
| Fatura | Fatura bilgisini pazaryerine iletir | 6 |
| Müşteri soruları | Ürün sorularını çeker ve yanıtlar | 7, opsiyonel |
İlk üç grup çalıştığında entegrasyonun asıl değeri ortaya çıkar. Kalanlar operasyonu kolaylaştırır ama olmadan da satış yapılabilir.
En zor kısım: kategori ve öznitelik eşleme
Entegrasyon projelerinde harcanan zamanın büyük bölümü burada geçer. Sebebi şu: kendi sitenizdeki kategori yapısı ile pazaryerinin kategori ağacı aynı mantıkla kurulmamıştır.
Sizin sitenizde “Kadın Ayakkabı” tek bir kategori olabilir. Pazaryerinde ise ayakkabı türüne göre onlarca alt kategori bulunur ve her birinin kendi zorunlu öznitelikleri vardır.
Zorunlu öznitelikler
Her kategori, o kategoriye özel zorunlu alanlar tanımlar. Bir tekstil ürününde kumaş tipi ve beden, bir elektronik üründe garanti süresi ve model kodu zorunlu olabilir.
Bu alanlar serbest metin değildir. Pazaryerinin tanımladığı seçenek listesinden bir değer göndermeniz gerekir. Yani sizin veritabanınızdaki “Pamuk” değeri, pazaryerindeki karşılığının kimlik numarasına çevrilmelidir.
Bu yüzden entegrasyonun ilk adımı kategori ağacını ve öznitelik listelerini çekip kendi tarafınızda saklamaktır. Bu veriler zaman içinde değiştiği için düzenli olarak yenilenmelidir.
Eşleme tablosu kurmak
Pratikte işe yarayan yapı şudur: kendi kategorileriniz ile pazaryeri kategorileri arasında bir eşleme tablosu tutmak.
Bu tablo bir kez kurulduktan sonra yeni ürünler otomatik olarak doğru kategoriye düşer. Eşleme yapılmamış bir kategoriye ürün eklendiğinde ise sistem uyarı vermeli, sessizce yanlış kategoriye göndermemelidir.
Öznitelikler için de benzer bir eşleme gerekir. Renk, beden ve malzeme gibi alanlarda kendi değerlerinizin pazaryeri karşılıklarını tanımlamanız gerekir.
Marka eşleştirme
Kategori kadar dikkat isteyen bir başka alan marka bilgisidir. Pazaryeri, markaları kendi listesinden tanır ve serbest metin kabul etmez.
Kendi sitenizde marka bir metin alanı olarak tutuluyorsa, bunun pazaryerindeki karşılığının kimlik numarasına çevrilmesi gerekir.
Markanız listede yoksa önce marka başvurusu yapılması gerekir. Bu süreç tamamlanmadan ürünler yayınlanamaz. Kendi üretimi olan işletmelerde bu adım sıkça atlanır ve entegrasyon kurulduğu halde tek ürün yayınlanamaz.
Kurduğumuz entegrasyonlarda en sık karşılaştığımız tıkanma noktası burası: kod tarafı sorunsuz çalışıyor, istekler başarıyla dönüyor ama ürünler yayınlanmıyor. Sebep genelde marka onayının beklemede kalması veya bir özniteliğin serbest metin olarak gönderilmesi oluyor.
Bunu erken yakalamanın yolu, reddedilen kayıtları sessizce loglamak değil, bir yönetici ekranında görünür kılmaktır. Aksi halde katalogun bir kısmının hiç yayınlanmadığı haftalarca fark edilmiyor.
Görsel gereksinimleri
Ürün görselleri erişilebilir bir adres üzerinden gönderilir. Yani görsellerinizin kendi sunucunuzda dışarıdan açılabilir olması gerekir.
Burada üç şey sık sorun çıkarır:
- Erişim engeli. Güvenlik eklentisi veya güvenlik duvarı dış istekleri engelliyorsa görseller çekilemez.
- Boyut ve oran. Pazaryerinin beklediği minimum çözünürlük ve en boy oranı sağlanmazsa ürün reddedilir.
- Görsel adresinin değişmesi. Medya kütüphanesinde yeniden düzenleme yapıldığında adresler değişir ve daha önce gönderilen görseller kırılır.
Görsellerin optimize edilmiş olması ayrıca gönderim süresini kısaltır. Boyut ve format tarafını görsel optimizasyonu yazısında anlattım.
Barkod ve stok kodu mimarisi
Entegrasyonun bel kemiği, iki sistemdeki ürünlerin birbiriyle eşleştirilmesidir. Bu eşleşme barkod üzerinden kurulur.
Kurallar nettir:
- Her varyasyonun kendi barkodu olmalı. Aynı ürünün 38 ve 40 numarası ayrı barkod taşır.
- Barkod benzersiz olmalı. İki ürüne aynı barkod verilirse stok güncellemesi yanlış ürüne gider.
- Barkod değişmemeli. Bir kez gönderildikten sonra değiştirilen barkod, yeni bir ürün olarak algılanır ve eskisi güncellenemez hale gelir.
WooCommerce tarafında barkod alanı varsayılan olarak bulunmaz. Genelde stok kodu alanı bu iş için kullanılır veya özel bir alan tanımlanır. Hangi alanın kullanılacağına entegrasyon başlamadan karar verilmelidir.
Varyasyonlu ürünlerde her varyasyonun ayrı stok kodu taşıdığından emin olun. Bu, entegrasyon projelerinde en sık atlanan hazırlıktır.
Stok ve fiyat senkronizasyonu
Bu, entegrasyonun en sık çalışan ve en kritik parçasıdır. Ürün aktarımı bir kez yapılır, stok güncellemesi ise gün boyunca sürekli çalışır.
Tetikleme mantığı
İki yaklaşım var. Zamanlanmış görevle belirli aralıklarla tüm ürünleri güncellemek ya da yalnızca değişen ürünleri anında göndermek.
Doğru yapı ikisinin birleşimidir:
- Olay bazlı gönderim. Sitede bir sipariş oluştuğunda veya stok elle değiştirildiğinde ilgili ürün hemen kuyruğa alınır.
- Periyodik tam senkronizasyon. Günde bir kez tüm katalog karşılaştırılır. Kaçan güncellemeler burada yakalanır.
Sadece periyodik çalışan bir yapıda, iki senkronizasyon arasındaki sürede fazla satış yapma riski doğar. Sadece olay bazlı çalışan bir yapıda ise başarısız olan bir istek fark edilmeden kalır.
Kuyruk kullanın
Stok güncellemesini doğrudan sipariş anında göndermek yanlış bir tasarımdır. Pazaryeri servisi yavaş yanıt verirse müşterinizin ödeme adımı bekler.
Doğru yapı şudur: sipariş anında ürün bir kuyruğa yazılır, arka planda çalışan bir işleyici kuyruğu boşaltır. Böylece müşteri deneyimi pazaryeri servisinin performansından etkilenmez.
Kuyruk ayrıca toplu gönderim imkanı sağlar. Tek tek istek göndermek yerine değişen ürünleri gruplayıp tek istekte göndermek, hem hızlı hem de limit dostudur.
Toplu işlem sonucunu takip etmek
Toplu gönderimlerde istek anında sonuç dönmez. Sistem bir işlem kimliği verir, sonucu ayrıca sorgulamanız gerekir.
Burada sık yapılan hata, isteği gönderip başarılı saymaktır. İşlem kimliği sorgulanmazsa hangi ürünlerin reddedildiğini asla öğrenemezsiniz.
Sağlıklı bir entegrasyon her toplu işlemin sonucunu sorgular, reddedilen kayıtları hata sebebiyle birlikte kaydeder ve bunları yönetici arayüzünde görünür kılar.
Fiyat alanlarını doğru kurmak
Pazaryerine gönderilen fiyat tek bir değer değildir. Liste fiyatı ve satış fiyatı ayrı alanlardır.
Liste fiyatı üstü çizili gösterilen referans fiyat, satış fiyatı ise müşterinin ödediği tutardır. İkisini aynı göndermek indirim görünümünü ortadan kaldırır.
Buradaki en yaygın hata, kendi sitenizdeki indirimli fiyat mantığını olduğu gibi aktarmaktır. Kendi sitenizde kampanya bittiğinde fiyat normale döner, ancak bu değişikliğin pazaryerine de yansıması gerekir.
Vergi oranı da ürün bazında gönderilir. Farklı vergi oranına tabi ürün grupları varsa bu bilginin katalogunuzda doğru tutulması gerekir. Yanlış vergi oranı ürünün reddedilmesine değil, hatalı faturalandırmaya yol açar ve fark edilmesi çok daha uzun sürer.
Sipariş akışı
Sipariş servisinde dikkat edilmesi gereken en önemli nokta şu: pazaryerinde sipariş ile paket aynı şey değildir.
Müşteri tek seferde beş ürün alsa bile, bu ürünler farklı paketlere bölünebilir. Kargo süreçleri ve durum güncellemeleri paket üzerinden yürür.
Kendi sisteminizde sipariş yapısını buna göre kurmanız gerekir. Bir pazaryeri siparişini kendi sitenizdeki tek bir siparişe birebir eşlemeye çalışmak, kargo aşamasında sorun çıkarır.
Durum geçişleri
Siparişler belirli durumlar arasında ilerler. Yeni sipariş, işleme alındı, kargoya verildi, teslim edildi gibi.
Bu geçişlerin bir kısmını siz tetiklersiniz, bir kısmı pazaryeri tarafından otomatik güncellenir. Entegrasyonun her iki yönü de doğru işlemesi gerekir.
Özellikle iptal ve iade durumlarında stok geri yüklemesinin çalıştığından emin olun. İade edilen ürünün stoğa dönmemesi, zamanla envanterin gerçekle bağını koparır.
Kargo ve teslimat bilgisi
Sipariş alındıktan sonraki adımda kargo bilgisinin doğru iletilmesi gerekir. Pazaryerleri teslimat sürelerini satıcı performansına yansıttığı için bu akıştaki gecikmeler doğrudan görünürlüğünüzü etkiler.
Entegrasyonda dikkat edilecek üç nokta var:
- Kargo firması eşlemesi. Kendi sisteminizdeki kargo seçenekleri pazaryerinin tanımlı listesiyle eşleşmelidir.
- Takip numarasının zamanında gönderilmesi. Gecikmeli gönderilen takip bilgisi, siparişin geç kargolanmış gibi görünmesine yol açar.
- Kısmi gönderim. Bir paketin bir kısmı gönderilip kalanı iptal edildiğinde akışın bunu doğru işlemesi gerekir.
Servis limitleri ve hata yönetimi
Pazaryeri servisleri belirli bir süre içinde kabul ettikleri istek sayısını sınırlar. Limit aşıldığında istekleriniz reddedilir.
Sağlam bir entegrasyonda şu üç davranış bulunur:
Kademeli yeniden deneme. Reddedilen istek hemen tekrar gönderilmez. Bekleme süresi her denemede artırılır. Aksi halde limit sürekli dolu kalır.
Hata ayrımı. Geçici hatalar ile kalıcı hatalar farklı ele alınmalıdır. Sunucu kaynaklı geçici bir hata tekrar denenmeli, ancak eksik zorunlu alan gibi kalıcı bir hata tekrar denenmemelidir. Aynı hatalı kaydı sonsuza kadar denemek kuyruğu kilitler.
Günlük tutma. Her isteğin ne gönderdiği ve ne yanıt aldığı kaydedilmelidir. Bir ürünün neden yayınlanmadığını anlamanın tek yolu budur.
Zaman aşımı ve tekrarlanan gönderim
İstek zaman aşımına uğradığında işlemin karşı tarafta gerçekleşip gerçekleşmediğini bilemezsiniz. Körlemesine tekrar göndermek çift kayıt üretebilir.
Bu yüzden gönderimlerin tekrar edilebilir olacak şekilde tasarlanması gerekir. Aynı barkodla yapılan ikinci bir stok güncellemesi zarar vermez, ancak aynı siparişe iki kez kargo bilgisi göndermek sorun çıkarır.
WooCommerce tarafındaki hazırlık
Entegrasyonun başarısı büyük ölçüde kendi sitenizdeki veri yapısının düzenine bağlıdır. Dağınık bir katalogla kurulan entegrasyon sürekli hata üretir.
Başlamadan önce şu beş maddeyi tamamlayın:
- Varyasyon yapısını netleştirin. Renk ve beden gibi nitelikler ürün bazında değil, site genelinde tanımlı olmalı. Her üründe farklı yazılmış nitelik değerleri eşlemeyi imkansız hale getirir.
- Stok kodlarını tekilleştirin. Boş veya tekrar eden stok kodları entegrasyonun ilk gün çökeceği yerdir.
- Görselleri düzenleyin. Pazaryerlerinin görsel boyut ve oran beklentileri vardır. Standart dışı görseller ürünün reddedilmesine yol açar.
- Ürün açıklamalarını sadeleştirin. Kendi sitenizde çalışan gömülü içerikler ve özel biçimlendirmeler pazaryerinde kabul edilmez.
- Fiyat mantığını kurun. Pazaryeri fiyatı site fiyatından farklı olacaksa, bu farkın nerede hesaplandığı en baştan belirlenmelidir.
Bu hazırlık entegrasyondan bağımsız olarak da faydalıdır. Düzenli bir katalog, kendi sitenizin arama ve filtreleme performansını da iyileştirir. Bu konuyu ürün sayfası SEO yazısında ele aldım.
Sunucu tarafında dikkat edilecekler
Entegrasyon arka planda sürekli çalışan bir yapıdır. Paylaşımlı barındırmada bu, kaynak limitlerini zorlayabilir.
WordPress’in kendi zamanlanmış görev sistemi ziyaretçi trafiğine bağlı çalışır. Trafik düşük olduğunda görevler gecikir. Entegrasyon için sunucu tarafında gerçek bir zamanlanmış görev tanımlamak daha güvenilirdir.
Kaynak tüketimi arttığında hangi paket tipinin uygun olduğunu hosting değiştirme yazısında anlattım.
Entegrasyon sağlığını izlemek
Entegrasyonun en tehlikeli hali çökmüş olması değil, sessizce yanlış çalışmasıdır. Çöken bir entegrasyon hemen fark edilir. Yarısı çalışan bir entegrasyon aylarca fark edilmez.
Bu yüzden entegrasyonun kendi sağlık göstergeleri olmalıdır. Takip edilmesi gereken dört değer şunlar:
| Gösterge | Ne anlama gelir | Alarm eşiği |
|---|---|---|
| Kuyrukta bekleyen kayıt sayısı | İşleyici yetişemiyor veya durmuş | Sayı sürekli artıyorsa |
| Son başarılı senkronizasyon zamanı | Akış ne zamandır çalışmıyor | Beklenen aralığın iki katı geçtiyse |
| Reddedilen kayıt oranı | Veri kalitesi bozuluyor | Toplam gönderimin belirli bir oranını aşarsa |
| Pazaryeri ile kendi stoğunuz arasındaki fark | Senkronizasyon güvenilirliği | Herhangi bir kalıcı fark varsa |
Son madde en önemlisi. Günde bir kez iki taraftaki stok değerlerini karşılaştıran bir kontrol, entegrasyonun gerçekten çalışıp çalışmadığını gösteren tek kesin ölçüdür.
Bu kontrolün sonucu bir yönetici ekranında görünmeli ve fark tespit edildiğinde bildirim üretmelidir. Kimsenin bakmadığı bir günlük dosyası izleme sayılmaz.
Birden fazla pazaryerine açılırken mimari
Bugün tek pazaryeriyle başlayıp yarın ikincisini eklemek yaygın bir senaryo. Baştan doğru kurulan mimari bu geçişi kolaylaştırır.
Kritik karar şu: entegrasyon mantığı pazaryerine özel mi yazılacak, yoksa ortak bir katman üzerinden mi çalışacak?
Ortak katman yaklaşımında kendi sisteminiz tek bir standart ürün ve stok modeli üretir. Her pazaryeri için yalnızca çeviri katmanı yazılır.
Bu yaklaşımın avantajı şudur: ikinci pazaryerini eklemek, birincinin tüm mantığını baştan yazmayı gerektirmez. Yalnızca kategori eşlemesi ve alan çevirisi yapılır.
Doğrudan pazaryerine özel yazılan entegrasyonlarda ise her yeni kanal sıfırdan bir proje demektir. İki kanalın ötesine geçmeyi düşünüyorsanız baştan ortak katman kurmak daha az emek ister.
Sık yapılan teknik hatalar
Kategori ağacını her seferinde yeniden çekmek. Bu veri sık değişmez. Her istekte çekmek gereksiz yük yaratır ve limitleri doldurur.
Tüm katalogu her senkronizasyonda göndermek. Değişmeyen ürünleri tekrar göndermek hem yavaştır hem de gereksizdir. Yalnızca değişen kayıtları göndermek gerekir.
Hata yanıtlarını yok saymak. Reddedilen ürünler görünür kılınmazsa, katalogun bir bölümünün hiç yayınlanmadığı aylarca fark edilmez.
Stok değerini doğrudan yansıtmak. Kendi sitenizde on adet varsa pazaryerine on göndermek risklidir. Aynı anda iki kanaldan satış olduğunda eksiye düşersiniz. Güvenlik payı bırakmak yaygın bir yaklaşımdır.
Tek yönlü düşünmek. Entegrasyon yalnızca ürün göndermekten ibaret değildir. Sipariş, iade ve stok geri yüklemesi de akışın parçasıdır.
Ne zaman özel geliştirme gerekir
Standart bir katalog yapısı ve tek bir pazaryeri söz konusuysa hazır çözümler işi görür.
Özel geliştirme şu durumlarda gerekli hale gelir:
- Stok birden fazla depo veya şube arasında dağıtılıyorsa
- Fiyatlandırma kural bazlı çalışıyorsa, örneğin kanala ve rekabete göre otomatik değişiyorsa
- Kendi ERP veya muhasebe sisteminizle çift yönlü bağlantı gerekiyorsa
- Ürün yapınız standart varyasyon mantığına oturmuyorsa
- Sipariş sonrası kendi iş akışınızın tetiklenmesi gerekiyorsa
Bu maddelerden biri sizde varsa hazır çözümü zorlamak yerine baştan özel bir yapı kurmak uzun vadede daha az maliyetlidir.
Mevcut katalog yapınızın entegrasyona hazır olup olmadığını değerlendirmek isterseniz bana yazabilirsiniz.
Sık sorulan sorular
Trendyol API kullanmak için ne gerekiyor?
Aktif bir satıcı hesabı, panel üzerinden oluşturulan erişim anahtarları ve satıcı kimlik numarası gerekir. Kimlik doğrulama yapısı ve servis adresleri için Trendyol’un geliştirici dokümantasyonundaki güncel bilgiler esas alınmalıdır. WooCommerce tarafındaki anahtarları oluşturma adımlarını da WooCommerce’in resmi REST API dokümantasyonundan takip edebilirsiniz.
Stok senkronizasyonu ne sıklıkta çalışmalı?
Sipariş ve stok değişikliklerinde anında tetiklenen bir kuyruk, buna ek olarak günde en az bir kez çalışan tam senkronizasyon önerilir. Yalnızca periyodik çalışan yapılarda fazla satış riski doğar.
Aynı ürünü hem sitemde hem Trendyol’da satarken stok nasıl yönetilir?
Tek bir stok kaynağı belirlenir ve tüm kanallar bu kaynaktan beslenir. Aynı anda iki kanaldan satış ihtimaline karşı pazaryerine gönderilen stokta güvenlik payı bırakmak yaygın bir uygulamadır.
Ürünlerim neden yayınlanmıyor?
En sık sebep kategori özniteliklerindeki eksikliktir. Zorunlu bir alan gönderilmediğinde veya seçenek listesi dışında bir değer gönderildiğinde ürün reddedilir. Toplu işlem sonucunu sorgulamak, reddedilme sebebini gösterir.
Hazır entegratör yerine özel geliştirme ne zaman mantıklı?
Çok depolu stok yönetimi, kural bazlı fiyatlandırma, ERP bağlantısı veya standart dışı ürün yapısı varsa özel geliştirme daha uygun olur. Tek pazaryeri ve standart katalog için hazır çözümler yeterlidir.
Bu yazıları da okumak isteyebilirsiniz ...
Yazar Hakkında
2014'ten bu yana web tasarım, WordPress ve SEO & AI görünürlük alanlarında 500'den fazla işletmeye hizmet veriyorum.