API Reference

Listeleme Entegrasyonu Önemli Bilgiler

Listeleme Entegrasyon Modelimize ait Dikkat Edilmesi Gereken Önemli Bilgiler yer almaktadır.

👍

Önemli Bilgi

Bu dokümanda yer alan endpoint url'leri test ortamına aittir. Dokumanda sayfasında test ortam endpointleri test edilebilir. Canlı ortam url'leri endpoint içinde "-sit" ifadesi kaldırılarak oluşturabilirsiniz. Canlı ortam endpoint'ine canlı ortam için verilen User/Password ile istek gönderilebilir.

📘

Hepsiburada API Authentication Bilgilendirmesi

Mevcuttaki tüm servislerimizin authentication yapısında değişiklik yapılmıştır. Sizlerden servislerimizdeki bu değişikliğin hızla yapılması noktasında desteğinizi rica ederiz.

Entegratöre Servis Anahtarı Ekleme/Görüntüleme işlemleri için hazırladığımız sayfamızı inceleyebilirsiniz.

Listing Bilgilerini Çekme

  • Satıcının tüm listing bilgilerini çekmek istediğinizde pagination kullanımı zorunludur.
  • Test ortamında örnek listingler oluşturduk.Bu örnek listingler ile test işlemlerinizi tamamlayabilirsiniz.​
  • API, HTTP Basic Auth. ile korunmaktadır, dolayısıyla istemci, kullanıcı adı ve şifreyi HTTP Authorization Header bilgisinde göndermelidir.
  • Hepsiburadasku ve merchantsku bilgisi ile de satıcı listing bilgisi sorgulayabilirsiniz.

    • Alan Açıklamaları
    Alan Adı Açıklama
    HepsiburadaSku
    Listinglerin Hepsiburada tarafındaki uniqueId değeridir.
    MerchantSku
    Listinglerin Merchantlar tarafındaki uniqueId değeridir.
    Price
    Listingin fiyatıdır.
    AvailableStock
    Listingin stok bilgisidir.
    DispatchTime
    Listingin kargoya veriliş süresidir.
    CargoCompany1
    Listingin üzerinde tanımlı olan kargo firmasıdır.
    CargoCompany2
    Listingin üzerinde tanımlı olan kargo firmasıdır.
    CargoCompany3
    Listingin üzerinde tanımlı olan kargo firmasıdır.
    ShippingAddressLabel
    Göndericinin adres satırıdır.
    shippingProfileName
    Sku'nun tanımlı olduğu teslimat profili bilgisidir.
    ClaimAddressLabel
    İade ve talepler için adres satırıdır.
    Pricing.FinalPrice
    İndirim ve kampanyalardan sonra satış fiyatıdır.
    Pricing.StartDate
    Kampanyanın başlama tarihini verir.
    Pricing.EndDate
    Kampanyanın bitiş tarihini verir.
    Pricing.Debtor
    Kampanya tanımlı listingin hangi firma tarafından karşılanacağını isim olarak belirtir.
    Pricing.Amount
    Kampanya tanımlı listingin yüzdelik olarak karşılanacağı
    MaximumPurchasableQuantity
    Listingin bir seferde alınabilecek maximum adet sayısıdır.
    IsSalable
    Listingin satış durumunu belirtir. True: satışta / False: satışta değil.
    CustomizableProperties
    Listingin özelleştirilebilir ürün olduğunu belirtir.
    IsSuspended
    Listingin askı durumunu belirtir. True: Askıda / False: Askıda değil.
    IsLocked
    Listingin kilit durumunu gösterir. True: kilitli / False: kilitli değil.
    LockReasons
    Listingin kilitlenme nedenini belirtir.
    IsFrozen
    Listingin dondurulma durumunu belirtir.
    CommissionRate
    Listing üzerine uygulanan Hepsiburada.com'un aldığı komisyonu belirtir.
    priceIncreaseDisabled
    Fiyat artışı kapalı
    priceDecreaseDisabled
    Fiyat düşürme kapalı
    stockDecreaseDisabled
    Stok düşürme kapalı

    Hata Durumları

    Hata Kodu
    Hata Mesajı
    400
    Bad Request: URL içerisindeki parametreleri kontrol edin.
    401
    Unauthorized: Password (Şifre) hatalı girilmiştir. Lütfen kontrol ediniz.
    404
    Not Found: URL hatalı gönderilmiştir. Lütfen kontrol ediniz.
    405
    Not Allowed: Http Protokol hatası. Lütfen kontrol ediniz.
    500
    Internal Server: Lütfen Ticket ileterek entegrasyon ekibi ile iletişime geçiniz.

    Listing Bilgilerini Güncelleme

    • API, HTTP Basic Auth. ile korunmaktadır, dolayısıyla istemci, kullanıcı adı ve şifreyi HTTP Authorization Header bilgisinde göndermelidir.
    • Listing güncelleme için aynı anda POST ettiğiniz devam eden / bekleyen işlemlerin sayısı 5’i geçemez. Günlük toplu güncelleme limitinizin sınırını aştınız.
    • Her satıcının günlük toplu limit sayısı listing sayısının 10 katı kadardır. Yani bir satıcının 100 adet listingi var ise bir gün içerisinde 1000 listing güncelleme limitidir.
    • Eğer bir listing satışa kapatılmak isteniyorsa stok veya fiyat bilgisinin sıfır gönderilmesi yeterlidir.
    • Eğer bir listing satışa açılmak isteniyorsa fiyat ve stok bilgisinin sıfırdan farklı bir değer gönderilmesi yeterlidir.
    • Listeleme Entegrasyonu, listing bilgilerini güncelleme servislerimizde yeni yapımızda kategori bazlı threshold değerlerine geçiş sağlanmış ve yeni hata mesajları eklenmiştir. Bu yapı ile birlikte fiyat artırma yada düşürme işlemlerinde threshold değerlerinin dışında bir fiyat güncellemesi yapılırsa ilgili sku kilitlenecektir. Listinglerinizin kilitlenmesi durumunda aşağıdaki aksiyonlardan birini uygulamanız gerekmektedir.
      1. Listing güncellemeden sonra yaptığınız listing güncelleme sorgulama servisinin reponse bilgisi içerisinde hata mesajı ile birlikte hata alan listingin girilebilecek maximum ve minimum değerleri iletilecektir. Size iletilen bu değerler arasında tekrar bir fiyat güncellemesi gönderirseniz kilit kaldırma api kullanmadan otomatik olarak sistem listingi satışa açacaktır. Aşağıda örnek reponse bilgisine görebilirsiniz.
      2. Eğer güncellenen fiyatın doğru olduğuna eminseniz ve gerçekten bu fiyattan listingi satışa açmak istiyorsanız kilit kaldırma api ile listingin üzerindeki kiliti kaldırabilir ve listingi girmiş olduğunuz son fiyat üzerinden satışa açabilirsiniz.
        Kilit kaldırma dokümanı : https://developers.hepsiburada.com/hepsiburada/reference/toplu-kilit-kaldırma 
      {
    "id": "715bae7f-2b90-4e88-9067-uhu7656892123",
    "status": "Done",
    "createdAt": "2023-10-02T11:09:16.334Z",
    "total": 1,
    "errors": null,
    "priceValidations": [
        {
            "elementNo": 1,
            "hepsiburadaSku": "HBCV00002LJ9YU",
            "merchantSku": "TESTTİRİTOSTTOST",
            "type": "MaxLock",
            "minPrice": 899.8,
            "maxPrice": 13767.0,
            "description": "Yüksek fiyat sebebiyle kilitlendi. Yapılan fiyat değişimi platform genelindeki fiyat aralıkları dışındadır, ürününüz kilitlenmiştir. Girmiş olduğunuz fiyattan eminseniz ürünün kilidini Envanter ekranından toplu olarak kaldırabilir veya önerilen aralıklarda tekrar fiyat girişi yapabilirsiniz."
        }
    ]
}

