XML Entegrasyonu Nasıl Yapılır? Trendyol, Hepsiburada ve N11 İçin Adım Adım Rehber

XML Entegrasyonu Nedir, Hangi Sorunu Çözer?

XML entegrasyonu, tedarikçinin yayınladığı ürün feed'ini (stok, fiyat, görsel, kategori) bir pazaryerinin API'sine çevirip otomatik yükleyen köprü sistemidir. Çözdüğü problem net: manuel ürün girişi. 6.000 ürünü Trendyol'a tek tek girmek bir kişiye 3-4 ay sürer. XML ile 7 günde biter.

Ama XML "sihirli kutu" değil. Tedarikçi feed'i kötüyse en iyi entegrasyon bile o kalitesizliği pazaryerine taşır. Bu yüzden önce feed kalitesi, sonra entegrasyon mantığı geliyor.

XML Akışında Olması Gereken 8 Temel Alan

Bir XML feed'in işe yarar olması için aşağıdaki 8 alan mutlaka olmalı. Eksik alan = pazaryeri reddi.

1. `stockCode` (Stok Kodu): Tedarikçinin kendi SKU'su. Eşsiz olmalı, değişmemeli.
2. `barcode` (Barkod): 13 haneli EAN. Trendyol ve Hepsiburada barkod ile çalışır.
3. `title` (Ürün Adı): Maksimum 100-150 karakter, marka + model + temel özellik.
4. `description` (Açıklama): Min. 800 karakter, temiz HTML, sıralı liste içerebilir.
5. `priceWithoutVat`, `vatRate`, `priceWithVat`: Üçü ayrı, KDV hesabı netleşsin.
6. `stock` (Stok): Anlık adet. Sıfır = pazaryerinden gizle.
7. `images` (Görseller): Min. 1000x1000, en az 3 görsel, watermark yok.
8. `category` (Kategori Yolu): Çok seviyeli, en az 2 derinlikte (örn. `Elektronik > Aksesuar > Kulaklık`).

Trendyol XML Entegrasyonu — Adım Adım

Trendyol Türkiye'nin en zor entegrasyon onayına sahip pazaryeri. Aşamalar:

1. Trendyol Satıcı Paneli'ne giriş. Vergi levhası ve mersis numarası onayı gerekli.
2. API anahtarı oluştur. `Hesap > Entegrasyon > API Bilgileri` altından supplierId, apiKey ve apiSecret al.
3. Kategori ağacını çek. `/sapigw/product-categories` endpoint'iyle tüm kategorileri JSON olarak indir.
4. Marka ID'lerini eşle. Trendyol her markayı kendi ID'siyle tutar; tedarikçi feed'indeki marka adını Trendyol marka ID'sine çevirmen lazım.
5. Öznitelik (attribute) eşlemesi. Her kategorinin zorunlu öznitelikleri farklı. Örn. "kulaklık" kategorisinde "bağlantı tipi" zorunlu.
6. İlk batch yükleme. Maks. 1000 ürün/istek. Her batch sonrası `batchRequestId` ile durum sorgulanır.
7. Onay bekle. Trendyol içerik moderasyonu 12-72 saat sürer. Reddedilen ürünler için ret sebebi gelir.
8. Stok ve fiyat güncelleme. `/sapigw/suppliers/{supplierId}/products/price-and-inventory` endpoint'iyle 15 dakikada bir push.

Hepsiburada Katalog ve XML Eşleştirmesi

Hepsiburada Trendyol'dan farklı çalışır: ürünler katalog tabanlı. Yani aynı barkodlu ürün zaten bir kataloğa bağlıysa sen sadece o kataloğa fiyat ve stok girersin. Yeni katalog açmak ayrı bir onay süreci.

1. Hepsiburada MPOP'a kayıt. Satıcı sözleşmesi imzala, mağaza onayı al.
2. Merchant ID ve API key oluştur. `Entegrasyon > MPOP API` altından.
3. Barkod kontrolü. Her ürün için Hepsiburada katalog API'sinde barkod sorgula.
4. Mevcut katalog varsa: Sadece `listing` (fiyat + stok) gönder. Ürün bilgisi katalogdan gelir.
5. Mevcut katalog yoksa: Yeni katalog talebi aç. Görsel + açıklama + öznitelik gönder. 24-48 saat onay.
6. Kargo profilini bağla. Hepsiburada kargo SLA'sını profil seviyesinde tutar.
7. İlk siparişleri test et. Sandbox modunda 5-10 sipariş simüle et.

