Trendyol Entegrasyon: API Bilgileri, Veri Aktarımı ve Sık Hatalar

Trendyol entegrasyon, Trendyol mağazanızı kendi e-ticaret sitenize, stok programınıza ya da muhasebe yazılımınıza Trendyol'un API'si üzerinden bağlamaktır. Trendyol'un entegrasyon belgelerine göre bu bağlantıyla ürün aktarılır, stok ve fiyat güncellenir, sipariş paketleri alınır, fatura gönderilir ve müşteri soruları yanıtlanır; iade, kargo ve cari hesap verisi için de ayrı servisler vardır. Bağlantının anahtarı satıcı panelinden alınır, gönderilen her toplu isteğin sonucu ayrıca okunur ve siparişler paket statüleriyle izlenir. Bu yazı entegrasyonun neyi taşıdığını, hangi kurallara bağlı olduğunu ve en sık nerede bozulduğunu anlatır.

Konu	Trendyol'un Kuralı
API Bilgileri	Satıcı kimliği, API anahtarı ve gizli anahtar; yalnızca ana kullanıcıya görünür
Test Ortamı	Ayrı hesap ve ayrı API bilgileri; sunucunun çıkış IP adresi önceden bildirilir
Ürün Açma	En alt seviyedeki kategoriyle ve zorunlu özelliklerle; aktarımdan sonra onay süreci
İşlem Sonucu	Dönen toplu işlem kimliği başarı demek değildir; sonuç ayrıca sorgulanır
Sipariş	Ödeme kontrolünden geçen sipariş paketlenir ve paket statüleriyle izlenir
Webhook	Anlık bildirim verir; yanında periyodik sipariş çekme önerilir
Sürüm	Eski ürün ve sipariş servisleri kullanım dışıdır; V2 sürümü kullanılır

Trendyol entegrasyonunun bağladığı işler

Trendyol, Marketplace API'sini Trendyol Partner Programı'na katılan firmaların mağazalarını kendi e-ticaret sistemlerine bağlaması için sunar. Belgedeki servisleri işin yönüne göre iki grupta düşünmek işi kolaylaştırır. Ürün, stok, fiyat ve fatura satıcıdan Trendyol'a gider; sipariş paketleri, iade talepleri, müşteri soruları ve cari hesap hareketleri Trendyol'dan satıcının sistemine gelir. Soruların cevabı ve iadenin onayı ya da reddi yine satıcıdan Trendyol'a döner. Bu yapı, sitede pazaryeri entegrasyonu diye anılan işin Trendyol'daki karşılığıdır.

Bağlantıyı kendi yazılımınız, altyapınızın Trendyol uygulaması ya da bir entegrasyon firması kurabilir. Trendyol isteği kimin attığını isteğin kimlik bilgisinden ayırt eder; anlattığı servisler her durumda aynıdır ve kod desteği vermediğini sık sorulan sorularında açıkça yazar. Hangi verinin taşınacağı bu yüzden bağlandığınız yazılımın kapsamına bağlıdır; ürünü taşıyıp iadeyi taşımayan bir bağlantı da kurulabilir.

Mikro ihracat ve yurt dışı satış modellerinde ayrı ürün açma ve ayrı stok-fiyat servisi yoktur. Türkiye ürün listesindeki ürünler satıcı panelinden ihracata açılır, stok ve fiyat güncellemeleri de Türkiye ürünlerinden kendiliğinden yansır.

API bilgileri ve isteklerin kimliği

Bağlantı üç bilgiyle kurulur: satıcı kimliği, API anahtarı ve API gizli anahtarı. Bu bilgiler satıcı panelinin entegrasyon bilgileri bölümündedir ve yalnızca ana kullanıcı (admin rolü) ile giriş yapıldığında görünür. Panele ek kullanıcıyla giren çalışan bu bilgileri göremez; bağlantıyı kuracak kişiye bilgiyi ana kullanıcının vermesi gerekir.

