n11 Entegrasyon: API, Ürün Eşleştirme, Stok ve Sipariş Aktarımı

n11 entegrasyon, n11 mağazanızı e-ticaret sitenize, stok programınıza ya da muhasebe yazılımınıza bağlayarak ürün, stok, fiyat, sipariş, iade ve soru verisinin elle girilmeden taşınmasıdır. Bağlantı n11'in API'si üzerinden kurulur ve anahtarı mağaza panelinizden alınır. Ürünler aktarılmadan önce n11 kategorileri ve kategori özellikleri kendi sisteminizdeki alanlarla eşleştirilir. Gönderilen stok ve fiyatın n11'de işlenip işlenmediği ayrıca sorgulanır; birden çok kanalda oluşan stok farkı ise n11'in sipariş reddi ve geciken kargolama kurallarına takılır.

Konu	n11'in Kuralı
Bağlantı Yolu	Ürünler elle, Excel şablonuyla ya da API entegrasyonuyla yüklenir
API Hesabı	Evrak süreçleri tamamlanınca mağaza panelinden açılır; bilgiler mağazanın kayıtlı e-postasına gider
Eşleştirme	Kategori ve özellikler ürün aktarımından önce eşlenir; yalnızca en alt kırılım kategori kullanılır
Ürün Anahtarı	Stok kodu benzersizdir; stok ve fiyat güncellemesi bu koda göre yapılır
Gönderimin Sonucu	İstek kuyruğa alınır; sonuç görev kimliğiyle ürün bazında sorgulanır
Stok Farkı	Stokta olmamak sipariş reddi için haklı gerekçe sayılmaz

n11 entegrasyon yolları ve API hesabı

n11, ürünlerin mağazaya üç yolla yüklenebildiğini yazar: elle tek tek giriş, Excel şablonuyla toplu yükleme ve API entegrasyonu. İlk iki yol az ürünlü ya da seyrek değişen kataloglarda iş görür. Stoğu ve fiyatı sık değişen, siparişi başka bir sistemde işlenen ya da aynı ürünü birden çok kanalda satan mağazada veriyi API taşır; böylece her değişiklik iki ayrı panele elle yazılmaz.

API'ye bağlanmak için n11 mağaza hesabınıza yüklediğiniz evrakların süreçleri tamamlanmış olmalıdır. Ardından mağaza panelindeki API hesapları bölümünde yeni bir hesap açılır; API Key ve API Secret bilgileri mağazanıza kayıtlı e-posta adresine gönderilir. Bu iki bilgi, bağlanacağınız entegrasyon yazılımına ya da altyapınızın n11 uygulamasına girilir. n11'in belgelerine göre istekler bu iki bilgiyle doğrulanır; kategori servislerine erişimde de 15 Ağustos 2025'ten beri API Key ve Secret zorunludur.

API Key ve Secret, mağazanız adına işlem yapmaya yarayan bilgilerdir. Onları yalnızca bağlantıyı kuracak yazılıma girin; e-postayla ya da mesajla dolaştırmayın. Mağazada birden çok yazılım çalışacaksa hangisinin hangi veriyi gönderdiğini bağlantıdan önce kararlaştırın.

n11 geliştirici belgelerini okurken bilinmesi gerekenler

n11'in güncel API belgesi n11 Developer sitesindedir. Mağaza Destek Merkezi'ndeki API sayfaları artık bu siteye yönlendirir; destek merkezinde eski bir sipariş servisinin alanlarını listeleyen bir sayfa ise hâlâ durur. Geliştirici sitesi ürün, sipariş ve iade entegrasyonu, mikro ihracat ve n11depom bölümlerinden ve bir değişiklik kaydından (Change Log) oluşur.

