Hepsiburada Yorumları Siteye Nasıl Aktarılır? API ve Ürün Eşleştirme Rehberi

Pazaryerinde yıllardır satış yapıyorsanız, elinizde farkında olmadığınız bir varlık birikmiştir: binlerce müşteri değerlendirmesi. Sorun şu ki bu değerlendirmeler Hepsiburada ürün sayfasında durur, kendi sitenizin ürün sayfasında ise sıfır yorum ve sıfır yıldız görünür. Aynı ürünü, aynı kutuyu, aynı kargoyu satıyorsunuz ama kendi sitenize gelen ziyaretçi hiçbir sosyal kanıt görmez. Bu birikimi düşününce akla gelen soru şu: Hepsiburada yorumları siteye nasıl aktarılır?

Bu yazı, Hepsiburada değerlendirmelerini kendi e-ticaret sitenize taşımanın teknik, hukuki ve mimari tarafını uçtan uca anlatıyor. Pazarlama cümleleri yerine gerçek engellere odaklanıyoruz: hangi verinin resmi API ile geldiği, hangisinin gelmediği, ürün eşleştirmenin neden en pahalı kısım olduğu, Trendyol ile Hepsiburada arasındaki somut protokol farkları ve birden fazla pazaryerinden gelen yorumları tek ürün sayfasında dürüstçe birleştirmenin yolu.

Hepsiburada yorumları siteye nasıl aktarılır?

Hepsiburada yorumları siteye üç bileşenli bir akışla aktarılır: pazaryerindeki ürün değerlendirmeleri (yıldız puanı, yorum metni, tarih, varsa satıcı yanıtı) düzenli aralıklarla çekilir, kendi sitenizdeki karşılık gelen ürünle eşleştirilir ve o ürünün sayfasında yayınlanır. Akışın bileşenleri şunlardır:

• Toplama: Verinin pazaryerinden alınması ve kendi veritabanınıza yazılması.
• Eşleştirme: Pazaryeri ürününün, sitenizdeki hangi ürüne ve hangi varyanta karşılık geldiğinin belirlenmesi.
• Gösterim: Yorumların ürün sayfasında, kaynağı belli olacak şekilde ve sayfa hızını bozmadan yayınlanması.

Çoğu ekip birinci adımı sorun sanır. Pratikte projeyi geciktiren neredeyse her zaman ikinci adımdır.

Önce netleştirelim: Hepsiburada satıcı API'sinde ne var, ne yok

Bu konuda dolaşan en büyük yanlış bilgi, Hepsiburada'nın satıcılara hazır bir yorum çekme uç noktası sunduğu iddiasıdır. Resmi geliştirici portalında yayınlanan entegrasyon başlıklarına baktığınızda tablo şudur:

Yani Hepsiburada satıcı API'si üzerinden soru-cevap verisini resmi ve sözleşmeli biçimde alabilirsiniz; ürün yorumlarını aynı yoldan alamazsınız. İlginç olan, Trendyol tarafında da durumun benzer olmasıdır: Trendyol'un satıcı entegrasyon dokümanı soru-cevap servisini belgeler, ürün değerlendirmeleri için satıcıya açık bir entegrasyon uç noktası belgelemez. Piyasadaki yorum modüllerinin neredeyse tamamı bu yüzden değerlendirme verisini satıcı API'sinden değil, ürünün herkese açık pazaryeri sayfasını besleyen veri kaynağından alır.

Bunu bilmek önemli, çünkü mimarinizi, hata toleransınızı ve müşteriye verdiğiniz sözü buna göre kurmanız gerekir. Resmi bir sözleşmeye dayanmayan bir veri kaynağı, sözleşmeli bir uç nokta kadar kararlı değildir; alan adları ve yanıt şemaları haber verilmeden değişebilir. Bu yüzden yorumları çektiğiniz anda kendi veritabanınıza yazın: kaynak bir gün değişse bile yayındaki içerik ayakta kalır.

Hepsiburada satıcı API kimlik doğrulaması nasıl çalışır?