Trendyol istekleri temel kimlik doğrulamayla yetkilendirir ve her istekte bir User-Agent bilgisi bekler. Bu bilgi isteği kimin attığını söyler: bir aracı firmayla çalışıyorsanız satıcı kimliğiniz ve firmanın adı, yazılım size aitse satıcı kimliğiniz ve kendi entegrasyonunuz olduğu yazılır. User-Agent bilgisi olmayan istek engellenir, yanlış kimlik bilgisi de yetki hatası döndürür.

Trendyol'un belgesi API anahtarının github, gitlab gibi açık platformlarda paylaşılmamasını ister. Anahtarı bilen herkes mağazanız adına ürün açabilir, fiyat değiştirebilir ve siparişe işlem yapabilir. Çalışan ya da birlikte çalıştığınız firma değiştiğinde anahtarın kimlerde olduğunu gözden geçirin.

Canlı ortam ve test ortamı

Trendyol'un canlı ortamında IP yetkilendirmesi gerekmez. Test ortamı ise canlıdan ayrı kurulmuştur: hesap ve API bilgileri canlıdakinden tamamen farklıdır, kendi satıcı paneli vardır ve erişim için uygulama sunucunuzun çıkış IP adresi Trendyol'a önceden bildirilir.

Test için ortak bir test hesabı kullanılabilir ya da özel test hesabı istenir; test ortamı talebi ve IP tanımı Trendyol'a açılan satıcı bildirimiyle yapılır. Test ortamında alınan 503 hatası belgeye göre IP yetkisinin olmamasından kaynaklanır; bu hatanın ayrıntısı Trendyol test ortamında 503 ve erişim sorunları maddesindedir.

Test siparişi açma ve test siparişinin statüsünü ilerletme servisleri yalnızca test ortamında çalışır. Bağlantıyı canlıya almadan önce bir siparişi paketlenmesinden faturasına kadar test siparişiyle denemek, hatayı gerçek bir müşterinin siparişinde yakalamaktan daha güvenlidir.

Ürünün Trendyol'a açılması

Ürün aktarımından önce Trendyol'un marka, kategori, kategori özellik ve özellik değeri listeleri alınır. Ürün yalnızca en alt seviyedeki kategoriyle açılır; alt kategorisi olan bir kategoriyle aktarım yapılamaz. Trendyol yeni kategori ve özellik ekleyebildiği için bu listelerin haftalık alınmasını önerir; güncel olmayan bir kategori ağacı eksik ya da hatalı veri girişine yol açar.

Kategorinin özellikleri kendi kurallarını taşır: bir özellik zorunlu olabilir, bazıları listeden seçilmek yerine serbest metin kabul eder, bazıları birden çok değer alır. Kendi sisteminizdeki renk, beden ya da malzeme alanının Trendyol'daki hangi özelliğe karşılık geldiği bu yüzden önceden eşlenir. Trendyol'un marka listesinde olmayan marka için ayrı bir marka yaratma servisi vardır. Zorunlu özelliklerin kontrolü Trendyol V2 kategori ve zorunlu ürün özellikleri maddesinde anlatılır.

Varyantlı ürünler aynı ana ürün koduyla, farklı barkod ve farklı stok koduyla aktarılır. Kategori özelliklerinden slicer olanlar ürünü ayrı içeriklere böler (çoğunlukla renk), varianter olanlar aynı içerik üzerindeki seçeneklerdir (çoğunlukla beden) ve bir kategoride yalnızca bir varianter seçilebilir. Ana ürün kodu, satıcı panelindeki model koduna denk gelir.

Barkod ürünün Trendyol'daki asıl anahtarıdır: stok ve fiyat güncellemeleri ve sipariş paketlerindeki işlemler içeri alınan barkoda göre yapılır. Barkodda özel karakter olarak yalnızca nokta, tire ve alt tire kullanılabilir. Ürünün liste fiyatı satış fiyatından küçük olamaz.

Aktarım başarılı olsa da ürün hemen satışa çıkmaz; önce Trendyol'un ürün onay sürecine girer. Onay süreci süren ya da reddedilen ürün yayına çıkmaz ve durumu ürün filtreleme servisinden okunur. Onaylanan üründe barkod, ana ürün kodu, marka, kategori ve varyant özelliklerinin değerleri güncellenemez; bu alanlar ilk aktarımda doğru gönderilmelidir.

