Trendyol API Entegrasyonu Rehberi: ERP, Stok ve Sipariş

Trendyol'da satış yapan pek çok firmada gün aynı şekilde başlar: siparişler panelden tek tek okunur, ERP'ye elle girilir, kargo etiketi ayrıca hazırlanır, depodaki stok değiştiğinde Trendyol'daki stok da birinin aklına gelirse güncellenir. Ürün sayısı ve sipariş adedi düşükken bu düzen idare eder. Ama katalog büyüdükçe ya da ikinci bir pazaryeri eklendikçe, elle yürüyen her adım hem zaman kaybına hem de hataya dönüşür: tükenmiş ürünün satılması, yanlış fiyatla açılan liste, geç bildirilen kargo.

Trendyol API entegrasyonu bu adımları sistemler arasında otomatik konuşturmanın yoludur. Bu yazıda Trendyol satıcı API'sinin genel yapısını, hazır entegratör ile özel entegrasyon arasındaki kararı, ERP ve kargo tarafını, teknik olarak dikkat edilmesi gereken noktaları ve sık yapılan hataları anlatıyoruz. Amaç kod yazdırmak değil; bir entegrasyon projesine başlamadan önce doğru soruları sorabilmenizi sağlamak.

Trendyol API entegrasyonu ne işe yarar?#

Pazaryeri entegrasyonu, Trendyol'daki mağazanızla sizin kendi sistemleriniz (ERP, muhasebe, depo yazılımı, kendi e-ticaret siteniz) arasındaki veri akışını otomatik hâle getirir. Bir API entegrasyonu kurulduğunda tipik olarak şu işler elle yapılmaktan çıkar:

• Yeni ürünlerin Trendyol'a aktarılması ve mevcut ürün bilgilerinin güncellenmesi
• Stok ve fiyatın tek bir kaynaktan, düzenli aralıklarla Trendyol'a gönderilmesi
• Yeni siparişlerin çekilip ERP'de satış kaydına dönüştürülmesi
• Kargo takip numarası ve fatura bilgisinin Trendyol'a bildirilmesi
• İade taleplerinin ve müşteri sorularının tek bir ekranda takip edilmesi

Buradaki asıl kazanç hız kadar tutarlılıktır. Stok bilgisi tek bir yerde tutulduğunda "hangi rakam doğru?" sorusu ortadan kalkar.

Trendyol satıcı API'sinin genel yapısı#

Trendyol, satıcılara ve entegratör firmalara REST tabanlı bir API sunar ve dokümantasyonunu geliştirici portalında yayınlar. Ayrıntılar zaman içinde değişebildiği için, bir projeye başlarken her zaman güncel dokümana bakmak gerekir. Genel çerçeve şöyledir.

Entegrasyon bilgileri ve kimlik doğrulama#

API'ye erişim için gereken satıcı kimliği, API anahtarı ve gizli anahtar satıcı panelinde, hesap bilgilerinin altındaki entegrasyon bilgileri bölümünde yer alır. İstekler bu anahtarlarla Basic Authentication yöntemiyle doğrulanır. Trendyol ayrıca her istekte, satıcı kimliğini ve isteği gönderen tarafı (kendi entegrasyonunuz mu, bir entegratör firma mı) belirten bir User-Agent başlığı ister. Bu anahtarlar mağazanız üzerinde işlem yapma yetkisi verdiği için parola gibi korunmalı, kod deposuna veya paylaşılan dosyalara yazılmamalıdır.

Ürün aktarımı#

Ürünler Trendyol'a kategori, marka, barkod, görsel, açıklama ve kategoriye özel özelliklerle birlikte gönderilir. Gönderilen ürünler doğrudan satışa açılmaz; Trendyol tarafında bir onay sürecinden geçer. Ürün aktarımı toplu bir işlem olarak çalışır: isteği gönderdiğinizde sonucu hemen değil, bir toplu işlem kimliği (batchRequestId) alırsınız ve hangi ürünün başarılı, hangisinin hatalı olduğunu bu kimlikle ayrıca sorgularsınız.

Stok ve fiyat güncelleme#

Stok ve fiyat güncellemeleri de toplu çalışır ve aynı şekilde bir işlem kimliği döner. Pratikte entegrasyonun en sık çalışan parçası budur, çünkü depodaki her hareket ve her fiyat değişikliği Trendyol'a yansımalıdır. Doğru tasarımda yalnızca değişen ürünler gönderilir, tüm katalog her seferinde baştan yollanmaz.

Sipariş paketlerini çekme#

Trendyol'da siparişler "paket" mantığıyla takip edilir. Entegrasyon belirli aralıklarla yeni ve durumu değişen paketleri çeker, bunları ERP'de siparişe dönüştürür. Paketin durumu (yeni, hazırlanıyor, kargoya verildi, teslim edildi, iptal) iki sistem arasında senkron tutulmalıdır.

