Pazaryeri Entegrasyonu: Trendyol, Hepsiburada ve N11 API'leri Nerede Ayrışıyor?

Pazaryeri entegrasyonu yaparken Trendyol, Hepsiburada ve N11'i aynı adaptörün üç kopyası gibi yazarsanız üçüncü haftada tıkanırsınız. Üçü de REST konuşur, üçü de ürün/stok/sipariş kavramlarını taşır, ama asenkron işlem modelleri, toplu güncelleme tavanları ve eşzamanlılık sınırları birbirinden bağımsız tasarlanmıştır: Trendyol bir batchRequestId verir ve sonucu yalnızca 4 saat saklar, Hepsiburada aynı anda bekleyen 5 işten fazlasını kabul etmez, N11 ise taskId üretip kuyruğa alır. Bu yazı, o üç modelin nerede ayrıştığını ve ortak bir senkronizasyon katmanının hangi noktalarda kırıldığını anlatıyor.

Aşağıdaki endpoint yolları, alan adları ve limitler 25 Eylül 2026 tarihinde pazaryerlerinin resmî geliştirici dokümantasyonundan okunmuştur. Pazaryeri servis sözleşmeleri sık değişir; entegrasyona başlamadan önce kendi satıcı panelinizdeki güncel dokümanı teyit edin.

Üç Pazaryeri, Üç Farklı Asenkronluk Modeli

Pazaryeri API'larının tamamında stok ve fiyat güncellemesi senkron değildir. İstek 200 dönebilir ve güncelleme yine de başarısız olabilir. Ayrışma tam burada başlıyor: her pazaryeri "işi aldım" ile "işi bitirdim" arasındaki boşluğu farklı bir nesneyle temsil ediyor ve o nesnenin ömrü farklı.

Bu tablodaki tek satır bile mimarinizi değiştirir. Hepsiburada'nın kendi dokümanı şunu açıkça yazıyor: "Listing güncelleme için aynı anda POST ettiğiniz devam eden / bekleyen işlemlerin sayısı 5'i geçemez" ve hemen ardından tavsiyeyi veriyor: "Limit 5 uyarısına takılmamak için tek seferdeki güncellenen sku adetinizi arttırmanızı öneririz." Yani Hepsiburada sizden az sayıda, büyük paket göndermenizi istiyor. Trendyol tarafında ise fiyat güncellemesi barkod bazında dakikada 30 istekle sınırlı, toplu uç ise servis grubu kotasına tabi; orada paketi büyütmek değil, gereksiz isteği hiç göndermemek kazandırıyor. İki pazaryeri sizi zıt yönlere itiyor ve tek bir "her yere 500'lük parti gönder" kuralı ikisinde de yanlış.

Trendyol'da User-Agent Göndermezseniz 403 Alırsınız

Trendyol'un yetkilendirme dokümanı, çoğu ekibin ilk gün kaybettiği yeri net söylüyor: istekte Authorization ile birlikte User-Agent başlığının da bulunması zorunlu, yoksa servis 403 döner. Biçim de serbest değil:

# Kendi entegrasyonunuzu yazıyorsanız
User-Agent: 1234 - SelfIntegration

# Bir entegratör firma üzerinden bağlanıyorsanız
User-Agent: 1234 - TrendyolSoft        # alfanumerik, en fazla 30 karakter

# Yetkilendirme hatalıysa
HTTP 401  ClientApiAuthenticationException

Buradaki 1234 Supplier ID'dir. Hata mesajı yanıltıcıdır: 403 gördüğünüzde ilk refleks "yetkim yok" olur, oysa çoğu zaman HTTP istemcinizin varsayılan User-Agent'ını ezmeyi unutmuşsunuzdur. Guzzle, cURL ve çoğu SDK kendi imzasını basar; Trendyol bunu kabul etmez.

İki Resmî Sayfa, İki Farklı Limit

