Hepsiburada Entegrasyon: Katalog, Listeleme, Sipariş ve Fatura

Hepsiburada entegrasyonu, mağazanızın ürün, stok, fiyat, sipariş ve muhasebe verisini satıcı panelinde elle girmek yerine web servis (API) üzerinden kendi sisteminizle otomatik alıp vermesidir. Hepsiburada'nın entegrasyon belgesi bu işi dört modele ayırır: katalog ürün, listeleme, sipariş ve muhasebe entegrasyonu. Bağlantı, bir entegratör firmaya satıcı panelinden yetki verilerek ya da kendi yazılımınızla, önce test ortamında denenerek kurulur. Sonucu belirleyen, Hepsiburada'ya özgü üç noktadır: ürünün katalogda hangi statüde olduğu, fiyatın eşik kontrolüne takılıp takılmadığı ve otomatik paketleme ayarının entegrasyonun çektiği siparişlerle uyumu.

Model	Aktardığı Veri	Ne İşe Yarar
Katalog Ürün Entegrasyonu	Ürün adı, açıklama, görsel, kategori ve özellikler	Ürünleri toplu olarak Hepsiburada sistemine gönderir
Listeleme Entegrasyonu	Stok, fiyat, kargoya veriliş süresi ve kargo firması	Ürünün mağazanızdaki satış kaydını günceller
Sipariş Entegrasyonu	Ödemesi tamamlanmış siparişler, paketler ve fatura bilgisi	Siparişleri kendi sisteminizde görüp takip etmenizi sağlar
Muhasebe Entegrasyonu	Satış tutarı, işlem bedelleri ve ödeme durumu	Teslim edilen siparişlerin finansal kayıtlarını çeker

Hepsiburada entegrasyonunun dört modeli

Hepsiburada'nın entegrasyon belgesine göre entegrasyon, ürün verisinin otomatik aktarım sistemidir: stok, fiyat ve kargoya veriliş süresi bir kez bağlandıktan sonra web servis üzerinden kendiliğinden güncellenir. Belge, listeleme ve sipariş entegrasyonunun birlikte kullanılabileceğini yazar. Pazaryeri entegrasyonunun genel tanımı sözlükte; bu yazı Hepsiburada'nın kendi belgelerinin anlattığı işleyişi özetler.

Hepsiburada Entegrasyon Portalı'nda dört modelin yanında kampanya ve promosyon, kargo, Hepsiburada'nın kendi fatura hizmeti E-Faturam, müşteri soruları için "Satıcıya Sor", müşteri talepleri ve tedarikçi bölümleri de bulunur. Portal sayfaları zaman içinde güncellenir; bağlantıyı kurmadan ve değiştirmeden önce ilgili bölümün portaldaki güncel anlatımını okuyun.

Hangi modelleri kuracağınız, her verinin hangi sistemde ana kayıt olarak tutulduğuna bağlıdır. Ürün bilgisi e-ticaret sitenizde, stok depo ya da muhasebe programınızda tutuluyorsa her verinin hangi yönde ve hangi sistemden aktarılacağı bağlantıdan önce belirlenir. Muhasebe tarafının genel anlatımı e-ticaret muhasebe entegrasyonu yazısındadır.

Entegratör yetkisi ve kendi yazılımınızla bağlantı

Hepsiburada'ya iki yoldan bağlanılır: bir entegratör firma aracılığıyla ya da mağazanın kendi entegrasyon yazılımıyla. Entegratörle çalışıyorsanız yetkiyi satıcı panelinden siz verirsiniz. Entegratörün Hepsiburada'da kullandığı geliştirici kullanıcı bilgisi entegratörden öğrenilir ve entegratör bu bilgiyle eklenir; yetki silinebilir, yeniden eklenebilir ve belirli bir tarih aralığıyla süreli verilebilir. Mağaza ID bilgisi de entegratörle paylaşılır.

Yetkinin devreye girmesi yaklaşık iki saat sürer; ilk denemede "geçersiz" uyarısı gelirse bir süre sonra yeniden denenir. Siparişler entegratörün ekranında görünmüyorsa ilk bakılacak yer, satıcı panelinde bu yetkinin tanımlı olmasıdır.

