Bir tedarikçi XML'inde ürün kategorisi şöyle gelebilir:

Ev > Mutfak > Cezve

Başka bir XML'de:

Mutfak Gereçleri / Kahve Ürünleri

Başka bir tedarikçide ise yalnız:

Cezve

yazabilir.

Trendyol tarafında ise ürünün gönderileceği kategori:

yalnızca kategori adıyla değil,

Trendyol kategori ID'si

üzerinden belirlenir.

Üstelik doğru kategori seçildikten sonra iş bitmez.

Seçilen kategori:

• hangi özelliklerin istendiğini,
• hangi özelliklerin zorunlu olduğunu,
• hangi değerlerin seçilebildiğini,
• hangi alanların varyant olduğunu,
• hangi alanların ürünleri ayrı içeriklere ayırdığını

da etkileyebilir.

Trendyol'un güncel Product V2 dokümantasyonunda ürün yaratma işleminden önce Marka Listesi, Kategori Listesi, Kategori Özellikleri ve Kategori Özellik Değerleri servislerinden gerekli bilgilerin alınması gerektiği açıkça belirtiliyor.

Dolayısıyla:

XML kategori eşleştirmesi

sadece:

“Mutfak → Mutfak”

şeklinde bir metin değiştirme işlemi değildir.

Daha doğru model:

Tedarikçi kategori yolu

↓

Normalize edilmiş ürün sınıfı

↓

Trendyol kategori ağacı

↓

En uygun leaf category

↓

Trendyol categoryId

↓

Kategori özellikleri

↓

Özellik değerleri

↓

Ürün doğrulama

↓

Trendyol ürün aktarımı

şeklindedir.

1. Önce Tedarikçi Kategorisi ile Trendyol Kategorisinin Farklı Sistemler Olduğunu Kabul Edin

Tedarikçi:

Ev > Mutfak > Cezveler

kullanıyor olabilir.

Trendyol kendi kategori ağacını kullanır.

İsimlerin benzemesi:

iki kategorinin sistem açısından aynı olduğu

anlamına gelmez.

Bu nedenle kaynak kategoriyi doğrudan hedef kategori kabul etmeyin.

2. Kaynak Kategori ile Hedef Kategoriyi Ayrı Alanlarda Tutun

Örneğin:

supplier_category

Ev > Mutfak > Cezveler

trendyol_category_id

XXXXX

trendyol_category_name

...

gibi ayrı alanlar tutulabilir.

Kaynak değer üzerine Trendyol kategorisi yazılmamalıdır.

3. Kaynak Kategori Bilgisini Olduğu Gibi Saklayın

Tedarikçi XML:

Ev/Mutfak/Kahve/Cezve

gönderiyorsa ham değer korunmalıdır.

Çünkü ileride yanlış mapping olduğunda:

tedarikçiden gerçekten hangi kategori geldi?

sorusuna cevap vermeniz gerekir.

Bu yaklaşım mevcut Ulu kategori hata rehberinde de temel kontrol olarak kullanılıyor.

4. Kategori Yolunu Ayrıştırın

Örneğin:

Ev/Mutfak/Kahve/Cezve

şu seviyelere ayrılabilir:

Seviye 1: Ev

Seviye 2: Mutfak

Seviye 3: Kahve

Seviye 4: Cezve

Yalnız son kelimeyi kullanmak bilgi kaybettirebilir.

5. Sadece “Cezve” Kelimesine Göre Mapping Yapmayın

Başka tedarikçi:

Elektrikli Cezve

kategorisini kullanabilir.

Başka ürün:

Oyuncak Cezve Seti

olabilir.

Kategori ismini tek başına eşleştirmek bazı ürünleri yanlış kategoriye gönderebilir.

6. Tam Kategori Yolunu Mapping Anahtarı Olarak Kullanabilirsiniz

Daha güçlü anahtar:

Ev > Mutfak > Kahve > Cezve

şeklindedir.

Bu:

Cezve

kelimesinden daha fazla bağlam taşır.

7. Tedarikçinin Kategori ID'si Varsa Onu da Saklayın

Örneğin:

supplier_category_id = 558

supplier_category_path = Ev > Mutfak > Cezve

İki bilgiyi birlikte tutmak mapping bakımını kolaylaştırabilir.

Ancak tedarikçi ID'sini Trendyol categoryId sanmayın.

8. Trendyol Kategori Ağacını Resmî Servisten Alın

Trendyol'un kategori servisi:

getCategoryTree

ürün oluştururken kullanılacak kategori ID bilgisini sağlar.

Bu nedenle kategori ID'sini:

• blogdan,
• eski Excel'den,
• başka satıcının entegrasyonundan

kalıcı gerçek olarak kopyalamak yerine güncel Trendyol verisinden almak daha güvenlidir.

9. Trendyol'da Ürün En Alt Kategoriye Eşleştirilmelidir

Bu 132'nin en önemli teknik kurallarından biridir.

Trendyol dokümantasyonuna göre ürün yaratılırken:

en alt seviyedeki kategori ID'si

kullanılmalıdır.

Eğer seçilen kategorinin alt kategorileri bulunuyorsa o kategoriyle ürün oluşturulamaz.

10. Ana Kategoriye Mapping Yapıp Bırakmayın

Örneğin:

Elektronik

çok genel olabilir.

Altında:

• telefon,
• kulaklık,
• kamera,
• aksesuar

gibi farklı dallar bulunabilir.

XML mapping mümkün olduğunca ürünün gerçek leaf kategorisine ulaşmalıdır.