Kargo ve fatura bildirimi#

Sipariş hazırlandıktan sonra kargo takip bilgisi ve fatura bilgisi Trendyol'a bildirilir. Bu adım geciktiğinde hem müşteri deneyimi hem de satıcı performansı etkilenir. E-fatura ya da e-arşiv süreci ERP üzerinden yürüyorsa, faturanın oluştuğu anda Trendyol'a iletilmesi entegrasyonun bir parçası olarak düşünülmelidir.

İadeler ve talepler#

İade ve değişim talepleri ayrı bir API grubuyla takip edilir. İade edilen ürünün depoya geri girişi, stoka eklenmesi ve muhasebede iade kaydının oluşması, Trendyol'daki talebin durumuyla eşleşmelidir. Bu adım çoğu zaman entegrasyonun en çok ihmal edilen kısmıdır.

Müşteri soruları#

Ürün sayfasındaki müşteri soruları da API üzerinden okunup yanıtlanabilir. Soru sayısı fazla olan mağazalarda bu soruların tek bir ekranda toplanması, sık sorulan konuların görülmesini ve cevap süresinin takip edilmesini kolaylaştırır.

Hazır entegratör mü, özel entegrasyon mu?#

Piyasada Trendyol, Hepsiburada, n11 ve diğer pazaryerlerini tek panelden yöneten hazır entegratör yazılımları var. Çoğu satıcı için doğru başlangıç noktası da bunlardır. Karar verirken şu soruları sormak işe yarar:

• Süreciniz standart mı? Ürünleri bir yerde tutup pazaryerlerine gönderiyor, siparişleri tek ekranda topluyorsanız hazır çözüm büyük ihtimalle yeterlidir.
• ERP'niz hazır çözümle konuşabiliyor mu? Kullandığınız ERP'nin (örneğin Logo, Mikro, Netsis) seçtiğiniz entegratörle hazır bir bağlantısı varsa iş büyük ölçüde kolaylaşır.
• Size özel kurallar var mı? Depoya göre stok ayırma, pazaryerine özel fiyat formülü, üretime bağlı termin, set ürünler veya karmaşık varyant yapısı gibi kurallar hazır çözümlerin ayar ekranlarına sığmıyorsa özel entegrasyon gündeme gelir.
• Kendi siteniz ve iç sistemleriniz de işin içinde mi? Pazaryeri, kendi e-ticaret siteniz ve iç sistemleriniz arasında tek bir veri akışı kurmak istiyorsanız, özel bir ara katman daha esnek olabilir.

İki yaklaşım birbirini dışlamaz. Bazı firmalar ürün ve sipariş akışını hazır entegratörle yürütüp, yalnızca hazır çözümün karşılamadığı adımı (örneğin özel fiyat hesabı ya da raporlama) ayrıca geliştirir.

ERP ve kargo ile birlikte düşünmek#

Trendyol API entegrasyonu tek başına bir proje değildir; aslında ERP, depo ve kargo arasındaki akışın bir parçasıdır. Başlamadan önce şu soruların cevabı netleşmelidir:

• Ana kaynak hangisi? Ürün bilgisi, stok ve fiyat hangi sistemde tutulacak? Genellikle ERP ana kaynaktır ve Trendyol'a yalnızca oradan veri gider. İki tarafta da elle düzenleme yapılması kısa sürede tutarsızlığa yol açar.
• Sipariş ERP'ye nasıl düşecek? Trendyol'dan gelen siparişin hangi cari hesaba, hangi depoya ve hangi belge tipiyle kaydedileceği önceden tanımlanmalıdır.
• Kargo etiketi nerede hazırlanacak? Kargo süreci Trendyol'un anlaşmalı kargosuyla mı, sizin kargo anlaşmanızla mı yürüyecek? Takip numarası hangi adımda oluşacak ve kim bildirecek?
• Fatura nereden kesilecek? E-fatura ya da e-arşiv ERP'den kesiliyorsa, fatura bilgisi Trendyol'a otomatik mi iletilecek?

Bu akış kâğıt üzerinde çizilmeden yazılan kod, genellikle sonradan yeniden yazılır.

Kategori ve özellik eşleştirmesi#

Ürün aktarımında en çok zaman alan iş çoğu zaman kod değil, eşleştirmedir. Trendyol her kategori için belirli özellikler ister (renk, beden, malzeme, garanti süresi gibi); bunların bir kısmı zorunludur, bir kısmı yalnızca önceden tanımlı değerleri kabul eder. Sizin ERP'nizdeki ürün grupları ve özellik adları ise büyük ihtimalle farklıdır.

