Trendyol API Entegrasyonu: 426 Hatası ve Kapanan Sipariş Servisi

Salı sabahı 09:40’ta siparişler durdu#

Bir ayakkabı markası. Gece boyunca siparişler sorunsuz aktı. Sabah 09:40’ta loglar kızardı ve tek bir satır tekrar etti: 426 Upgrade Required.

Panik on dakika sürdü. Sonra kendiliğinden geçti. Kimse not almadı, çünkü düzelmişti.

Öğlen tekrar oldu. Akşam bir kez daha.

Ekip sunucuyu yeniden başlattı. Hosting firmasını aradı. Trendyol panelinden mağaza durumunu kontrol etti, API anahtarını yeniledi, güvenlik duvarı kurallarına baktı. Hiçbiri sebep değildi.

Sistem bozulmamıştı. Trendyol, kapanacak bir servisi kullanmaya devam ettikleri için onlara kasıtlı olarak hata döndürüyordu.

Bu yöntemin adı brownout ve pazaryeri API’lerinde giderek yaygınlaşıyor. Servis sağlayıcı, kapanma tarihinden önce eski uç noktayı günün belirli aralıklarında bilerek devre dışı bırakır. Amaç ceza vermek değil, haber vermektir: sessizce çalışmaya devam eden bir entegrasyon kimseyi uyarmaz, ama günde üç kez on dakika duran bir entegrasyon mutlaka birinin dikkatini çeker.

426 tam olarak ne diyor#

HTTP 426 Upgrade Required, istemcinin kullandığı sürümün artık desteklenmeyeceğini bildirir. Sunucu “isteğin yanlış” demez. “Bu kapıdan girmeye devam edemezsin” der.

Trendyol’un 30 Temmuz 2026 tarihli geliştirici duyurusu tarihi net veriyor: aşağıdaki sipariş uç noktası 15 Ekim 2026 itibarıyla kullanım dışı kalıyor. O tarihe kadar bu servise yapılan isteklerde günde üç kez, onar dakika boyunca 426 dönüyor.

Aynı yöntem ürün tarafında zaten uygulandı. Ürün v1 servisleri için brownout günde üç kez on beşer dakikaydı ve servis 15 Eylül 2026’da kapandı. Yani bu bir deneme değil, Trendyol’un yerleşmiş geçiş pratiği.

Brownout penceresinin kısa ve aralıklı olması, sorunun fark edilmesini kolaylaştırdığı kadar yanlış teşhis edilmesini de kolaylaştırıyor; çünkü on dakika sonra her şey normale döndüğü için ekipler bunu geçici bir ağ dalgalanması ya da pazaryerinin kendi tarafındaki bir kesinti sanıp kayda bile geçirmiyor. Entegrasyonu izleyen bir uyarı sisteminiz yoksa bu döngü haftalarca sürebilir. Tarih geldiğinde ise servis kalıcı olarak kapanır ve o gün siparişleriniz hiç gelmez.

Burada bir noktanın altını çizmek gerekiyor. İnternette bulacağınız Türkçe entegrasyon rehberlerinin büyük bölümü hâlâ api.trendyol.com/sapigw adresini yazıyor. O adres artık geçerli değil; güncel taban adres apigw.trendyol.com/integration. Eski adrese göre yazılmış bir kılavuzu takip ederseniz hata ayıklamaya kendi kodunuzdan değil, yanlış bir başlangıç noktasından başlarsınız.

10.000 kayıt sınırı neyi kırar#

v2 uç noktasında erişilebilecek maksimum kayıt sayısı 10.000 ile sınırlandırıldı. Bu, çoğu satıcı için günlük işleyişte sorun çıkarmaz. Sorun, geçmişi tarayan işlerde çıkar.

Tipik senaryo şu. Muhasebe ayı kapatırken tüm siparişleri çekip mutabakat yapan bir toplu iş vardır. Bu iş sayfa sayfa ilerler, page parametresini artırır ve veri bitene kadar döner. Sınır devreye girdiğinde döngü erkenden biter. Hata fırlamaz. Rapor eksik üretilir ve kimse fark etmez.