Güncellemede bir alanı boş (null) göndermek, o alanın üründeki değerini tamamen siler; değişmesi istenmeyen alan isteğe hiç eklenmez. Bu risk onaysız ürün güncellemesinde boş alan riski maddesinde ayrıntılıdır. Arşivlenen ürün Trendyol'da görünmez ama silinmez; fiyat hatası ya da tedarik edememe nedeniyle satışı durdurulan ürünün kilidini satıcı kendisi açabilir.

Kuyruğa alınan isteklerin sonucu

Ürün aktarma, ürün güncelleme, stok ve fiyat güncelleme, arşivleme, silme ve kilit kaldırma istekleri Trendyol'da hemen işlenmez, kuyruğa alınır. Başarılı bir istek yanıt olarak toplu işlem kimliği döndürür. Trendyol'un sık sorulan sorularına göre bu kimliğin dönmesi işlemin başarılı olduğu anlamına gelmez; sonuç Toplu İşlem Kontrolü servisinden ayrıca okunur.

Sonuçta işlemin tamamlanıp tamamlanmadığı ve hata alan her ürünün nedeni yazar. Sonuçlar belgede yazan süre boyunca görüntülenebildiği için entegrasyon yazılımının sonucu bu süre içinde okuyup kaydetmesi gerekir. Stok ve fiyat güncellemesinde toplu işlem düzeyinde bir durum dönmez, sonuç ürün bazında okunur. Kimliğin izlenmesi Trendyol V2 toplu işlemlerinde batchRequestId ve hata takibi maddesinde anlatılır.

Stok ve fiyat, aktarılan ve onaylanan ürünlerde eş zamana yakın güncellenir. Gönderilen stok satılabilir stoktur; sipariş alındığında ya da yeniden stok gönderildiğinde değişir. Yalnızca stok ya da yalnızca fiyat da gönderilebilir. Trendyol değişiklik olmadan aynı isteğin kısa süre içinde tekrar gönderilmesini hatayla geri çevirir; bu yüzden yalnızca değişen stok ve fiyat gönderilir. Kuralın ayrıntısı stok ve fiyat güncellemesinde tekrar istek hatası maddesindedir.

Sipariş paketleri ve paket statüleri

Trendyol'da sipariş, ödeme kontrolünden geçtikten sonra sistem tarafından otomatik olarak paketlenir ve entegrasyon siparişi bu paket üzerinden alır. Paket ya sipariş paketlerini çekme servisinden ya da webhook ile gelir. Paketleme ve paket üzerindeki işlemler, ürün aktarımında gönderilen barkoda göre yapılır.

Paket statülerinin çoğunu Trendyol kendisi verir. Satıcının bildirebildiği yalnızca iki statü vardır ve sırası bellidir: önce toplamaya başlandığını söyleyen Picking, sonra faturanın kesildiğini söyleyen Invoiced. Ödeme onayı bekleyen Awaiting ve Verified statülerindeki sipariş yalnızca stok için kullanılır; belge, bu siparişlerin kargoya verilmesi hâlinde yaşanabilecek iptallerden Trendyol'un sorumluluk kabul etmediğini yazar.

Paketten bir ya da birkaç kalem iptal edilirse ya da paket bölünürse sipariş numarası aynı kalır, ama eski paket bozulur ve yeni bir paket kimliğiyle yeni bir kargo barkodu oluşur. Tedarik edememe bildirimi de aynı sonucu doğurur. Bu yüzden böyle bir işlemden sonra paketler yeniden çekilir ve gönderim yeni paketle yapılır; ayrıntı Trendyol paket bölmede yeni paket kimlikleri maddesindedir.

Tedarik edememe nedenleri belgede tanımlı bir listedir: stok tükenmesi, kusurlu ürün, hatalı fiyat, entegrasyon hatası, toplu alım ve mücbir sebep. Entegrasyon hatası, entegrasyon firmasından kaynaklanan hatalı fiyat ya da stok aktarımını anlatır. Stok ve siparişte hangi tarafın neyden sorumlu olduğu Trendyol entegrasyonunda stok ve sipariş sorumluluğu maddesinde anlatılır.