11. “İlk Eşleşen Kategori” Algoritması Kullanmayın

Kaynak:

Aksesuar

Trendyol'da birden fazla Aksesuar benzeri kategori bulunabilir.

Kod:

adı Aksesuar olan ilk kategori

seçiyorsa yanlış ürün grubu oluşabilir.

Kategori yolunun tamamı değerlendirilmelidir.

12. Kategori ID'yi İsimden Ayrı Saklayın

Örneğin:

target_category_id

ve:

target_category_path

ayrı tutulabilir.

ID entegrasyon için,

path ise insanlar tarafından kontrol için değerlidir.

13. Kategori Mapping Tablosu Oluşturun

Örnek kayıt:

Supplier: Tedarikçi A

Source ID: 558

Source path: Ev > Mutfak > Cezveler

Target: Trendyol Cezve kategorisi

Target ID: güncel Trendyol kategori ID

Status: VERIFIED

Version: MAP_V1

şeklinde olabilir.

14. Her Tedarikçiye Ayrı Mapping Katmanı Kullanmak Gerekebilir

Tedarikçi A:

Mutfak > Cezve

Tedarikçi B:

Ev Gereçleri > Kahve

Tedarikçi C:

Züccaciye > Pişirme

kullanabilir.

Hepsi aynı Trendyol kategorisine gidebilir.

15. Many-to-One Mapping Normaldir

Örneğin üç kaynak kategori:

Cezve

Kahve Cezvesi

Çelik Cezveler

tek Trendyol kategorisine bağlanabilir.

Bu hata değildir.

Önemli olan mapping'in doğrulanmış olmasıdır.

16. One-to-Many Mapping Daha Dikkatli Yönetilmelidir

Tedarikçi kategorisi:

Elektronik Aksesuar

çok genel olabilir.

İçinde:

• telefon kılıfı,
• kablo,
• adaptör,
• araç şarj cihazı

bulunabilir.

Bu kategori tek Trendyol hedef kategorisine bağlanamayabilir.

17. Genel Kaynak Kategoride Ürün Seviyesi Kural Kullanabilirsiniz

Örneğin:

Supplier Category = Elektronik Aksesuar

Ürün tipi = USB Kablo

↓

Trendyol hedef A

Supplier Category = Elektronik Aksesuar

Ürün tipi = Araç Şarj Cihazı

↓

Trendyol hedef B

Bu durumda mapping anahtarı yalnız kaynak kategori değildir.

18. Ürün Adı Yardımcı Sinyal Olabilir

Örneğin:

3 Metre Type-C Şarj Kablosu

başlığı yanlış kategori adaylarını elemekte kullanılabilir.

Ancak ürün adından otomatik olarak kesin kategori belirlemek risklidir.

19. Marka Tek Başına Kategori Belirlememelidir

Bir marka:

telefon aksesuarı,

kulaklık,

akıllı saat

üretebilir.

Dolayısıyla:

Marka X → Kulaklık

şeklinde sabit kural güvenilir değildir.

20. XML'deki Ürün Özelliklerini Mapping Sinyali Olarak Kullanın

Örneğin ürün:

• 128 GB,
• 256 GB,
• ekran boyutu,
• RAM

gibi alanlar taşıyorsa belirli elektronik ürün sınıflarına işaret edebilir.

Ancak yine de final kategori doğrulanmalıdır.

21. Kategori Seçildikten Sonra Kategori Özelliklerini Çekin

Trendyol'un güncel V2 servisinde kategoriye ait özellikler:

Kategori Özellik Listesi v2

servisinden alınır.

Dokümantasyonda bu bilgilerin ürün yaratma sırasında kullanılacağı belirtiliyor.

22. Kategori Mapping ve Attribute Mapping'i Ayrı İşler Olarak Görün

Birinci mapping:

Kaynak kategori → Trendyol categoryId

İkinci mapping:

Kaynak ürün alanları → Trendyol kategori özellikleri

dir.

İkisini tek tabloya sıkıştırmak ileride yönetimi zorlaştırabilir.

23. Doğru Kategori Seçmek Zorunlu Özellikleri Değiştirebilir

Kategori özellik servisinde alanlar için:

required

bilgisi dönebiliyor.

Dolayısıyla yanlış kategori seçilirse ürün:

kendisinde bulunmayan bir özelliği zorunlu olarak istemeye başlayabilir.

24. Eksik Zorunlu Özellik Bazen Kategori Hatasının Belirtisidir

Örneğin cezve ürününden:

beden

istenmeye başladıysa:

yalnız eksik attribute problemi değil,

yanlış kategori mapping problemi

de olabilir.

Mevcut Ulu kategori hata rehberi de bu sinyali özellikle ayırıyor.

25. required=true Alanlarını Otomatik Kontrol Edin

Kategori seçildiğinde sistem:

hangi özellikler zorunlu?

listesini oluşturabilir.

Ürün gönderilmeden önce eksikler bulunabilir.

26. allowCustom Bilgisini Dikkate Alın

Trendyol kategori özellik yapısında bazı özelliklerin serbest değer kabul edip etmediğine ilişkin bilgi bulunabilir.

Bu yüzden XML'deki her değeri doğrudan:

custom text

olarak göndermek doğru değildir.

27. Ön Tanımlı Değer Gereken Alanlarda Trendyol Değer ID'sini Kullanın

Örneğin XML:

Renk = Siyah

gönderiyor.

Trendyol ilgili attribute için kendi değer listesini sunabilir.

Bu durumda:

Siyah → ilgili Trendyol attribute value ID