Büyük hacimli tarama için Trendyol ayrı bir servis sunuyor: getShipmentPackagesStream. Bu servis imleç tabanlı akış yöntemiyle çalışır ve tam tarama, periyodik senkronizasyon ile dışa aktarma işleri için tasarlanmıştır. Son üç aylık siparişleri döndürür.

Geçerken dikkat edilecek tek şey var ve bu sessiz bir tuzaktır: imleç tabanlı sayfalamaya geçildiği için totalElements, totalPages ve page alanları artık dönmez. Bu alanlara bakarak kaç sayfa çekeceğini hesaplayan kod çökmez, sadece yanlış sonuç üretir.

Hangi hata hangi sebebe bakar#

Entegrasyon hatalarında en çok kaybedilen zaman, yanlış yerde arama yapmakla geçer. Kod bazlı bir ayrım tablosu işi kısaltır.

Haziran 2026’da getShipmentPackage servisinin limitleri değiştirildi ve yeni limitlerin üzerinde istek atan entegrasyonlar 429 almaya başladı. İki hatayı birbirine karıştıran ekipler, sürüm sorununu çözmek yerine haftalarca istek sıklığını düşürmeye çalıştı. İkisi farklı problemdir ve farklı çözülür.

API anahtarı, satıcı kimliği ve 403’ün asıl sebebi#

Entegrasyona yeni başlayanların en sık takıldığı yer kimlik doğrulamadır ve buradaki sorunların çoğu anahtarın yanlış olmasından değil, isteğin eksik gönderilmesinden kaynaklanır.

API bilgileri Trendyol Satıcı Paneli içindeki entegrasyon bilgileri bölümünden alınır; burada size bir satıcı kimliği, bir anahtar ve bir gizli anahtar verilir. Bu üçlüyü koda gömmek yerine ortam değişkenlerinde tutun, çünkü pazaryeri anahtarları sızdığında yapılabilecek şey sipariş okumakla sınırlı kalmaz.

Asıl tuzak şurada. Trendyol, isteklerin kendisini tanıtmasını bekler ve User-Agent başlığını göndermeyen çağrıları reddeder. Anahtarınız doğru olsa bile bu başlık eksikse yanıt 403 olur. Kütüphanelerin bir kısmı varsayılan bir başlık gönderdiği için sorun geliştirme ortamında görünmez, ancak sunucuda farklı bir HTTP istemcisi kullanıldığında aynı kod bu kez 403 döndürmeye başlar. Hata ayıklarken ilk bakılacak yer budur.

Geçişi nasıl yaparsınız#

Sıra önemli. Çoğu ekip doğrudan adresi değiştirip canlıya alıyor, sonra sipariş sayıları tutmayınca geri dönüyor.

1. Önce ölçün. Loglarınızda eski uç noktaya kaç farklı yerden istek gittiğini bulun. Tek bir servis sanılan şey çoğu zaman üç ayrı yerdedir: sipariş çekme, kargo durumu güncelleme ve bir unutulmuş rapor işi.
2. Yeni adresi test ortamında bağlayın. Aynı tarih aralığı için eski ve yeni servisten gelen sipariş sayısını karşılaştırın.
3. Sayfalama kodunu gözden geçirin. page ve totalPages alanlarına bağımlı her döngüyü işaretleyin.
4. Toplu tarama işlerini akış servisine taşıyın. Günlük senkronizasyonu v2’de bırakabilirsiniz, ay sonu mutabakatını taşıyın.
5. Canlıya aldıktan sonra bir hafta sayıları elle karşılaştırın. Bu adım atlanırsa eksik veri ancak muhasebe kapanışında görünür.

Bu adımların hiçbiri teknik olarak zor değildir, ancak sırayla yapılmadığında birbirini maskeler: adres değiştirildikten sonra sipariş sayısı düştüğünde bunun sayfalama kodundan mı, tarih filtresinden mi yoksa kayıt sınırından mı kaynaklandığını ayırt etmek, hepsini aynı anda değiştirmiş bir ekip için neredeyse imkânsızdır.

Test ortamı konusunda gerçekçi olmak gerekiyor. Pazaryeri entegrasyonlarında üretim verisine birebir benzeyen bir test ortamı çoğu zaman bulunmaz, bu yüzden doğrulamayı canlı veriyle ama salt okunur biçimde yapmak en pratik yoldur: yeni uç noktadan veriyi çekin, hiçbir yere yazmayın, yalnızca eski servisin döndürdüğü kayıtlarla karşılaştırın. Fark çıkarsa sebebi canlıya almadan bulmuş olursunuz.