Belgede servislerin bir bölümü REST, bir bölümü SOAP olarak anlatılır: ürün, stok-fiyat ve sipariş listeleme servisleri REST, iade talepleri ve ürün soru-cevap servisleri SOAP olarak yazılıdır. Sayfaların çoğunda güncelleme tarihi yoktur ve bazı örnekler kendi içinde çelişir. Belgenin bir sayfasını tek başına okumak yerine değişiklikleri Change Log'dan izlemek bu yüzden daha güvenlidir.

n11, Change Log'daki bazı değişikliklerde mağazasında ürün entegrasyonu olan satıcıdan entegratörünü bilgilendirmesini ister. Kullandığınız yazılımın n11'in hangi servislerine bağlandığını, değişiklik kaydını kimin izlediğini ve bir alan değiştiğinde yazılımın ne kadar sürede güncellendiğini bağlantıdan önce sorun. Örneğin n11, 15 Ekim 2025'ten beri alıcıdan T.C. kimlik numarası istemez; bu alan sipariş verisinde boş gelebilir ve entegrasyonun onu zorunlu saymaması gerekir.

n11 API'siyle aktarılan veriler

n11'in API'si mağazanın satış işlerinin büyük bölümünü kapsar. Hangi verinin gerçekten taşındığı ise bağlandığınız yazılımın kapsamına bağlıdır; bir yazılım yalnızca stok ve fiyatı, bir başkası sipariş ve iadeyi de taşıyabilir.

Veri	Yön	Not
Kategori ve Özellikler	n11'den Okunur	Kategori ağacı tek istekte gelir; özelliğin zorunlu ya da varyant olduğu servisten okunur
Ürün	n11'e Gönderilir	Yükleme, hızlı yükleme, bilgi güncelleme, silme ve sorgulama ayrı servislerdir
Stok ve Fiyat	n11'e Gönderilir	Liste fiyatı ve satış fiyatı birlikte gider; istekte olmayan alan değişmez
Sipariş	İki Yönlü	Paketler listelenir; paket bölme, toplama talebi ve fatura bağlantısı n11'e gönderilir
Kargo Bilgisi	n11'den Okunur	Takip numarası ve takip bağlantısı sipariş paketiyle gelir
İade	İki Yönlü	İade talepleri listelenir, onaylanır, ertelenir ya da reddedilir
Ürün Soruları	İki Yönlü	Sorular listelenir ve cevaplanır; bir soruya bir kez cevap verilir

n11depom kullanan mağazalar da depoyu entegrasyon yazılımıyla bağlayabilir; sipariş listelerken n11depom siparişleri ayrı bir gönderici bilgisiyle çağrılır. n11depom'un işleyişi bu yazının konusu değildir.

Kategori ve özellik eşleştirmesi

n11'in destek merkezi, ürünler yüklenmeden önce n11 kategorilerinin ve kategori özelliklerinin çekilip kendi sisteminizdeki alanlarla eşleştirilmesini ister; ürün aktarımına bundan sonra başlanması önerilir. Eşleştirme, örneğin sizin "Kadın Elbise" diye tuttuğunuz ürün grubunun n11 ağacında hangi kategoriye, sizin "Renk" alanınızın n11'in hangi özelliğine karşılık geldiğini tanımlar.

Ürün yüklemede yalnızca en alt kırılımdaki kategori kullanılır; alt kategorisi olmayan kategori en alt kırılımdır. Eşleştirme bu yüzden ağacın son dalına kadar iner. Her kategorinin özellikleri ayrıca okunur ve her özellik için üç bilgi gelir: zorunlu olup olmadığı, varyant özelliği olup olmadığı ve serbest değer kabul edip etmediği. Zorunlu özellik her üründe gönderilmelidir; eksik gönderilirse aktarım hata verir.

Serbest değere izin verilmeyen bir özellikte yalnızca n11'in listesindeki değerler kabul edilir. Örneğin sizin "Lacivert" yazdığınız renk n11 listesinde başka bir yazımla duruyorsa ürün hata alır; bu yüzden özelliklerin yanında değerlerin de eşlenmesi gerekir. n11'in Excel kılavuzu da özellik değerlerinin listeden olduğu gibi, değiştirilmeden yazılmasını ister.