{
    "id": "715bae7f-2b90-4e88-9067-uhu7656892456",
    "status": "Done",
    "createdAt": "2023-10-02T11:48:59.417Z",
    "total": 1,
    "errors": null,
    "priceValidations": [
        {
            "elementNo": 1,
            "hepsiburadaSku": "HBCV00002LJ9YU",
            "merchantSku": "TESTTİRİTOSTTOST",
            "type": "MinLock",
            "minPrice": 899.8,
            "maxPrice": 13767.0,
            "description": "Düşük fiyat sebebiyle kilitlendi. Yapılan fiyat değişimi platform genelindeki fiyat aralıkları dışındadır, ürününüz kilitlenmiştir. Girmiş olduğunuz fiyattan eminseniz ürünün kilidini Envanter ekranından toplu olarak kaldırabilir veya önerilen aralıklarda tekrar fiyat girişi yapabilirsiniz."
        }
    ]
}
    • Sadece HepsiJet kargo firmasını seçtiyseniz yanında standart bir kargo firması da seçmeniz gerekmektedir. Standart bir kargo firması seçmediğiniz durumda hata mesajı olarak MissingStandartCargoCompany dönecektir.
    • Listing servisinde kargo firması isimleri yazım formatı ve örnek listesi aşagıdaki gibidir; Yurtiçi Kargo Aras Kargo PTT Kargo Borusan Lojistik Horoz Lojistik HepsiJet MNG Kargo Sürat Kargo Ceva Lojistik UPS Mağaza Hesabı
    • ShippingProfileName bilgisi merchant panel'den oluşturulan teslimat profillerinin sku'lara tanımlanmasını ifade eder. Tanımlanan teslimat profiline göre siparişlerde kargo firmasıda buna göre oluşacaktır.
    • Bilgilerden; ProductName, ShippingProfileName ve MaximumPurchasableQuantity haricindeki tüm bilgilerin gönderilmesi zorunludur.
    • Json formatında örnekteki gibi response almak için headers kısmında “key”: “Accept”, “value”: “application/json” formatında gönderilmesi gerekir.
    • Xml almak istenirse headers kısmında “key”: “Accept”, “value”: “application/xml” formatında gönderilmesi gerekir.
    • Göndermiş olduğunuz istek başarılı bir şekilde iletilmiş ise yukarıdaki şekilde Inventory Upload Id dönecektir, bu inventory upload id bilgisini daha sonra Listing Güncelleme İşlem Kontrolü metodunda kullanacaksınız.
    • Göndermiş olduğunuz istek içerisinde eksik alan ile gönderimi yada endpoint isteğinde hata alındıysa Inventory Upload Id dönmeyecektir. Hata bilgisi işlem response’unda dönecektir. Ayrıca detay bilgi istenmesi durumunda response headers kısmındaki “x-correlation-id” değeri ile bu detaylar sorgulanabilir.
    • “x-correlation-id” değeri ile son 7 güne kadar istek durumunu kontrol edebiliriz. Bu kontrol için id bilgisi ile satıcı destek panelinden kayıt açılması gerekmektedir.
    • price-uploads / stock-uploads body’de HepsiburadaSku bilgisi ve MerchantSku bilgisi tek basina olabilir veya ikiside ayni anda olabilir.

      • XML olarak body gönderebilmek için örnektir:
      İlgili servise ait örnek XML request ve response body içerikleri aşağıdaki gibidir. http isteğin header kısmında da Content-Tpye=application/xml olarak giriş yapmanız gerekmektedir.

      <?xml version="1.0" encoding="utf-8"?>
