Trendyol API 2026 Değişiklikleri: Alan Adları, V2 Geçişi ve 10 Ağustos Tarihi

2026, Trendyol satıcı API'siyle entegrasyon geliştiren herkes için iki dalgalı bir yıl: Nisan'da orders kalem alanları yeniden adlandırıldı ve eski adlar birkaç gün içinde prod'dan kaldırıldı; 10 Ağustos 2026'da ise Ürün V1 servisleri tamamen kapanıyor. Kendi entegrasyonunu yazan satıcıysan, bir ERP/entegratör geliştiriyorsan ya da Trendyol verisi çeken herhangi bir sistemi ayakta tutuyorsan bu yazı senin için: tüm değişiklikleri tek yerde topladık — eski→yeni alan adı tablosu, yeni kapsam ve kayıt sınırları, V2'nin V1'den farkları ve geçişi nasıl test edeceğin.

2026 zaman çizelgesi: neyin ne zaman değiştiği

Kritik olan şu: bunların hiçbiri "API hata vermeye başlar, fark edersin" cinsinden değişiklikler değil. Alan adı değişiminde istek yine 200 döner, JSON yine gelir — sadece senin okuduğun anahtar artık yoktur ve kodun sessizce null okur. Sipariş tutarlarını bu alanlardan hesaplayan bir sistemde bunun anlamı, bir sabah tüm kalemlerin 0 TL görünmesidir.

Nisan 2026: orders alan adı değişiklikleri (eski → yeni)

2 Nisan 2026 changelog'uyla duyurulan ve 6 Nisan'da eski adları prod'dan kaldırılan değişikliklerin tam listesi:

Dikkat: vatBaseAmount → vatRate saf bir yeniden adlandırma değil

Tablodaki satırların çoğu ad değişikliği; vatBaseAmount → vatRate ise içerik değişikliği. Alan artık bir tutar değil, oran taşıyor. KDV matrahına ihtiyacın varsa onu KDV dahil satır tutarından kendin türetmen gerekiyor: matrah = lineGrossAmount ÷ (1 + vatRate/100). Burada satıcıların klasik hatasına da değinelim: Trendyol'da müşteri fiyatları KDV dahildir ve komisyon KDV dahil satış fiyatı üzerinden hesaplanır — bu Nisan'da değişen bir kural değil, zaten geçerli olan kural. Nisan'da değişen şey API alan adlarıydı. Marj hesabını API verisinden kuran bir entegrasyonda bu ayrımı doğru kodlamak kritik; ayrıntısı "Trendyol komisyonu KDV dahil fiyattan mı kesilir?" yazısında.

Neden çoğu entegrasyon bunu geç fark etti?

Çünkü hiçbir şey "kırılmadı". HTTP 200, geçerli JSON, tanıdık yapı — sadece item["price"] artık undefined. Dinamik dillerde ve toleranslı parser'larda bu, exception değil sessiz null/0 üretir. Duyuru (2 Nisan) ile kaldırma (6 Nisan) arasında yalnızca birkaç gün olduğu için "changelog'u ayda bir okurum" ritmi de yetmedi. Ders: alan bazında boş-değer oranını izleyen bir alarm, changelog takibinden daha güvenilir bir sigortadır — aşağıdaki test bölümünde nasıl kurulacağını anlatıyoruz.

Orders geçmişi 1 ayla sınırlanıyor: backfill'i erteleme

Orders endpoint'inden çekilebilen geçmiş kapsamı 1 ayla sınırlanıyor. Bunun pratik anlamı büyük: bugüne kadar "lazım olunca eski siparişleri API'den çekerim" diyebiliyordun; artık diyemeyeceksin. Yapman gerekenler:

• Kendi veri tabanını tek gerçek kaynak yap. Siparişleri çektiğin anda kalıcı olarak sakla; API'yi arşiv gibi kullanma.
• Geçmişe dönük ihtiyacın varsa backfill'i şimdi koş. Pencere daraldıktan sonra o veriye API'den erişemezsin.
• Artımlı senkronu sıklaştır. Senkron işin birkaç hafta aksarsa, kaçan aralık kalıcı veri kaybına dönüşebilir.

Sipariş verisi; hakediş mutabakatı, iade analizi ve gerçek kâr hesabının ham maddesi. Bu verinin üzerine hangi kesintilerin bindiğini görmek için Trendyol hakedişi nasıl hesaplanır yazısına bakabilirsin.

getShipmentPackages'a 10.000 kayıt sınırı ve Stream endpoint

Yüksek hacimli mağazaların gönderi paketlerini sayfa sayfa çektiği getShipmentPackages endpoint'ine 10.000 kayıt sınırı geliyor. Trendyol, bu sınırı aşan hacimler için Stream endpoint'ini öneriyor. Entegrasyon tarafında bu, "sayfa numarasını artıra artıra sonuna kadar git" deseninin yüksek hacimde artık çalışmayacağı anlamına gelir: 10.000. kayıttan sonrası gelmez ve kodun bunu bir hata olarak değil, "liste bitti" olarak görür — yine sessiz bir veri kaybı senaryosu. Günlük paket adedi bu sınıra yaklaşan bir sistem geliştiriyorsan Stream tabanlı akışı şimdiden planla; yaklaşmıyorsan bile sınıra çarpınca alarm üreten bir kontrol ekle.

