Invozon × Hepsiburada

Hepsiburada, Türkiye'nin en eski büyük ölçekli e-ticaret platformu ve Trendyol'dan sonra en yüksek satıcı yoğunluğuna sahip pazaryeridir. 1998'den bu yana yayında olması, kullanıcı tabanında daha "geleneksel" bir profil oluşturmuş; ortalama sepet tutarı Trendyol'a kıyasla yüksektir, dönüşüm oranı ise daha sabittir. Hepsiburada Marketplace API'si, yapı olarak Trendyol'a göre daha modüler bir tasarım sunar — listing, listing-offer, order, shipment ve product hizmetleri ayrı uç noktalar üzerinden çalışır. Bu modülerlik güç verir ama aynı zamanda her akış için ayrı bir kimlik doğrulama bağlamı, ayrı bir hata kümesi anlamına gelir.

Invozon'un Hepsiburada konektörü bu çoklu yüzeyi tek bir tutarlı API altında soyutlar. Tek bir ürün gönderme çağrısı arka planda hem product servisine (içerik) hem listing servisine (satış teklifi) hem de gerekli ise variant-group servisine düşer; biz bu kaskadı sizin için yönetiriz. Hepsiburada'nın merchantId bağlamlı imzalama mantığı, ürün ve teklif uç noktalarının ayrı subdomain'lerde olması (mpop, listing-external), HepsiJet kargo süreçleri ve "varyant set" mantığı gibi platform-özgü konular bu rehberde özetlenmiştir.

Bu rehber, Hepsiburada satıcı hesabınızı Invozon'a bağlamak, sık akışları çalıştırmak ve platform-özgü tuzaklardan kaçınmak için yazılmıştır. Tüm örnekler cURL ve gerçekçi JSON ile gösterilmiştir.

Bağlantı kurma

Hepsiburada entegrasyonu için MerchantID, Username ve Password olmak üzere üç bilgiye ihtiyacınız vardır. Hepsiburada API'si Basic Auth kullanır (kullanıcı adı + şifre Base64'lenir), Trendyol'un imzalı anahtar modelinden farklıdır.

1. hepsiburada.com.tr/satici üzerinden Mağaza Yönetim Sistemi'ne (MPOP) giriş yapın.
2. Sol menüden Entegrasyonlar → API Bilgileri sekmesine geçin.
3. Sayfada görünen MerchantID (GUID formatında, örn. 4a9c8e7d-1f2b-4d3c-9a8e-7b6c5d4e3f2a) değerini not alın.
4. Yeni Entegrasyon Kullanıcısı Oluştur butonuna basın, bir kullanıcı adı belirleyin (genellikle firmaadi-api gibi).
5. Hepsiburada size bir geçici şifre verecek; ilk çağrıda şifreyi değiştirmeniz beklenir. Kalıcı şifreyi belirleyip güvenli bir yere kaydedin.
6. Yeni kullanıcıya hangi servislere erişim verileceğini seçin: Ürün, Listing, Sipariş, Kargo, İade, Fatura servislerinin tümünü onaylamanız önerilir.

Invozon Konsolu'nda Settings → Marketplaces → Hepsiburada sekmesine geçin ve üç değeri girin. Test için Stage ortamı seçtiğinizde Hepsiburada'nın mpop-sit (System Integration Test) ortamına bağlanılır.

# Bağlantı doğrulama
curl -X POST https://api.invozon.com/v1/marketplaces/hepsiburada/ping \
  -H "Authorization: Bearer $INVOZON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "4a9c8e7d-1f2b-4d3c-9a8e-7b6c5d4e3f2a",
    "username": "invozon-api",
    "password": "********"
  }'

{
  "status": "connected",
  "merchant_id": "4a9c8e7d-1f2b-4d3c-9a8e-7b6c5d4e3f2a",
  "merchant_name": "Örnek Ticaret A.Ş.",
  "services": ["product", "listing", "order", "shipment", "return", "invoice"],
  "checked_at": "2026-06-02T08:14:22Z"
}

Bağlantı kurulduktan sonra Invozon, Hepsiburada'nın oturum cookie davranışını, Basic Auth header'ını ve subdomain çeşitliliğini sizin için yönetir.

Endpoint referansı