Bu yüzden kalıcı bir eşleştirme tablosu kurmak gerekir: hangi ürün grubunuz hangi Trendyol kategorisine, hangi özelliğiniz hangi Trendyol özelliğine ve hangi değeriniz hangi Trendyol değerine karşılık geliyor. Marka bilgisinin de Trendyol'daki marka listesiyle eşleşmesi gerekir. Bu tablo bir kez düzgün kurulduğunda yeni ürün açmak hızlanır; kurulmadığında her ürün ayrı bir el işi olur.

Rate limit ve toplu işlem mantığı#

Trendyol, API'ye gelen istek sayısını sınırlar. Kesin değerler uç noktaya göre değişebildiği ve zamanla güncellendiği için bunları güncel dokümandan kontrol etmek gerekir. Tasarım açısından önemli olan şunlardır:

• Toplu gönderin, tek tek değil. Stok ve fiyat güncellemeleri birden fazla ürünü tek istekte taşıyabilir. Her ürün için ayrı istek atmak hem limitlere takılır hem de gereksiz yavaştır.
• Yalnızca değişeni gönderin. Son gönderilen değeri saklayın; değişmeyen ürünü tekrar yollamayın.
• Sonucu sorgulayın. Toplu işlemler hemen sonuç döndürmez. Dönen işlem kimliğini saklayıp bir süre sonra sonucu kontrol eden bir adım olmalıdır. Trendyol'un dokümanına göre toplu işlem sonuçları, işlem tamamlandıktan sonra dört saate kadar görüntülenebiliyor; bu yüzden kontrol adımını geciktirmemek gerekir.
• Sınıra takılınca bekleyin. Sınır aşıldığında istek reddedilir. Entegrasyon bu durumda aynı isteği hemen tekrarlamak yerine bekleyip artan aralıklarla yeniden denemelidir.

Genel mantık kısaca şöyle özetlenebilir:

degisenler = son_gonderimden_beri_degisen_stoklar()
for parca in parcalara_bol(degisenler):
    islem_id = trendyol.stok_fiyat_gonder(parca)
    kuyruga_ekle(islem_id)

# daha sonra çalışan ayrı bir görev
for islem_id in bekleyen_islemler():
    sonuc = trendyol.toplu_islem_sonucu(islem_id)
    hatali_kalemleri_kaydet(sonuc)

Hata yönetimi ve loglama#

Bir entegrasyonun kalitesi, her şey yolundayken değil, bir şey ters gittiğinde ortaya çıkar. Ağ kesilir, Trendyol bir ürünü reddeder, ERP'de bir cari hesap eksik çıkar. Bu durumlar için:

• Gönderilen her isteği ve dönen her cevabı tarih, ürün ve işlem kimliğiyle birlikte kaydedin. "Bu ürünün fiyatı neden yanlış görünüyor?" sorusu geldiğinde cevap loglarda olmalıdır.
• Hatalı kalemleri sessizce atlamayın. Reddedilen ürünleri ve başarısız siparişleri bir listede toplayıp ilgili kişiye bildirin.
• Aynı siparişin iki kez işlenmesini engelleyin. Sipariş tekrar çekildiğinde ERP'de ikinci bir kayıt oluşmamalıdır.
• Kimin neyi değiştirdiğini takip edin. Fiyat ve stok değişikliklerinin kaynağı (ERP, elle düzeltme, kampanya) görünür olmalıdır.

Test ve canlı ortam#

Trendyol, canlı ortamın yanında ayrı bir test (stage) ortamı tanımlar. Test ortamı, gerçek siparişleri ve gerçek stokları etkilemeden entegrasyonu denemek içindir. Ancak test ortamına erişim için canlı ortamdan farklı tanımlamalar gerekebilir; bu konuyu baştan Trendyol'un güncel dokümanı ve destek kanalıyla netleştirmek iyi olur.