<listings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <listing>
            <HepsiburadaSku>HBV00000TWKQJ</HepsiburadaSku>
            <MerchantSku>HBV00000TWKQJ_TEST</MerchantSku>
            <ProductName>Brita Intenza + Su Filtresi Kahve Makineleri Için</ProductName>
            <Price>118,97</Price>
            <AvailableStock>9</AvailableStock>
            <DispatchTime>3</DispatchTime>
            <MaximumPurchasableQuantity>0</MaximumPurchasableQuantity>
            <ShippingProfileName>MigratedProfile_2020-11-18 13:48:11.408</ShippingProfileName>
            </listing>
            <listing>
            <HepsiburadaSku>HBV00000WNZEH</HepsiburadaSku>
            <MerchantSku>HBV00000WNZEH_TEST</MerchantSku>
            <ProductName>Limon İle Zeytin:Kahraman Zeytin- Sesli Kitap</ProductName>
            <Price>11</Price>
            <AvailableStock>999</AvailableStock>
            <DispatchTime>3</DispatchTime>
            <MaximumPurchasableQuantity>0</MaximumPurchasableQuantity>
            <ShippingProfileName>MigratedProfile_2020-11-18 13:48:11.408</ShippingProfileName>
            </listing>
</listings>

      <?xml version="1.0"?>