Invozon'un Hepsiburada uç noktaları /v1/marketplaces/hepsiburada/ öneki altındadır. Hepsiburada'da ürün ve listeleme ayrı kavramlardır: bir "ürün" platforma kaydedilen içeriktir, bir "listing" ise o ürünün belirli bir satıcı tarafından satışa sunulmuş halidir. Invozon iki adımı tek istekte gizler ama dilerseniz ayrı ayrı çağırabilirsiniz.

Ürün listeleme

Yeni ürün açma işlemi iki aşamadan oluşur: önce ürün içeriği product servisine gönderilir, içerik onayı geldikten sonra listing servisi üzerinden satış teklifi yapılır. Invozon mode parametresi ile her iki aşamayı tek seferde tetikleyebilir.

curl -X POST https://api.invozon.com/v1/marketplaces/hepsiburada/products \
  -H "Authorization: Bearer $INVOZON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "content_and_listing",
    "items": [
      {
        "merchant_sku": "INV-TSH-001-M-BLK",
        "product_name": "Basic Tişört Siyah Medium",
        "brand": "Invozon Basics",
        "category_id": "computer_electronics_clothing_basic_tshirt",
        "description_html": "<p>Pamuklu, slim fit, ön baskısız temel tişört.</p><ul><li>%100 pamuk</li><li>30 derecede yıkanır</li></ul>",
        "tax_vat_rate": 10,
        "barcode": "8690000123456",
        "variant_group_id": "INV-TSH-001",
        "images": [
          { "url": "https://cdn.example.com/tsh-001-1.jpg", "order": 1 },
          { "url": "https://cdn.example.com/tsh-001-2.jpg", "order": 2 }
        ],
        "attributes": {
          "Renk": "Siyah",
          "Beden": "M",
          "Materyal": "Pamuk",
          "Kalıp": "Slim"
        },
        "listing": {
          "price": 199.90,
          "available_stock": 25,
          "dispatch_time_days": 2,
          "shipment_template": "TR-SHIPMENT-STD"
        }
      }
    ]
  }'

Yanıt:

{
  "tracking_id": "f51a0f3c-9c1e-4c4e-b820-3f1a9e8c7d12",
  "accepted_count": 1,
  "rejected_count": 0,
  "status_url": "/v1/marketplaces/hepsiburada/imports/f51a0f3c-9c1e-4c4e-b820-3f1a9e8c7d12"
}

İçerik durumunu sorgulamak için:

curl https://api.invozon.com/v1/marketplaces/hepsiburada/imports/f51a0f3c-9c1e-4c4e-b820-3f1a9e8c7d12 \
  -H "Authorization: Bearer $INVOZON_TOKEN"

{
  "tracking_id": "f51a0f3c-9c1e-4c4e-b820-3f1a9e8c7d12",
  "content_status": "APPROVED",
  "hb_sku": "HBV0000123ABC",
  "listing_status": "ACTIVE",
  "url": "https://www.hepsiburada.com/basic-tisort-siyah-m-p-HBV0000123ABC"
}

content_status Hepsiburada içerik ekibi tarafından WAITING, APPROVED veya REJECTED değerlerini alabilir. Onay süreci 6-48 saat sürer.

Stok güncelleme

Stok ve fiyat güncellemesi Hepsiburada'da listing servisi üzerinden yapılır. Invozon ikisini tek istekte birleştirir.

curl -X POST https://api.invozon.com/v1/marketplaces/hepsiburada/inventory \
  -H "Authorization: Bearer $INVOZON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "merchant_sku": "INV-TSH-001-M-BLK", "available_stock": 12, "price": 189.90 },
      { "merchant_sku": "INV-TSH-001-L-BLK", "available_stock": 0,  "price": 189.90 }
    ]
  }'

{
  "tracking_id": "9e8c7d12-3f1a-4c4e-b820-f51a0f3c9c1e",
  "accepted": 2,
  "rejected": 0
}

Stok bilgisi Hepsiburada vitrininde 1-3 dakika içinde güncellenir. Stok 0 olan listing'ler otomatik olarak OUT_OF_STOCK durumuna geçer; fakat tamamen pasifleştirilmek için ayrıca status: "inactive" göndermeniz gerekir.

Sipariş alma

Hepsiburada siparişlerini durum filtresi ile çekersiniz. Hepsiburada'nın durum makinesi Trendyol'dan farklıdır: Open → InProgress → Shipped → Delivered ana akıştır, ancak iptal/iade alt durumları zengin.