Canlıya geçişi kademeli yapmak da riski azaltır: önce yalnızca okuma (siparişleri çekip ERP'ye yazmadan karşılaştırma), sonra sınırlı sayıda ürün için stok ve fiyat gönderimi, en son tüm katalog. Her aşamada iki sistemdeki rakamların uyuştuğunu kontrol etmek, sorunları küçükken yakalamayı sağlar.

Birden fazla pazaryeri için ortak katman#

Trendyol'un yanında Hepsiburada ve n11'de de satış yapıyorsanız, her pazaryeri için ayrı ayrı ERP bağlantısı yazmak kısa sürede yönetilemez hâle gelir. Daha sağlıklı bir yapı, ERP ile pazaryerleri arasına ortak bir katman koymaktır:

• ERP yalnızca bu katmanla konuşur; ürün, stok, fiyat ve sipariş tek bir ortak formatta tutulur.
• Her pazaryeri için ayrı bir bağlayıcı, bu ortak formatı o pazaryerinin API'sine çevirir.
• Kategori eşleştirmesi, fiyat kuralları ve stok ayırma her pazaryeri için ayrı tanımlanabilir ama tek yerden yönetilir.

Bu yaklaşım, yeni bir pazaryeri eklemeyi mevcut akışa dokunmadan yalnızca yeni bir bağlayıcı yazmaya indirger. Hazır entegratörlerin çoğu da temelde bu mantıkla çalışır.

Sık yapılan hatalar#

• Stoku iki yerde tutmak: Hem ERP'de hem Trendyol panelinde elle stok düzeltmek, er geç fazla satışa yol açar.
• Tüm katalogu sık aralıklarla baştan göndermek: Limitlere takılır ve asıl acil güncellemeleri geciktirir.
• Toplu işlem sonucunu kontrol etmemek: İstek gönderildi diye işlemin başarılı olduğu varsayılır, reddedilen ürünler haftalarca fark edilmez.
• İadeleri sonraya bırakmak: Sipariş akışı kurulur ama iade akışı elle kalır; stok ve muhasebe kayıtları zamanla ayrışır.
• API anahtarlarını açıkta tutmak: Anahtarların kodda, e-postada ya da paylaşılan tablolarda durması ciddi bir güvenlik riskidir.
• Dokümanı bir kez okuyup bırakmak: Pazaryeri API'leri güncellenir. Duyuruları takip etmeyen bir entegrasyon, bir gün sessizce çalışmayı bırakabilir.

Nereden başlamalı?#

İlk adım kod değil, envanterdir: bugün elle yaptığınız pazaryeri işlerini listeleyin, hangisinin ne kadar zaman aldığını ve en çok hangisinde hata çıktığını not edin. Çoğu firmada en hızlı kazanç stok senkronizasyonu ve sipariş aktarımından gelir; ürün aktarımı ve iade akışı bunları izler.

Pazaryeri tarafında hangi adımın otomasyona uygun olduğunu, hazır bir çözümün yetip yetmeyeceğini ya da özel bir ara katmana ihtiyaç olup olmadığını birlikte değerlendirmek isterseniz iletişim sayfasından bize ulaşabilirsiniz. Gelen e-postaların sınıflandırılması için E-Posta Robotu, teklif süreçleri için Fiyatlandırma ve Teklif Otomasyonu gibi diğer çözümlerimize de hizmetler sayfasından göz atabilirsiniz.

Sık Sorulan Sorular#

Trendyol API entegrasyonu için API anahtarını nereden alırım?#

Satıcı kimliği, API anahtarı ve gizli anahtar Trendyol satıcı panelinde, hesap bilgilerinin altındaki entegrasyon bilgileri bölümünde yer alır. Bu bilgiler mağazanızda işlem yapma yetkisi verdiği için yalnızca entegrasyonu kuracak kişiyle güvenli bir kanaldan paylaşılmalıdır.

Hazır entegratör kullanmak mı, özel entegrasyon yaptırmak mı daha mantıklı?#

Süreciniz standartsa ve ERP'nizin hazır bir bağlantısı varsa hazır entegratör çoğu zaman daha hızlı ve ekonomiktir. Depoya göre stok ayırma, pazaryerine özel fiyat kuralları ya da kendi sitenizle ortak bir veri akışı gibi ihtiyaçlar hazır çözüme sığmıyorsa özel entegrasyon değerlendirilebilir.

Trendyol entegrasyonu Logo, Mikro veya Netsis ile çalışır mı?#

Bu ERP'ler dışarıdan veri alıp vermeye imkân tanır; ancak bağlantının nasıl kurulacağı kullandığınız ürüne, sürüme ve lisansa bağlıdır. Başlamadan önce ERP tarafında hangi bağlantı yöntemlerinin açık olduğunu ERP iş ortağınızla netleştirmek gerekir.

Stok ve fiyat ne sıklıkla güncellenmeli?#

Stok ne kadar hızlı değişiyorsa güncelleme de o kadar sık olmalıdır, ama her seferinde tüm katalog değil yalnızca değişen ürünler gönderilmelidir. Böylece hem API sınırlarına takılmazsınız hem de fazla satış riski azalır.

Hepsiburada ve n11 için ayrı entegrasyon mu gerekir?#

Her pazaryerinin kendi API'si vardır, bu yüzden her biri için ayrı bir bağlayıcı gerekir. Ancak ERP ile pazaryerleri arasına ortak bir katman koyarsanız ERP tarafı tek kalır ve yeni bir pazaryeri eklemek yalnızca yeni bir bağlayıcı yazmak anlamına gelir.