Entegrasyonun geri kalan mimarisi (tek stok kaynağı, kuyruk, idempotency) için Trendyol ve Hepsiburada entegrasyonu yazımız daha ayrıntılı bir çerçeve veriyor. Siparişin ERP tarafına düşmesi ve e-fatura katmanı ayrı konulardır; bu geçiş yalnızca veriyi çektiğiniz kapıyı değiştirir.

Bu işi ne zaman yaptırmayın#

İki durumda dışarıdan destek almak para kaybıdır.

Hazır bir entegratör kullanıyorsanız bu geçiş sizin işiniz değil. Sağlayıcınız bunu yapmakla yükümlü. Yapmanız gereken tek şey, onlara yazıp 15 Ekim öncesinde geçişi tamamladıklarını yazılı olarak teyit etmek. Teyit alamıyorsanız asıl sorun bu geçiş değil, sağlayıcı seçiminizdir.

Tek bir yerden sipariş çeken, günde yirmi otuz sipariş alan ve kodu elinizin altında olan bir yapınız varsa bu değişiklik yarım günlük iştir. Adresi değiştirin, sayfalama kodunu kontrol edin, sayıları karşılaştırın. Bunun için ajans tutmak gereksiz.

Dışarıdan destek, siparişin ERP’ye, kargoya, muhasebeye ve müşteri kaydına dağıldığı, geçmişi tarayan toplu işlerin bulunduğu kurulumlarda anlamlı hale gelir. Orada risk adres değişikliği değil, sessizce eksilen veridir.

Bir daha aynı yerden vurulmamak için#

Bu olayın asıl dersi 426 kodunu öğrenmek değil. Asıl ders, entegrasyonun sessizce bozulabildiğini ve çoğu ekibin bunu öğrenmek için müşterinin şikâyet etmesini beklediğini görmektir.

İki basit önlem bu riski büyük ölçüde kapatır. Birincisi, pazaryeri çağrılarından dönen HTTP kodlarını tek tek saymak ve 2xx dışındaki her kodu ayrı bir sayaçta tutmaktır; 426 ya da 429 gibi bir kod ilk kez göründüğünde haberiniz olur, üç hafta sonra değil. İkincisi, “bugün kaç sipariş çektik” sorusunun cevabını her sabah otomatik olarak Trendyol panelindeki rakamla karşılaştırmaktır. Bu karşılaştırma, kodun fırlatmadığı ama sonucu bozan hataların neredeyse tamamını yakalar.

Uyarıyı nereye düşüreceğiniz önemli değil; e-posta, Slack ya da basit bir panel olabilir. Önemli olan, kimsenin bakmadığı bir log dosyasında kalmamasıdır. Kurulumu bir saat sürer ve tek bir kaçırılmış kampanya gününün maliyetini fazlasıyla karşılar.

Hepsiburada tarafında da benzer bir yapı var: webhook yanıtınız beş saniyenin üzerine çıkarsa sistem bildirim göndermeyi durdurabiliyor. Yani iki pazaryerinde de sessiz kopma mümkün ve ikisinde de çözüm aynı yere çıkıyor, düzenli mutabakata.

Takvimi takip etmek, hatayı beklemekten ucuz#

Pazaryeri entegrasyonlarında ekiplerin çoğu tepkiseldir: bir şey kırılır, bakılır, düzeltilir. Trendyol ve Hepsiburada ise değişiklikleri önceden, tarihli olarak duyuruyor.

Trendyol’un changelog sayfası düz metin olarak erişilebilir durumda. Ayda bir kez okumak, yılda bir kez acil müdahaleden çok daha ucuz. Aynısı ürün verisi tarafı için de geçerli.

Kendi entegrasyonunuzun hangi uç noktalara bağlı olduğunu bilmiyorsanız başlangıç noktası geçiş değil, envanter çıkarmaktır. API entegrasyonları ve kurumsal yazılım tarafında yaptığımız ilk iş de budur. Mevcut kurulumunuzu konuşmak isterseniz bize yazın; sık sorulanlara SSS sayfasından bakabilirsiniz.