curl "https://api.invozon.com/v1/marketplaces/hepsiburada/orders?status=Open&start=2026-06-01T00:00:00Z&end=2026-06-02T00:00:00Z&offset=0&limit=50" \
  -H "Authorization: Bearer $INVOZON_TOKEN"

{
  "offset": 0,
  "limit": 50,
  "total": 2,
  "orders": [
    {
      "order_number": "1283749812",
      "order_date": "2026-06-01T18:42:11Z",
      "status": "Open",
      "customer": {
        "first_name": "Ayşe",
        "last_name": "K.",
        "email": "[email protected]",
        "phone": "+90-5xx-xxx-xxxx"
      },
      "shipping_address": {
        "city": "İstanbul",
        "town": "Beşiktaş",
        "address": "Bebek Mah. Cevdetpaşa Cad. No:48 D:7",
        "postal_code": "34342",
        "country": "TR"
      },
      "billing_address": "same_as_shipping",
      "cargo_company": "HepsiJet",
      "cargo_tracking_number": "HJ73625109283",
      "total_price": 199.90,
      "items": [
        {
          "line_item_id": "L-5512837461",
          "merchant_sku": "INV-TSH-001-M-BLK",
          "hb_sku": "HBV0000123ABC",
          "quantity": 1,
          "unit_price": 199.90,
          "commission": 28.79,
          "vat_rate": 10
        }
      ]
    }
  ]
}

Sipariş statüsü güncelleme

Hepsiburada'da sipariş kalemleri tek tek (line_item_id ile) ilerletilir. Aynı sipariş içindeki iki kalemden birini gönderip diğerini iptal etmek mümkündür.

curl -X PATCH https://api.invozon.com/v1/marketplaces/hepsiburada/orders/1283749812/items/L-5512837461 \
  -H "Authorization: Bearer $INVOZON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "InProgress",
    "package_id": "PKG-2891-01"
  }'

Geçerli durum geçişleri:

• Open → InProgress (hazırlanıyor)
• InProgress → Shipped (kargoya verildi)
• Open → Cancelled (stok yokluğu vb. ile)

Hepsiburada'da bir kalemi Shipped durumuna geçirebilmek için cargo_tracking_number zorunludur. HepsiJet kullanıyorsanız bu otomatik gelir, anlaşmalı kargonuzda manuel girmeniz gerekir.

Kargo etiketi üretme

HepsiJet ile çalışıyorsanız etiket Invozon üzerinden tek istekte alınır.

curl https://api.invozon.com/v1/marketplaces/hepsiburada/orders/1283749812/label \
  -H "Authorization: Bearer $INVOZON_TOKEN" \
  -H "Accept: application/pdf" \
  -o etiket-1283749812.pdf

Etiket formatı varsayılan olarak A6 (Zebra termal yazıcı uyumlu). A4'e geçmek için ?format=a4 parametresi ekleyin.

Anlaşmalı kargonuzla çalışıyorsanız etiket Invozon'dan değil kendi kargonuzun panelinden alınır; yine de Invozon'a cargo_tracking_number bildirip kalem statüsünü Shipped'a almanız gerekir.

İade akışı

Hepsiburada iade akışı claim değil return olarak adlandırılır.

curl "https://api.invozon.com/v1/marketplaces/hepsiburada/returns?status=Open&start=2026-05-25T00:00:00Z&end=2026-06-02T00:00:00Z" \
  -H "Authorization: Bearer $INVOZON_TOKEN"

{
  "returns": [
    {
      "return_id": "RT-88123745",
      "order_number": "1283749812",
      "line_item_id": "L-5512837461",
      "reason": "BEDEN_KUCUK",
      "status": "Open",
      "customer_note": "Beden küçük geldi, bir beden büyüğünü tercih ederim.",
      "request_date": "2026-06-02T06:12:55Z",
      "expected_action": "approve_within_3_days"
    }
  ]
}

İadeyi onaylamak:

curl -X POST https://api.invozon.com/v1/marketplaces/hepsiburada/returns/RT-88123745/approve \
  -H "Authorization: Bearer $INVOZON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "refund_amount": 199.90, "note": "İade kabul edildi." }'

Reddetmek:

curl -X POST https://api.invozon.com/v1/marketplaces/hepsiburada/returns/RT-88123745/reject \
  -H "Authorization: Bearer $INVOZON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Ürün kullanılmış olarak iade edildi", "evidence_url": "https://cdn.example.com/iade-foto.jpg" }'