Kargo bilgisi de sipariş verisiyle gelir. Kargo firması paket bazında değiştirilebilir; değişiklikten sonra paket yeniden çekilip kontrol edilir. Belgede sayılan bazı kargo firmalarında, kargo bedelini Trendyol'un ödediği gönderilerde ortak etiket barkodu Trendyol'dan alınır; öteki gönderilerde etiket ilgili kargo firmasından alınır.

Webhook ve periyodik sipariş çekme

Webhook, bir paketin statüsü değiştiğinde Trendyol'un sizin bildirdiğiniz bir adrese istek göndermesidir. Tek webhook bütün paket statülerini verir ve her istek siparişin tam verisini taşır; böylece sipariş, servis sürekli sorgulanmadan sisteminize düşer.

Trendyol, webhook ile veri gönderiminin her zaman mümkün olmayabileceğini yazar ve sipariş çekme servisiyle periyodik eşitleme yapılmasını önerir. Webhook'u tek kaynak saymak, bir kesinti sırasında oluşan siparişin sisteme geç ya da hiç düşmemesine yol açabilir. Trendyol'un değişiklik kaydında da webhook modelinde kesinti yaşandığını ve o aralıktaki siparişlerin sonradan aktarıldığını bildiren bir duyuru yer alır.

Bildirim en az bir kez iletilir; aynı pakete ait bildirim birden çok gelebilir. Bildirimi karşılayan adresin tekrar eden isteği tolere etmesi, yani aynı paketi ikinci bir sipariş gibi kaydetmemesi zorunludur; sözlükte bu davranış idempotent işlem diye anlatılır. Başarısız istek belirli aralıklarla yeniden denenir; belgede yazan sayıda hatadan sonra webhook pasife alınır ve satıcıya e-posta gider. Kesilen bildirimin nedenleri Trendyol webhook sipariş bildirimleri neden kesilir maddesindedir.

Çok sayıda paketi taramak ya da düzenli eşitleme yapmak için belge, sipariş paketlerini akışla (imleçle) çekme servisini önerir. Kayıp kaydın nasıl yakalanacağı Trendyol sipariş aktarımında cursor ve kayıp kayıt kontrolü maddesinde anlatılır.

İade talepleri ve müşteri soruları

Müşterinin açtığı iade talepleri iade servisinden çekilir. Ürün satıcıya ulaştığında iade, işlem bekleyen (WaitingInAction) statüsüne geçer ve yalnızca bu statüdeki iade onaylanabilir ya da reddedilebilir. Ret, belgede tanımlı ret sebeplerinden biriyle ve kısa bir açıklamayla yapılır. Trendyol ret sebeplerini değişiklik kaydıyla günceller; kaldırılan bir sebeple gönderilen istek hata verir. İade kaydının okunması Trendyol iade durumu ve değişiklik geçmişi maddesindedir.

Müşteri soruları da servisle çekilir ve cevap entegrasyondan gönderilebilir. Yalnızca cevap bekleyen statüdeki soru cevaplanır; cevap yasaklı kelime kontrolünden geçer ve yasaklı kelime içeren cevap reddedilir. Belgede yazan süre içinde cevaplanmayan soru kapanır, cevaplanmış soru da tekrar cevaplanamaz. Eksik görünen soruların ve reddedilen cevapların nedenleri Trendyol müşteri soruları eksik görünüyor ya da cevap reddediliyor maddesindedir.

Fatura bağlantısı ve cari hesap ekstresi

Satış faturası satıcının kendi sisteminde oluşturulur; entegrasyon faturanın bağlantısını Trendyol'a aktarır ya da dosyasını yükler. Bağlantı gönderildiğinde Trendyol müşteriye fatura bağlantısını iletir. Belge, bu yolla gönderilen fatura bağlantılarının hukuki zorunluluk gereği 10 yıl boyunca erişilebilir olması gerektiğini yazar; bağlantıyı veren sistemin bu süre boyunca açık kalması bu yüzden önemlidir.

