Hepsiburada’da stok ve fiyat güncelleme: 4.000 SKU ve fiyat kilidi

Hepsiburada’da eşik dışı bir fiyat gönderirseniz ürün kilitlenir ve satıştan düşer. 4.000 SKU’luk sınır, aynı anda 5 bekleyen işlem kuralı ve fiyat kilidinden çıkma yolu.

Hepsiburada’nın listeleme servisi, Trendyol ve N11’den iki konuda belirgin şekilde ayrışıyor: tek istekte gönderebileceğiniz kalem sayısı çok daha yüksek, ama eşzamanlı işlem sayısı sıkı sınırlı. Bir de diğer ikisinde olmayan bir mekanizma var: fiyat kilidi.

Önce ortam: dokümandaki adresler test ortamı

Doküman portalındaki uç nokta adresleri test ortamına aittir. Canlı adresi, adresteki -sit ifadesini kaldırarak oluşturursunuz ve canlı ortama canlı için verilen kullanıcı adı / şifre ile istek atarsınız.

Bu ayrımı atlamak, “doküman çalışıyor ama canlıda olmuyor” türü saatlerce sürebilen bir arayışa yol açıyor.

Kimlik doğrulama HTTP Basic Auth ile yapılır; kullanıcı adı ve şifre Authorization başlığında gönderilir. Hangi kimlik bilgisinin size gerektiğini kimlik bilgileri yazısında ele aldık — Hepsiburada’da birden fazla kimlik türü var ve karıştırmak kolay.

Sınırlar

Kural	Değer
Tek istekte SKU	En fazla 4.000
Aynı anda bekleyen/devam eden işlem	En fazla 5
Komisyon sorgulama — istek başına SKU	En fazla 50
Komisyon sorgulama — dakikalık istek	Ortalama 240 (aşılırsa 429)

5 işlem kuralı mimarinizi belirliyor

Bu, diğer pazaryerlerinde karşılığı olmayan bir kısıt. Aynı anda beşten fazla güncelleme işleminiz “devam ediyor” durumunda olamaz.

Hepsiburada’nın kendi önerisi net: limit uyarısına takılmamak için tek seferdeki SKU adedini artırın. Yani küçük paketleri hızlı hızlı göndermek yerine, 4.000’e kadar büyük paketler hâlinde az sayıda istek atmak doğru yaklaşım.

Trendyol ve N11’de 1.000 kalemlik paketlerle çalışan bir kurgunuz varsa, Hepsiburada için paket boyutunu ayrıca ayarlamanız gerekir — tek bir “paket boyutu” sabitiyle üç pazaryerine birden gitmek burada verimsiz kalır.

Satışa açma ve kapatma

Ayrı bir “durum” alanı yok; stok ve fiyat üzerinden yönetiliyor:

• Satışa kapatmak için: stok veya fiyat bilgisini sıfır gönderin.
• Satışa açmak için: fiyat ve stok bilgisinin ikisini de sıfırdan farklı gönderin.

Buradaki tuzak şu: fiyatı yanlışlıkla sıfır gönderen bir kod, ürünü sessizce satıştan düşürür. Gönderim öncesi sıfır kontrolü koymak iyi fikir.

Fiyat kilidi: en kritik mekanizma

Hepsiburada, listeleme güncellemelerinde kategori bazlı eşik (threshold) değerlerine geçti. Eşiğin dışında bir fiyat güncellemesi yaparsanız ilgili SKU kilitlenir.

Yanıt, kilidin tipini ve kabul edilen aralığı veriyor:

"priceValidations": [
  {
    "elementNo": 1,
    "hepsiburadaSku": "HBCV00002LJ9YU",
    "merchantSku": "TESTSKU",
    "type": "MaxLock",
    "minPrice": 899.8,
    "maxPrice": 13767.0,
    "description": "Yüksek fiyat sebebiyle kilitlendi..."
  }
]

• MaxLock — gönderdiğiniz fiyat platform genelindeki aralığın üstünde.
• MinLock — aralığın altında.

Her iki durumda da minPrice ve maxPrice alanları kabul edilen bandı söylüyor. Bu veri altın değerinde: kodunuz kilitlenen SKU’yu loglarken bandı da kaydederse, bir sonraki denemede doğru aralığı bilirsiniz.

Kilitten çıkmak

İki yol var:

• Fiyatın doğru olduğundan eminseniz Toplu Kilit Kaldırma API’si ile kilidi kaldırıp ürünü son girdiğiniz fiyattan satışa açarsınız.
• Ya da önerilen aralıkta yeniden fiyat girersiniz.