Eşleştirme bir kez yapılıp bırakılmaz. n11'in hata listesinde kapatılmış bir kategorinin kimliğinin geçersiz sayılması ve kategori için geçersiz hâle gelen özellik değeri ayrı hatalardır; ikisinde de güncel liste yeniden çekilir ve eşleştirme düzeltilir. Altyapıya özgü örnekler için ideasoft n11 aktarımındaki kategori ve özellik hataları maddesine bakabilirsiniz.

Barkod, stok kodu ve varyant

n11'de her ürünün ve her varyantın kendine ait bir GTIN, yani barkodu olur; barkod sistemini GS1 yönetir, Türkiye'de TOBB temsil eder. Yüklenen ürünün barkodu n11 kataloğundaki bir barkodla eşleşirse ürün, özelliklerine bakılmadan "satıcı onayı bekliyor" durumunda açılır. Barkodun katalogdaki kategorisi sizin gönderdiğiniz kategoriden farklıysa da ürün satıcı onayına düşer.

Satıcı onayı bekleyen ürünler mağaza panelindeki Aksiyon Bekleyenler alanında toplanır. Hatalı eşleşen kategori, hatalı fiyat şüphesi ve katalogda eşleşen ürün etiketleri burada görünür ve ürün satıcının onayıyla satışa açılır. Entegrasyonla gönderdiğiniz ürün satışa çıkmıyorsa ilk bakılacak yer burasıdır.

Stok kodu her ürün için benzersizdir ve entegrasyonun asıl anahtarıdır: stok ve fiyat güncellemesi, ürün silme ve ürün sorgulama bu koda göre yapılır. Aynı stok kodunun ya da aynı barkodun birden çok üründe kullanılması n11'in yükleme hataları arasındadır. Stok kodu sonradan değişirse n11'deki ürünle sizin sisteminizdeki ürünün bağı kopar; kodu baştan değişmeyecek biçimde seçin.

Varyantlar ürün ana koduyla bağlanır: aynı ana kodla gönderilen ürünler n11'de tek sayfada seçenek olarak görünür. Renk ve beden gibi varyant özelliklerinde bütün varyantlarda aynı ana kod ve aynı yazım kullanılır. Marka, renk ve beden gibi temel özellikler ise ürün açıldıktan sonra güncelleme servisiyle değiştirilemez; n11'in belgesine göre bunları yalnızca n11 güncelleyebilir. Bu alanların ilk gönderimde doğru olması bu yüzden önemlidir.

Stok ve fiyat gönderiminin sonucu

n11'e gönderilen ürün, stok ve fiyat istekleri sırayla işlenir. İstek kabul edildiğinde n11 bir görev kimliği ve "IN_QUEUE" durumu döner; bu, isteğin kuyruğa alındığını gösterir, işlendiğini göstermez. İstek işleme alınmazsa durum "REJECT" olur ve nedeni yanıtta yazar. Görevin sonucu ayrıca sorgulanır: tamamlanan görevde her stok kodu için başarılı ya da başarısız durumu ve başarısızlığın nedeni görünür.

Bu yüzden bir entegrasyon yazılımında "gönderildi" yazısı tek başına yeterli değildir; yazılımın görev sonucunu okuyup başarısız ürünleri nedeniyle birlikte göstermesi gerekir. n11'in belgesi, gönderim ile ürünün n11'de güncel görünmesi arasındaki süreyi vermez.

Fiyat gönderiminde liste fiyatı ve satış fiyatı birlikte gider; liste fiyatı satış fiyatından küçük olamaz. Ondalık ayırıcı noktadır ve noktadan sonra iki hane bulunur; virgül ya da fazla hane isteği başarısız yapar. İstekte bulunmayan alan değişmez ve tek istekte en çok 1000 stok kodu gönderilir. Güncelleme yalnızca Onaylı ya da Beklemede durumundaki ürünlerde yapılır; Katalog Onay Sürecinde olan ürün güncellenemez.

