Trendyol Entegrasyonu

Trendyol Partner API nedir ve neyi otomatikleştirir?

Trendyol Partner API (Marketplace Entegrasyon API'si), satıcıların ürün kataloğunu, stok ve fiyatını, siparişlerini ve kargo süreçlerini kendi ERP/e-ticaret sisteminden otomatik yönetmesini sağlayan RESTful (JSON) bir servistir. Manuel panel girişini ortadan kaldırır: binlerce SKU'yu tek elden güncellemek, siparişleri dakikalar içinde çekmek ve oversell'i önlemek ancak API ile ölçeklenebilir. Trendyol'da satıcı olarak 6563 sayılı Elektronik Ticaretin Düzenlenmesi Hakkında Kanun kapsamında ETHS (elektronik ticaret hizmet sağlayıcı)konumundasınız; platform ise aracı (ATHS/ETAHS) taraftır. Entegrasyona başlamadan ETBİS (Elektronik Ticaret Bilgi Sistemi) kaydınızın ve GİB e-Fatura/e-Arşiv mükellefiyetinizin hazır olması gerekir.

Yetkilendirme: sellerId, API Key ve API Secret

Kimlik doğrulama basittir ama sık yanlış kurulur. Trendyol Basic Auth kullanır; Bearer token değil. Adımlar:

• 1. Panelden anahtar alın: Satıcı Paneli → Hesap Bilgilerim → Entegrasyon Bilgileri'nden apiKey, apiSecret ve sellerId kopyalanır.
• 2. Authorization başlığı: Authorization: Basic base64(apiKey:apiSecret) biçiminde kodlanır.
• 3. User-Agent zorunlu: User-Agent: {sellerId} - SelfIntegration gönderilir; eksikse istekler reddedilebilir.
• 4. Base URL: güncel entegrasyon tabanı https://apigw.trendyol.com/integration (eski adres: https://api.trendyol.com/sapigw).
• 5. Test → canlı: önce sandbox akışını doğrulayın, sonra production'a alın.

Ürün gönderimi: batch ve batchRequestId takibi

Ürün oluşturma asenkrondur. POST .../product/sellers/{sellerId}/products çağrısı anında ürünleri yaratmaz; bir batchRequestId döndürür ve kayıtları kuyruğa alır. Kalem bazlı sonucu görmek için GET .../products/batch-requests/{batchRequestId}çağrısını poll edersiniz; her satır SUCCESS / FAILED / PROCESSING statüsüyle döner. Bu tasarım toplu yüklemeyi hızlandırır ama "gönderdim, oldu" varsayımını riskli kılar — mutlaka batch sonucunu okuyun.

Zorunlu/temel alanlar ve doğrulama kaynakları:

• barcode, title, productMainId, stockCode: benzersiz kimlikler; SKU eşlemenizin tek kaynağı.
• brandId: Marka servisi (/brands) ile doğrulanır; serbest metin kabul edilmez.
• categoryId + attributes: Kategori servisi (/product-categories) ve kategoriye bağlı attribute listesi ile eşleştirilir; zorunlu özellikler eksikse ürün FAILED döner.
• listPrice, salePrice, vatRate, currencyType: fiyat ve KDV; e-Fatura tutarlarıyla uyumlu olmalı.
• cargoCompanyId, dimensionalWeight, images: kargo firması, desi ve görseller.

Stok ve fiyat senkronizasyonu

Stok ve fiyat, ürün güncellemeden ayrı ve daha hızlı bir uçtan yönetilir: POST .../products/price-and-inventory. Gövdeye items listesi (barcode + quantity + salePrice + listPrice) verilir; bu da asenkrondur ve batchRequestId döndürür. Doğru senkron periyodunu seçmek için basit bir bütçe formülü:

Gerekli çağrı/gün ≈ (SKU sayısı ÷ batch boyutu) × günlük senkron sayısı. Örneğin 20.000 SKU, 1.000'lik batch ve günde 24 tam senkron → 20 × 24 = 480 çağrı/gün. Oversell riskini de emniyet stoğuyla yönetin: buffer = ortalama satış hızı × senkron periyodu.

Sipariş çekme ve kargo bildirimi

Siparişler GET /order/sellers/{sellerId}/orders ile statü ve tarih aralığına göre sayfalı çekilir. Sık kullanılan statüler: Created, Picking, Invoiced, Shipped, Delivered, Cancelled. Yeni siparişler için 1–5 dakikalık polling tipik bir yaklaşımdır. KVKK 6698 gereği müşteri verisi çoğunlukla maskeli gelir; bu veriyi yalnızca gönderi ve fatura amacıyla, tanımlı saklama süresiyle işleyin.

Kargo tarafında paketi shipment-packages üzerinden bildirir, TrendyolExpress veya anlaşmalı kargo (Yurtiçi, Aras, MNG, Sürat) ile süreci kapatırsınız. Faturayı e-Fatura/e-Arşiv olarak keser, gönderide gerekiyorsa e-İrsaliye kullanırsınız. Kargo maliyetini doğru hesaplamak için desi formülünü unutmayın: desi = (En × Boy × Yükseklik) / 3000; faturalanan ağırlık genelde fiziksel kg ile desi'nin büyüğüdür.

Maliyet: komisyon, hizmet bedeli ve net hakediş

Fiyatlamayı doğru kurmak için net hakedişi baştan modelleyin:

Net Hakediş = Satış Fiyatı − Komisyon − Platform/İşlem Bedeli − Kargo (desi) − İade/Kupon Payı

İki yardımcı metrik: take rate = platform komisyonu ÷ GMV ve efektif komisyon = (komisyon + hizmet bedeli) ÷ satış fiyatı × 100. Aşağıdaki oranlar kamuya açık, temsili aralıklardır; kategori, kampanya ve döneme göre değişir, kendi sözleşmenizdeki güncel oranı esas alın.

Senkronizasyon stratejisi: hangisi ne zaman?

Yaygın hatalar ve iyi uygulamalar

• Batch sonucunu okuyun: batchRequestId'i poll etmeden "yükleme başarılı" saymayın.
• Idempotency + retry: başarısız kalemleri exponential backoff (ör. 1s, 2s, 4s) ile tekrar deneyin; aynı barcode'u mükerrer yaratmayın.
• Rate limit'e saygı: istekleri sıraya alın, 429 dönerse bekleyin; kategori/marka listeleri gibi statik veriyi cache'leyin.
• Loglama: her çağrının isteğini/yanıtını ve batchRequestId'i saklayın; uyuşmazlık analizini kolaylaştırır.
• Mevzuat: e-Fatura/e-Arşiv, e-İrsaliye ve KVKK maskeleme kurallarını süreçlere gömün; pazarlama iletisi göndereceksen İYS onayı şart.

Tek pazaryeriyle başlayıp Hepsiburada ve n11'i de eklerken tek stok havuzunu korumak isterseniz çoklu pazaryeri entegrasyonu çözümümüze ve stok/sipariş senkronizasyonu çözümümüze göz atın. Kargo ve e-fatura akışını uçtan uca kurmak için kargo entegrasyonu rehberini inceleyebilir, kendi akışınız için talep oluşturabilirsiniz.