Hepsiburada API Entegrasyonu: Satıcılar İçin Teknik Rehber
Özet
Hepsiburada Marketplace API, OAuth 2.0 kimlik doğrulaması ile çalışır ve stok, fiyat, sipariş ve kargo takibini otomatize eder. Temel entegrasyon 5–8 iş günü içinde tamamlanır; çift yönlü stok senkronizasyonu için webhook yapılandırması gereklidir. 500+ SKU'yu olan satıcılar için API entegrasyonu operasyonel hatayı %80 oranında azaltır.
Hepsiburada API Entegrasyonu Nasıl Yapılır?
- 1
Merchant hesabı ve API erişimi talep edin
Aktif Hepsiburada merchant hesabı gerekir. Merchant panelinden API erişim talebi açılır; Hepsiburada onay sürecinden sonra Merchant ID ve API kimlik bilgileri verilir. Onay süresi hesabın satış geçmişine göre değişir.
- 2
Kimlik bilgilerini alın ve güvenli saklayın
Merchant panel > API Yönetimi bölümünden kullanıcı adı/şifre veya anahtar bilgileri alınır. Bu bilgiler yalnızca sunucu ortam değişkeninde (.env) tutulur; hiçbir koşulda client tarafına veya repoya konmaz.
- 3
Test ortamında bağlantıyı doğrulayın
Canlı veriye dokunmadan önce basit bir okuma çağrısıyla (kategori veya ürün listesi) kimlik bilgilerinin ve base URL'in doğruluğu doğrulanır. Yazma işlemleri ancak okuma çalıştıktan sonra denenir.
- 4
Listing ve stok/fiyat uçlarını bağlayın
Ürün gönderimi, stok güncelleme ve fiyat güncelleme uçları kurulur. Kendi veritabanınızdaki ürün ID'si ile Hepsiburada tarafındaki ID eşleştirmesi (mapping) tablosu bu aşamada oluşturulur — sonradan eklenmesi en pahalı adımdır.
- 5
Sipariş akışı ve webhook kurun
Yeni siparişler için webhook ucu tanımlanır; webhook'un ulaşmadığı durumlar için periyodik sipariş çekme (polling) yedek mekanizma olarak bırakılır. Kargo takip numarası bildirimi ve iptal/iade işleme uçları bağlanır.
- 6
Rate limit, retry ve stok koruması ekleyin
429 yanıtına karşı istek kuyruğu ve exponential backoff kurulur. Eş zamanlı siparişte stoğun negatife düşmemesi için kilit/koruma mekanizması eklenir. Temel entegrasyon 5-8 iş günü, çift kanal panel 2-3 haftadır.
Hepsiburada API Nedir?
Hepsiburada Marketplace API, satıcıların ürün, stok, sipariş ve fiyat verilerini kendi yazılımlarından yönetmelerine olanak tanıyan programatik bir arayüzdür. Manuel panel girişi yerine tüm işlemler otomatik gerçekleşir. Hem tek satıcı hem de çok kanallı (Trendyol + Hepsiburada) operasyonlar için idealdir.
API Erişim Koşulları
Hepsiburada API'sine erişim için bazı ön koşullar vardır:
- Aktif Hepsiburada merchant hesabı
- Merchant ID ve API anahtarı (merchant panel > API Yönetimi)
- Minimum stok / satış hacmi eşiği (Hepsiburada onay sürecine tabidir)
- Teknik entegrasyon belgesi imzalanması
Hepsiburada API Anahtarı Nasıl Alınır?
API'yi kullanmadan önce merchant hesabınız üzerinden erişim talebi açıp kimlik bilgilerinizi almanız gerekir. Etsy veya eBay'den farklı olarak burada ayrı bir geliştirici hesabı açılmaz — erişim doğrudan satıcı hesabına bağlanır ve Hepsiburada'nın onayına tabidir.
- 1. Aktif Hepsiburada merchant (satıcı) hesabıyla panele giriş yapın
- 2. API Yönetimi bölümünden API erişim talebi oluşturun
- 3. Hepsiburada onay sürecini tamamlayın — satış geçmişi ve hacim değerlendirilir
- 4. Onay sonrası Merchant ID ve API kimlik bilgileri panelde görünür hale gelir
- 5. Kimlik bilgilerini yalnızca sunucu ortam değişkeninde (.env) saklayın — client tarafına veya repoya koymayın
- 6. Yazma işlemlerine geçmeden önce basit bir okuma çağrısıyla bağlantıyı doğrulayın
Temel API Fonksiyonları
Hepsiburada API'sinin en çok kullanılan uç noktaları şunlardır:
- Ürün listeleme: Yeni ürün ekle, mevcut ürün güncelle
- Stok güncelleme: Anlık stok miktarı güncellemesi
- Fiyat güncelleme: Toplu veya tekil fiyat değişikliği
- Sipariş çekme: Yeni siparişleri otomatik al
- Kargo güncelleme: Takip numarası ve kargo firması bildirimi
- İptal/İade yönetimi: İade taleplerini programatik işle
Trendyol + Hepsiburada Çift Kanal Entegrasyonu
Türkiye'deki büyük e-ticaret satıcılarının önemli bir kısmı hem Trendyol hem Hepsiburada'da satış yapar. Bu iki kanalın stok ve siparişlerini elle yönetmek yüksek hata riskine yol açar. Solman Digital tarafından geliştirilen çift kanal panel; iki platformu tek arayüzden yönetir, stok aşım riskini ortadan kaldırır ve sipariş fulfillment sürecini otomatize eder.
Teknik Mimari
Hepsiburada API entegrasyonu genellikle şu bileşenlerden oluşur:
- Next.js API route veya Node.js servisi — API çağrılarını yönetir
- Cron job (scheduled job) — stok ve fiyat güncelleme döngüsü (15 dk'da bir)
- PostgreSQL veritabanı (Supabase) — sipariş ve stok geçmişi
- Webhook endpoint — Hepsiburada'dan anlık sipariş bildirimi
- Hata yönetimi ve yeniden deneme (retry) mekanizması
Sık Karşılaşılan Sorunlar
Entegrasyonlarda en çok karşılaştığımız teknik problemler:
- Rate limiting: API çağrı limitleri aşıldığında 429 hatası — istek kuyruğu gerekli
- Ürün eşleştirme: Kendi veritabanı ile Hepsiburada ürün ID'lerinin tutarlı tutulması
- Stok negatife düşme: Eş zamanlı sipariş durumunda koruma mekanizması şart
- Token yenileme: API token süresi dolduğunda otomatik yenileme
Sık Sorulan Sorular
Hepsiburada API entegrasyonu ne kadar sürer?
Temel entegrasyon (stok + sipariş) 5–7 iş günü. Trendyol ile çift kanal panel dahil kapsamlı bir çözüm 2–3 haftada tamamlanır.
Hepsiburada API ücretsiz mi?
API erişimi ücretli değildir; merchant hesabı olan satıcılar Hepsiburada onay sürecinden geçtikten sonra ücretsiz kullanabilir.
Trendyol ve Hepsiburada entegrasyonunu aynı sistemde yapabilir misiniz?
Evet. Solman Digital'in tamamladığı referans projelerden biri, iki pazaryerini tek panelde birleştiren çift kanal yönetim sistemidir. Stok, sipariş ve fiyat senkronizasyonu her iki platformda anlık çalışır.
Hepsiburada API anahtarı nasıl alınır?
Aktif merchant hesabıyla merchant panelinden API erişim talebi açılır. Hepsiburada onay sürecinden sonra Merchant ID ve API kimlik bilgileri panelin API Yönetimi bölümünden alınır. Erişim satıcı hesabına bağlıdır; ayrı bir geliştirici hesabı açılmaz. Kimlik bilgileri yalnızca sunucu tarafında (.env) saklanır.
Hepsiburada API dokümantasyonu nerede?
Teknik dokümantasyon Hepsiburada'nın geliştirici portalı üzerinden, API erişimi onaylanmış merchant hesaplarına açılır. Uç nokta listesi, istek/yanıt şemaları ve hata kodları burada yayımlanır. Entegrasyona başlamadan önce güncel sürümün kontrol edilmesi gerekir — uçlar zaman içinde değişebilir.
Rate limit aşıldığında (429) ne yapılmalı?
İstekler doğrudan tekrar gönderilmez; exponential backoff ile artan bekleme süresi uygulanır ve istekler bir kuyruğa alınır. Toplu stok/fiyat güncellemelerinde tek tek çağrı yerine mümkün olan yerde toplu (batch) uç kullanılır. Kuyruk olmadan yapılan toplu güncelleme entegrasyonun en sık çöktüğü noktadır.
WooCommerce veya WordPress ile Hepsiburada entegrasyonu yapılabilir mi?
Evet. WooCommerce ürün ve stok verileri API üzerinden Hepsiburada'ya senkronize edilir, gelen siparişler WooCommerce'e aktarılır. Bu senaryoda ürün eşleştirme tablosu (WooCommerce ürün ID ↔ Hepsiburada ID) kritik bileşendir.
Stok neden negatife düşer ve nasıl engellenir?
Aynı ürüne birden fazla kanaldan eş zamanlı sipariş geldiğinde, stok düşümü sıraya girmezse iki sipariş de kabul edilir ve stok negatife düşer. Çözüm, stok güncellemesini veritabanı seviyesinde kilitle (transaction/lock) yapmak ve kanallar arası tek bir stok kaynağı tutmaktır.
Solman Digital
Bu rehber, gerçekleştirilen projelerden derlenen doğrudan deneyime dayanmaktadır. Konuya ilişkin sorularınız için doğrudan uzman erişimi sunuyoruz.
Hepsiburada veya çift kanal API entegrasyonu için
Ücretsiz Araçlar
Rakamları Kendiniz Hesaplayın
Entegrasyon veya geliştirme kararı vermeden önce TicaretHub'un ücretsiz hesaplama araçlarıyla mevcut durumunuzu analiz edebilirsiniz.