n11'in mağaza panelinde ayrıca bir fiyat güncelleme limiti vardır; limitin artırılması talep açılarak istenir. Toplu fiyat değişikliği planlıyorsanız bu limiti önceden kontrol edin. Stok ve fiyatın bir altyapıda neden güncellenmediğine örnek olarak ikas n11 entegrasyonunda stok ve fiyat maddesine bakabilirsiniz.

Sipariş, kargo, iade ve soru verisi

Siparişler n11'de paket olarak listelenir; bir sipariş birden çok ürün satırı taşıyabilir. Yeni sipariş "Created" durumuyla gelir, onaylanan paket "Picking" durumuna geçer. Paket bölme ve lojistik firma gönderilerindeki toplama talebi yalnızca bu durumda yapılabilir. Bölünen paketler aynı sipariş numarasını farklı paket numarası ve farklı kargo kampanya koduyla taşır; kargo takip numarası ve takip bağlantısı paketle birlikte gelir.

Sipariş listeleme servisinin belgesinde dakikada en çok 1000 istek sınırı yazar; her istekte tek bir durum sorgulanır ve 2024 Kasım öncesi siparişler bu serviste bulunmaz. Bu sınırlar, yazılımın siparişleri hangi sıklıkla çekeceğini ve eski siparişlerin aktarılıp aktarılamayacağını belirler. n11'in iki sipariş servisini karşılaştıran sayfasına göre eski serviste ayrı duran teslim edildi, iade edildi ve tamamlandı gibi durumlar yeni serviste tek durumda toplanır; ayrım gerekiyorsa paketin geçmişine bakılır.

İade talepleri API'den listelenir, onaylanır, ertelenir ya da reddedilir; parçalı iptal de yapılabilir. "Yeni Sipariş" durumundaki bir sipariş ise API'den parçalı iptal edilemez, yalnızca panelden reddedilir. İadenin süreleri ve ret sebepleri n11 iade yazısında anlatılır.

Ürün soruları da API'den okunup cevaplanabilir. Liste isteği dakikada bir kez yapılabilir, cevap en çok 2048 karakter olur ve her soruya bir kez cevap verilir; cevaptan sonra soru kapanır. Soruları yazılımdan cevaplıyorsanız cevabı göndermeden önce son kez okuyun.

Faturanın siparişe bağlantı olarak kaydedilmesi n11 fatura yazısında, takip numarası ve toplama talebinin kargo sürecindeki yeri n11 kargo yazısında anlatılır.

Siparişle gelen alıcı adı, adresi ve e-postası kişisel veridir. n11'in müşteri iletişimi sayfasına göre bu bilgiler siparişin ve faturanın teslimi dışında kullanılamaz; başka amaçla kullanmak 6698 sayılı Kanun'un ihlali olur. Entegrasyon yazılımında bu verinin kimlerin erişimine açık olduğunu da kontrol edin.

Tek stoktan birden çok kanala satışın riskleri

Aynı ürünü n11'de, kendi sitenizde ve başka bir pazaryerinde aynı depodan satıyorsanız son adet bir kanalda satıldığında öbür kanallar bunu entegrasyonun gönderdiği stok güncellemesiyle öğrenir. Güncelleme gecikir ya da başarısız olursa ürün n11'de satışta görünmeye devam eder ve stokta olmayan ürün için sipariş gelebilir. n11 bu riskin kendisini anlatmaz, ama sonucunu kendi kurallarına bağlar.

n11'in kurallarına göre ürün satışa sunulduğu hâlde stokta bulunmaması, siparişi reddetmek için haklı gerekçe sayılmaz ve sözleşmedeki cezai yaptırıma bağlanır. Siparişi reddetmeyip ürünü tedarik etmeye çalışırken hazırlık süresi geçerse sipariş geciken kargolamaya düşer. Gecikme beş gün ve üzerine çıkar ve sipariş iptal edilirse "Tedarik Edilemeyen Sipariş" sayılır ve ek ceza uygulanır. Sipariş reddi ve geciken kargo mağaza puanını da etkiler.