Entegratörün kullandığı servis anahtarı satıcı panelinde entegratör bazında görüntülenir ve entegratörün ekranına girilir. Yeni bir anahtar oluşturursanız eski anahtar entegratörün ekranında kalır; anahtarın orada da güncellenmesi gerekir. Portal, servislerin kimlik doğrulama yapısının değiştiğini katalog, listeleme, sipariş, talep ve muhasebe sayfalarında ayrıca duyurur. API anahtarı bir paroladır; e-postayla dolaştırılmaz, yalnızca bağlantıyı kuran ekrana girilir.

Kendi yazılımını yapacak mağaza satıcı panelinden destek kaydı açar. Önce test ortamı bilgileri iletilir; test adımları başarıyla tamamlanınca canlı ortam bilgileri için yeniden kayıt açılır. Entegrasyonla ilgili teknik sorular da satıcı panelindeki Destek Merkezi'nde entegrasyon başlığıyla açılan kayıtla sorulur ve kayıtlar aynı yerden izlenir.

Test ortamından canlı mağazaya geçiş

Hepsiburada'nın test ortamına e-postayla iletilen kullanıcı adı ve parolayla girilir. Test için sipariş oluşturma yalnızca test ortamında vardır; canlı mağazada siparişler müşteriden gelir. Bu yüzden sipariş aktarımı, paketleme ve fatura gönderimi canlıya geçmeden önce test siparişleriyle denenir.

Belge önemli bir farkı ayrıca yazar: test ortamının kategori ağacı canlı ortamla birebir aynı değildir ve canlıya geçince kategori ağacının yeniden listelenmesi gerekir. Testte yapılan kategori eşleştirmesi canlıda kontrol edilmeden ürün gönderilirse kategori uyarısıyla karşılaşılabilir.

Siparişlerin sizin sisteminize bildirimle gelmesini istiyorsanız Hepsiburada'nın webhook modeli kullanılır. Bu modelde mağaza, belgedeki sözleşmeye uygun kendi servisini geliştirir ve servisin temel adresini Hepsiburada'ya iletir. Önce canlı olmayan bir test servisiyle denenir, testte süreç tamamlanmadan canlıda işlem yapılmaz; güvenlik kullanıcı adı ve parolayla sağlanır. Kendi API çağrılarınızla yaptığınız işlemler webhook ile size geri gönderilmez; bu işlemlerin kaydını sisteminizin ayrıca tutması gerekir.

Kategori, özellik ve değer eşleştirmesi

Hepsiburada'da kategori, ürün açmak için zorunludur ve ürünün veri modelini belirler: ürünün hangi özellikleri taşıyacağı tamamen kategoriye bağlıdır. Ürün yalnızca en alt düzeydeki (uç), aktif ve kullanıma açık kategorilerin altına açılır. Bir üst kategoriye ya da aktif olmayan kategoriye gönderilen ürün "Category is not a leaf category and is not an available category" uyarısı alır; çözüm, aktif kategorileri yeniden listeleyip uygun uç kategoriyi seçmektir.

Kategorinin özelliklerinden zorunlu olarak işaretlenenlerin hepsi gönderilir. Zorunlu olmayan özellikleri de eşleştirip göndermek, belgeye göre ürünün açılması ve aramalarda çıkması için önemlidir. Liste türündeki (enum) özelliklerde Hepsiburada'nın değer listesindeki karşılık önceliklidir; listede uygun değer yoksa kendi değeriniz metin olarak eklenebilir.

Özellik değerleri de kategoriye bağlıdır: aynı özelliğin, örneğin rengin, değer listesi iki kategoride farklı gelebilir. Bir kategoride kurduğunuz renk ya da beden eşleştirmesini başka bir kategoriye kopyalamadan önce o kategorinin listesiyle karşılaştırın. Ürünlerin barkodu da bu aşamada denetlenir; aynı barkodun iki ayrı üründe kullanılması sık görülen yükleme uyarılarındandır.

Ürün statüleri ve eşleşen ürün onayı

Ürün bilgisi gönderildiğinde bir takip kodu döner ve ürünün sonucu bu kodla ürün durumu sorgusundan okunur; hata ve uyarılar da orada görünür. Ürün, Hepsiburada'da şu statülerden birinde bulunur:

Statü	Anlamı	Mağazanın Yapabileceği
İncelenecek	Ürün giriş ekibinin kontrolü bekleniyor	Sonucu ürün durumu sorgusundan izler
Ürün Bilgileri Eksik	Eksik alanlar durum sorgusunda listelenir	Eksikleri API ile günceller
Katalog Sürecinde	Ürünü ürün giriş ekibi giriyor	API ile güncelleme gönderemez
Eşleşen	Ürün Hepsiburada kataloğunda zaten bulunuyor	Eşleşmeyi onaylar ya da reddeder; karardan önce güncelleme gönderebilir
Satışa Hazır	Ürün kataloğa eklendi, mağaza için listing oluştu	API ile ürün güncellemesi gönderemez; fiyat ve stok gönderir
Reddedildi	Satışı izne bağlı ya da internette tamamen yasak ürün	İzne bağlı üründe önce satış izni gerekir

Eşleşen statüsü Hepsiburada'nın katalog yapısından gelir: gönderdiğiniz ürün katalogda zaten varsa karar mağazaya kalır. Eşleşme satıcı panelinden ya da API ile onaylanır ya da reddedilir. Onaylamadan önce katalogdaki ürünün marka, model ve varyant bilgisinin sizin ürününüzle gerçekten aynı olduğunu kontrol edin; farklı bir ürüne bağlanan kayıt, müşterinin gördüğü sayfayla sizin gönderdiğiniz ürünü ayırır.

Ürün güncellemesinde ürün adı, açıklama, görseller, video, özellikler, KDV, garanti süresi, desi, özelleştirilebilirlik ve barkod değiştirilebilir; Hepsiburada stok kodu değiştirilemez. Mevcut bir görseli değiştirmek için aynı adres üzerinden güncelleme yapılmaz, yeni görsel yeni bir adresle gönderilir. Kabul edildiği hâlde satışta görünmeyen ürünün ayrıntılı kontrolü Hepsiburada ürünü kabul edildi ama satışta yok maddesindedir.

Ürün yüklemesi ile satışa açılma arasındaki fark

Hepsiburada'da ürün yüklemek ürünü doğrudan satışa açmaz. Yeni ürün girişleri ürün giriş ekiplerince kontrol edilip onaylanır ve satışa hazır duruma gelir. Satışa hazır listingler envanter alanında görünür; ürünü satışa açmak için fiyat ve stok gönderilir. Katalog entegrasyonu çalışıyor diye ürünlerin satıldığını varsaymayın: katalog ve listeleme iki ayrı aşamadır.

Listing, ürünün mağazanızdaki satış kaydıdır. Kayıtta Hepsiburada stok kodu, mağaza stok kodu (SKU), fiyat, stok, kargoya veriliş süresi, en çok üç kargo firması, teslimat profili adı ve iade ile talepler için adres satırı bulunur. Mağaza stok kodu, sizin sisteminizdeki ürünle Hepsiburada'daki kaydı bağlayan alandır; iki üründe aynı kodun kullanılması mükerrer stok kodu uyarısına yol açar.

Bir listingi satışa kapatmak için stok ya da fiyat sıfır gönderilir; yeniden açmak için ikisi de sıfırdan farklı gönderilir. Fiyatı ve stoğu olduğu hâlde satışa kapatılmış bir ürün, satışa açma servisiyle ya da fiyat ve stok yeniden gönderilerek açılır.

Stok, fiyat ve kargoya veriliş süresinin güncellenmesi

Listing güncellemesi gönderildiğinde bir işlem kimliği döner; güncellemenin uygulanıp uygulanmadığı ve varsa uyarılar bu kimlikle sorgulanır. İstek hatalı ya da eksikse kimlik dönmez, hata yanıtın kendisinde görünür. Ayrıntı gerekirse yanıt başlığındaki istek kimliğiyle ("x-correlation-id") satıcı destek panelinden kayıt açılarak isteğin durumu sorgulatılır. Entegrasyon ekranınız yalnızca "gönderildi" bilgisini değil, sorgunun sonucunu da göstermelidir.