Trendyol'un yetkilendirme sayfası klasik kuralı anlatıyor: bir endpoint için 10 saniye içinde en fazla 50 istek, 51'incide 429 too.many.requests. Servis limitleri sayfası ise 14 Eylül 2026'dan itibaren geçerli, tamamen farklı bir model tarif ediyor: limitler endpoint bazında değil servis grubu bazında ve satıcının ürün adedi kademesine göre değişiyor.

Pratik sonuç: kotanız artık tek bir uca değil, o gruptaki bütün uçlara ortak. Kategori ağacını ve marka listesini dakikada bir tazeleyen bir arka plan işi, ürün okuma kotanızın yarısını yiyip asıl ürün senkronizasyonunuzu aç bırakabilir. Kota sayacınızı endpoint başına değil servis grubu başına tutun.

İade onay/red servisinin dakikada 5 istekle sınırlı olması da ayrıca planlanmalı. Yoğun iade günlerinde birikmiş 400 iadeyi işlemek en az 80 dakika sürer; bu işi sipariş kuyruğunuzdan ayrı, kendi hız sınırına sahip bir kuyruğa koyun.

Stok ve Fiyat: Aynı İş, Üç Ayrı Sözleşme

Trendyol'un stok/fiyat ucu tek ve nettir:

POST https://apigw.trendyol.com/integration/inventory/sellers/{sellerId}/products/price-and-inventory
Content-Type: application/json

{
  "items": [
    { "barcode": "8680000000001", "quantity": 42, "salePrice": 249.90, "listPrice": 349.90 }
  ]
}

# Yanit
{ "batchRequestId": "..." }

Doküman üç kısıtı ayrıca belirtiyor: tek istekte en fazla 1.000 SKU, ürün başına en fazla 20.000 adet stok ve aynı isteği 15 dakika içinde tekrar göndermeyin. Son madde tek başına bir mimari kararı dayatır: gönderilecek veriyi hazırlarken son gönderilen değerle karşılaştırıp değişmemiş SKU'ları elemek zorundasınız. Bunu yapmayan bir entegrasyon, ürün kataloğunu her turda toptan gönderir ve hem kotayı hem de bu 15 dakikalık kuralı ihlal eder.

N11'in sözleşmesi benzer ama alan adları farklı ve doğrulama kuralları daha katı:

POST https://api.n11.com/ms/product/tasks/price-stock-update
appkey: ...
appsecret: ...
Content-Type: application/json

{
  "integrator": "SelfIntegration",
  "skus": [
    { "stockCode": "ABC-01", "listPrice": 349.90, "salePrice": 249.90,
      "quantity": 42, "currencyType": 1 }
  ]
}

# Yanit
{ "id": 987654321 }      # taskId - TaskDetail servisiyle sorgulanir

N11'in dokümanı üç kuralı açıkça yazıyor: fiyat güncellemesinde listPrice ve salePrice birlikte gönderilmeli, listPrice salePrice'tan büyük olmalı (değilse istek reddedilir) ve ondalık ayıracı nokta olmalı, virgülden sonra tam iki hane bulunmalı. Bu sonuncusu PHP'de number_format($tutar, 2, '.', '') demeyi unutan ekiplerin klasik hatasıdır; Türkçe yerel ayarda 1.234,56 üreten bir formatlayıcı isteği sessizce çöpe attırır.

Hepsiburada tarafında stok ve fiyat ayrı servislerle yürür (stock-uploads ve price-uploads); her ikisi de hepsiburadaSku ve merchantSku bilgisini ayrı ayrı veya birlikte kabul eder ve başarılı istek karşılığında bir Inventory Upload Id döner. Listelemeyi satışa kapatmak için stok ya da fiyat alanına sıfır göndermek, açmak için ikisini de sıfırdan farklı göndermek gerekir. "Sıfır fiyat" burada bir hata değil, bir komuttur. Fiyat hesaplama zincirinizde bir yerde sıfır üretme ihtimali varsa (indirim kuralı, kur çevirimi, eksik maliyet kaydı), o değeri servise ulaşmadan önce yakalayın.