Yorum verisi doğrudan API'den gelmese bile sağlıklı bir eşleştirme için katalog servisine bağlanmanız gerekir: sitenizdeki ürünle pazaryerindeki ürünü ancak SKU ve barkod üzerinden güvenilir biçimde bağlayabilirsiniz. Hepsiburada tarafında kimlik doğrulama şöyle işler.

1. merchantId bir GUID'dir

Trendyol'da satıcı kimliği kısa bir sayıdır (supplierId). Hepsiburada'da ise b2910839-83b9-4d45-adb6-86bad457edcb biçiminde bir GUID'dir. Daha da önemlisi: bu kimlik her serviste aynı yerde durmaz. Katalog, listeleme ve sipariş servislerinde URL yolunun içinde geçer; soru-cevap servisinde ise HTTP başlığı olarak gönderilir. Entegrasyon yazarken bunu tek bir yardımcı fonksiyona sabitlemek yerine servis bazında ayırmak gerekir.

2. Basic auth, iki parçalı

Trendyol'un üç parçalı yapısının (supplierId:apiKey:apiSecret) aksine Hepsiburada klasik iki parçalı Basic auth kullanır: Authorization: Basic base64(kullanici:sifre). Şifre, satıcı panelinden alınan servis anahtarıdır. Kullanıcı adı alanına entegrasyon için tanımlanmış servis kullanıcısı ya da merchantId GUID'i yazılır; hangisinin geçerli olduğu hesabınıza tanımlanan entegratör kaydına göre değişebildiği için ilk denemeyi test ortamında yapmak zaman kazandırır.

3. User-Agent başlığı zorunludur

Bu, entegrasyonu ilk kuran herkesin takıldığı tuzaktır. Hepsiburada servisleri User-Agent başlığını zorunlu tutar ve bu başlığın entegratör kullanıcı adınızı taşıması beklenir. Başlık boşsa ya da kullandığınız HTTP kütüphanesinin varsayılan imzasıysa, kimlik bilgileriniz doğru olsa bile 401 Unauthorized alırsınız. Saatlerce şifre kontrol edip sorunu bulamamanın en yaygın nedeni budur.

4. Her servis ayrı alan adında

Trendyol tek bir API ağ geçidi kullanırken Hepsiburada her servisi ayrı bir alt alan adında sunar: katalog için mpop, fiyat ve stok için listing-external, sipariş için oms-external, soru-cevap için api-asktoseller-merchant. Test (SIT) ortamı, aynı alan adının sonuna -sit eklenmiş halidir; canlıya geçerken tek yaptığınız bu eki kaldırmaktır. Bu yüzden host değerini koda gömmek yerine ortam değişkeninden okumak şart.

5. Accept başlığını unutmayın

Bazı uç noktalar Accept: application/json göndermediğinizde XML döner. JSON bekleyen bir çözümleyiciye XML gelince alacağınız hata, kimlik doğrulama hatasına benzemez ama sizi yine de yanlış yere bakmaya iter.

Yorum verisine ulaşmanın üç yolu ve gerçek maliyetleri

Üçüncü yöntemi kullanacaksanız üç kuralı baştan koyun: düşük eşzamanlılık (paralel istek sayısını tek haneli tutun), 429 ve 5xx yanıtlarında üstel geri çekilme, ve agresif önbellek. Yorumlar dakikada değişen bir veri değildir; günde bir ya da birkaç kez senkron etmek hem yeterli hem sürdürülebilirdir. Ürün başına saatte onlarca istek atan bir kurgu, kısa sürede engellenmenin en hızlı yoludur.

Hepsiburada ile Trendyol arasındaki somut farklar

İki pazaryeri için tek bir entegrasyon katmanı yazacaksanız aşağıdaki farkları arayüz tasarımınıza baştan yansıtın. Yoksa Trendyol için yazdığınız istemciyi Hepsiburada'ya uyarlarken her satırda istisna eklemek zorunda kalırsınız.