<Result xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Id>3957bf91-a1ee-4657-92a0-fcb07bb69d83</Id>
</Result>

      Alan açıklamaları

      Alan Adı Açıklama
      HepsiburadaSku
      Listinglerin Hepsiburada tarafındaki uniqueId değeridir.
      MerchantSku
      Listinglerin Merchantlar tarafındaki uniqueId değeridir.
      ProductName
      Listingin Hepsiburada.com üzerinde görünen adıdır.
      Price
      Listingin fiyatıdır.
      AvailableStock
      Listingin stok bilgisidir.
      DispatchTime
      Listingin kargoya veriliş süresidir.
      MaximumPurchasableQuantity
      Listingin bir seferde alınabilecek maximum adet sayısıdır.
      Bu değer 0 olarak gönderilirse sınırsız anlamına gelmektedir. 
      CargoCompany1
      Listingin üzerinde tanımlı olan kargo firmasıdır.
      CargoCompany2
      Listingin üzerinde tanımlı olan kargo firmasıdır.
      CargoCompany3
      Listingin üzerinde tanımlı olan kargo firmasıdır.

      Response Uyarı Açıklamaları​

      Hata Adı Açıklama
      ProductNotFound
      Girilen HBSku bilgisi kataloğumuzda yer almıyor ise dönen hatadır.
      MismatchingSkusSpecified
      Girilen HBSku ve MerchantSku bilgileri yanlış eşleştirildiğinde alınan hatadır.
      DuplicateHepsiburadaSkuSpecified
      Yollanılan XML dosyası ya da yüklenen excel dosyasının içerisinde birden fazla HBSku kodu bulunduğu zaman alınan hatadır.
      DuplicateMerchantSkuSpecified
      Yollanılan XML dosyası ya da yüklenen excel dosyasının içerisinde birden fazla MerchantSku kodu bulunduğu zaman alınan hatadır.
      MissingHeaders
      Yollanılan XMl dosyasında tag yada excel dosyasında başlık eksik ise alınan hatadır.
      InvalidPrice
      Fiyat bilgisi decimal dışında bir değer girildiği zaman alınan hatadır. Aynı zamanda fiyat bilgisi nokta ile yazıldığında da dönülmektedir.
      InvalidAvailableStock
      Stok bilgisi tam sayı dışında bir değer girildiği zaman alınan hatadır.
      InvalidDispatchTime
      Kargoya veriliş süresi tam sayı dışında bir değer girildiği zaman alınan hatadır.
      DiscountedListingPriceIncrease
      Kontrol edildiğinde ürün güncelleme işleminde " Girilen Fiyat indirim süresince geçerli değerden daha yüksek " olduğundan hata alınmıştır.
      MerchantAlreadyListedAgainstProduct
      Ürün mükerrer yaratılmış gözükmektedir. Bu yüzden ürünü güncelleyemiyorsunuz. Askıda olan ürünün silinmesi gereklidir.
      ListingDeletedRecently
      Silinmiş yada listingler arasında olmayan sku için güncelleme gönderilemez.
      ListingFrozen
      Kilitli listing için güncelleme yapılamaz.
      MissingStandardCargoCompany
      Listing güncellemede CargoCompany kısmında tanımlanan kargo firması tek basına tanımlanamaz, Tanımlanan kargo firması ile birlikte standart bir kargo firması daha CargoCompany2 alanında tanımlanması gerekir.  Kargo firması bilgisinde HepsiJet, Horoz, Borusan gibi kargolar tek kargo firması olarak gönderildiğinde MissingStandardCargoCompany uyarısı alınır.
      OutOfPriceRange
      Canlı sistemde yanlış fiyatlandırmalara karşı çalışan bir mekanizma bulunmaktadır. Listelenmiş yayındaki fiyatların en düşüğü ve en yükseği hariç diğerlerinin ortalaması alınarak 0 TL – 50 TL arası => %250 50 TL – 100 TL arası => %150 100 TL – 200 TL arası => %120 200 TL – 500 TL arası => %100 500 TL – 2000 TL arası => %90 2000 TL üzeri => %80 maximum fiyat girilebilir. Eğer bu değerin dışında bir değer girilirse outofpricerange hatası alınacaktır.
      restrictedProductBrand
      Bu ürün üzerinde marka kısıtı olduğu gözükmektedir. Bu ürünü satabilmek adına alınması gereken aksiyonlar bulunmaktadır. Kategori yöneticiniz ile iletişime geçerek bu kısıtın nasıl kaldırılacağını görüşebilirsiniz.

      Listing Güncelleme İşlem Kontrolü

      Bu metod listing güncelleme için göndermiş olduğunuz isteklerin başarılı/başarısız durumlarını kontrol etmenize olanak tanır.

    • Göndermiş olduğunuz request içerisindeki bütün listingler hatasız bir şekilde tamamlandıysa aşağıdaki gibi response içerisinde herhangi bir hata dönmeyecektir.
    • Göndermiş olduğunuz request içerisindeki listinglerden hata alan bir satır var ise aşağıdaki gibi error parametresi içerisinde HBSKU, MerchantSku, listing update endpointinde göndermiş olduğunuz request içerisindeki sırası ve hata nedeniyle birlikte response olarak dönecektir.

      • Alan Açıklamaları

      Alan Adı Açıklama
      Id
      Listing güncelleme işlem kontrolü için gerekli Id değeridir. listing update işleminden sonra response içerisinde dönülür.
      Status
      Gönderilen requestin başarı durumunu belirtir. Done: Tamamlandı / Failed: hata aldı.
      Processed
      Listingin Hepsiburada.com üzerinde görünen adıdır.
      Total
      Listing update işlemi için göndermiş olduğunuz request içerisindeki toplam listing sayısıdır.
      Errors.Error.ElementNo
      Listing update endpointinde göndermiş olduğunuz request içerisindeki sırasını belirtir.
      Errors.Error.HepsiburadaSku
      Hata alan listingin HBSKU değeridir.
      Errors.Error.MerchantSku
      Hata alan listingin MerchantSku değeridir.
      Errors.Error.Errors.string
      Hata alan listingin hata nedenini belirtir.

      Responce Uyarı Açıklamaları

      Hata Adı Açıklama
      ProductNotFound
      Girilen HBSku bilgisi kataloğumuzda yer almıyor ise dönen hatadır.
      MismatchingSkusSpecified
      Girilen HBSku ve MerchantSku bilgileri yanlış eşleştirildiğinde alınan hatadır.
      DuplicateHepsiburadaSkuSpecified
      Yollanılan XML dosyası ya da yüklenen excel dosyasının içerisinde birden fazla HBSku kodu bulunduğu zaman alınan hatadır.
      DuplicateMerchantSkuSpecified
      Yollanılan XML dosyası ya da yüklenen excel dosyasının içerisinde birden fazla MerchantSku kodu bulunduğu zaman alınan hatadır.
      MissingHeaders
      Yollanılan XMl dosyasında tag yada excel dosyasında başlık eksik ise alınan hatadır.
      InvalidPrice
      Fiyat bilgisi decimal dışında bir değer girildiği zaman alınan hatadır. Aynı zamanda fiyat bilgisi nokta ile yazıldığında da dönülmektedir.
      InvalidAvailableStock
      Stok bilgisi tam sayı dışında bir değer girildiği zaman alınan hatadır.
      InvalidDispatchTime
      Kargoya veriliş süresi tam sayı dışında bir değer girildiği zaman alınan hatadır.
      DiscountedListingPriceIncrease
      Kontrol edildiğinde ürün güncelleme işleminde " Girilen Fiyat indirim süresince geçerli değerden daha yüksek " olduğundan hata alınmıştır.
      MerchantAlreadyListedAgainstProduct
      Ürün mükerrer yaratılmış gözükmektedir. Bu yüzden ürünü güncelleyemiyorsunuz. Askıda olan ürünün silinmesi gereklidir.
      ListingDeletedRecently
      Silinmiş yada listingler arasında olmayan sku için güncelleme gönderilemez.
      ListingFrozen
      Kilitli listing için güncelleme yapılamaz.
      MissingStandardCargoCompany
      Listing güncellemede CargoCompany kısmında tanımlanan kargo firması tek basına tanımlanamaz, Tanımlanan kargo firması ile birlikte standart bir kargo firması daha CargoCompany2 alanında tanımlanması gerekir.  Kargo firması bilgisinde HepsiJet, Horoz, Borusan gibi kargolar tek kargo firması olarak gönderildiğinde MissingStandardCargoCompany uyarısı alınır.
      OutOfPriceRange
      Fiyat hatalarına karşı tedbirli olmanız gerekmektedir. Canlı sistemde yanlış fiyatlandırmalara karşı çalışan bir mekanizma bulunmaktadır. Listelenmiş yayındaki fiyatların en düşüğü ve en yükseği hariç diğerlerinin ortalaması alınarak 0 TL – 50 TL arası => %250 50 TL – 100 TL arası => %150 100 TL – 200 TL arası => %120 200 TL – 500 TL arası => %100 500 TL – 2000 TL arası => %90 2000 TL üzeri => %80 maximum fiyat girilebilir. Eğer bu değerin dışında bir değer girilirse outofpricerange hatası alınacaktır.
      restrictedProductBrand
      Bu ürün üzerinde marka kısıtı olduğu gözükmektedir. Bu ürünü satabilmek adına alınması gereken aksiyonlar bulunmaktadır. Kategori yöneticiniz ile iletişime geçerek bu kısıtın nasıl kaldırılacağını görüşebilirsiniz.
      InvalidMaximumPurchasableQuantity
      Geçersiz Maksimum Satın Alınabilir Miktar.

      Listing Silme

      Bu metod satıcıya ait listinglerin silinmesine olanak tanır.

    • API, HTTP Basic Auth. ile korunmaktadır, dolayısıyla istemci, kullanıcı adı ve şifreyi HTTP Authorization Header bilgisinde göndermelidir.
    • Satışta olan bir listingi silemezsiniz.

      • Listing Satışa Açma/Kapatma

      Bu metod satıcıya ait listinglerin satışa açmanıza veya kapatmanıza olanak tanır.

    • Listingi satışa açabilmek için stok ve fiyat bilgisinin daha önceden girilmiş olması gereklidir. Stok ve fiyat bilgisi 0 olan listingler bu endpoint üzerinden satışa açılamaz.
    • Listingi satışa kapatmak için isterseniz stok ve fiyat bilgisini 0 gönderebilir, isterseniz Listing Satışa Açma/Kapatma endpointimizi kullanabilirsiniz.

      • Buybox Bilgilerini Listeleme

      Bu metod satıcıya ait listinglerin satış sırasını listeleme bilgilerine ulaşmanıza olanak sağlar. Satıcı Listing Bilgilerini Çekme endpoint’inden dönen responce içerisinde IsSalable=true olan sku için buybox sorgusu yapılabilir. Maximum 10 sku’ya kadar aralarına virgül ile ayrıştılarak istek gönderilebilir.

      Alan Açıklamaları

      Alan Adı Açıklama
      SKU
      Listinglerin Hepsiburada tarafındaki uniq değeridir.
      Rank
      Listinglerin satış sıralama değeridir.
      Price
      Listingin fiyatıdır.
      Dispatch Time
      Listingin kargoya veriliş süresi
      MerchantRating
      Merchantların mağaza puan değeridir.

      ShippingProfileName Listeleme

      Bu metod merchant üzerinde tanımlı olan teslimat profil isimlerinin listelenmesini sağlar.

      Alan Açıklamaları

      Alan Adı Açıklama
      Name
      Teslimat profilinin isim bilgisidir.
      CreatedAt
      Teslimat profilinin oluşturulduğu tarih bilgisidir.
      UpdatedAt
      Teslimat profilinin son güncellendiği tarih bilgisidir
      Id
      Teslimat profilinin unique id bilgisidir

      Toplu Kilit Kaldırma

      Bu metod satıcıya ait listinglerin güncelleme işlemi sonrası alınan MinLock ve MaxLock uyarıları sonrasında girilen fiyatlardan dolayı kilitlenen ürünlerin api üzerinden toplu olarak girilen fiyatlarla kilitinin kaldırılması ve satışa açılması işlemi için kullanılmaktadır.