Sipariş Çekmede Asıl Sınır Sayfa Boyutu Değil

Trendyol sipariş paketlerini GET /order/sellers/{sellerId}/orders ile verir. startDate ve endDate milisaniye cinsinden Unix zaman damgasıdır, page sıfırdan başlar, size varsayılan ve azami 200'dür, shipmentPackageIds ile en fazla 50 paket sorgulanabilir. Sıralama orderByField ile PackageLastModifiedDate veya CreatedDate üzerinden yapılır. Artımlı senkronizasyonda PackageLastModifiedDate kullanın; CreatedDate ile sıralarsanız eski bir siparişin durum değişikliğini kaçırırsınız.

Hepsiburada'nın sipariş ucu https://oms-external.hepsiburada.com/packages/merchantid/{merchantId} adresinde ve buradaki iki kısıt Trendyol'dakinden çok daha keskin:

• limit en fazla 10. Trendyol'da 200'lük sayfa çekerken burada 10'luk sayfa çekiyorsunuz; aynı sipariş hacmi 20 kat daha fazla istek demek.
• beginDate/endDate yalnızca 24 saatlik sorgu için geçerli. Doküman, daha geniş bir aralık verilirse sistemin veri kaybını önlemek için EndDate'i yok saydığını ve BeginDate'e 24 saat eklediğini yazıyor.

İkinci madde sessiz bir tuzaktır: 7 günlük bir aralık istediniz, servis 200 döndü, ama elinizdeki yalnızca ilk günün verisi. Hata yok, uyarı yok, eksik veri var. Geriye dönük tarama yazıyorsanız aralığı siz 24 saatlik dilimlere bölün.

Hız tarafında Hepsiburada'nın sipariş dokümanı 1 saniyede 1.000 isteğe kadar izin verildiğini, aşımda 429 TooManyRequest döndüğünü belirtiyor. Yani darboğaz istek sayısı değil, sayfa başına 10 kayıt.

Webhook'a Güvenin, Ama Yalnız Bırakmayın

Trendyol sipariş durum değişiklikleri için webhook sunuyor ve modeli oldukça açık tanımlanmış: yalnızca POST ve JSON, hedef URL içinde "Trendyol", "Dolap" veya "Localhost" geçemez, kimlik doğrulama API_KEY (x-api-key başlığıyla) ya da BASIC_AUTHENTICATION olabilir. Tetiklenebilen 13 statü var: CREATED, PICKING, INVOICED, SHIPPED, CANCELLED, DELIVERED, UNDELIVERED, RETURNED, UNSUPPLIED, AWAITING, UNPACKED, AT_COLLECTION_POINT, VERIFIED.

İki kural mimariyi belirliyor. Birincisi, bir satıcı için oluşturulabilecek azami webhook sayısı 15 ve pasif olanlar da bu sayıya dahil. Test sırasında oluşturup silmediğiniz webhook'lar kotanızı doldurur. İkincisi, başarısız istekler 5 dakikada bir yeniden denenir; tekrarlayan başarısızlıkta webhook pasifleştirilir ve satıcıya iki e-posta gider. Trendyol'un kendi dokümanı bile yedek olarak periyodik getShipmentPackages taraması öneriyor. Bunu öneri değil zorunluluk olarak okuyun: webhook'unuz bir gece pasifleşirse, sabah siparişlerin geldiğini ancak periyodik tarama söyler.

Bu Mimari Şurada Kırılıyor

Dört gerçek hata, dördü de sahada tekrarlanıyor:

1. Batch sonucunu geç sorgulamak. Trendyol batch sonuçlarını yalnızca 4 saat saklıyor. Gece 02:00'de tetiklenen toplu güncellemenin sonucunu sabah 09:00'da sorgularsanız kayıt yok. Hangi SKU'nun neden reddedildiğini artık öğrenemezsiniz; tek çareniz hepsini yeniden göndermektir, bu da kotayı yer. Sorgulamayı işin kendisine bağlayın, ayrı bir sabah raporuna değil.

2. Kısmi başarıyı tam başarı saymak. Üç pazaryerinde de toplu istek kısmen başarılı olabilir. Trendyol'un batch yanıtında failedItemCount ve kalem başına failureReasons alanları var; status: "COMPLETED" görmek "hepsi geçti" anlamına gelmez, yalnızca "işlem bitti" anlamına gelir. N11'de de görev PROCESSED iken kalem bazında Fail olabilir.

3. Aynı SKU'yu iki farklı işten güncellemek. Sipariş webhook'u stok düşürürken, zamanlanmış tam senkronizasyon aynı SKU için eski stoğu yazarsa pazaryerinde satılmış ürün yeniden satışa açılır. Kanal başına ve SKU başına kilit alın; Laravel tarafında Illuminate\Queue\Middleware\WithoutOverlapping tam bu iş için var ve expireAfter() ile kilidin takılı kalmasını engelleyebilirsiniz.

4. Hata kodlarını tek bir sınıfa toplamak. Trendyol'un hata kodları sayfası 504 Gateway Timeout için doğrudan "isteği daha küçük parçalara bölün" diyor, 502 ve 500 için ise yeniden denemeyi öneriyor. Bunlar farklı davranışlar gerektirir: 504'te partiyi küçültüp yeniden gönderirsiniz, 500'de aynı partiyi geri çekilmeli (backoff) tekrar denersiniz, 429'da beklersiniz, 400'de asla tekrar denemezsiniz çünkü veri hatalıdır ve tekrar denemek yalnızca kota yakar.

<?php
// Pazaryeri yanitini davranisa ceviren tek nokta.
// Her pazaryeri adaptoru bu enum'u dondurur; kuyruk isi buna gore karar verir.

enum PazaryeriSonuc {
    case Basarili;
    case TekrarDene;        // 500, 502, 503  -> geri cekilmeli tekrar
    case PartiyiBol;        // 504            -> yariya bol, yeniden gonder
    case Beklet;            // 429            -> kota penceresi dolana kadar bekle
    case KaliciHata;        // 400, 401, 403  -> tekrar DENEME, operasyona dus
}

function yanitiCevir(int $httpKod): PazaryeriSonuc
{
    return match (true) {
        $httpKod >= 200 && $httpKod < 300 => PazaryeriSonuc::Basarili,
        $httpKod === 429                    => PazaryeriSonuc::Beklet,
        $httpKod === 504                    => PazaryeriSonuc::PartiyiBol,
        $httpKod >= 500                     => PazaryeriSonuc::TekrarDene,
        default                             => PazaryeriSonuc::KaliciHata,
    };
}

Ortak Adaptör mü, Pazaryeri Başına Servis mi?

Kargo entegrasyonunda ortak arayüz + taşıyıcı başına strateji sınıfı neredeyse her zaman doğru cevaptır. Pazaryerinde durum daha incelikli, çünkü ürün modeli ile stok/fiyat modeli farklı davranır.

Ürün açma tarafında ortak bir model kurmaya çalışan ekipler, her yeni kategori kuralında o modeli yamalar ve altı ay sonra hiçbir pazaryerine tam uymayan bir ara katmanla kalır. Ürünü kaynak sisteminizde tutun, pazaryerine gönderim anında o pazaryerinin kendi yükünü oluşturun.

Trendyol'un ürün oluşturma ucu (POST /product/sellers/{sellerId}/v2/products) tek istekte 1.000 ürün kabul ediyor ve alan sınırları net: barcode 40, title 100, productMainId 40, stockCode 100, description 30.000 karakter, en fazla 8 görsel. Kendi veritabanı şemanızda bu alanları daha uzun tanımlarsanız, veri pazaryerine değil sizin tarafınızda kırılır. Uzunluk doğrulamasını gönderim anında değil, kayıt anında yapın.