Soru-cevap tarafındaki expireDate davranışı, yorum aktarımıyla doğrudan ilgili olmasa da aynı modülü kuruyorsanız kritiktir: süre dolduktan sonra gönderdiğiniz cevap hata döner ve soru otomatik kapanmış statüsüne düşer. Bekleyen soruları sık çekip son tarihe göre sıralamak bu kaybı önler. Ayrıca Hepsiburada'da cevap gönderimi JSON değil multipart/form-data ile yapılır ve ek dosya formatları sınırlıdır; Trendyol istemcinizi kopyalayıp buraya uyarlarsanız ilk hata burada çıkar.

En zor kısım: ürün eşleştirme

Yorum çekmek bir günlük iştir; doğru ürüne bağlamak haftalarca sürebilir. Karşılaşacağınız tipik durumlar şunlardır.

Aynı ürün sayfası, birden fazla satıcı

Hepsiburada'da (Trendyol'da da) değerlendirmeler çoğu zaman ürüne aittir, satıcıya değil. Buybox mantığıyla aynı ürün sayfasında birden fazla satıcı bulunabilir. Bu, sayfadaki yorumların bir kısmının sizin gönderdiğiniz siparişlere değil, başka bir satıcının teslimatına ait olabileceği anlamına gelir. Kargo hızı ya da paketleme hakkındaki bir şikayeti kendi sitenize taşırken bunu bilmek gerekir. Sağlıklı yaklaşım: ürün özelliğine dair yorumları taşımak, teslimat ve satıcı deneyimine dair olanları filtrelenebilir tutmaktır.

Varyant dağınıklığı

Pazaryerinde her renk ve beden ayrı bir listing olabilirken sitenizde tek üründe varyant olarak durur; ya da tam tersi. Karar vermeniz gereken şey şudur: yorumlar varyant düzeyinde mi, ürün düzeyinde mi toplanacak? Çoğu mağaza için doğru cevap ürün düzeyinde toplamak, varyant bilgisini yorumun içinde etiket olarak göstermektir. Böylece yeni çıkardığınız bir renk sıfır yorumla kalmaz, ama okuyucu yorumun hangi varyant için yazıldığını görür.

Eşleştirme öncelik sırası

1. Barkod / GTIN: En güvenilir anahtar. İki tarafta da doluysa doğrudan kullanın.
2. merchantSku: Sizin kendi stok kodunuz olduğu için genelde sitenizdeki SKU ile birebir eşleşir.
3. hbSku: Hepsiburada'nın kendi ürün kodu. Kalıcıdır, ancak sitenizde karşılığı yoktur; eşleştirmeyi kurduktan sonra kayıt anahtarı olarak saklayın.
4. İsim benzerliği: Son çare. Otomatik uygulamayın; öneri listesi çıkarıp panelde onaya düşürün.

Eşleştirme tablosunu ayrı tutun ve manuel düzeltmeyi mümkün kılın. Otomatik eşleşme oranı hiçbir zaman yüzde yüz olmaz; kalan kuyruğu bir insanın yirmi dakikada temizleyebileceği bir ekran, aylarca sürecek bir algoritma çalışmasından daha değerlidir.

Çoklu pazaryerinden gelen yorumları tek üründe birleştirme

Hem Hepsiburada hem Trendyol'da satış yapıyorsanız aynı ürünün sitenizdeki sayfasında iki kaynaktan yorum toplanır. Burada iyi bir tasarım, kötü bir tasarımdan çok daha fazla iş görür.

1. Kanonik ürün kimliği kullanın

Yorumları doğrudan ürün sayfasına bağlamayın. Araya bir kanonik ürün katmanı koyun: sitenizdeki ürün kimliği ana anahtar olsun, her pazaryeri listeleme kaydı bu anahtara bağlansın. Yarın Pazarama, Koçtaş ya da Amazon eklediğinizde tek yapacağınız yeni bir kaynak satırı eklemektir; gösterim katmanına hiç dokunmazsınız.

2. Kaynak rozetini her yorumda gösterin