mapping'i gerekebilir.

Kategori özellik değerleri V2 servisi bunun için kullanılabiliyor.

28. Attribute Adı ile Attribute Value'yu Karıştırmayın

Örneğin:

Attribute: Materyal

Value: Çelik

iki ayrı kavramdır.

Mapping'in de:

source field → attribute

ve:

source value → target value

katmanları bulunabilir.

29. Attribute ID'leri de Güncel Kaynaktan Alın

Eski entegrasyondan:

Renk = Attribute 47

gibi bir değer bulmuş olabilirsiniz.

Bunu bütün kategoriler için sabit varsaymayın.

Kategori özelliklerini güncel servis üzerinden doğrulayın.

30. Kategoriye Göre Aynı Özelliğin Davranışı Değişebilir

Renk:

bir kategoride standart özellik,

başka kategoride varyant ayırıcı

olabilir.

Bu nedenle global:

Renk her zaman böyle gönderilir

kuralı hatalı olabilir.

31. varianter Bilgisini Kontrol Edin

Trendyol ürün yapısında kategori özelliği:

varianter=true

olarak dönebilir.

Bu bilgi aynı içerikte bulunan varyantların ayrılmasında rol oynar. Trendyol dokümantasyonunda beden gibi değerler örnekleniyor.

32. slicer Bilgisini de Kontrol Edin

Trendyol dokümantasyonunda slicer özelliklerin ürünü ayrı içeriklerde açmak için kullanılabildiği, renk veya elektronik kategorilerinde hafıza gibi değerlerin buna örnek olabileceği belirtiliyor.

Bu nedenle kategori mapping varyant mimarisini de etkileyebilir.

33. Kategori Yanlışsa Varyant Yapısı da Yanlış Kurulabilir

Örneğin ürün:

128 GB

256 GB

varyantlarına sahip.

Yanlış kategoride hafıza:

normal attribute

olarak görülürken doğru kategoride farklı varyant davranışı beklenebilir.

Kategori mapping yalnız kategori etiketi değildir.

34. Parent ve Variant Ürünleri Aynı Kategori Mantığında Tutun

Bir ürün ailesinin varyantları:

aynı temel ürün sınıfına

ait olmalıdır.

Aynı productMainId ailesindeki ürünlerin farklı ve ilgisiz kategorilere dağılması şüpheli durumdur.

35. Attribute Mapping Kategori Değiştiğinde Yeniden Kontrol Edilmelidir

Bugün ürün:

Kategori A.

Yarın mapping:

Kategori B.

B kategorisinin:

• zorunlu alanları,
• değer listeleri,
• varyant özellikleri

farklı olabilir.

Eski attribute mapping otomatik taşınmamalıdır.

36. Trendyol Kategori Ağacını Kalıcı ve Değişmez Kabul Etmeyin

Trendyol güncel dokümantasyonunda kategori ağacının belirli aralıklarla güncellendiğini açıkça belirtiyor. Güncel olmayan kategori ağacının eksik veya hatalı veri girişine yol açabileceği uyarısı bulunuyor.

Bu nedenle mapping:

bir kere yap ve unut

işi değildir.

37. Kategori Ağacını Düzenli Yenileyin

Trendyol dokümantasyonu kategori ve özellik listelerinin güncel tutulmasını, kategori/özellik değişiklikleri nedeniyle düzenli olarak yeniden alınmasını öneriyor.

Entegrasyon bu yenilemeyi otomatikleştirebilir.

38. Eski Mapping'leri Güncel Kategori Ağacına Karşı Doğrulayın

Mapping tablonuzda:

500 Trendyol categoryId

var.

Yeni kategori ağacı geldi.

Sistem kontrol etmelidir:

Bu ID hâlâ kullanılabilir mi?

Hâlâ leaf kategori mi?

Attribute yapısı değişti mi?

39. Mapping Durumları Oluşturun

Örneğin:

VERIFIED

doğrulanmış.

AUTO_MAPPED

otomatik önerilmiş.

REVIEW_REQUIRED

manuel kontrol gerekiyor.

UNMAPPED

hedef bulunamadı.

STALE

yeniden doğrulanmalı.

Bu yapı mapping operasyonunu yönetilebilir hale getirir.

40. Otomatik Mapping İçin Güven Skoru Kullanabilirsiniz

Örneğin:

Tam kaynak yol + ürün tipi + attribute uyumu yüksek:

confidence = 0.98

Yalnız kategori adı benziyor:

confidence = 0.55

Düşük güvenli kayıtlar otomatik yayın yerine incelemeye gönderilebilir.

41. Benzer Kelime Oranı Tek Başına Güven Skoru Olmasın

Source:

Telefon Aksesuarları

Target:

Moda Aksesuarları

kelime benzerliği yüksektir.

Semantik olarak yanlıştır.

Bu nedenle string similarity yalnız bir sinyal olmalıdır.

42. Mapping Sözlüğü Oluşturun

Örneğin:

Cep Telefonu → Telefon

Şarj Aleti → Şarj Cihazı

Kulaklıklar → Kulaklık

gibi normalize edilmiş terimler eşleştirmeyi destekleyebilir.

Ancak sözlük final categoryId değildir.

43. Türkçe Karakter Normalizasyonunu Kontrollü Yapın

Örneğin:

Küçük Ev Aletleri

ve:

Kucuk Ev Aletleri

comparison sırasında aynılaştırılabilir.

Fakat ham değer yine korunmalıdır.

44. Büyük/Küçük Harf Farklarını Mapping Sinyalinden Çıkarın