Yalnızca stok ya da yalnızca fiyat değişiyorsa belge ayrı stok ve fiyat servislerini kullanmayı önerir: bu servisler daha hızlı işlenir ve kampanya kısıtlarına takılmaz. Genel envanter güncellemesi stok ve fiyat dışındaki alanlar için önerilir. Listeleme entegrasyonu ayrıca listingleri anlık verileriyle listeleme, silme, aktif ve pasif yapma ile kilit kaldırma işlerini kapsar.

Aynı anda bekleyen işlem sayısının ve tek istekte gönderilebilecek SKU sayısının üst sınırları vardır; sınır aşıldığında "exceeds his inventory upload limit" uyarısı gelir. Belge, sınıra takılmamak için tek seferde güncellenen SKU sayısını artırmayı önerir; yani çok sayıda küçük istek yerine daha az sayıda toplu istek. Sınırların güncel değerini portalın listeleme bölümünden okuyun.

Kargo firması adları belgedeki yazım biçimiyle gönderilir. Yalnızca HepsiJET seçilirse yanında standart bir kargo firması da seçilmelidir. Teslimat profili, satıcı panelinde oluşturulan profilin SKU'ya tanımlanmasıdır ve siparişte hangi kargo firmasının kullanılacağını belirler. Teslimat profili, gönderim süresi ve kargo değişikliği Hepsiburada kargo yazısında anlatılır.

Fiyat kilidi ve kampanya kısıtları

Hepsiburada, yanlış fiyatlandırmaya karşı kategori bazlı eşik değerleriyle kontrol yapar. Fiyat artışı ya da düşüşü eşiğin dışında kalırsa ilgili SKU kilitlenir: yüksek fiyatta "MaxLock", düşük fiyatta "MinLock" görünür ve açıklama, yapılan değişimin platform genelindeki fiyat aralıklarının dışında olduğunu söyler. Fiyattan eminseniz kilit, kilit kaldırma servisiyle ya da satıcı panelindeki Envanter ekranından toplu olarak kaldırılır; değilseniz önerilen aralıkta yeni fiyat girilir.

Eski "OutOfPriceRange" uyarısı da aynı korumayı anlatır; belge bu kontrolü genel kural olarak yazar ve kaldırılamayacağını belirtir. Kilit uyarısı geldiğinde önce entegrasyonun fiyatı hangi alandan aldığına bakın: KDV hariç tutarın, eski bir fiyat listesinin ya da hatalı ondalık biçiminin gönderilmesi eşik dışı fiyat üretir. Fiyatın noktayla yazılması ayrıca "InvalidPrice" uyarısı verir.

Kampanyaya giren üründe ek kısıtlar olabilir. İndirim süresince geçerli fiyatın üstüne çıkılmak istenirse "DiscountedListingPriceIncrease", stok düşürülmek istenirse "DiscountedListingStockDecrease" uyarısı gelir; bu durumda kategori yöneticisiyle görüşülür. Entegrasyonunuz fiyatı ya da stoğu otomatik kurallarla değiştiriyorsa kampanyadaki ürünlerde bu kuralların neye yol açacağını kampanyaya girmeden önce kontrol edin.

Siparişlerin çekilmesi ve otomatik paketleme

API'ye yalnızca ödemesi tamamlanmış siparişler gelir; bunlar satıcı panelinde "Paketlenecekler" olarak görünür. Havaleli siparişlerin ön bilgileri ayrı bir servisle alınıp stok ayrılabilir; havalenin ödemesi tamamlanınca sipariş hemen API'ye düşer.

Paketlemenin iki yöntemi vardır. Hepsiburada'nın otomatik paketlemesi siparişi geldikten sonra 15 dakika içinde paketler; belge, stok bitme ihtimali yoksa bu yapıyı önerir. API ile paketlemede aynı pakete konabilecek kalemler listelenir ve paketlemeyi mağazanın sistemi yapar; stok bitme ihtimali olan mağaza bu yapıyı kullanır. Test ortamında iki yöntem de denenebilir; hangisiyle çalışılacağı canlıya geçmeden belirlenir.