Bu, hem güven hem mevzuat açısından en önemli maddedir. Her yorumun yanında Hepsiburada değerlendirmesi ya da Trendyol değerlendirmesi etiketi görünmelidir. Kaynağı gizlemek kısa vadede daha derli toplu bir tasarım verir, uzun vadede güveni yok eder: ziyaretçi aynı yorumu pazaryerinde görüp sizde farklı bir bağlamda bulduğunda ne düşüneceğini tahmin edin. Rozet ayrıca ziyaretçiye şunu söyler: bu yorumları ben yazmadım, doğrulanmış alışverişlerin yapıldığı bir platformdan geldiler.

3. Ortalama puanı ağırlıklı hesaplayın

İki kaynağın ortalamasının ortalamasını almak yaygın bir hatadır. Doğrusu, toplam puanı toplam yorum sayısına bölmektir:

Basit ortalama alsaydınız 4,45 çıkardı; doğru sonuç 4,6'dır. Ölçekler her iki pazaryerinde de beş üzerinden olduğu için dönüştürme gerekmez, ama farklı ölçek kullanan bir kaynak eklerseniz normalizasyonu veritabanına yazarken yapın, gösterim anında değil.

4. Tekrarları ayıklayın

Aynı müşteri aynı ürünü iki pazaryerinden almışsa iki ayrı yorum yazmış olabilir; bu meşru bir durumdur ve silmeniz gerekmez. Asıl temizlemeniz gereken şey aynı kaynaktan gelen mükerrer kayıtlardır: senkron tekrar çalıştığında aynı yorumu ikinci kez eklememek için kaynak ve yorum kimliği ikilisine benzersiz kısıt koyun. Yorum kimliği gelmiyorsa metin, tarih ve puan üçlüsünün karmasını (hash) anahtar olarak kullanın.

5. Sıralama ve filtreyi ziyaretçiye bırakın

Varsayılan sıralama en yeni yorum olsun. Kaynağa göre filtre, yıldıza göre filtre ve varyant filtresi sunun. Sadece beş yıldızlıları göstermek gibi bir kurgu dönüşümü artırmaz; deneyimli alışveriş yapan kullanıcı 4,9 ortalamalı ve tek tip yorumlu sayfaya güvenmez, olumsuz yorumların nasıl karşılandığına bakar.

6. Satıcı yanıtlarını da taşıyın

Olumsuz bir yoruma verdiğiniz makul bir yanıt, olumlu on yorumdan daha ikna edicidir. Pazaryerinde yanıtladığınız değerlendirmeleri yanıtıyla birlikte aktarın ve yanıtı görsel olarak ayırın.

7. Yorumsuz ürünler için dürüst bir boşluk bırakın

Eşleşmeyen ya da hiç yorumu olmayan ürünlerde blok tamamen gizlensin. Kategori ortalamasını ürün sayfasında gösterip yıldız izlenimi yaratmak, hem tüketici mevzuatı hem güven açısından risklidir.

Şeffaflık, KVKK ve mevzuat tarafı

Bu bölüm benzer içeriklerin çoğunda hiç yok; oysa bir denetimde ilk sorulacak yer burasıdır.

• Seçici gösterim riski: Ticari Reklam ve Haksız Ticari Uygulamalar Yönetmeliği, tüketici değerlendirmelerinin sunumuna ilişkin hükümler içerir. Yalnızca olumlu yorumları yayınlayıp olumsuzları gizlemek yanıltıcı ticari uygulama olarak değerlendirilebilir. Filtreleme yapacaksanız küfür, spam ve kişisel veri temizliği gibi tarafsız kriterlerle yapın ve bu kriteri sayfada açıklayın.
• Kaynak belirtme: Yorumun nereden geldiğini ve hangi tarihte alındığını gösterin. Bu hem şeffaflık hem de içeriğin size ait olmadığını ortaya koyan bir atıftır.
• KVKK: Yorum metni kişisel veri içerebilir. Müşteri adını tam yazmayın; pazaryerinde kısaltılmış geliyorsa aynı kısaltmayı koruyun. Sipariş numarası, telefon ve adres gibi bilgiler yanlışlıkla yorum metnine yazılmışsa senkron sırasında maskeleyin. İhtiyacınız olmayan müşteri kimliği alanlarını veritabanınıza hiç almayın.
• Metni değiştirmeyin: Yorumu düzeltmek, kısaltmak ya da olumlu hale getirmek hem etik hem hukuki olarak sorunludur. Yalnızca maskeleme ve zararlı içerik temizliği yapın.
• Kullanım koşulları: Pazaryeri verisini otomatik toplarken ilgili platformun kullanım koşullarını gözden geçirin. Kendi mağazanıza ait değerlendirmeleri kendi vitrininizde göstermek makul bir kullanım olsa da hacim ve yöntem burada belirleyicidir.