Hepsiburada iade reddi için 72 saat içinde fotoğraflı kanıt sunma şartı vardır; aksi halde Müşteri Operasyon ekibi iadeyi satıcı aleyhine sonuçlandırır.

Varyant grubu yönetimi

Hepsiburada'da aynı ürünün farklı varyantları (beden/renk) variant_group_id ile birbirine bağlanır. Invozon, bu grupları sorgulamak ve grup düzeyinde güncelleme yapmak için bir uç nokta sunar.

curl https://api.invozon.com/v1/marketplaces/hepsiburada/variant-groups/INV-TSH-001 \
  -H "Authorization: Bearer $INVOZON_TOKEN"

{
  "variant_group_id": "INV-TSH-001",
  "shared_attributes": { "Marka": "Invozon Basics", "Materyal": "Pamuk" },
  "variants": [
    { "merchant_sku": "INV-TSH-001-S-BLK",  "Beden": "S",  "Renk": "Siyah" },
    { "merchant_sku": "INV-TSH-001-M-BLK",  "Beden": "M",  "Renk": "Siyah" },
    { "merchant_sku": "INV-TSH-001-L-BLK",  "Beden": "L",  "Renk": "Siyah" },
    { "merchant_sku": "INV-TSH-001-XL-BLK", "Beden": "XL", "Renk": "Siyah" }
  ]
}

Bir varyantı gruptan çıkarmak için:

curl -X DELETE https://api.invozon.com/v1/marketplaces/hepsiburada/variant-groups/INV-TSH-001/variants/INV-TSH-001-XL-BLK \
  -H "Authorization: Bearer $INVOZON_TOKEN"

Kampanya katılımı

Hepsiburada'nın Süper Fırsatlar, Mobil Fırsat ve Çarşamba İndirimleri gibi kampanyaları satıcı performansını ciddi biçimde etkiler.

curl https://api.invozon.com/v1/marketplaces/hepsiburada/campaigns?status=upcoming \
  -H "Authorization: Bearer $INVOZON_TOKEN"

{
  "campaigns": [
    {
      "campaign_id": "HB-SUPER-2026-06",
      "name": "Yaz Süper Fırsatlar Haziran",
      "starts_at": "2026-06-15T00:00:00Z",
      "ends_at": "2026-06-22T23:59:59Z",
      "discount_code": "SUPERHAZIRAN26",
      "min_discount_percent": 15
    }
  ]
}

Kampanya kodu (discount_code) müşteri sepetinde manuel girilir; satıcı tarafında bu kodun komisyon iadesini Hepsiburada otomatik yapar.

Pazaryeri-spesifik notlar

Kategori ağacı yapısı. Hepsiburada kategorileri Trendyol'a göre daha derin bir ağaç (genellikle 5-7 seviye) oluşturur ve category_id yerine human-readable bir slug kullanır (computer_electronics_clothing_basic_tshirt). Yanlış kategori seçimi içerik onayında en sık reddedilme nedenidir. Invozon auto_category: true flag'i ile başlık + öznitelik kombinasyonuna göre öneri sunar.

HepsiJet. Tavsiye edilen kargo entegrasyonudur. Hepsiburada'nın kendi kargo şirketi olduğu için "Hızlı Teslimat" rozeti almanın önkoşuludur. HepsiJet kullanıyorsanız etiket otomatik, kargo bedeli otomatik düşülmüş olur. Anlaşmalı kargonuzu kullanırken shipment_template alanında kendi kargo şablonunuzun ID'sini göndermeniz gerekir.

Description HTML. Trendyol'dan farklı olarak Hepsiburada ürün açıklamasında belirli HTML etiketlerine izin verir (p, ul, ol, li, strong, em, br). img, script, iframe, style yasaktır. HTML olarak gönderildiği için Markdown'ı önce HTML'e dönüştürmeniz gerekir; Invozon description_markdown alanını otomatik dönüştürür.

Varyant set zorunluluğu. Bir kategoride varyant kullanıyorsanız (giyim, ayakkabı, telefon kapağı) tüm varyantları aynı variant_group_id altında göndermeniz zorunludur. Tek varyantlı ürün için bile bu alan zorunlu olabilir; emin değilseniz variant_group_id = merchant_sku olarak ayarlayın.