Test Ortamı: Trendyol'da IP Yetkilendirmesi Var

Canlı ortam (apigw.trendyol.com) için IP yetkilendirmesi gerekmiyor, ancak test ortamı (stageapigw.trendyol.com) uygulama sunucunuzun dışa çıkış IP'sinin önceden tanımlanmasını istiyor. Doküman bunun için çağrı merkezini (0850 258 58 00) ve Satıcı Merkezi destek kaydını işaret ediyor. Test hesabı ve API bilgileri canlı ortamdan tamamen ayrıdır.

Bu, planlama açısından önemli: entegrasyonun ilk günü kod yazmakla değil, IP tanımı ve test hesabı talebiyle geçer. Konteyner tabanlı bir altyapıda çalışıyorsanız dışa çıkış IP'nizin sabit olduğundan emin olun; otomatik ölçeklenen bir NAT havuzunun arkasından çıkıyorsanız test ortamı rastgele başarısız olur ve bunu hata sanıp günlerce kod ararsınız.

Efor Bandı ve Kapsam Yazarken Ayrılması Gerekenler

ininia'da yazılım geliştirme 300-400 USD/adam-gün bandında, adam-gün dökümüyle fiyatlanır. Pazaryeri entegrasyonu teklifi alırken şu kalemlerin ayrı satırlar hâlinde görünmesini isteyin; toplu verilen tek rakam kapsamın anlaşılmadığının işaretidir:

• Ortak SKU modeli, kanal eşleme tablosu ve kilit altyapısı (bir kez)
• Pazaryeri başına stok/fiyat adaptörü ve asenkron sonuç takibi
• Pazaryeri başına sipariş çekme, sayfalama ve tarih penceresi mantığı
• Kategori/marka/özellik eşlemesi ve yönetim arayüzü (en çok hafife alınan kalem)
• Webhook alıcısı, imza doğrulaması ve yedek tarama işi
• Kota sayacı, geri çekilme ve hata sınıflandırma katmanı
• İade ve talep akışları

Kendi kapsamınız için aralık görmek isterseniz proje fiyat hesaplama aracımızı kullanabilirsiniz.

Sıkça Sorulan Sorular

Pazaryeri entegrasyonunu kendim mi yazmalıyım, entegratör mü kullanmalıyım?

Ürün sayınız birkaç bini aşmıyorsa ve fiyatlandırmanız standartsa entegratör daha ucuza çıkar. Kendi entegrasyonunuz şu üç durumda kazanır: dinamik fiyatlandırma kuralınız var (rakip takibi, kampanya motoru), çok depolu stok yönetiyorsunuz, ya da siparişi kendi ERP'nizdeki bir iş akışına bağlamanız gerekiyor. Ara durumda hibrit çalışır: ana pazaryeri için kendi adaptörünüz, kuyruktakiler için entegratör.

Stok senkronizasyonunu ne sıklıkla çalıştırmalıyım?

Sabit bir periyot yerine olay tetiklemeli çalışın. Trendyol'un "aynı isteği 15 dakika içinde tekrar göndermeyin" kuralı zaten kör periyodik gönderimi dışlıyor. Stok değişikliği olayını yakalayıp yalnızca değişen SKU'ları gönderin; buna ek olarak günde bir kez tam mutabakat taraması yapın.

N11'de SOAP mı REST mi kullanmalıyım?

Yeni yazılan entegrasyonda REST. N11 hâlâ her ikisini birlikte sunuyor ve SOAP servisleri (api.n11.com/ws/ProductService.wsdl gibi) çalışmaya devam ediyor; fiyat-stok ve sipariş tarafında ise REST uçları daha yeni ve daha iyi dokümante edilmiş durumda. SOAP servislerinin kapatılmasına ilişkin ilan edilmiş bir tarih bulamadık, bu yüzden "SOAP yakında kapanıyor" varsayımıyla plan yapmayın; ama yeni kodu da oraya yazmayın.