CEZVE

Cezve

cezve

karşılaştırmada aynı kategori adayı olarak görülebilir.

Bu yalnız teknik normalizasyondur.

Kategori anlamını değiştirmez.

45. Gereksiz Boşluk ve Noktalama İşaretlerini Normalize Edin

Kaynak:

Ev > Mutfak > Cezve

ve:

Ev>Mutfak>Cezve

aynı kategori yolu olabilir.

Comparison key oluşturulabilir.

46. Kaynak Kategoriyi Normalleştirmek Orijinal Veriyi Silmek Değildir

İki alan kullanılabilir:

raw_supplier_category

normalized_supplier_category

Böylece hem mapping kolaylaşır hem hata araştırması yapılabilir.

47. Fallback Kategori Kullanacaksanız Kontrollü Kullanın

Mapping bulunamadığında:

Diğer

kategorisine otomatik göndermek kısa vadede aktarımı devam ettirebilir.

Ancak ürünün yanlış yerde yayınlanmasına da neden olabilir.

Trendyol gibi kategoriye bağlı attribute sisteminde sessiz fallback özellikle risklidir.

48. Mapping Bulunmayan Ürünü Yayınlamamak Daha Güvenli Olabilir

Örneğin:

mapping_status = UNMAPPED

ise ürün:

HOLD

durumunda tutulabilir.

Doğru kategori doğrulandıktan sonra gönderilebilir.

49. “En Yakın Kategoriye At” Kuralını Kontrolsüz Kullanmayın

Kaynak kategori bulunamadı diye:

en benzer isimli Trendyol kategorisine

otomatik atmak ürünlerin yanlış sınıflandırılmasına yol açabilir.

Özellikle çok ürünlü XML'de hata toplu hale gelir.

50. Yeni Kaynak Kategorileri Ayrı Kuyruğa Alın

Dün tedarikçide:

150 kategori.

Bugün:

Yeni 5 kaynak kategori için mapping yoksa:

NEW_SOURCE_CATEGORY

raporu oluşturulabilir.

51. Yeni Kategorilerin Ürünlerini Sessizce Eski Mapping'e Sokmayın

Tedarikçi:

Akıllı Ev > Sensör

diye yeni kategori açtı.

Sistem bunu otomatik:

Elektronik Aksesuar

altına atmamalıdır.

Önce mapping doğrulanmalıdır.

52. Mapping Tablosunu Versiyonlayın

Örneğin:

MAP_TRENDYOL_V1

MAP_TRENDYOL_V2

MAP_TRENDYOL_V3

şeklinde.

Bir ürünün neden başka kategoriye geçtiğini geriye dönük inceleyebilirsiniz.

53. Mapping Değişikliğinde Kim ve Ne Zaman Bilgisi Tutun

Örneğin:

Source Category 558

Eski target → 1001

Yeni target → 2145

Değiştiren → admin

Tarih → 23.08.2026

Sebep → Trendyol kategori yapısı güncellendi

Bu audit kaydı çok değerlidir.

54. Mevcut Ürünlerde Mapping Değişikliğini Toplu Uygulamadan Önce Test Edin

Bir kategori altında:

4.000 ürün

bulunuyor olabilir.

Tek mapping değişikliği:

4.000 ürünü etkiler.

Önce küçük örneklemde sonuç kontrol edilmelidir.

55. Onaylı Ürünlerde Kategori Değişikliğinin Sınırlı Olduğunu Unutmayın

Trendyol'un güncel onaylı ürün V2 güncelleme dokümantasyonunda:

categoryId

alanının onaylı ürünlerde değiştirilemediği belirtiliyor. Aynı kısıtlama barkod, productMainId, brandId ve bazı varyant özellikleri için de bulunuyor.

Bu nedenle doğru kategori:

ürün ilk oluşturulmadan önce

mümkün olduğunca doğrulanmalıdır.

56. “Sonra Düzeltiriz” Yaklaşımı Kategori İçin Risklidir

Ürün:

yanlış kategoriyle oluşturuldu.

Onaylandı.

Daha sonra categoryId'nin standart content update üzerinden değiştirilememesi operasyonu karmaşıklaştırabilir.

Bu yüzden pre-publish kontrol önemlidir.

57. Category Preflight Kontrolü Oluşturun

Ürün gönderilmeden önce:

Kaynak kategori mevcut mu?

Mapping var mı?

Target leaf category mi?

Target category güncel mi?

Required attributes dolu mu?

Attribute values geçerli mi?

kontrol edilebilir.

58. Ürün Yaratmadan Önce Marka + Kategori + Özellikleri Birlikte Kontrol Edin

Trendyol Product V2 dokümantasyonu ürün yaratma öncesinde:

• marka listesi,
• kategori listesi,
• kategori özellikleri,
• kategori özellik değerleri

bilgilerinin alınmasını istiyor.

Kategori mapping tek başına yeterli değildir.

59. XML Kategori Mapping Tablosunu Trendyol Payload'ından Ayırın

Mapping tablonuz:

source category → target category

ilişkisini tutar.

Product payload ise:

• barcode,
• title,
• brandId,
• categoryId,
• quantity,
• stockCode,
• attributes

gibi gerçek ürün verilerini içerir. Trendyol V2 ürün yaratma dokümantasyonunda categoryId zorunlu alanlardan biridir.

60. Mapping Sonucunu Önce Dry-Run Olarak Üretin

Örneğin:

10.000 XML ürünü.

Canlı göndermeden önce rapor:

Mapped → 8.950

Manual review → 700

Unmapped → 350

şeklinde üretilebilir.

Bu, binlerce yanlış ürünün Trendyol'a gitmesini önler.

61. Kategori Dağılımını Önce/Sonra Karşılaştırın

XML kaynak:

Cezve → 500

Tencere → 700

Oyuncak → 600

Mapping sonrası Trendyol'da:

Cezve → 500

Tencere → 700

Oyuncak → 0

Diğer → 600

görülüyorsa sorun vardır.

62. Hedef Kategoride Anormal Yoğunluk Arayın

Örneğin normalde:

200 ürün

bulunan kategoriye yeni mapping sonrası:

8.000 ürün

düştü.

Bu durum mapping bug'ı olabilir.

63. Kategori Sıkıştırma Oranını İzleyebilirsiniz

Tedarikçide:

200 alt kategori.

Trendyol mapping sonrası:

5 hedef kategori.

Bu her zaman hata değildir.

Ama aşırı sıkıştırma ürün detayını kaybettirebilir.

64. Required Attribute Error Oranını Mapping Sonrası İzleyin

Yeni mapping sonrası:

required attribute missing

hataları sert biçimde arttıysa kategori yanlış olabilir.

Bu özellikle toplu entegrasyon değişikliklerinde güçlü sinyaldir.

65. Ürün Aktarımının HTTP Başarısını Nihai Başarı Sanmayın

Trendyol ürün yaratma isteği kabul edildiğinde size:

batchRequestId

dönebilir.

Bu yalnız işlemin kuyruğa alınmasıyla ilgilidir.

Trendyol dokümantasyonu, ürün ve aktarım sonucunun ayrıca Toplu İşlem Kontrolü servisi üzerinden takip edilmesini istiyor.

66. batchRequestId Sonucunu Mutlaka Kontrol Edin

Ürün gönderildi.

HTTP cevap başarılı.

Ama item:

kategori veya attribute nedeniyle başarısız olabilir.

Batch sonucunda item bazlı durum kontrol edilmelidir.

67. failureReasons Alanını Loglayın

Trendyol'un toplu işlem kontrolü dokümantasyonu, ürün bazında hata oluştuğunda:

failureReasons

alanının kontrol edilmesini söylüyor.

Kategori mapping sistemi bu hataları raporlamalıdır.

68. Kategori Hatalarına Ayrı Error Code Verin

Örneğin:

SOURCE_CATEGORY_MISSING

CATEGORY_MAPPING_MISSING

TARGET_CATEGORY_NOT_FOUND

TARGET_NOT_LEAF

CATEGORY_ATTRIBUTE_MISSING

ATTRIBUTE_VALUE_UNMAPPED

CATEGORY_MAPPING_STALE

TRENDYOL_CATEGORY_REJECTED

gibi.

Bu hata analizi çok daha kolay olur.

69. Genel API Hatası ile Mapping Hatasını Ayırın

401:

kimlik doğrulama sorunu olabilir.

500:

geçici servis problemi olabilir.

Kategori mapping yanlışlığı bunlarla aynı hata sınıfında tutulmamalıdır.

70. Trendyol V1 ve V2 Servislerini Karıştırmayın

Bugün özellikle kritik.

Trendyol'un güncel dokümanına göre Product V1 endpoint'leri 15 Eylül 2026 itibarıyla kullanım dışı kalacak ve V2 geliştirmesine geçilmesi gerekiyor.

132 bu yüzden yeni kurulacak sistemi V2 mantığıyla anlatmalıdır.

71. Kategori Ağacı Servisi V1–V2 Ortak Kullanımda

Trendyol'un güncel V2 endpoint listesinde:

Kategori Listesi

servisi V1–V2 ortak olarak gösteriliyor.

Kategori Özellik Listesi v2 ve Kategori Özellik Değerleri v2 ise V2 tarafında ayrı endpoint'ler olarak yer alıyor.

Bu ayrım teknik geliştirmede önemlidir.

72. XML → Trendyol Mapping Katmanını Yeniden Kullanılabilir Tasarlayın

Yanlış yapı:

Tedarikçi A XML parser'ın içine:

if category == "Cezve" → 123

yazmak.

Daha doğru yapı:

Supplier parser

↓

Normalized product

↓

Marketplace mapping layer

↓

Trendyol adapter

şeklindedir.

Böylece aynı ürün verisi başka pazaryerleri için de kullanılabilir.

73. Trendyol Kategorisini XML'in İçine Yazmak Zorunda Değilsiniz

Kaynak XML tedarikçinin verisidir.

Sizin sisteminiz:

supplier_category

verisini alıp kendi mapping veritabanınızda:

trendyol_category_id

oluşturabilir.

Kaynak feed'i değiştirmek gerekmeyebilir.

74. Mağaza Kategorisi ile Trendyol Kategorisini de Ayrı Tutun

Kendi sitenizde:

Ev & Mutfak > Cezve

kullanabilirsiniz.

Trendyol:

başka taxonomy

kullanabilir.

Bu nedenle:

supplier category

store category

Trendyol category

üç ayrı katman olabilir.

75. Tek Bir “global_category” Katmanı İşinizi Kolaylaştırabilir

Örnek:

Supplier A → Kahve Pişiriciler

Supplier B → Cezveler

↓

Internal category → Cezve

↓

Store category → Cezveler

↓

Trendyol category → ilgili Trendyol leaf ID

Bu mimari çoklu tedarikçide yararlı olabilir.

76. Ancak Internal Category Katmanını Zorunlu Görmeyin