Otomatik paketleme ayarı ile entegrasyonun çektiği sipariş verisi uyumlu olmalıdır. Ayar kapalıysa entegrasyon ödemesi tamamlanmış siparişleri çeker ve paketleme adımını mağaza ya da entegratör yapar; açıksa entegrasyon paket bilgilerini çeker. Ayar ile entegratörün kurgusu birbirini tutmazsa siparişler entegratörün ekranına düşmeyebilir; bu durumda yetkiyle birlikte bu ayara da bakın.

Sipariş kaleminde son teslim tarihi, durum, KDV, teslimat adresi ve fatura bilgileri bulunur; fatura bu alandaki T.C. kimlik numarası, vergi numarası ve vergi dairesi ile adrese göre oluşturulur. Bir siparişteki sipariş, kalem ve paket numaralarının nasıl eşleştirileceği Hepsiburada sipariş, kalem ve paket kimlikleri maddesinde, paketlendikten sonra yapılabilecek işlemler Hepsiburada paketleme sonrası işlem durumu maddesinde anlatılır.

Fatura, muhasebe kayıtları ve müşteri talepleri

Sipariş faturası, pdf biçiminde ve .pdf uzantılı bir http adresi olarak paket bazında Hepsiburada'ya iletilir; fatura müşteriye gönderilir ve satıcı paneline aktarılır. Faturanın oluştuğu hâlde müşteriye ulaşmadığı durumun kontrolü Hepsiburada faturası müşteriye ulaşmıyor maddesindedir.

Hepsiburada'nın kendi fatura hizmeti E-Faturam'ın da entegrasyon servisleri vardır: fatura gönderme, taslak, iptal ile gelen ve giden kutusu sorguları. Gönderimde alıcı e-Fatura mükellefiyse fatura e-Fatura olarak iletilir, değilse e-Arşiv fatura olarak oluşur.

Muhasebe entegrasyonu finansal kayıtları çeker. Kayıtlar sipariş teslim edildikten sonra oluşur; bu yüzden henüz teslim edilmemiş siparişin finansal kaydı bu servisten gelmez. Kayıtlarda satış tutarı, teslimat başına işlem bedeli ve bunların iadesi gibi kayıt tipleri, ödendi ya da ödenecek bilgisi, kaydın fatura olup olmadığı ve gelir mi gider mi olduğu yer alır. Kayıtlar tarih aralığıyla ya da sipariş, paket, SKU veya fatura numarasıyla sorgulanır.

Talep servisleri iade, eksik parça, eksik ürün, hasarlı ya da yanlış ürün, teslim edilmeyen ürün ve eksik fatura gibi müşteri taleplerini entegrasyonla alıp kabul ya da ret yanıtı vermeyi sağlar. Eksik fatura talebi entegrasyonla iletilir; ancak kabul için fatura yüklemek gerektiğinden belgeye göre kabul satıcı panelinden yapılır.

Hepsiburada entegrasyonunda sık görülen uyarılar

Hepsiburada'nın entegrasyon belgesi ve sık sorulan soruları, satıcıların en çok karşılaştığı uyarıları adlarıyla verir. Uyarının adı, sorunun katalogda mı, listingde mi yoksa kargo tanımında mı olduğunu gösterir:

Durum	Uyarı	Neye Bakılır
Mükerrer Barkod	Barcode must be unique barcode	Barkod önceki bir yüklemede başka bir üründe kullanılmış
Önceden Yüklenmiş Ürün	Can not update product in matched or in catalog progress status	Barkod mağazaya daha önce yüklenmiş; ürün eşleşen ya da katalog sürecinde
Marka Kısıtı	restrictedProductBrand	Üründe marka kısıtı var; kategori yöneticisiyle görüşülür
Mükerrer Listing	MerchantAlreadyListedAgainstProduct	Ürün mükerrer yaratılmış; askıdaki ürünün silinmesi gerekir
Yeni Silinmiş Listing	ListingDeletedRecently	Güncelleme yakın zamanda silinmiş bir listinge gönderilmiş
Dondurulmuş Listing	ListingFrozen	Güncelleme dondurulmuş bir listinge gönderilmiş
Eksik Standart Kargo	MissingStandardCargoCompany	Yalnızca HepsiJET seçilmiş; yanına standart bir kargo firması eklenir
Teslimat Tanımı	Delivery manipulation	Kendi anlaşmalı kargosuyla çıkan ya da dijital kod satan mağaza için tanımlama gerekir