Faturanın durumu sipariş verisinde izlenir: fatura beslenmemiş, kontrolde, hatalı bulunmuş ya da doğru bulunmuş olabilir. Hatalı bulunan fatura silinip yeniden gönderilir. Aynı pakete ikinci bir fatura ya da başka bir pakete gönderilmiş bir bağlantıyı yeniden göndermek çakışma (409) hatası verir; bu hata Trendyol fatura linkinde 409 hatası maddesinde ayrıntılıdır.

Muhasebe tarafında Trendyol'un cari hesap ekstresi servisi satış, iade, indirim ve kupon işlemlerini, hakediş ödemelerini ve Trendyol ile satıcı arasındaki faturaları verir; kargo faturalarının ayrıntısı ayrı bir servistedir. Belgeye göre ödeme emri, istisnalar dışında her çarşamba o hafta vadesi gelen siparişler için oluşur. Bu verinin muhasebe programına aktarılması muhasebe, ERP ve e-fatura entegrasyonu kapsamındaki bir iştir.

Servis sınırları ve sürüm değişiklikleri

Trendyol servislere istek sınırı uygular; sınır aşılınca 429 (çok fazla istek) hatası döner. Sınırlar servis gruplarına göre ortak sayılır ve satıcının ürün listeleme sınırına göre değişir: ürün servislerinde okuma, ürün yazma ve stok-fiyat yazma ayrı gruplardır, aynı gruptaki aktarma, güncelleme ve silme istekleri birlikte sayılır. Belgede yazan sınırlar zaman içinde güncellendiği için yazılımın sabit bir sayıya göre değil, 429 geldiğinde bekleyip yeniden deneyecek biçimde kurulması gerekir.

Ortak sınırın ayrıntısı Trendyol API 429 hatası ve ortak servis limitleri maddesinde, kavramın kendisi hız sınırlama teriminde anlatılır.

Trendyol servislerini sürümle günceller ve eski sürümleri kapatır. Belgeleri, eski ürün servislerinin (V1) ve sipariş çekme servisinin eski sürümünün kullanım dışı bırakıldığını yazar ve yeni sürüme (V2) geçilmesini ister. V2 sipariş servisi erişilebilir kayıt sayısını ve geriye dönük veri kapsamını sınırladığı için büyük taramalarda akış servisi önerilir. Bir bağlantı kodu değişmeden yalnızca bir sürüm kapanışıyla durabilir; bu yüzden belgelerin değişiklik kaydı düzenli izlenir (API sürümleme).

Değişiklik kaydı yalnızca sürüm kapanışlarını değil, yeni alanları ve ertelenen değişiklikleri de duyurur. Sipariş verisine ve webhook'a ödeme yöntemi alanının eklenmesi ve menşei bilgisinin ayrı alana taşınmasının ertelenmesi bu duyurulara örnektir.

Trendyol bağlantısında sık görülen hatalar

Trendyol'un belgelerinde ve sık sorulan sorularında öne çıkan hataların çoğu iki noktada toplanır: isteğin sonucunu okumamak ve Trendyol'un yeni oluşturduğu kimlikleri izlememek.

• Kimliği Sonuç Sanmak: Toplu işlem kimliği dönünce işi bitmiş saymak; hata alan ürün, sonuç okunmadan fark edilmez.
• Değişmeyen Stoğu Tekrar Göndermek: Her döngüde bütün kataloğu göndermek; değişmemiş istek hatayla geri döner.
• Boş Alan Göndermek: Güncellemede alanı boş bırakarak ürünün mevcut içeriğini silmek.
• Eski Kategori Listesiyle Çalışmak: Haftalık yenilenmeyen liste, sonradan eklenen zorunlu özelliği kaçırır.
• Yalnızca Webhook'a Güvenmek: Periyodik sipariş çekmeyi bırakmak ya da tekrar gelen bildirimi ikinci sipariş saymak.
• Eski Paket Kimliğiyle Devam Etmek: Bölünen ya da kısmen iptal edilen paketi yeniden çekmeden işleme devam etmek.
• Ödeme Bekleyen Siparişi Göndermek: Awaiting ya da Verified statüsündeki siparişi Created olmadan kargoya vermek.
• Faturayı İki Kez Beslemek: Aynı pakete ikinci fatura ya da aynı bağlantıyı başka bir pakete göndermek.
• Anahtarı Açık Depoya Koymak: API bilgilerini kodla birlikte herkese açık bir depoda paylaşmak.
• Eski Sürümde Kalmak: Kullanım dışı bırakılan ürün ve sipariş servislerine bağlı bir yazılımla çalışmayı sürdürmek.