Küçük entegrasyonda:

Supplier category → Trendyol category

doğrudan mapping yeterli olabilir.

Mimari katalog büyüklüğüne göre seçilmelidir.

77. Manuel Override Desteği Bulundurun

Otomatik sistem ürün için:

Kategori A

öneriyor.

Operatör:

Kategori B

olarak doğruladı.

Yeni sync geldiğinde sistem manuel kararı ezmemelidir.

78. Manuel Override Kaynağını Kaydedin

Örneğin:

mapping_source = MANUAL_VERIFIED

veya:

mapping_source = AUTOMATIC_RULE

gibi.

Hangi kararın insan tarafından verildiği bilinmelidir.

79. Supplier Kategorisi Değiştiğinde Manuel Mapping'i Körü Körüne Korumayın

Ürün tedarikçide:

Cezve

iken:

Elektrikli Mutfak Aleti

kategorisine taşındı.

Bu gerçek ürün sınıfının değiştiğine işaret edebilir.

Manual override yeniden inceleme gerektirebilir.

80. Ürün Bazlı Override ile Kategori Bazlı Mapping'i Ayırın

Kategori mapping:

1.000 ürün

etkileyebilir.

Product override:

tek SKU

etkiler.

Bu ayrım toplu hata riskini ciddi biçimde azaltır.

81. Kategori Mapping'i Değiştirmeden Etki Analizi Yapın

Örneğin:

Source Category 558

→ yeni target.

Sistem önce göstermeli:

Etkilenecek ürün: 3.481

Aktif ürün: 2.950

Mevcut Trendyol ürün: 2.100

Yeni required attribute eksik: 620

Bu bilgi onay öncesinde değerlidir.

82. Kategori Değişikliği Sonrasında Attribute Coverage Hesaplayın

Yeni hedef kategori:

5 zorunlu özellik

istiyor.

XML ürünlerinin:

%95'inde 5/5,

%4'ünde 4/5,

%1'inde 2/5

var.

Bu sonuç publish readiness için kullanılabilir.

83. %100 Otomasyon Hedefi Koymak Zorunda Değilsiniz

Bazı supplier kategorileri çok temizdir.

Otomatik map yapılabilir.

Bazıları çok genel veya karışıktır.

Manuel inceleme daha güvenli olabilir.

İyi sistem:

neyi otomatik yapmaması gerektiğini de bilir.

84. Kategori Mapping Coverage Ölçün

Örneğin:

Toplam source category → 300

Doğrulanmış mapping → 270

Review → 20

Unmapped → 10

mapping coverage = %90 verified

gibi raporlanabilir.

85. Ürün Bazlı Coverage da Ayrı Hesaplanmalıdır

10 unmapped kategori:

yalnız 15 ürün

etkiliyor olabilir.

Başka tek kategori:

4.000 ürün

etkileyebilir.

Kategori sayısı ve ürün sayısı birlikte raporlanmalıdır.

86. En Çok Ürün Etkileyen Mapping'leri Önce İnceleyin

Örneğin:

Kategori A → 5.000 ürün

Kategori B → 8 ürün

İnsan kontrolü zamanı sınırlıysa önce A doğrulanabilir.

Risk bazlı sıra kullanışlıdır.

87. Satış Hacmi Yüksek Ürünleri Ayrı Önceliklendirin

Bir mapping:

50 ürün

etkiliyor.

Ama bu ürünler toplam satışların:

%40'ını

oluşturuyor.

Sadece ürün adediyle öncelik belirlemek yeterli olmayabilir.

88. Test Ortamı Varsa Kullanın

Trendyol dokümantasyonunda birçok servis için:

PROD

ve:

STAGE

endpoint'leri bulunuyor.

Teknik entegrasyon geliştirmelerinde uygun test ortamı kullanılması canlı katalog riskini azaltabilir.

89. Küçük Batch ile Pilot Yayın Yapın

İlk mapping sonrası:

50 farklı kategori × binlerce ürün

göndermek yerine sınırlı örneklemle:

• categoryId,
• attributes,
• variation,
• onay durumu

kontrol edilebilir.

90. Ürün Onay Sürecini Mapping Kalitesinin Bir Parçası Olarak İzleyin

Trendyol Product V2 dokümantasyonuna göre ürün yaratma isteği başarılı olsa bile ürünler onay sürecine girer ve reddedilen ürünler yayına çıkmaz.

Bu nedenle:

API request accepted

ile:

product published

aynı şey değildir.

91. Kategori Bazlı Red Oranını Hesaplayın

Örneğin:

Kategori A → %1 red

Kategori B → %35 red

Kategori B mapping'i veya attribute mapping'i incelenmelidir.

Bu güçlü operasyon metriğidir.

92. Supplier Bazlı Kategori Başarı Oranı Tutun

Supplier A:

%99 mapped.

Supplier B:

%70 mapped.

Supplier B'nin taxonomy'si daha genel veya daha düzensiz olabilir.

Bu bilgi entegrasyon maliyetini gösterir.

93. Kategori Mapping'i Ürün Fiyat ve Stok Sync'inden Ayırın

Fiyat:

sık değişebilir.

Stok:

çok sık değişebilir.

Kategori:

daha seyrek değişir.

Her stok güncellemesinde kategori mapping'i baştan hesaplamak gereksiz olabilir.

94. Buna Karşılık Kategori Ağacı Güncellemesini İzleyin

Kategori sürekli değişmeyebilir.

Ama Trendyol taxonomy güncellendiğinde mapping doğrulaması çalışmalıdır.