Aynı ürünü üç pazaryerinde farklı fiyatla satabilir miyim?

Teknik olarak evet, her pazaryerine ayrı listPrice/salePrice gönderirsiniz. Mimari uyarı: fiyatı pazaryeri adaptöründe değil, kendi fiyat motorunuzda hesaplayın ve adaptöre hazır iki sayı verin. Fiyat kuralını adaptörün içine yazan sistemlerde aynı kural üç kez ve birbirinden farklı biçimde yaşamaya başlıyor.

Sipariş numarasını neyle eşleştirmeliyim?

Pazaryerinin kendi paket kimliğiyle. Trendyol'da paket bazında çalışılır ve bir sipariş birden fazla pakete bölünebilir; Hepsiburada'da paket listeleme kalem bazında LineitemId (GUID) ve Quantity taşır. Kendi sipariş numaranızı tekilleştirme anahtarı olarak kullanmayın; pazaryeri kimliğini birincil, kendi numaranızı ikincil referans yapın.

429 aldığımda ne kadar beklemeliyim?

Trendyol'un dokümanı sabit bir bekleme süresi vermiyor. Pratik yaklaşım: servis grubu başına kendi sayacınızı tutup limite yaklaşınca isteği kuyrukta beklatmak, 429 aldığınızda ise o grup için üssel geri çekilme uygulamak. 429'u "tekrar dene" hatası gibi işleyip hemen yeniden göndermek, limiti daha da uzun süre kilitler.

Sırada Ne Var

Bu yazı üç pazaryerinin sözleşme farklarını anlatıyor; asıl zor kısım, aynı stok sayısını üç kanalda tutarlı tutmak ve aşırı satışı (oversell) önlemek. Rezervasyon modeli, olay sıralaması ve idempotency tarafını stok ve fiyat senkronizasyonu yazımızda ayrıca ele aldık. Sipariş sonrası sevkiyat tarafı için kargo entegrasyonu rehberine bakabilirsiniz.

Bir sonraki somut adımınız kod yazmak değil: üç pazaryerinin satıcı panelinden API bilgilerinizi alın, Trendyol için test ortamı IP tanımını başlatın ve elinizdeki SKU sayısını Trendyol kademe tablosuyla karşılaştırıp hangi kotaya düştüğünüzü öğrenin. Bu üç bilgi, mimarinin geri kalanının nasıl şekilleneceğini belirliyor.

ininia olarak e-ticaret ve pazaryeri tarafında senkronizasyon altyapıları kuruyoruz; kapsamımızı e-ticaret & perakende sayfasında, ERP bağlantısı için ERP entegrasyonları sayfasında görebilir, kendi projeniz için iletişim sayfasından yazabilirsiniz. Kendi ürünlerimiz arasındaki pazaryeri projelerine projeler sayfasından göz atabilirsiniz.

Kaynaklar: Trendyol Geliştirici Dokümantasyonu (Yetkilendirme, Servis Limitleri, Stok ve Fiyat Güncelleme, Batch Request Sonucu, Ürün Oluşturma V2, Sipariş Paketi Listeleme, Webhook Model, Canlı/Test Ortam Bilgileri, Hata Kodları sayfaları), Hepsiburada Geliştirici Portalı ("Listeleme Entegrasyonu Önemli Bilgiler", "Sipariş Entegrasyonu Önemli Bilgiler"), n11 Mağaza Destek Merkezi ("RestAPI Fiyat-Stok Güncelleme ve İşlem Sonucu Sorgulama Servisi", "RestAPI Ürün Yükleme", "RestAPI Sipariş Listeleme"). Tamamı 25 Eylül 2026'da okunmuştur.