Uzman desteği gerektiren durumlar

Trendyol bağlantısında servislerin kendisi kadar hangi verinin hangi sistemden çıkacağının kararı da sonucu belirler: stok tek bir yerde tutulur, sipariş tek bir yerde işlenir, fatura tek bir sistemden kesilir. AdPix, pazaryeri entegrasyonu kurulumu hizmetinde mağazayı Trendyol'a altyapının kendi bağlantısıyla ya da bir entegrasyon yazılımıyla bağlar; kategori, nitelik, varyant, stok ve fiyat eşlemesini kurar, bağlantıyı deneme aktarımı ve ilk siparişlerle sınar. Mağazanın Trendyol'daki ürün içeriği, kampanya ve satış işleri Trendyol danışmanlığı kapsamında ele alınır.

Trendyol entegrasyonu için diğer rehberler

• Pazaryeri entegrasyonu kurulumu
• n11 entegrasyon: API, ürün eşleştirme, stok ve sipariş aktarımı
• E-ticaret entegrasyon danışmanlığı
• Webhook nedir
• Trendyol sipariş paketleri eksik geliyorsa sayfalama ve tarih kontrolü
• Trendyol kargo değişikliğinde paket, desi ve koli eşleşmesi

Trendyol entegrasyonu hakkında sık sorulan sorular

Trendyol API bilgilerini satıcı panelinde kim görebilir?

Satıcı kimliği, API anahtarı ve API gizli anahtarı satıcı panelinin entegrasyon bilgileri bölümünde durur ve yalnızca ana kullanıcı (admin rolü) ile girişte görünür. Bağlantıyı bir yazılım firması kuracaksa bilgiyi ana kullanıcı iletir; Trendyol anahtarın açık platformlarda paylaşılmamasını ister.

Trendyol test ortamı canlı mağaza bilgileriyle kullanılabilir mi?

Kullanılamaz. Test ortamının hesap ve API bilgileri canlı ortamdan tamamen farklıdır; ortak test hesabı kullanılır ya da özel test hesabı istenir. Test ortamına erişim için uygulama sunucusunun çıkış IP adresi Trendyol'a önceden bildirilir, canlı ortamda ise IP yetkisi gerekmez.

Trendyol'a gönderilen ürün neden satışa çıkmıyor?

İki neden öne çıkar. İstekten dönen toplu işlem kimliği başarı anlamına gelmez; ürün hata almış olabilir ve nedeni Toplu İşlem Kontrolü sonucunda yazar. Hatasız aktarılan ürün de önce onay sürecine girer; onayı süren ya da reddedilen ürün yayına çıkmaz.

Trendyol webhook kullanılıyorsa sipariş çekme servisine gerek kalır mı?

Kalır. Trendyol, webhook ile gönderimin her zaman mümkün olmayabileceğini belirtir ve sipariş çekme servisiyle periyodik eşitleme önerir. Aynı pakete ait bildirim birden çok gelebileceği için karşılayan sistem tekrar eden bildirimi ikinci bir sipariş olarak kaydetmemelidir.

Trendyol entegrasyonu eski sürüm servislerle çalışmaya devam eder mi?

Trendyol'un belgeleri eski ürün servislerinin (V1) ve sipariş çekme servisinin eski sürümünün kullanım dışı bırakıldığını yazar ve V2 sürümüne geçilmesini ister. Eski sürümle kurulmuş bir bağlantı bu yüzden durabilir; yazılımın hangi sürümü kullandığını sağlayıcınıza sorun ve değişiklik kaydını izleyin.