n11 Entegrasyonu

n11 API nedir ve neyi otomatikleştirir?

n11 API, satıcıların kendi sistemlerinden n11.com'a ürün yüklemesini, stok ve fiyatı güncellemesini, sipariş ve kargo süreçlerini yönetmesini sağlayan bir entegrasyon arayüzüdür. Klasik yapısı SOAP/XML tabanlıdır; servislere WSDL üzerinden erişilir. Panelden manuel işlem yerine, katalog ve stoğu programatik yönetmek büyük SKU adetlerinde tek pratik yoldur. n11'de satıcı olarak 6563 sayılı Kanun kapsamında ETHS konumundasınız; platform aracı (ATHS/ETAHS) taraftır. Başlamadan ETBİS kaydınız ve GİB e-Fatura/e-Arşiv altyapınız hazır olmalıdır.

Servisler ve yetkilendirme

n11 entegrasyonu servis bazlıdır ve her SOAP isteğinin gövdesine auth bloğu (appKey + appSecret) eklenir. Temel servisler:

Yetki alma adımları:

• 1. Mağaza aç: n11 satıcı başvurusu ve belge kontrolü (birkaç iş günü).
• 2. Anahtar al: Satıcı Paneli → Ayarlar → API'den appKey ve appSecret.
• 3. SOAP client: WSDL'e (ör. ProductService.wsdl) bağlanıp operasyonları çağırın.
• 4. Güvenlik: anahtarları sunucuda saklayın, asla istemciye gömmeyin.

Ürün aktarımı ve batch

Ürün SaveProduct ile eklenir; gövdede productSellerCode, title, kategori id, price, currencyType, görseller ve stockItems (miktar + sellerStockCode + attribute'lar) yer alır. Kategoriye bağlı zorunlu özellikleri CategoryService'ten çekip eşleştirmezseniz kayıt hata döner. Toplu yüklemede sınırlar:

• Batch boyutu: tek istekte ~100 kaleme kadar; güvenli tercih 50 kalem/istek.
• Rate limit: istekler arası kısa bekleme (yaklaşık saniyede 1 istek) bırakın.
• Retry: başarısız kalemleri exponential backoff ile tekrar deneyin.
• Cache: kategori/attribute gibi statik veriyi önbelleğe alın.

Stok senkronizasyonu ve oversell kontrolü

Stok, UpdateStockByStockSellerCode ile sellerStockCode üzerinden güncellenir. Kaç sıklıkta senkron edeceğinizi iki formülle planlayın:

• Emniyet stoğu (buffer) = ortalama satış hızı × senkron periyodu. Örn. dakikada 2 satış, 15 dk periyot → ~30 adet tampon.
• Yeniden sipariş noktası (ROP) = (günlük satış × tedarik süresi) + emniyet stoğu.

Sipariş çekme (polling) ve kargo bildirimi

Siparişler OrderService.OrderList ile statü (ör. Approved) ve tarih aralığına göre sayfalı çekilir. Tipik akış: her 5 dakikada bir yeni siparişleri poll et, kendi veritabanına kaydet, stok düş, fatura kes ve kargoyu hazırla. Müşteri kişisel verisini KVKK 6698 kapsamında yalnızca gönderi ve fatura amacıyla, sınırlı saklama süresiyle işleyin.

Kargo bildirimi OrderItemShipment ile yapılır: sipariş kalemine takip numarası ve kargo firması (ör. Yurtiçi Kargo, Aras, MNG) yazılır; n11 alıcıya bilgilendirme gönderir. Faturayı e-Fatura/e-Arşiv olarak keser, gönderide gerekiyorsa e-İrsaliye kullanırsınız. Kargo maliyetini desiden hesaplayın: desi = (En × Boy × Yükseklik) / 3000.

Maliyet: komisyon, net hakediş ve Settlement

Fiyatı kurmadan önce net hakedişi modelleyin: Net Hakediş = Satış Fiyatı − Komisyon − Hizmet Bedeli − Kargo (desi) − İade/Kupon Payı. Gerçekleşen hakedişi SettlementService'ten çekerek muhasebeyle uzlaştırın. Yardımcı metrik: efektif komisyon = (komisyon + hizmet bedeli) ÷ satış fiyatı × 100. Aşağıdaki oranlar kamuya açık, temsili aralıklardır; kategori ve döneme göre değişir, güncel sözleşmenizi esas alın.

Hata yönetimi ve iyi uygulamalar

• Hata kodlarını ele alın: geçersiz appKey, kategori bulunamadı, mükerrer stok kodu gibi tipik SOAP hatalarında anlamlı log ve kullanıcı mesajı üretin.
• Retry + kuyruk: toplu işlemleri queue'ya alın, başarısızları 3 denemeye kadar exponential backoff ile yeniden gönderin.
• Idempotency: aynı sellerStockCode/SKU'yu mükerrer yaratmayın; güncelleme ile ekleme akışını ayırın.
• Monitoring: API sağlığını periyodik kontrol edin, gecikme ve hata oranını izleyin.
• Mevzuat: e-Fatura/e-Arşiv, e-İrsaliye, KVKK maskeleme; pazarlama iletisi için İYS onayı zorunludur.

n11'i Trendyol ve Hepsiburada ile aynı stok havuzundan yönetmek için çoklu pazaryeri entegrasyonu çözümümüze ve stok/sipariş senkronizasyonu çözümümüze göz atın. Diğer API'ler için Trendyol ve Hepsiburada rehberlerini inceleyebilir, kendi akışınız için talep oluşturabilirsiniz.