Yani:

low-frequency but high-impact

bir süreç olarak düşünülebilir.

95. Mapping Değişikliğini Normal Stok Güncellemesi Gibi Sessiz Uygulamayın

Stok:

10 → 9

küçük değişikliktir.

Kategori:

Telefon Aksesuarı → Oyuncak

çok daha büyük içerik değişikliğidir.

Bu nedenle onay mekanizması farklı olabilir.

96. Kategori Mapping İçin Ayrı Dashboard Oluşturabilirsiniz

Örneğin:

Mapped categories

Unmapped

Needs review

Stale

Missing required attributes

Trendyol rejected

gibi göstergeler bulunabilir.

97. Trendyol Tarafındaki Kategori Değişimlerini Snapshot Olarak Saklayabilirsiniz

Bugünkü kategori ağacı:

TREE_2026_08_23

gibi saklanabilir.

Yarın bir mapping bozulduğunda eski ve yeni taxonomy karşılaştırılabilir.

98. Attribute Snapshot da Faydalıdır

Kategori ID aynı kalabilir.

Ama zorunlu attribute seti değişebilir.

Eski:

3 required.

Yeni:

4 required.

Bu yüzden yalnız kategori ağacı değil attribute yapısı da izlenebilir.

Trendyol da kategori özelliklerinin yeni alanlarla güncellenebileceğini belirtiyor.

99. Mapping Motorunun Çıktısı Açıklanabilir Olmalıdır

Sistem:

Bu ürün Trendyol Category X'e gitti.

Neden?

Örneğin:

Supplier category exact match

• product type match
• attribute compatibility
• manual verified rule

şeklinde gerekçe görülebilmelidir.

100. İyi Trendyol Kategori Mapping'i “Ürünü Bir Kategoriye Sokmak” Değil, Doğru Trendyol Veri Şemasını Seçmektir

132'nin ana teknik mesajı budur.

Kategori seçildiğinde:

categoryId

değişir.

Ardından:

required attributes

attribute values

variant logic

gibi veri beklentileri de şekillenir.

Bu yüzden kategori mapping:

taxonomy + schema mapping

olarak düşünülmelidir.

TRENDYOL XML KATEGORİ EŞLEŞTİRME KONTROL LİSTESİ

Kaynak kategori

XML'deki orijinal değer saklanıyor mu?

Kategori yolu

Yalnız son isim yerine tam path tutuluyor mu?

Supplier category ID

Varsa ayrı saklanıyor mu?

Normalizasyon

Boşluk, karakter ve kategori yolu kontrollü normalize ediliyor mu?

Trendyol kategori ağacı

Güncel resmî kaynaktan alınıyor mu?

Leaf category

Seçilen hedef gerçekten en alt kategori mi?

Target ID

Trendyol categoryId kayıtlı mı?

Target path

İnsan kontrolü için kategori yolu tutuluyor mu?

Mapping tablosu

Source → target ilişkisi açık mı?

Tedarikçi ayrımı

Farklı XML kaynakları ayrı yönetiliyor mu?

Many-to-one

Kontrollü mü?

One-to-many

Deterministik ürün kuralları var mı?

Confidence

Otomatik mapping için güven seviyesi var mı?

Manual review

Belirsiz kategoriler insan kontrolüne düşüyor mu?

Fallback

Mapping yokken yanlış kategoriye sessizce ürün atılıyor mu?

Yeni kategori

Yeni source kategorileri tespit ediliyor mu?

Kategori özellikleri

Target seçildikten sonra yeniden çekiliyor mu?

Required

Zorunlu özellikler eksik mi?

Attribute mapping

XML alanları Trendyol attribute'larına bağlandı mı?

Value mapping

Kaynak değerler Trendyol değer ID'lerine eşleşiyor mu?

allowCustom

Serbest metin yalnız izin verilen yerde mi kullanılıyor?

Varianter

Kategoriye göre doğru yorumlanıyor mu?

Slicer

Kategoriye göre doğru yorumlanıyor mu?

Varyant ailesi

Aynı ürün ailesi tutarlı mı?

Mapping version

Kurallar versiyonlanıyor mu?

Audit

Kim, ne zaman mapping değiştirdi görülebiliyor mu?

Impact analysis

Değişiklik kaç ürünü etkiliyor?

Dry-run

Canlı göndermeden önce sonuç hesaplanıyor mu?

Distribution

Hedef kategori dağılımında anomali var mı?

Batch result

Trendyol batch sonucu kontrol ediliyor mu?

Failure reason

Ürün bazlı hata sebebi saklanıyor mu?

Onay durumu

Request başarılı olsa bile ürün gerçekten yayınlanmış mı?

V2

Yeni geliştirme Product V2'ye göre mi kuruluyor?

Approved product

Kategori sonradan kolayca değiştirilemeyeceği hesaba katılıyor mu?

Snapshot

Kategori/attribute değişiklikleri izlenebiliyor mu?

TRENDYOL XML KATEGORİ EŞLEŞTİRMESİ NASIL KURULUR? 20 ADIM

1. Tedarikçi XML'indeki kategori alanı, kategori ID'si ve kategori yolunu tespit edin.

2. Orijinal kategori verisini değiştirmeden saklayın.

3. Karşılaştırma için normalize edilmiş kategori anahtarı oluşturun.

4. Güncel Trendyol kategori ağacını resmî servisten alın.

5. Trendyol kategori ağacını ID, parent ve leaf bilgileriyle yerel yapıda saklayın.