Mesafeli Sözleşmeler Yönetmeliği'nin 16. maddesi de aynı yöndedir: satıcı, taahhüt ettiği süre içinde edimini yerine getirmek zorundadır ve bu süre mal satışında otuz günü geçemez. Maddenin dördüncü fıkrasına göre malın stokta bulunmaması, edimin yerine getirilmesinin imkânsızlaşması sayılmaz. Bu yazı genel bilgilendirme içindir, hukuki görüş yerine geçmez.

AdPix'in önerisi, kanallara gönderilen stoğu ana stoğun tamamı olarak değil, bir pay ayırarak hesaplamaktır. Az adetli ürünlerde son adetler bütün kanallara gönderilmez, bir güvenlik stoğu bırakılır; çok satan ürünlerde güncellemenin sıklığı ve görev sonuçları düzenli izlenir. Stok iki ayrı yazılımdan gönderiliyorsa n11'e stoğu hangisinin yazdığı tek bir kurala bağlanır. Kampanya dönemindeki stok planı n11 kampanyaları yazısında ayrıca anlatılır.

Entegrasyondan önce hazırlanacaklar

Entegrasyonun büyük bölümü, bağlantıdan önce verinin hazırlanmasıdır. n11'in belgeleri ve hata listesi şu hazırlıkları gerektirir:

• Evrak ve API Hesabı: mağaza evraklarının süreçleri tamamlanır, API hesabı açılır.
• Teslimat Şablonu: ürün yüklemede şablonun adı gönderilir; şablon n11'de önceden tanımlı olmalıdır.
• Kategori ve Özellik Eşleştirmesi: her ürün grubu için en alt kırılım kategori ve zorunlu özellikler eşlenir.
• Barkod ve Stok Kodu: her ürün ve varyant için benzersiz bir barkod ve değişmeyecek bir stok kodu bulunur.
• Ürün Adı ve Açıklama: ad en az 15 karakterdir; ad ve açıklamada yasaklı kelime, açıklamada çok sayıda açık HTML etiketi bulunmaz.
• Görseller: adresler https ile başlar, her görsel en çok 10 MB olur.
• KDV ve Hazırlık Günü: KDV oranı 0, 1, 10 ya da 20 olarak, hazırlık günü de her üründe girilir.
• Deneme Grubu: bütün katalogdan önce küçük bir ürün grubu gönderilir ve görev sonuçları okunur; bu adım n11'in kuralı değil, AdPix'in önerisidir.

Onaya giden kategorilerdeki ürünleri n11 ekipleri inceler. n11'in ürün onay sürecine göre reddedilen ürün düzeltilip aynı gün bir kez daha gönderilebilir; düzeltme yapılmadan üç kez gönderilen ürün "yasaklı ürün" durumuyla reddedilir. Hata çıktığında aynı veriyi değiştirmeden yeniden göndermek bu yüzden zarar verir.

n11 entegrasyonunda sık yapılan hatalar

n11'in hata listesinde ve belgelerinde en çok karşılaşılan durumlar şunlardır:

• Görev Sonucuna Bakmamak: kuyruğa alınan istek işlenmiş sayılır, başarısız ürünler fark edilmez.
• Üst Kategoriye Eşlemek: ürün yüklemede yalnızca en alt kırılım kategori kabul edilir.
• Eski Özellik Listesiyle Çalışmak: kapatılan kategori ya da geçersiz hâle gelen özellik değeri hata verir; liste yeniden çekilir.
• Eksik Marka: marka bilgisi boş gönderilir ya da o kategoride bulunmayan bir marka kimliği kullanılır.
• Mükerrer Kod: aynı stok kodu ya da aynı barkod birden çok üründe kullanılır.
• Fiyat Biçimi: fiyat virgülle ya da iki haneden fazla ondalıkla gönderilir, liste fiyatı satış fiyatından düşük kalır.
• Tanımsız Teslimat Şablonu: şablon adı boş ya da n11'de tanımlı olmayan bir adla gönderilir.
• Kimlik Numarasını Zorunlu Saymak: alıcının T.C. kimlik numarası alanı 15 Ekim 2025'ten beri boş gelebilir.
• Aksiyon Bekleyenleri Unutmak: katalogla eşleşen ürün satıcı onayı beklerken satışa açılmaz.