SEO tarafı: yıldızlı snippet beklentisini doğru kurun

Yorum modülü satan pek çok sayfa şunu vaat eder: Google sonuçlarında yıldız kazanın. Burada dikkatli olmak gerekir. Google'ın değerlendirme snippet'i (Review ve AggregateRating) yapılandırılmış veri politikası, başka sitelerden toplanan yorum ve puanların işaretlenmemesi gerektiğini açıkça söyler. Yani Hepsiburada'dan aldığınız iki yüz yorumu kendi ürününüzün AggregateRating işaretlemesine dahil etmek politikayla çelişir ve zengin sonuç kaybına ya da manuel işleme yol açabilir.

Doğru kurgu şudur:

1. Pazaryeri yorumlarını sayfada gösterin. Bu tamamen serbesttir ve dönüşüme birebir etki eder.
2. Bu yorumları Review ve AggregateRating yapılandırılmış verisine dahil etmeyin; kaynak rozetiyle ayrı bir blokta sunun.
3. Kendi sitenizde doğrulanmış müşteri yorumu toplamaya ayrıca başlayın ve yalnızca onları işaretleyin. Pazaryeri yorumları zaten sayfa içeriğini zenginleştirdiği ve uzun kuyruk aramalarına doğal metin kazandırdığı için SEO faydasını yıldız olmadan da sağlar.

İkinci teknik nokta: yorumlar sayfaya sonradan JavaScript ile yükleniyorsa arama motorları ve AI tarayıcıları çoğu zaman o içeriği görmez. En azından ilk beş-on yorumu sunucu tarafında HTML içine basın, kalanını daha fazla göster düğmesiyle yükleyin. Bu aynı zamanda Largest Contentful Paint metriğinizi korur; onlarca yorumu tek seferde basmak mobil skorunuzu düşürür.

Hepsiburada yorumları siteye nasıl aktarılır: adım adım kontrol listesi

1. Satıcı panelinde entegratör bilgileri bölümünden servis anahtarınızı ve merchantId GUID'inizi alın.
2. Önce SIT (test) ortamına bağlanın; alan adının -sit ekli sürümünü kullanın.
3. İlk isteği katalog servisine atın ve User-Agent ile Accept başlıklarının doğru gittiğini doğrulayın.
4. Mağazanızın tüm ürünlerini sayfalama ile (offset ve limit) çekip yerel bir tabloya yazın.
5. Barkod ve merchantSku üzerinden sitenizdeki ürünlerle eşleştirme tablosunu üretin; eşleşmeyenleri manuel onay kuyruğuna alın.
6. Değerlendirme toplama işini günlük bir zamanlanmış görev olarak kurun; artımlı çalışsın, son çekim tarihinden sonrasını alsın.
7. Kaynak ve yorum kimliği üzerine benzersiz kısıt koyarak mükerrer kaydı engelleyin.
8. Kişisel veri maskelemesini ve spam filtresini kayıt anında uygulayın, gösterim anında değil.
9. Ürün sayfasına yorum bloğunu ekleyin: kaynak rozeti, yıldız dağılımı, filtre, sayfalama ve satıcı yanıtı.
10. Yapılandırılmış veriyi yalnızca kendi topladığınız yorumlar için üretin; pazaryeri yorumlarını kapsam dışında bırakın.