Satıcı panelinde görünmeyen bir ürün önce "Aksiyon Bekleyen Ürünler" alanında barkodla aranır; barkodla bulunamazsa yükleme sonucunda dönen takip koduyla uyarı sorgulatılır. Uyarının nedeni giderilmeden aynı isteği yeniden göndermek sonucu değiştirmez ve bekleyen işlem sayısını artırır. Kategori yöneticisine yönlendiren uyarılarda (marka kısıtı, kampanya kısıtı, kendi kargo anlaşması) çözüm entegrasyon ekranında değil, Hepsiburada'yla yapılan görüşmededir.

Uzman desteği gerektiren durumlar

Ürün sayısı kalabalık, kategori ve özellik eşleştirmesi uzun ya da stok birden çok satış kanalıyla paylaşılıyorsa bağlantının ilk kurgusu sonraki bütün güncellemeleri belirler. AdPix, pazaryeri entegrasyonu kurulumu hizmetinde hangi modellerin kurulacağını ve her verinin hangi sistemde ana kayıt olarak tutulacağını işletmeyle birlikte belirler; kategori ve özellik eşleştirmesini, otomatik paketleme ayarıyla sipariş aktarımının uyumunu ve stok ile fiyat güncellemelerinin sonuç kontrolünü kurar ve canlıya geçmeden önce test eder. Fiyat kilidine, kampanya kısıtına ya da ürün statüsüne takılan mağazanın katalog ve listing düzeni Hepsiburada danışmanlığı kapsamında incelenir.

Hepsiburada entegrasyonu için diğer rehberler

• Pazaryeri entegrasyonu kurulumu
• Hepsiburada kargo
• Hepsiburada komisyon hesaplama
• Trendyol entegrasyon
• n11 entegrasyon
• Pazaryeri entegrasyonu nedir

Hepsiburada entegrasyonu hakkında sık sorulan sorular

Hepsiburada entegratör yetkisi ne zaman geçerli olur?

Yetki satıcı panelinden verilir ve devreye girmesi yaklaşık iki saat sürer. İlk denemede "geçersiz" uyarısı gelirse bir süre sonra yeniden deneyin. Siparişler entegratör ekranına düşmüyorsa önce yetkinin tanımlı olduğuna ve süreli verildiyse süresinin dolmadığına bakın.

Hepsiburada'da Satışa Hazır statüsündeki ürün neden satılmıyor?

Satışa Hazır statüsü, ürünün kataloğa eklendiğini ve mağazanız için listing oluştuğunu gösterir. Listing, fiyat ve stok gönderilene kadar satışa açılmaz; stoğu ya da fiyatı sıfır olan listing kapalı kalır. Gönderdiğiniz fiyat ve stoğun sonucunu dönen işlem kimliğiyle sorgulayın.

Eşleşen statüsündeki ürün için ne yapılmalı?

Eşleşen statüsü, gönderdiğiniz ürünün Hepsiburada kataloğunda zaten bulunduğunu gösterir. Eşleşmeyi satıcı panelinden ya da API ile onaylamanız ya da reddetmeniz gerekir; karar vermeden önce güncelleme gönderebilirsiniz. Onaylamadan önce marka, model ve varyantın sizin ürününüzle aynı olduğunu kontrol edin.

Hepsiburada fiyat kilidi nasıl kaldırılır?

Eşik dışında kalan fiyat değişikliği SKU'yu MaxLock ya da MinLock ile kilitler. Fiyattan eminseniz kilit, kilit kaldırma servisiyle ya da satıcı panelindeki Envanter ekranından toplu olarak kaldırılır; emin değilseniz önerilen aralıkta yeni bir fiyat girilir. Kampanyadaki üründe ayrıca kampanya kısıtı olabilir.

Otomatik paketleme açıkken entegrasyon hangi siparişleri çeker?

Otomatik paketleme açıkken sipariş geldikten sonra 15 dakika içinde paketlenir ve entegrasyon paket bilgilerini çeker. Kapalıyken ödemesi tamamlanmış siparişler çekilir ve paketlemeyi mağaza ya da entegratör yapar. Stok bitme ihtimali olan mağazada paketlemenin API ile yapılması gerekir.