Fatura zorunluluğu. Hepsiburada her sipariş için e-fatura veya e-arşiv fatura URL'sini Shipped durumuna geçmeden önce sisteme yüklemenizi ister. Invozon e-fatura entegrasyonlarınız üzerinden bu yüklemeyi otomatik yapar; entegrasyonunuz yoksa POST /v1/marketplaces/hepsiburada/orders/{id}/invoice ile manuel yükleyebilirsiniz.

Komisyon yapısı. Hepsiburada komisyonu kategoriye göre %5-22 arasında değişir, ek olarak işlem başına ~6 TL hizmet bedeli vardır. "Süper Satıcı" rozetli mağazalarda komisyon -2 puan indirim alabilir.

Soru-cevap performansı. Hepsiburada satıcı puanı (Satıcı Performans Skoru) hesabında soru-cevap cevap süresinin payı yüksektir; 24 saatlik SLA agresif uygulanır.

Sınırlamalar

• Hepsiburada API'si MerchantID başına dakikada ~300 istek tavanı uygular. Toplu ürün yüklemesi yaparken Invozon istekleri otomatik olarak yumuşatır.
• Ürün başlığında 100 karakter, açıklamada 25.000 karakter (HTML dahil) sınırı vardır.
• Görsel sayısı en fazla 10'dur, her görsel en az 1000×1000 piksel ve maksimum 5 MB olmalıdır.
• Toplu fiyat/stok güncellemesi tek istekte en fazla 500 SKU içerebilir.
• Hepsiburada kategori değişikliği API üzerinden yapılamaz; ürünü pasifleştirip yeni kategoride yeniden açmanız gerekir, bu da SKU'nun yorumlarını ve satış skorunu sıfırlar.
• Birden fazla mağaza altında aynı içeriği (HB SKU) listeleyemezsiniz; her hb_sku tek bir satıcıya bağlanır.
• Hepsiburada Express (HepsiJet) dışındaki kargolarda iade kabul süreci ortalama 5-9 iş günü sürer.
• HepsiBurada şu an sandbox dışında "test siparişi" üretme imkânı sunmuyor; satıcılar production'da küçük bir test SKU ile akış doğrulaması yapar.

Sık Sorulan Sorular

Ürünü gönderdim ama "İçerik Onayda" yazıyor, ne kadar sürer? Hepsiburada içerik onay süresi ortalama 6-48 saattir, hafta sonu daha uzun olabilir. 72 saati geçtiyse rejection_reason alanını kontrol edin; en sık ret nedeni yanlış kategori veya marka onayı eksikliğidir.

Marka onayı nasıl alınır? Markanızın tescil belgesini Hepsiburada Satıcı Paneli'nden Marka Onayı sekmesine yüklemeniz gerekir. Onay 5-10 iş günü sürer. Onay gelmeden o markaya ait ürünleriniz WAITING_FOR_BRAND durumunda bekler.

HepsiJet etiketi otomatik basılmıyor, ne yapmalıyım? Sipariş kalemini InProgress durumuna aldığınızdan emin olun; Open durumdaki kalemlerde etiket üretilmez. Yine de PDF gelmiyorsa Hepsiburada tarafında HepsiJet entegrasyonunuzun aktif olduğunu MPOP → Kargo Ayarları'ndan kontrol edin.

Fatura yüklemezsem ne olur? Shipped durumuna geçtiğiniz andan itibaren 48 saat içinde fatura yüklemezseniz Hepsiburada satıcı performans skorunuzu düşürür ve sipariş "Faturasız Gönderim" olarak işaretlenir; tekrarı halinde satışlarınız geçici olarak askıya alınabilir.

Aynı ürünü hem Trendyol hem Hepsiburada'da satıyorum, stoğu tek noktadan nasıl yönetirim? Invozon her iki konektörü tek SKU üzerinden besler; merchant_sku veya barcode ile eşleştirilmiş ürünlerde Invozon'un Stock Sync modülü tek stok hareketini her iki pazaryerine eş zamanlı yansıtır.

Hepsiburada sandbox var mı? Evet, mpop-sit.hepsiburada.com üzerinde stage ortamı vardır. Invozon environment: "stage" ayarı ile bu adrese yönlendirir. Sandbox'da test sipariş üretmek için Hepsiburada teknik ekiplerine başvurmanız gerekir.

---

Resmî dokümantasyon: https://developers.hepsiburada.com