6. Her kaynak kategori için aday Trendyol kategorileri oluşturun.

7. Tam kategori yolu, ürün tipi ve ürün özellikleriyle adayları daraltın.

8. Yalnız en alt seviyedeki uygun Trendyol kategorisini hedef olarak kabul edin.

9. Source category → Trendyol categoryId mapping tablosunu oluşturun.

10. Belirsiz mapping'leri otomatik yayın yerine manuel incelemeye gönderin.

11. Seçilen kategori için Trendyol V2 kategori özellik listesini alın.

12. required, allowCustom, varianter, slicer ve ilgili diğer kuralları okuyun.

13. XML alanlarını Trendyol attribute ID'leriyle eşleştirin.

14. Gereken alanlarda XML değerlerini Trendyol attribute value ID'leriyle eşleştirin.

15. Ürün bazında category + required attribute preflight kontrolü çalıştırın.

16. Tüm katalog için dry-run yaparak mapped, review ve unmapped ürünleri raporlayın.

17. Küçük bir ürün grubunu Product V2 üzerinden test edin.

18. Dönen batchRequestId ile item bazlı işlem sonuçlarını ve failureReasons değerlerini kontrol edin.

19. Mapping, kategori ve attribute kurallarını versiyonlayarak değişiklik geçmişini saklayın.

20. Trendyol kategori ağacı veya özellik yapısı güncellendiğinde mevcut mapping'leri yeniden doğrulayın.

SIK SORULAN SORULAR

Trendyol XML kategori eşleştirmesi nedir?

Tedarikçinin XML'de kullandığı kategori bilgisinin, Trendyol'un kategori ağacındaki doğru en alt kategori ve categoryId ile ilişkilendirilmesidir. Bunun ardından ilgili Trendyol kategorisinin beklediği özellik ve özellik değerlerinin de eşleştirilmesi gerekir.

XML'deki kategori adını doğrudan Trendyol'a gönderebilir miyim?

Ürün yaratma tarafında Trendyol kategori bilgisi categoryId üzerinden gönderiliyor. Ayrıca ürün için en alt seviyedeki kategori ID'sinin kullanılması gerekiyor. Bu nedenle tedarikçi kategori metni genellikle önce Trendyol kategori ağacına map edilmelidir.

Trendyol kategori eşleştirmesini bir kez yaptıktan sonra tekrar kontrol etmek gerekir mi?

Evet. Trendyol kategori ağacı ve kategori özelliklerinin güncellenebileceğini açıkça belirtiyor ve güncel kategori/özellik bilgilerinin kullanılmasını öneriyor. Bu nedenle eski mapping'ler düzenli olarak yeniden doğrulanmalıdır.

Doğru kategori seçildiği halde ürün neden reddedilebilir?

Kategori seçimi yalnız adımlardan biridir. Seçilen kategoriye ait zorunlu özellikler, geçerli özellik değerleri, marka, barkod ve diğer Product V2 alanları da doğru olmalıdır. Ayrıca API isteğinin alınmış olması ürünün kesin yayınlandığı anlamına gelmez; batch sonucu ve ürün onay durumu kontrol edilmelidir.

Trendyol'da yanlış kategori sonradan düzeltilebilir mi?

Bu nedenle kategoriyi başta doğru seçmek özellikle önemlidir. Trendyol'un güncel onaylı ürün V2 güncelleme dokümantasyonunda onaylı ürünler için categoryId alanının standart content update ile değiştirilemediği belirtiliyor. Yanlış kategoriyle ürün oluşturup “sonra düzeltirim” yaklaşımı operasyonu zorlaştırabilir.

TRENDYOL XML KATEGORİ EŞLEŞTİRMESİNİN DOĞRU MODELİ

Basit ama riskli yöntem:

XML category = Cezve

↓

Trendyol'da adı Cezveye benzeyen ilk kategori

↓

Ürünü gönder

şeklindedir.

Daha kontrollü model:

Raw supplier category

↓

Supplier category path

↓

Normalized category signature

↓

Güncel Trendyol category tree

↓

Leaf-category candidate list

↓

Ürün tipi / başlık / attribute sinyalleri

↓

Verified Trendyol categoryId

↓

Category Attributes V2

↓

Required attribute kontrolü

↓

Attribute value mapping

↓

Variant/slicer kontrolü

↓

Dry-run

↓

Product V2 create

↓

Batch result

↓

Approval / rejection analysis

↓

Mapping history

şeklinde ilerlemelidir.

Örneğin:

Kaynak XML

Kategori:

Ev > Mutfak > Kahve > Cezveler

Ürün:

Paslanmaz Çelik Cezve 12 No

Materyal:

Çelik

Renk:

Gümüş

Mapping katmanı

Supplier category → doğrulanmış Trendyol leaf category

↓

Trendyol categoryId

↓

Kategori özellikleri çekilir.

Attribute katmanı

XML material = Çelik

↓

Trendyol ilgili Materyal attribute/value

XML color = Gümüş

↓

Trendyol ilgili Renk attribute/value

Validation

Leaf category → doğru

Required fields → tamam

Attribute values → geçerli

↓

READY

Ancak kaynak:

Ev Gereçleri

gibi aşırı genel ise:

AUTO_PUBLISH

yerine:

REVIEW_REQUIRED

sonucu daha güvenli olabilir.

132'nin ana prensibi:

Kategori mapping'in amacı her ürüne mutlaka otomatik kategori vermek değil; yanlış kategoride ürün yayınlanmasını önleyecek kadar güvenilir eşleştirme üretmektir.