Sık karşılaşılan hatalar ve anlamları

• 401 Unauthorized: Çoğunlukla şifre değil, eksik ya da yanlış User-Agent. Ayrıca her servis aynı kullanıcıyı kabul etmeyebilir; servis bazlı kimlik farkını kontrol edin.
• Yanıt XML geldi: Accept: application/json göndermemişsiniz.
• 400 Bad Request: Sayfalama parametrelerini karıştırmış olabilirsiniz; katalogda offset ve limit, soru-cevapta page ve size beklenir.
• 404 Not Found: merchantId'yi başlık yerine URL yoluna (ya da tersi) koymuş olabilirsiniz.
• 415 veya 422: Soru cevaplarken gönderdiğiniz dosya tipi desteklenmiyor. İzin verilen formatlar sınırlıdır: jpg, png, bmp, pdf, docx, xlsx.
• 429 veya 5xx: Hız sınırına takıldınız. Eşzamanlılığı düşürün, üstel geri çekilme uygulayın, işi gece saatlerine yayın.
• Yorumlar geldi ama yanlış üründe: Neredeyse her zaman isim benzerliğiyle otomatik eşleştirme yapılmış demektir. Bu eşleşmeleri geri alıp manuel onaya çevirin.

Altyapıya göre uygulama notları

Yorum bloğunu sitenize eklerken kullandığınız altyapı mimariyi değiştirir:

• Shopify: Yorumları metafield olarak saklamak küçük hacimlerde işe yarar, ama binlerce yorumda sınırlara ve yönetim zorluğuna takılırsınız. Daha sağlıklısı verinin kendi sunucunuzda durması ve tema tarafında bir bölüm ile çekilmesidir. İlk yorumların sunucu tarafında basılabilmesi için app proxy kullanımı SEO açısından avantajlıdır.
• Ikas: Tema tarafına eklenen bir blok ile gösterim yapılır; ürün eşleştirmesinde ikas ürün kimliğini kanonik anahtar olarak kullanmak en temizidir.
• Ticimax ve T-Soft: Ürün sayfası şablonuna eklenen bir alan üzerinden çalışır; her iki altyapıda da yorumları sayfa yüklenirken sunucu tarafında basabilmek için şablon düzenleme yetkisine ihtiyacınız olur.

Hangi altyapıda olursanız olun ortak kural aynıdır: veri sizin veritabanınızda dursun, tema yalnızca göstersin. Böylece pazaryeri tarafındaki bir değişiklik sitenizi kırmaz, sadece senkronu durdurur ve elinizdeki yorumlar yayında kalır.

STools tarafında nasıl çözüyoruz

Yukarıdaki mimariyi her mağaza için sıfırdan kurmak yerine hazır bir modül tercih ediyorsanız, Hepsiburada Yorum Modülü katalog eşleştirmesi, artımlı senkron, kaynak rozetiyle gösterim ve kişisel veri maskeleme adımlarını paket halinde sunar. Aynı ürün sayfasında Trendyol değerlendirmelerini de birleştirmek isteyenler için Trendyol Yorum Modülü aynı kanonik ürün katmanını paylaşır; iki kaynak tek ortalamada ağırlıklı olarak toplanır ve her yorum kendi rozetiyle görünür. Modüller Shopify, Ikas, Ticimax ve T-Soft altyapılarıyla çalışır.

Özet

Hepsiburada değerlendirmelerini kendi ürün sayfalarınıza taşıma projesinde başarı, veriyi çekebilmekten çok üç karara bağlıdır: ürünü doğru eşleştirmek, kaynağı şeffaf göstermek ve yapılandırılmış veri sınırını doğru çizmek. Bu üçünü baştan doğru kurarsanız pazaryerinde yıllardır biriken sosyal kanıtı kendi vitrininize taşımış olursunuz; yanlış kurarsanız hem güven hem arama görünürlüğü tarafında geri adım atarsınız. Kurulum sırasında takıldığınız bir nokta olursa destek@stools.digital adresinden yazabilirsiniz.