Türkiye'de e-ticaret operasyonu yöneten bir yazılım geliştiriyorsanız pazaryeri API entegrasyonu çoğu zaman ilk büyük teknik sınavdır. Ürün açma, kategori eşleştirme, stok ve fiyat güncelleme, sipariş çekme, fatura akışı ve kargo durumu aynı anda yönetilmek zorunda kalır.
Bu rehber, API Deposu'ndaki Trendyol Seller API, Hepsiburada Seller API ve N11 Marketplace API kayıtlarını ürün mimarisi açısından karşılaştırır. Amaç sadece endpoint listelemek değil; entegrasyonun nerede kırılabileceğini ve nasıl daha sürdürülebilir kurulacağını göstermektir.
Hızlı karşılaştırma
| API | En iyi kullanım | Kimlik doğrulama | Entegrasyon notu |
|---|---|---|---|
| Trendyol Seller API | Ürün, stok/fiyat ve sipariş yönetimi | Basic Auth | Satıcı onayı ve sözleşme gerekir |
| Hepsiburada Seller API | Katalog, stok, sipariş ve fatura akışları | API Key + Merchant ID | Test ve canlı ortam ayrımı dikkate alınmalı |
| N11 Marketplace API | Ürün güncelleme, stok ve sipariş | API Key + Secret | SOAP/WSDL mirası olan akışlar olabilir |
Ortak model oluşturun
Pazaryeri entegrasyonlarında en büyük hata, her sağlayıcının yanıtını uygulama modeline doğrudan taşımaktır. İlk pazaryeri hızlı bağlanır, ikinci pazaryeri eklendiğinde alan adları, varyant yapısı, kategori ID'leri ve sipariş statüleri karışır. Bu yüzden en başta ortak bir model gerekir.
Örneğin uygulama içinde MarketplaceProduct, MarketplaceOffer, MarketplaceOrder, MarketplaceShipment ve MarketplaceSyncJob gibi kavramlar kullanılabilir. Trendyol, Hepsiburada ve N11 adaptörleri bu ortak modele veri dönüştürür. Böylece UI ve iş kuralları sağlayıcıya doğrudan bağımlı kalmaz.
Stok ve fiyat senkronizasyonu
Stok güncellemesi basit bir PATCH çağrısı gibi görünür, fakat gerçek operasyonda yarış durumları ortaya çıkar. Aynı SKU hem mağazada hem pazaryerinde hem ERP'de güncellenebilir. Son yazan kazanır yaklaşımı yanlış stok gösterimine neden olabilir.
Bu yüzden stok kaynağını belirleyin. Eğer ERP ana kaynaksa pazaryerlerinden gelen stok bilgisi sadece doğrulama için kullanılmalıdır. Eğer pazaryeri siparişleri stok düşürüyorsa sipariş çekme ve stok güncelleme job'ları aynı sırada ve idempotent çalışmalıdır.
Sipariş ve hata yönetimi
Sipariş çekme akışı tekrar çalıştırıldığında aynı siparişi iki kez oluşturmamalıdır. Her pazaryeri sipariş ID'si uygulama içinde tekil tutulmalı, aynı event tekrar gelirse mevcut kayıt güncellenmelidir. Kargo, iade ve fatura durumları da ayrı state machine ile modellenmelidir.
Hata yönetiminde sağlayıcı mesajını doğrudan kullanıcıya basmak iyi değildir. Backend tarafında CATEGORY_MAPPING_FAILED, PRICE_UPDATE_REJECTED, ORDER_SYNC_FAILED gibi domain hataları üretmek daha anlaşılırdır. Loglarda sağlayıcı response'u saklanabilir, fakat kullanıcıya kısa ve aksiyon alınabilir mesaj gösterilmelidir.
Canlıya geçiş planı
Tüm katalogla canlıya çıkmak risklidir. Önce az sayıda SKU, tek kategori ve sınırlı sipariş akışıyla pilot yapın. Ürün yükleme, stok güncelleme, fiyat güncelleme, sipariş çekme ve iptal/iade gibi ana senaryoları ayrı ayrı test edin.
Pazaryeri entegrasyonları düzenli bakım ister. Kategori ağaçları, zorunlu alanlar ve onay kuralları değişebilir. Bu yüzden entegrasyonun yanında operasyon paneli, sync logları ve başarısız job ekranı da ürünün parçası olmalıdır.
Operasyon paneli neden gerekir?
Pazaryeri entegrasyonunda hatayı sadece log dosyasında görmek yeterli değildir. Operasyon ekibi hangi ürünün hangi pazaryerine aktarılamadığını, hangi siparişin işlenemediğini ve hangi stok güncellemesinin reddedildiğini panelden görebilmelidir. Aksi halde teknik ekip her küçük veri hatasında manuel müdahale etmek zorunda kalır.
İyi bir panelde son senkronizasyon zamanı, başarısız job sayısı, sağlayıcı hata mesajı, tekrar deneme butonu ve etkilenen SKU listesi bulunur. Bu bilgiler hem müşteri desteğini hızlandırır hem de pazaryeri API değişikliklerini erken fark etmenizi sağlar.
Veri sahipliği
Ürün açıklaması, görsel, fiyat ve stok gibi alanlarda hangi sistemin ana kaynak olduğu net olmalıdır. Eğer ERP ana kaynaksa pazaryerinden gelen değişiklikler doğrudan master veriyi ezmemelidir. Eğer satıcı panelindeki manuel değişiklikler kabul edilecekse bu değişikliklerin uygulamaya nasıl geri döneceği ayrıca tasarlanmalıdır.
Bu karar verilmeden yazılan entegrasyonlar zamanla tutarsız katalog üretir. Aynı ürün Trendyol'da başka, Hepsiburada'da başka, N11'de başka fiyatla kalabilir. Bu yüzden pazaryeri API'leri teknik bağlantıdan çok veri yönetişimi konusudur.
İlgili API Deposu kayıtları
Kaynaklar
Sik Sorulan Sorular
›Türkiye pazaryeri entegrasyonunda önce hangi akış yapılmalı?
Genellikle önce ürün, stok/fiyat ve sipariş çekme akışları yapılır. İade, fatura ve kargo entegrasyonları daha sonra kontrollü şekilde eklenmelidir.
›Trendyol, Hepsiburada ve N11 API'leri aynı modelle kullanılabilir mi?
Hayır. Her pazaryeri kategori, ürün, varyant, stok ve sipariş alanlarını farklı modelleyebilir. Uygulama içinde ortak bir marketplace adapter katmanı oluşturmak daha sağlıklıdır.
›Pazaryeri API anahtarları frontend'de tutulabilir mi?
Hayır. Satıcı API anahtarları sipariş ve ürün verisine eriştiği için backend tarafında saklanmalı, kullanıcı yetkisi ve audit kaydıyla korunmalıdır.
›Stok senkronizasyonu ne sıklıkla yapılmalı?
Ürün tipine ve satış hacmine bağlıdır. Kritik stoklarda event veya kısa aralık gerekirken düşük hacimli kataloglarda periyodik batch senkronizasyon yeterli olabilir.