Satıcı panelinde Envanter ekranından toplu kilit kaldırma da mümkün.

Pratik sonuç: otomatik fiyatlandırma kullanıyorsanız bu mekanizma sizi doğrudan ilgilendiriyor. Rakip takibiyle agresif fiyat düşüren bir kurgu, eşiğin altına inip ürünü kilitleyebilir — ve ürün kilitliyken satışta olmaz. Fiyat değişimlerine kendi tarafınızda da bir alt/üst sınır koymak, bu durumu baştan önler.

Fiyat değiştirirken üstü çizili fiyat göstermenin ayrı bir hukuki kuralı olduğunu da unutmayın: on günlük en düşük fiyat kuralı.

İşlem sonucunu takip etmek

Başarılı bir istek Inventory Upload Id döner. Bu kimliği Listing Güncelleme İşlem Kontrolü metodunda kullanırsınız.

İstekte eksik alan varsa ya da uç nokta hatası alındıysa Inventory Upload Id dönmez; hata bilgisi doğrudan yanıtta gelir. Yani kodunuzun ilk kontrolü “kimlik döndü mü” olmalı.

Ayrıca yanıt başlıklarındaki x-correlation-id değeriyle isteğin durumunu son 7 güne kadar sorgulayabilirsiniz. Bu değeri loglamak, sonradan “o gönderime ne oldu” sorusunu cevaplamanın tek yolu.

Desen Trendyol ve N11 ile aynı: istek kabul edilmesi güncellemenin yapıldığı anlamına gelmiyor. Üçünün karşılaştırmasını ayrı yazıda topladık.

Zorunlu alanlar ve kargo

Gönderimde ProductName, ShippingProfileName ve MaximumPurchasableQuantity dışındaki tüm alanlar zorunludur.

Kargo tarafında dikkat edilecek bir kural var: yalnızca HepsiJet seçtiyseniz, yanında standart bir kargo firması da seçmeniz gerekir. Seçmezseniz MissingStandartCargoCompany hatası dönüyor.

Kargo firması adlarının yazım biçimi de sabit: Yurtiçi Kargo, Aras Kargo, PTT Kargo, Borusan Lojistik, Horoz Lojistik, HepsiJet, MNG Kargo, Sürat Kargo, Ceva Lojistik, UPS, Mağaza Hesabı. Kendi sisteminizdeki kargo adlarını bu listeye eşlemeniz gerekir.

Yanıt biçimini Accept başlığıyla seçersiniz: application/json ya da application/xml.

Hata kodları

Kod	Anlamı
400	Adresteki parametreleri kontrol edin
401	Şifre hatalı
404	Adres hatalı
405	HTTP protokol hatası (yanlış metot)
500	Ticket açıp entegrasyon ekibiyle iletişime geçin

Bir bonus: komisyon sorgulama

Hepsiburada’da listinglerinizin komisyon bilgisine API ile ulaşabiliyorsunuz. İstek başına en fazla 50 SKU, dakikada ortalama 240 istek; aşılırsa 429 dönüyor.

Bu, kâr hesabını otomatikleştirmek isteyenler için değerli: komisyon oranını elle girmek yerine listing bazında çekip hesaba katabilirsiniz. Trendyol tarafında böyle bir servis bulamadık; oran panelden okunuyor.

Kontrol listesi

• Canlı adreste -sit kaldırıldı mı, canlı kimlik bilgisi kullanılıyor mu?
• Paket boyutu Hepsiburada için ayrıca ayarlandı mı (4.000’e kadar)?
• Aynı anda 5’ten fazla bekleyen işlem oluşmuyor mu?
• Fiyat veya stokun yanlışlıkla sıfır gitmesine karşı kontrol var mı?
• Kilitlenen SKU’lar minPrice / maxPrice ile birlikte loglanıyor mu?
• Inventory Upload Id dönmediğinde hata yakalanıyor mu?
• x-correlation-id saklanıyor mu?
• Kargo firması adları Hepsiburada’nın yazımına eşleniyor mu?

Kaynak

Sınırlar, fiyat kilidi mekanizması, zorunlu alanlar, kargo kuralları ve hata kodları Hepsiburada geliştirici portalındaki “Listeleme Entegrasyonu Önemli Bilgiler” dokümanından alınmıştır (22.10.2026 güncellemesi).

Son kontrol: 2 Kasım 2026. Hepsiburada eşik değerlerini ve sınırları değiştirebilir; uygulamadan önce güncel dokümanı teyit edin.