Uzman desteği gerektiren durumlar

Entegrasyonun yolu, eşleştirmenin kapsamı ve stoğun kanallara nasıl dağıtılacağı mağazanın ürün yapısına göre değişir. AdPix, pazaryeri entegrasyonu kurulumu hizmetinde altyapının n11 bağlantısını ya da entegrasyon yazılımını kurar; kategori ve özellik eşleştirmesini, barkod ve stok kodu düzenini ve stok kurallarını hazırlar, ürünleri önce küçük bir grupla aktarıp görev sonuçlarını okur. Mağazanın n11'deki satış, kampanya ve sipariş işleri n11 danışmanlığı kapsamında ele alınır.

n11 entegrasyonu için diğer rehberler

• n11 danışmanlığı
• n11 kargo süreci ve kargoya verme süresi
• n11 kampanya türleri ve katılım öncesi kontrol
• Pazaryeri entegrasyonu nedir
• ideasoft n11 aktarımında kategori ve özellik hataları
• ikas n11 entegrasyonunda stok ve fiyat sorunları

n11 entegrasyonu hakkında sık sorulan sorular

n11 entegrasyonu için API anahtarı nereden alınır?

n11'in destek merkezine göre mağaza hesabına yüklenen evrakların süreçleri tamamlandıktan sonra mağaza panelindeki API hesapları bölümünden yeni hesap açılır. API Key ve API Secret bilgileri mağazaya kayıtlı e-posta adresine gönderilir; bu bilgiler entegrasyon yazılımına ya da altyapının n11 uygulamasına girilir.

n11 API'siyle hangi veriler aktarılabilir?

n11'in geliştirici belgeleri kategori ve özellik, ürün, stok ve fiyat, sipariş paketi, kargo takip bilgisi, fatura bağlantısı, iade talepleri ve ürün soruları için servisler anlatır. Bunlardan hangisinin taşındığı bağlandığınız yazılımın kapsamına bağlıdır; bağlantıdan önce yazılımın hangi servisleri kullandığını sorun.

n11'de kategori eşleştirmesi neden gerekir?

n11 ürünü kendi kategori ağacına ve kategoriye ait özelliklere göre açar. Ürün yüklemede yalnızca en alt kırılımdaki kategori kullanılır, zorunlu özellikler kategoriye göre değişir ve eksik gönderilen zorunlu özellik aktarımda hata verir. Eşleştirme, sizin alanlarınızın n11'deki karşılığını bu yüzden önceden tanımlar.

n11'e gönderilen stok ve fiyat neden hemen değişmiyor?

n11 stok ve fiyat isteklerini sırayla işler: istek önce kuyruğa alınır, sonucu görev kimliğiyle ayrıca sorgulanır ve başarısız ürünün nedeni görev sonucunda görünür. Katalog onay sürecindeki ürün güncellenemez; virgüllü ya da iki haneden fazla ondalıklı fiyat da isteği başarısız yapar.

Stokta kalmayan ürünün n11 siparişi reddedilebilir mi?

Reddedilebilir, ama n11'in kurallarına göre ürün satışa sunulduğu hâlde stokta bulunmaması sipariş reddi için haklı gerekçe sayılmaz ve sözleşmedeki cezai yaptırıma bağlanır; sipariş reddi mağaza puanını da etkiler. Mesafeli Sözleşmeler Yönetmeliği de stok yokluğunu edimin imkânsızlaşması saymaz.