10 Ağustos 2026: Ürün V1 servisleri kapanıyor

Yılın en sert tarihi bu: Ürün V1 servisleri 10 Ağustos 2026'da kapanıyor. Alan adı değişikliğinin aksine burada geçiş dönemi sonrası istekler tamamen çalışmaz hale gelecek. V2'nin V1'den farkları:

• Yeni endpoint: onaylı ürünler /products/approved üzerinden listeleniyor.
• Sayfa boyutu küçüldü: size en fazla 100. V1'de daha büyük sayfalarla çalışan senkron işlerin istek sayısı artacak — rate limit ve süre bütçeni buna göre güncelle.
• İç içe yapı: ürün cevabında content ve variants iç içe geliyor. Düz (flat) ürün satırı bekleyen parser'lar ve veritabanı eşlemeleri yeniden yazılmalı.
• Cursor tabanlı sayfalama: sayfa numarası yerine nextPageToken kullanılıyor. "page=5'e atla" gibi rastgele erişim yok; her sayfa bir öncekinin token'ıyla çekiliyor. Kaldığın yerden devam edebilmek için token'ı kalıcı saklamak (checkpoint) senin sorumluluğunda.

V2 geçiş kontrol listesi

1. Kodunda V1 ürün endpoint'lerine giden tüm çağrıları envanterle (grep yeterli).
2. V2 cevabının iç içe content/variants yapısına göre parse ve veritabanı eşlemesini güncelle.
3. Sayfalamayı nextPageToken döngüsüne çevir; token'ı checkpoint olarak sakla, boş/son sayfa davranışını testle doğrula.
4. size=100 ile toplam istek sayısını ve senkron süresini yeniden hesapla.
5. Geçişi 10 Ağustos'a bırakma: V2'yi şimdi devreye al, V1'i yalnızca karşılaştırma için birkaç hafta paralel tut, sonra kapat.

Entegrasyonunu nasıl test edersin? (Nisan'dan çıkardığımız dersler)

Bu değişiklikleri kendi entegrasyonumuzda canlı yaşadık; aşağıdaki pratikler teori değil, Nisan sabahı işe yarayan şeyler:

• Ham cevabı sakla. Parse ettiğin alanların yanında API'nin ham JSON'unu da (ör. bir raw_data kolonu) tut. Alan adı değiştiğinde geçmiş veriyi yeni şemayla yeniden işleyebilirsin; saklamadıysan o veri parse edildiği günkü varsayımlara gömülüdür.
• Alan bazında boş-değer alarmı kur. "Son 24 saatte gelen kalemlerin %90'ından fazlasında lineUnitPrice boş" gibi bir koşul, alan adı değişikliğini changelog'dan önce haber verir. Sessiz kırılmaya karşı en ucuz sigorta bu.
• Bilinmeyen alanları logla. Cevapta ilk kez gördüğün anahtarı bir kez logla ("first seen" disiplini). Yeni alanlar genelde eskilerinin kaldırılacağının ilk sinyalidir.
• Gerçek mağaza verisiyle doğrula. Sipariş geçmişi olmayan bir test mağazasında orders şemasını doğrulayamazsın; boş liste her şemayla "uyumludur". Küçük bir tarih penceresiyle gerçek mağazadan çekip alanları tek tek karşılaştır.
• Dokümana değil cevaba güven. Örnek: finans tarafında settlements tutarları credit/debt alanlarında gelir ve satıcı geliri kabaca credit − komisyon ile bulunur; otherfinancials çağrısında transactionType zorunludur ve tarih aralığı en fazla 15 günlük pencerelerle taranır. Bunların hiçbirini varsayımla değil, canlı cevabı inceleyerek öğrendik — aynı disiplini her endpoint'e uygula.
• Sayfalama uç durumlarını testle. Son sayfa, boş sonuç, geçersiz token, sınıra (10.000 kayıt / size 100) çarpma — hepsi için beklenen davranışı yazılı hale getir ve otomatik testle sabitle.

Veriyi çekmek işin yarısı

API'den doğru veriyi çekmek işin yarısı; öteki yarısı o veriden doğru sonuç çıkarmak: komisyon, kargo, hizmet bedeli ve stopaj düşüldükten sonra hangi ürünün gerçekten kâr ettiğini görmek. Tek bir ürün için bu hesabı Trendyol kâr hesaplama aracıyla, bir ödeme döneminin tamamı için hakediş hesaplama aracıyla yapabilirsin. Entegrasyonu sıfırdan yazıp bakımını üstlenmek istemiyorsan: Verimle Trendyol hesabını bağladığında sipariş, kesinti ve finans verisini çeker, ürün bazında gerçek kârı hesaplar ve beklenmeyen kesintileri tespit edip itiraz taslağı hazırlar — API şemasını izlemek ve bu yazıdaki gibi değişikliklere uyum sağlamak da bizim işimiz olur. Kâr Röntgeni özelliğini incele.