Hepsiburada'nın kritik özelliği: aynı barkodlu birçok satıcı aynı kataloğu paylaşır. Yani fiyat rekabeti anında görünür. Buy Box (Hepsiburada'da "Sepete Ekle" sırası) genelde en ucuza ve en hızlı kargolayana gider.

N11 XML Yükleme ve Vitrin Çalışmaları

N11 hâlâ Türkiye'nin önemli pazaryerlerinden biri, özellikle elektronik ve hobi kategorisinde. Entegrasyonu Trendyol'a göre daha rahat:

1. N11 mağaza açılışı. Bireysel ya da kurumsal satıcı sözleşmesi.
2. API erişimi. `Mağazam > Entegrasyon > API` altından appKey ve appSecret al.
3. SOAP servislerini bağla. N11 hâlâ REST yanında SOAP destekler, eski entegrasyonlar SOAP üzerinden çalışır.
4. Kategori ağacını al. `CategoryService.GetTopLevelCategories` ile başla, sonra alt kategorilere in.
5. Ürün şemasını hazırla. Her kategori için `subtitle`, `productCondition`, `preparingDay` gibi zorunlu alanları doldur.
6. Batch yükleme. Maks. 100 ürün/istek. Trendyol'a göre daha küçük batch.
7. Vitrin çalışması. N11 vitrin = kategori filtresi. Doğru anahtar kelimelerle daha üst sırada görünürsün.

Pazarama ve PTTAvm İçin XML Hazırlığı

Pazarama ve PTTAvm büyüyen pazaryerleri, rekabet daha düşük, organik trafik yakalamak daha kolay. Entegrasyon ikisinde de XML/REST karışık.

Pazarama

• Mağaza açılışı 24-48 saat, vergi numarası onayı yeterli.
• REST API + manuel XML yükleme seçeneği var.
• Kategori sayısı Trendyol'dan az, eşleme daha hızlı.
• Komisyon oranları rekabetçi, özellikle ev/yaşam kategorisinde.

PTTAvm

• PTT'nin kendi pazaryeri, devlet referansı tüketici güvenini artırıyor.
• XML feed kabul ediyor; format Trendyol'a benzer ama kategori ağacı farklı.
• Kargo PTT entegre, ekstra anlaşma gerekmiyor.
• Henüz az satıcı var, doğru kategoride 1. sayfaya çıkmak kolay.

Kategori Eşleme: En Çok Yapılan Hatalar

Kategori eşleme XML entegrasyonunun en zaman alan ve hata yapılan kısmı. Sık karşılaştığımız 5 hata:

1. Tek seviyeli eşleme. Tedarikçinin "Elektronik" kategorisini Trendyol'un "Elektronik" kök kategorisine eşlemek. Hatalı — Trendyol alt kategori bekler.
2. Yanlış öznitelik atama. "Kadın ayakkabı" kategorisinde "taban yüksekliği" zorunlu; boş bırakırsan ürün reddedilir.
3. Marka adının yanlış yazımı. "Adidas" yerine "Adıdas" yazarsan Trendyol marka ID'sini bulamaz, ürün ret listesine düşer.
4. Kategori ID'lerini hardcode etmek. Pazaryerleri kategori ID'lerini ara sıra değiştirir. Hardcode = bir gün entegrasyon kopar.
5. Cinsiyet/yaş grubu eksik. Giyim kategorilerinde "cinsiyet" zorunlu öznitelik; eksik gelirse batch ret.

Stok ve Fiyat Güncelleme Sıklığı

Her pazaryerinin kendi rate limit ve önerdiği güncelleme sıklığı var:

• Trendyol: Min. 15 dakika önerilir, kritik kategorilerde 5 dakika. Rate limit 45 req/10s.
• Hepsiburada: 15-30 dakika ideal. Listing API ayrı, batch güncelleme destekli.
• N11: 30-60 dakika yeterli. SOAP servisi daha yavaş.
• Pazarama: 30 dakika ideal.
• PTTAvm: 1 saatlik güncelleme yeterli.

Akıllı Bayi'de tüm pazaryerleri için paralel kuyruk yapısı kullanıyoruz. Her pazaryerinin kendi worker'ı var, biri yavaşladığında diğerleri etkilenmez.

Görsel ve Açıklama Optimizasyonu

Pazaryeri arama algoritmaları görsel ve açıklamaya ciddi puan veriyor. Optimize edilmemiş içerikle ürün listelense bile sıralamada arkalara düşer.

Görsel için kontrol listesi

• Min. 1000x1000 px, ideali 1500x1500 px.
• Beyaz ya da çok açık gri arka plan.
• Watermark, logo, telefon numarası yok.
• Ürün kadrajın %85'ini doldurmalı.
• Min. 3 görsel: ön, yan, detay.

Açıklama için kontrol listesi

• Min. 800 karakter (daha uzun her zaman daha iyi).
• İlk 200 karakterde marka + model + ana özellik.
• HTML temiz: `<ul>`, `<strong>`, `<p>` evet; inline style hayır.
• Teknik özellikler tablo olarak.
• Kullanım/kurulum kısa anlatımı.

Hata Ayıklama ve XML Validasyon

XML entegrasyonu kurulduktan sonra hata loglarına bakmak rutinin parçası olmalı. En sık görülen 4 hata tipi:

1. Parse hatası. Tedarikçi XML'i bozuk karakter içeriyor (ör. `&` escape edilmemiş). Çözüm: XML parser'ı tolerant moda al, hatalı satırı atla, raporla.
2. Şema validasyon hatası. Pazaryeri zorunlu alanı boş geldi. Çözüm: ön validasyon katmanı, boşluk varsa o ürünü gönderme.
3. Rate limit aşımı. Trendyol IP banı. Çözüm: kuyruk kütüphanesi ile istek havuzunu sınırla.
4. Onay timeout. Pazaryeri batch'i 72 saatte cevaplamadı. Çözüm: 72. saatte tekrar sorgu, yine cevap yoksa batch'i yeniden gönder.

Akıllı Bayi'nin Hazır Entegrasyon Avantajı

Yukarıdaki adımları sıfırdan kurmak isteyene tahmini süre: 2-3 hafta tam zamanlı geliştirici + sürekli bakım. Akıllı Bayi'de bunların hepsi paket içinde:

• Trendyol, Hepsiburada, N11, Pazarama, PTTAvm için hazır eşleme.
• 60.000+ ürün için pre-mapped kategori ağacı.
• 3 tedarikçi feed'i tek panelde, çakışma yönetimi otomatik.
• Rate limit yönetimi `p-limit` ile dahili.
• Saat 11:00 kargo cut-off entegre.
• Webhook tabanlı sipariş bildirimi, otomatik stok rezervasyon.
• Hata logları renk kodlu dashboardda gerçek zamanlı.

Sıfır Kod ile Entegrasyon Mümkün mü?

Cevap: evet, ama Akıllı Bayi gibi hazır altyapı kullanırsan. Kendi başına XML parse + REST API çağırma + rate limit + hata yönetimi yazıyorsan kod kaçınılmaz.

Akıllı Bayi panelinde tek satır kod yazmadan:

• Pazaryeri API key'ini panel formuyla bağlarsın.
• Kategori eşlemesini otomatik %85 görür, kalan %15'i tıklayarak onaylarsın.
• Kâr marjı kuralını dropdown'dan seçersin.
• İlk batch yüklemeyi "Yükle" butonuyla başlatırsın.
• Hata logu gelirse renk kodlu uyarı görürsün.

Sonuç: XML entegrasyonu 2026'da hâlâ teknik bir iş ama artık sıfırdan yazılmak zorunda değil. Doğru altyapıyla 7 günde mağaza açar, manuel ürün girişine harcayacağın 3-4 ayı doğrudan pazarlama ve müşteri hizmetine kanalize edersin.