Hepsiburada Entegrasyonu

Hepsiburada Merchant API nedir ve neyi otomatikleştirir?

Hepsiburada Merchant API, satıcıların ürün kataloğunu, fiyat ve stoğunu, siparişlerini, kargo ve iade süreçlerini kendi sisteminden yönetmesini sağlayan RESTful (JSON) bir entegrasyon katmanıdır. Panelden manuel giriş yerine, binlerce SKU'yu programatik güncellemek ve siparişleri gerçek zamanlıya yakın çekmek mümkün olur. Hepsiburada'da satıcı olarak 6563 sayılı Kanun kapsamında ETHS konumundasınız; platform aracı (ATHS/ETAHS) taraftır. Başlamadan önce ETBİS kaydınız ve GİB e-Fatura/e-Arşiv altyapınız hazır olmalıdır.

Yetkilendirme: Merchant ID ve API anahtarı

Hepsiburada'da işlemler Merchant ID (satıcı numarası) etrafında döner ve servisler çoğunlukla Basic Auth ile korunur. Ürün listeleme, fiyat-stok ve sipariş (OMS) uçları farklı servis alan adları altında toplanabilir; bu yüzden entegrasyonu servis bazında modüler kurun.

• 1. Panelden bilgi alın: Merchant Panel → Entegrasyon / API Ayarları'ndan merchantId, kullanıcı adı ve API anahtarı kaydedilir.
• 2. Kimlik doğrulama: Authorization: Basic base64(kullanıcıAdı:apiKey) başlığı gönderilir.
• 3. Test → onay → canlı: önce test ortamında akış doğrulanır, ardından Hepsiburada onayıyla production'a geçilir.
• 4. Servis ayrımı: ürün (listing/product), fiyat-stok ve sipariş uçlarını ayrı istemcilerle yönetin.

Ürün gönderimi: asenkron ve moderasyonlu

Ürün oluşturma senkron değildir. Gönderilen kalem bir işlem/izleme kimliği (tracking id)döndürür; katalog eşleştirme ve içerik moderasyonu sonrası SUCCESS / FAILED durumuna geçer. Durumu ilgili status ucundan poll edersiniz. Reddedilmeyi azaltmak için alanları baştan doğru gönderin:

• merchantSku: kendi benzersiz stok kodunuz; SKU eşlemenizin tek kaynağı.
• hepsiburadaSku: var olan katalog ürününe bağlanıyorsanız Hepsiburada ürün kodu.
• categoryId + attributes: kategoriye bağlı zorunlu özellikler (marka, model, renk, ölçü) eksikse ürün FAILED döner.
• price, availableStock, dispatchTime: fiyat, satılabilir stok ve kargoya hazırlık süresi (gün).
• images: görsel kuralları (çözünürlük, zemin) sağlanmalı; aksi halde reddedilir.
• vatRate, warranty: KDV oranı e-Fatura ile uyumlu olmalı, garanti süresi ay cinsinden.

Stok ve fiyat senkronizasyonu

Fiyat ve stok, katalogdan ayrı ve daha hızlı bir uçtan toplu güncellenir (price-inventory tipi servis). Doğru periyot için basit bir bütçe: gerekli çağrı/gün ≈ (SKU sayısı ÷ batch boyutu) × günlük senkron sayısı. Oversell'i önlemek için tampon bırakın: buffer = ortalama satış hızı × senkron periyodu.

Sipariş yönetimi, HepsiJet ve iade

Siparişler statü (Approved, Preparing, Shipped, Delivered, Cancelled, Returned) ve tarih aralığına göre sayfalı çekilir. KVKK 6698 gereği müşteri verisi kısıtlı/maskeli gelebilir; yalnızca gönderi ve fatura amacıyla işleyin. Kargoda iki yol vardır: HepsiJet ile teslimat ve iade platformca yönetilir, takip numarası otomatik üretilir; ya da anlaşmalı kargonuzla gönderip takip numarasını siz bildirirsiniz. Maliyet desiye bağlıdır: desi = (En × Boy × Yükseklik) / 3000.

İade tarafında Mesafeli Sözleşmeler Yönetmeliği'nin 14 gün cayma hakkı geçerlidir; talepleri API'den çeker, süresi içinde onaylar veya gerekçeyle reddedersiniz. Kusurlu üründe kargoyu satıcı, cayma halinde çoğunlukla alıcı üstlenir. Her satış için e-Fatura/e-Arşiv, gönderide gerekli ise e-İrsaliye düzenlenir.

Maliyet: komisyon ve net hakediş

Fiyatı kurmadan önce net hakedişi modelleyin: Net Hakediş = Satış Fiyatı − Komisyon − Hizmet/İşlem Bedeli − Kargo (desi) − İade/Kupon Payı. Yardımcı metrikler: take rate = komisyon ÷ GMV ve efektif komisyon = (komisyon + hizmet bedeli) ÷ satış fiyatı × 100. Aşağıdaki oranlar kamuya açık, temsili aralıklardır; kategori ve döneme göre değişir, sözleşmenizdeki güncel oranı esas alın.

Yaygın hatalar ve iyi uygulamalar

• Tracking id'yi izleyin: ürün gönderimini "başarılı" saymadan önce status ucundan SUCCESS/FAILED sonucunu okuyun.
• Görsel ve attribute kuralları: reddedilmelerin çoğu eksik zorunlu özellik veya görsel kuralından kaynaklanır; şablonu baştan sağlayın.
• Retry + idempotency: geçici hatalarda exponential backoff ile tekrar deneyin, mükerrer merchantSku yaratmayın.
• İade SLA'sı: talepleri süresi içinde işleyin; gecikme mağaza puanını ve görünürlüğü düşürür.
• Mevzuat: e-Fatura/e-Arşiv, e-İrsaliye, KVKK maskeleme; pazarlama iletisi için İYS onayı zorunludur.

Hepsiburada'yı Trendyol ve n11 ile aynı stok havuzundan yönetmek için çoklu pazaryeri entegrasyonu çözümümüzü ve kargo & e-fatura entegrasyonu çözümümüzü inceleyin. Diğer pazaryeri API'leri için Trendyol ve n11 rehberlerine göz atabilir, kendi akışınız için talep oluşturabilirsiniz.