Siparis Entegrasyonu Onemli Bilgiler

👍

Ö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.

📘

Hepsiburada Sipariş Entegrasyonu Limitleri

Sipariş Entegrasyonu servislerimize SIT(Test) ve Prod(Canlı) ortamlarımızda gelen isteklerde bir limit değeri eklenecektir. Kullanıcılarımız artık belirli bir zaman dilimi içerisinde limit değeri kadar (10 saniye içerisinde 10k) istek gönderililebiliyor olacak. Limit değerini aşan istekler için 429 TooManyRequest hatası alınacaktır.Bununla birlikte response header içerisinde aşağıdaki bilgiler dönülüyor olacaktır.

X-RateLimit-Remaining : Geçerli zaman aralığında kalan istek sayısı
X-RateLimit-Limit : İzin verilen maksimum request sayısı
X-RateLimit-Reset : Geçerli zaman aralığının yenilenmesine kalan saniye

Test İçin Sipariş Oluşturma

Bu işlev yalnızca TEST ortamında mevcuttur. Testlerinizi tamamlayabilmeniz için sipariş oluşturmanıza 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.
  • Merchantid (gerekli, guid, b2910839-83b9-4d45-adb6-86bad457edcb) Her satıcının unique bir tanımlayıcısıdır.
  • Ordernumber (gerekli, string,0116431) Sipariş numarası unique bir değer olmalıdır, sipariş oluştururken rastgele değiştirebilirsiniz.
  • LineItems Doğru bir hbsku değeri ile bir siparişte istediğiniz sayıda lineitem oluşturabilirsiniz. (Aşağıdaki örnek 2 adet lineitem için oluşturulmuştur.)
  • LineItems.MerchantId MerchantId parametresi URL de sağlanan MerchantId ile aynı olmalıdır.
{
"OrderNumber":"041241341",
"OrderDate":"2018-12-21T09:34:47",
"Customer":{
   "CustomerId":"dfc8a27f-faae-4cb2-859c-8a7d50ee77be",
   "Name":"Test User"
},
"DeliveryAddress":{
   "AddressId":"e66765b3-d37d-488c-ae15-47051245dc9b",
   "Name":"Hepsiburada Office",
   "AddressDetail":"Trump Towers",
   "Email":"[email protected]",
   "CountryCode":"TR",
   "PhoneNumber":"902822613231",
   "AlternatePhoneNumber":"045321538212",
   "Town":"Sisli",
   "District":"Kustepe",
   "City":"İstanbul"
},
"LineItems":[
   {
      "Sku":"HBV0000106NM0",
      "MerchantId":"823539cd-1f10-4971-8859-cd648cfb4ff6",
      "Quantity":1,
      "Price":{"Amount":301.4,"Currency":"TRY"},
      "Vat":0,
      "TotalPrice":{"Amount":301.4,"Currency":"TRY"},
      "CargoCompanyId":1,
      "DeliveryOptionId":1
   },
   {
      "Sku":"HBV0000106NLG",
      "MerchantId":"823539cd-1f10-4971-8859-cd648cfb4ff6",
      "Quantity":1,
      "Price":{"Amount":301.4,"Currency":"TRY"},
      "Vat":0,
      "TotalPrice":{"Amount":301.4,"Currency":"TRY"},
      "CargoCompanyId":1,
      "DeliveryOptionId":1
   }
]
}

Ödemesi Tamamlanmış Siparişleri Listeleme

Bu metod ödemesi tamamlanmış yeni siparişleri (Paketlenecek statüdekileri) listeleyebilmenize olanak tanır.

  • API üzerinden sadece ödemesi tamamlanan siparişler gelecektir. Merchant Panel üzerinde ise Paketlencekler kısmına karşılık gelir. Havaleli olan siparişlerinde ödemesi tamamlandıktan hemen sonra API üzerinden akıtılmaktadır. Havaleli siparişlerin ön bilgileri "Ödemesi Beklenen Siparişler" servisinden alınarak stok rezervesi yapılabilir.
  • Offset, Limit(opsiyonel, int) Offset ve Limit birbirine bağlı iki parametredir. Sadece bir tanesi gönderildiğinde hata alınacaktır. Kullanım zorunludur.
  • Limit Offset pagenation yapısı olarak işlev görmektedir. Limit bir sayfada kaç adet sipariş listeleneceğini belirtirken, Offset hangi siparişten sonraki siparişlerin gösterileceğini belirtir.
  • Limit:10 Offset:0 gönderildiğinde ilk 10 sipariş listelenecektir. Limit:10 Offset:10 gönderildiğinde ilk 10 siparişten sonraki 10 sipariş listelenecektir.
  • Opsiyonel olan begindate ve enddate parametrelerini kullandığınızda statüleri Open ve Unpacked durumunda olan siparişlerinizi belirli bir tarih arasında listeleyebilirsiniz.
  • Ödemesi tamamlanmış siparişler endpointinden sonraki adım olan Aynı Pakete Konulabilecek Kalemleri Listeleme endpoint'idir.
    Alan Açıklamaları
Alan Adı Açıklama
totalCount
Anlık olarak kaç adet ödemesi tamamlanan siparişinizin olduğunu belirtir.
limit
Bir sayfada kaç adet siparişin listeleneceğini belirtir.
offset
Hangi siparişten sonraki siparişlerin listeleneceğini belirtir.
pageCount
Toplam kaç adet sayfa olacağını belirtir.
items.dueDate
Siparişin kargoya verilmesi gereken son teslim tarihini belirtir.
items.lastStatusUpdateDate
Sipariş içerisinde bulunan kalemin en son işlem gördüğü tarihtir.
items.id
Sipariş içerisindeki kalemlerin unique değeridir. (Aynı pakete konulabilecek kalemleri listeleme endpointinde kullanılacaktır.)
items.sku
Sipariş içerisindeki listinglerin HBSKU değeridir.
items.orderId
Siparişin hepsiburada tarafında unique değeridir.
items.orderNumber
Sipariş numarasıdır.
items.orderDate
Siparişin oluşturulma tarihidir.
items.quantity
Siparişin içerisindeki kalemlerin adet sayısıdır.
items.merchantId
Merchantın uniqueId değeridir. (Test(SIT) ve canlı ortam için merchantId bilgisi hepsiburada.com tarafından iletilecektir.)
items.totalPrice.currency
Siparişteki kalemlerin her birinin toplam adet tutarının para birimi cinsinden değeridir.
items.totalPrice.amount
Siparişteki kalemlerin her birinin toplam adet tutarıdır.
items.unitPrice.currency
Siparişteki tek bir kalemin tutarının para birimi cinsinden değeridir.
items.unitPrice.amount
Siparişteki tek bir kalemin tutarının değeridir.
items.vat
KDV tutarıdır.
items.vatRate
KDV oranıdır.
items.customerName
Müşterinin adıdır.
items.status
Siparişin durumunu belirtir. Open: Yeni sipariş belirtir. / Unpacked: Paketi bozulan siparişleri belirtir.
items.shippingAddress
Teslimat adresidir.
items.invoice
Fatura bu alan içerisindeki bilgiler ile oluşturulmalıdır.
items.invoice.turkishIdentityNumber
Müşterinin T.C numarasıdır.
items.invoice.taxNumber
Müşterinin vergi dairesinin numarasıdır.
items.invoice.taxOffice
Müşterinin vergi dairesinin adıdır.
items.invoice.address
Siparişin fatura adresidir.
items.invoice.address.addressId
Siparişin hepsiburada.com üzerindeki unique değeridir.
items.invoice.address.address
Fatura adresinin açık adresidir.
items.invoice.address.name
Fatura adresinin isim bilgisidir.
items.invoice.address.email
Fatura adresinin mail bilgisidir.
items.invoice.address.countryCode
Fatura adresinin ülke bilgisinin kısa kodudur.
items.invoice.address.phoneNumber
Fatura adresinin telefon numarasıdır.
items.invoice.address.alternatePhoneNumber
Fatura adresinin alternarif telefon numarasıdır.
items.invoice.address.district
Fatura adresinin mahalle bilgisidir.
items.invoice.address.city
Fatura adresinin şehir bilgisidir.
items.invoice.address.town
Fatura adresinin ilçe bilgisidir.
items.sapNumber
Hepsiburada.com tarafında siparişin içerisinde bulunan kalemlerin sıra bilgisini verir.
items.dispatchTime
Siparişin kargoya verilme süresidir.
items.commission
Hepsiburada.com üzerinden alınan komisyondur.
items.commission.currency
Hepsiburada.com üzerinden alınan komisyon bedelinin komisyon cinsinden değeridir.
items.commission.amount
Hepsiburada.com üzerinden alınan komisyon bedelidir.
items.paymentTermInDays
Listing bazında merchanta ödeme yapılacağı gün verisidir.
items.commissionType
Hepsiburada.com tarafındaki komisyon bedelinin unique değeridir.
items.cargoCompanyModel.id
Kargo firmasının hepsiburada.com üzerindeki unique değeridir.
items.cargoCompanyModel.name
Listingin üzerine tanımlı kargo firmasının isim bilgisidir.
items.cargoCompanyModel.shortName
Listingin üzerine tanımlı kargo firmasının kısa isim bilgisidir.
items.cargoCompanyModel.logoUrl
Listingin üzerine tanımlı kargo firmasının logo url bilgisidir.
items.cargoCompanyModel.trackingUrl
Listingin paketlendikten sonraki kargo takip urlini belirtir.
items.cargoCompany
Listingin üzerine tanımlı kargo firmasının isim bilgisidir.
items.customizedText01
Özelleştirilebilir ürünün içerik bilgisini verir.
items.customizedText02
Özelleştirilebilir ürünün içerik bilgisini verir.
items.customizedText03
Özelleştirilebilir ürünün içerik bilgisini verir.
items.customizedText04
Özelleştirilebilir ürünün içerik bilgisini verir.
items.customizedTextX
Özelleştirilebilir ürünün içerik bilgisini verir.
items.creditCardHolderName
Sipariş verilen kartın üzerinde bulunan isim bilgisidir.
items.isCustomized
Sipariş verilen kalemin kişinin isteklerine göre özelleştirilebilir ürün olduğunu belirtir. True: Özelleştirilebilir ürün. False: Özelleştirilemeyen ürün
items.canCreatePackage
Ürünün paketlenebilir ürün olduğunu belirtir.
items.isCancellable
Listingin iptal edilme durumudur. True: İptal edilebilir ürün / False: İptal edilemez ürün
items.isCancellableByHbAdmin
Listingin Hbadmin tarafından iptal edilebilirlik durumudur. True: Hbadmin tarafından iptal edilebiir. / False: Hbadmin tarafından iptal edilemez.
items.deliveryType
eslimatın teslim verisidir. StandardDelivery: Standart teslimat / BT: Bugün Teslimat / YT: Yarın teslimat
items.deliveryOptionId
Teslimatın teslim verisidir. 1: StandardDelivery / 2: BT(Bugün teslimat) / 4: YT(yarın teslimat)
items.slot
Müşterinin paketi teslim almak için seçtiği saat aralığıdır.
items.pickUpTime
Merchantın kargo firmasına teslim etmesi gereken saat aralığıdır.
unitmerchantDiscount.amount
Merchant tarafından uygulanan birim indirim tutarı
totalmerchantDiscount.amount
Merchant tarafından uygulanan toplam indirim tutarı
items.purchasePrice
Drop çalışan merchantlar için ürünün fiyat bilgisidir.
items.creationReason
Siparişin hangi method ile tekrar yaratıldığını iletmektedir.Yeni Yaratılan : OrderCreated Transfer için : OrderLineTransferred Resend için : OrderLineResend Değişim için : ClaimChangeAccepted Parçalı paketleme : DeliveryCreated

Ödemesi Beklenen Siparişleri Listeleme

Bu metod ödemesi tamamlanmamış (fraud kontrolü , havale ödemeleri) yeni siparişleri listeleyebilmenize olanak tanır.

  • Ödemesi tamamlanmamış siparişleri listeleme endpointine düşen siparişler kayıt altına alınarak rezerve stoklar oluşturulmalıdır.
  • Belirli periyotlar ile bu method çağırılmalı ve daha önceden gelen bir siparişin bu method üzerinde dönmediği görüldüğünde ödemesi tamamlanmış siparişleri listeleme endpointine istek atılmalıdır.
  • Eğer ödemesi tamamlanmış siparişleri listeleme endpointi üzerinde listeleniyor ise sipariş onaylanmıştır ve rezerve stok kaldırılarak gerçek stok onaylanabilir.
  • Eğer ödemesi tamamlanmış siparişleri listeleme endpointi üzerinde listelenmiyor ise ödemesi tamamlanmamış ve iptal olmuş demektir. Rezerve stok tekrardan artırılabilir.

Alan Açıklamaları

Alan AdıAçıklama
items.idSipariş içerisindeki kalemlerin unique değeridir.
items.skuSipariş içerisindeki listinglerin HBSKU değeridir.
items.nameSipariş içerisindeki listinglerin adını iletir
items.merchantSkuSipariş içerisindeki listinglerin satıcı stok kodu değeridir
items.OrderNumberSipariş içerisindeki listinglerin sipariş numarası değeridir
items.orderDateSiparişin oluşturulma tarihidir
items.quantitySiparişin içerisindeki kalemlerin adet sayısıdır
items.merchantIdMerchantın uniqueId değeridir. (Test(SIT) ve canlı ortam için merchantId bilgisi hepsiburada.com tarafından iletilecektir.)
PropertiesSipariş içerisindeki ürünlerin varyant özellik değeri bilgileridir.

Siparişin Kargo Firmasının Değiştirilmesi

Bu method Open statüdeki siparişlerin kargo firmalarının değiştirilmesine olanak tanır. Bu alanda sadece değiştirebileceğiniz kargo firmaları listelenir.

  • İlk olarak Ödemesi tamamlanmış siparişler endpointinden listelediğiniz kalemlere ait lineitemId bilgisini almanız gerekmektedir. Daha sonra listelenen kargo firmaları içerisinde ShortName değeri ile güncelleme işlemini yapabilirsiniz.

Hata Durumları

Hata KoduHata Mesajı
409Hata:Kargo değişimi yapılamıyor. ( Statusu uygun değildir. ) Openlar üzerinde işlem yapılmaktadır.

Paketli Siparişin Kargo Firmasının Değiştirilmesi

Bu method Open ve Package statüdeki paketlerin kargo firmalarının değiştirilmesine olanak tanır. Bu alanda sadece değiştirebileceğiniz kargo firmaları listelenir.

  • API, HTTP Basic Auth. ile korunmaktadır, dolayısıyla istemci, kullanıcı adı ve şifreyi HTTP Authorization Header bilgisinde göndermelidir.
  • İlk olarak packagenumber bilgisine sahip olmanız gerekmektedir. Daha sonra listelenen kargo firmaları içerisinde ShortName değeri ile güncelleme işlemini yapabilirsiniz.
  • Kargo değişiklğinde paket numarası ve barkod değişikliği olmayacaktır, aynı barkod kullanılmalıdır.

Hata Durumları​

Hata KoduHata Mesajı
409Hata:Kargo değişimi yapılamıyor. ( Statusu uygun değildir. )

Aynı Pakete Konulabilecek Kalemleri Listeleme

Bu metod aynı müşteriye gidecek olan tek paket içerisine girebilecek kalemleri görebilmenize olanak tanır.

  • Merchantid (gerekli, guid, b2910839-83b9-4d45-adb6-86bad457edcb) Her satıcının unique bir tanımlayıcısıdır. Lineitemid (gerekli, guid, 52910839-8369-4dg5-adb6-86bad457edcb) Her sipariş kaleminin unique bir tanımlayıcısıdır. (Bknz: Ödemesi Tamamlanmış Siparişleri Listeleme items.id)
  • Lineitemid (gerekli, guid, 52910839-8369-4dg5-adb6-86bad457edcb) Her sipariş kaleminin unique bir tanımlayıcısıdır. (Bknz: Ödemesi Tamamlanmış Siparişleri Listeleme items.id)
  • Bir sipariş içerisinde birden fazla kalem olabilir. Gömlek, pantolon ve ayakkabı aynı sipariş içerisinde ise her biri tek bir kalem olarak değerlendirilir. Url içerisindeki lineitemid alanına karşılık gelmektedir. Bu bilgiye ödemesi tamamlanmış siparişler endpointinde bulunan items.id alanından ulaşabilirsiniz.
  • Url içerisinde göndermiş olduğunuz items.id değeri response içerisinde bir daha sizlere dönmemektedir. Bu nedenle url içerisindeki items.id değerininde paketlerken kullanılması ve başta quantity değerinin alınması gerekmektedir.
  • Aynı Pakete Konulabilecek Kalemleri Listeleme enpointinden sonraki adım olan Kalem veya Kalemleri Paketleme enpointidir.
  • Beraber paketlenebilecek kalem bulunmadığı durumda 404 Not Found dönecektir.
  • İstekte gönderilen lineitemid open statüsünde değilse hata mesajı 409 Conflict dönecektir. Mesaj: Bu ürün paketlenemez.(line item:{lineitemid} can NOT be packaged!!!)

Alan Açıklamaları

Alan AdıAçıklama
lineItems.orderNumberİlgili kalemin sipariş numarasıdır
lineItems.lineItemIdİlgili kalemin unique değeridir
lineItems.quantityİlgili kalemin adet değeridir

Hata Durumları

Hata KoduHata Mesajı
400Bad Request: URL içerisindeki parametreleri kontrol edin.
401Unauthorized: Password ve şifre hatalı girilmiştir. Lütfen kontrol ediniz.
404Not Found: Paketlenecek başka bir ürün bulunamamıştır. URL içerisindeki Mevcut lineitemid ile paketlemeyi yapabilirsiniz.
405Not Allowed: Http Protokol hatası. Lütfen kontrol ediniz.
500Internal Server: İstek bilgilerini body ile kontrol etmenizi öneririz. Hata tekrarlı devam ederse ticket ileterek entegrasyon ekibi ile iletişime geçiniz.

Kalem veya Kalemleri Paketleme

Bu metod kalem veya kalemleri paketlemenize olanak tanır.

  • Merchantid (gerekli, guid, b2910839-83b9-4d45-adb6-86bad457edcb) Her satıcının unique bir tanımlayıcısıdır.
  • LineitemId(gerekli, guid, 32910839-83b9-4545-adb6-76dad457edc4) Paket içerisinde gönderilecek olan kalem.
  • Quantity (gerekli, int, 2) Paket içerisinde bulunan kalemin adet sayısı.
  • Sipariş üzerinde bir adres değişikliği yapıldıysa adres değişikliği süreci tamamlanana kadar “Order has an ongoing change address demand” hatası alınacaktır. Bu hata alındığında berlirli periyotlar ile tekrar paketleme denenmesi gerekmektedir.
  • Serial number alanı zorunlu değildir. ürüne ait seri numarasınıda geçmek istediğinizde iletebileceğiniz alandır.
  • Oluşturmuş olduğunuz paket numarası ile Paket Bilgilerini Listeleme endpointinden Kargo Barkod numarasına ulaşabilirsiniz.
  • Mağaza hesabı modelinde paketlemede kullanılacak bazı sortname bilgileri aşağıdaki gibidir.

Alan Açıklamalar

Alan AdıAçıklama
lineItemRequests.idİlgili kalemin unique değeridir
lineItems.quantityİlgili kalemin adet değeridir
packageNumberOluşturduğunuz paketin numarasıdır
parcelQuantityPaketteki koli adedi ( optional)
deciPaket deci bilgisi ( optional)

Hara Durumları

400Bad Request: URL içerisindeki parametreleri kontrol edin.
401Unauthorized: Password ve şifre hatalı girilmiştir. Lütfen kontrol ediniz.
404Not Found: URL hatalı gönderilmiştir. Lütfen kontrol ediniz. İstek gönderdiğiniz limeitem.Id ile paketlenebilecek bir lineıtem.Id bulunmamaktadır.
405Not Allowed: Http Protokol hatası. Lütfen kontrol ediniz.
409Conflict: İstek gönderdiğiniz lineıtem.Id ile iptal edilmiştir.
500Internal Server: İstek bilgilerini body ile kontrol etmenizi öneririz. Hata tekrarlı devam ederse ticket ileterek entegrasyon ekibi ile iletişime geçiniz.

Paket Bozma

Bu metod oluşturduğunuz paketleri bozmanıza olanak tanır.

  • Paket bozulduktan sonra paket içerisindeki kalemler tekrar ödemesi tamamlanmış siparişler end-point’inde listelenmeye başlayacaktır.

Bozulan (Unpack) Paket Bilgilerini Listeleme

Bu metod merchant’ların unpacked olan paketlerini görüntüleyebilmelerini sağlamaktadır.

  • API, HTTP Basic Auth. ile korunmaktadır, dolayısıyla istemci, kullanıcı adı ve şifreyi HTTP Authorization Header bilgisinde göndermelidir.
  • Bozulan (Unpack) paket bilgilerini listeleme endpointinde limit – offset yada beginDate – endDate parametreleri kullanarak istek göndermeniz gerekir.

Alan Açıklamaları

Alan AdıAçıklama
Total CountMerchant’a ait unpacked olan paketlerin toplam sayısı
Unpacked DatePaketin bozulma tarihi
Package NumberPaket numarası

Paket Bilgilerini Listeleme

Bu metod satıcıya ait paket bilgilerine ulaşmanıza olanak tanır.Paketlerin open statüsü vardır.Open statüsündeki paket gönderime hazır anlamına gelmektedir.

  • Paket bilgilerini listeleme endpointinde limit – offset yada beginDate – endDate parametreleri kullanarak istek göndermeniz performans açısından önem arz etmektedir.
  • Limit, offset, pagecount, totalcount datalarına response header’ından erişim sağlayabilirsiniz.
  • Begindate, Enddate parametresi 24 saatlik sorgular için geçerlidir. Eğer 24 saatin dışında bir aralık değeri verilirse sistem otomatik olarak Enddate parametresini ignore edecek, Begindate parametresinde girilen değerin üzerine 24 saat ekleyerek işlem yapacaktır. Paket kaybı olmaması adına sadece 24 saatlik aralık değeri girmeniz gerekmektedir.
  • Limit-offset parametresi kullanırken limit maximum 10 olacak şekilde kullanılmalıdır.
  • Timespan parametresi ile tek başına gönderimde sadece 24 saat değeri gönderilebilir ve son 24 saati kapsar eski tarihli açık siparişler için 24 saatlik tarih aralığı verileren begindate enddate ile çekilebilir.
  • Timespan limit offset ile birlikte kullanımda timespan değeri 24 saat’den büyük verilebilir.

Alan Açıklamaları

Alan Adı Açıklama
id Siparişin hepsiburada tarafında unique değeridir.
status Siparişin durumu belirtir
customerId Müşteri unique id değeridir.
orderDate Siparişin oluşturulma tarihidir.
dueDate Siparişin kargoya verilmesi gereken son teslim tarihini belirtir.
barcode Siparişin kargo barkod numarasıdır.
packageNumber Paket numarasıdır.
cargoCompany Siparişin tanımlı kargo firmasının isim bilgisidir.
shippingAddressDetail Teslimat adresidir.
recipientName Teslim alacak isim bilgisidir.
shippingCountryCode Ülke kısaltma bilgisi
shippingDistrict Teslimat adresinin mahalle bilgisidir.
shippingTown Teslimat adresinin ilçe bilgisidir.
shippingCity Teslimat adresinin şehir bilgisidir.
email Mail bilgisidir.
phoneNumber Telefon numarasıdır.
companyName Fatura kesilecek isim/şirket ünvanı
billingAddress Siparişin fatura adresidir.
billingCity Fatura adresinin şehir bilgisidir.
billingTown Fatura adresinin ilçe bilgisidir.
billingDistrict Fatura adresinin mahalle bilgisidir.
billingPostalCode Fatura adresinin posta kodu bilgisidir.
taxOffice Fatura vergi dairesi
taxNumber Vergi Numarası
identityNo TC Kimlik numarası
totalPrice.currency Paket içerisindeki kalemlerin her birinin toplam adet tutarının para birimi cinsinden değeridir.
totalPrice.amount Paket içerisindeki kalemlerin her birinin toplam adet tutarıdır.
items Kalemler
lineItemId Sipariş içerisindeki kalemlerin unique değeridir.
listingId Listing'in unique id değeridir.
merchantId Merchantın uniqueId değeridir.
hbSku Sipariş içerisindeki listinglerin HBSKU değeridir.
merchantSku Sipariş içerisindeki listinglerin Satıcı stok kodu değeridir.
quantity Siparişin içerisindeki kalemlerin adet sayısıdır.
price.currency Para birimi cinsinden değerdir.
price.amount Paket içindeki tek bir kalemin tutarının değeridir.
vat KDV tutarıdır.
totalPrice Paket içindeki kalemlerin her birinin toplam adet tutarıdır.
commission.currency Hepsiburada.com üzerinden alınan komisyon bedelinin komisyon cinsinden para birimi değeridir.
commission.amount Hepsiburada.com üzerinden alınan komisyon bedelidir.
commissionRate Komisyon oranı bilgisidir.
unitHBDiscount.amount Hepsiburada tarafından uygulanan indirim tutarı
totalHBDiscount.amount Hepsiburada tarafından uygulanan indirimin toplam tutarı
merchantUnitPrice Merchant birim satış fiyatı
merchantTotalPrice Merchantın toplam satış fiyat tutarı
cargoPaymentInfo Kargo bedeli satıcı mı müşteri mi karşılar bilgisidir.
customizedText01 Özelleştirilebilir ürünün içerik bilgisini verir.
customizedText02 Özelleştirilebilir ürünün içerik bilgisini verir.
customizedText03 Özelleştirilebilir ürünün içerik bilgisini verir.
customerName Müşterinin adıdır.
properties Siparişteki kalem'in varyant bilgileridir.(Renk, beden vs.)
productName Ürün adı bilgisidir.
orderNumber Sipariş numarası
orderDate Siparişin oluşturulma tarihidir.
deliveryType Teslimat türü
customerDelivery Randevulu siparişler için zaman aralığı
pickupTime Merchantın kargo firmasına teslim etmesi gereken saat aralığıdır.
weight Paketin ağırlık bilgisi
gtip ürünlerin gümrük vergileri için kullanılan koddur.
vatRate KDV oranıdır.
purchasePrice Drop çalışan merchantlar için ürünün fiyat bilgisidir.
discountToBeBilledToHB HB’ye faturalandırılacak indirim (KDV dahil) alanı ifade eder.
productBarcode SKU'nun EAN barcode bilgisini ifade eder.
unitmerchantDiscount.amount
Merchant tarafından uygulanan birim indirim tutarı
totalmerchantDiscount.amount
Merchant tarafından uygulanan toplam indirim tutarı
deptorDifferenceAmount satıcı tarafından uygulanan indirim tutarı
isCargoChangable Kargo değişikliğine uygun ise true değilse false değeri alır
creationReason
Siparişin hangi method ile tekrar yaratıldığını iletmektedir.Yeni Yaratılan : OrderCreated Transfer için : OrderLineTransferred Resend için : OrderLineResend Değişim için : ClaimChangeAccepted Parçalı paketleme : DeliveryCreated

Paket Bölme

Bu metod bir paketin kalem bazlı ayrılarak yeniden paketlenmesine olanak tanır.

  • Merchantid (gerekli, guid, b2910839-83b9-4d45-adb6-86bad457edcb) Her satıcının unique bir tanımlayıcısıdır.
  • packagenumber (gerekli, int, 5000031611) Her paketin unique bir tanımlayıcısıdır.
  • OrderLineId(gerekli, guid, 32910839-83b9-4545-adb6-76dad457edc4) Paket içerisinde gönderilecek olan kalem.
  • Quantity (gerekli, int, 2) Paket içerisinde bulunan kalemin adet sayısı.
  • parcelQuantity; Paketteki koli adedi ( optional)
  • deci;Paket deci bilgisi ( optional)

Pakette boşta kalan kalem veya kalemler varsa tek paket olarak otomatik paketlenir.

Hata Kodları

HataKodu Hata Mesajı
400
Bad Request: URL içerisindeki parametreleri kontrol edin.
401
Unauthorized: Password ve şifre hatalı girilmiştir. Lütfen kontrol ediniz.
404
Not Found: URL hatalı gönderilmiştir. Lütfen kontrol ediniz. İstek gönderdiğiniz limeitem.Id ile paketlenebilecek bir lineıtem.Id bulunmamaktadır.
405
 Not Allowed: Http Protokol hatası. Lütfen kontrol ediniz.
409
Conflict: İstek gönderdiğiniz lineıtem.Id ile iptal edilmiştir.
500
Internal Server: Lütfen Ticket ileterek entegrasyon ekibi ile iletişime geçiniz.

Paket İçin Kargo Bilgilerini Listeleme

Bu metod bir paketin taşıma durumunu ve kargo takip bilgisine ulaşmanıza olanak tanır.

  • 404 Not Found hatası alındığında cannot find package with package number response dönecektir.

Hata Kodları

Hata Kodu Hata Mesajı
400
Bad Request: URL içerisindeki parametreleri kontrol edin.
401
Unauthorized: Password ve ş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.

Alan Açıklamaları

Alan Adı Açıklama
packageNumber
Oluşturulan paketin numarasıdır.
barcode
Oluşturulan paketin kargo barkodudur.
status
Kargo durumunu belirten alandır. Intransit: Nakil halinde / Delivered: Teslim edildi.
cargoCompany
Paketin teslim edildiği kargo firmasını belirtir.
trackingInfoCode
Paketin kargo takip numarasıdır.
trackingInfoUrl
Paketin kargo takip url bilgisidir.

Siparişe Ait Detay Listeleme

Bu metod bir siparişe ait kalemlerin detaylarını listelemenize olanak tanır.

  • Ödemesi tamamlanmamış bir sipariş numarası ile istek gönderildiğinde hata mesajı dönecektir. Mesaj: Bu sipariş için sonuç bulunmadı, lütfen siparişin ödeme durumunu kontrol ediniz.

Statü Bilgileri

Status Açıklama
Open
Açık sipariş.
Packaged
Paketlenmiş sipariş.
CancelledByMerchant
Merchant tarafından iptal edilmiş sipariş.
Delivered
Teslim edilmiş sipariş.
InTransit
Kargoda olan sipariş.
ClaimCreated
Talep açılmış kalem.
CancelledByCustomer
Müşteri tarafından iptal edilmiş sipariş.
CancelledBySap
SAP tarafından iptal edilen sipariş Fraud vb durumlarda oluşur.

Fatura Linki Gönderme

Merchant tarafından kendi sisteminde yaratılmış E-Arşiv fatura bilgisini Hepsiburada sistemine transfer ederek müşteri (hepsiburada.com üzerinden sipariş veren) ile faturanın paylaşılması için bu method kullanılacaktır.
Bu servisin tetiklenmesi için fatura url’inin Content-type’ı “application/pdf” veya “text/html” olmalıdır.

Hata Durumları

Hata Kodu Hata Mesajı
400
Bad Request: Gönderilen link içeriği pdf formatında değil. Lütfen kontrol ediniz.
403
Forbidden Paket istek gönderilen merchant'a ait değil. Lütfen paket numaranızı kontrol ediniz.
409
Conflict: Pakete ait fatura eklenmiş.

Ortak Barkod Oluşturma

API, HTTP Basic Auth. ile korunmaktadır, dolayısıyla istemci, kullanıcı adı ve şifreyi HTTP Authorization Header bilgisinde göndermelidir.

  • Ortak barkod ilk aşamada yalnızca HepsiJet ve Aras kargo firmasını desteklemektedir.
  • Desteklenen çıktı formatları; zpl, base64zpl, pdf, png ve jpg Endpoint’de format=zpl, format=pdf gibi desteklenen formatları ekleyerek ilgili çıktı alınabilir. Convert ederek de görseline ulaşabilirsiniz.

*Hata Durumları

Hata Kodu Hata Mesajı
101
Barcode veremediği durumda alınır. Kargo firması hatasıdır.
102
Barcode veremediği durumda alınır: "Merchant kargo barkod aktif değil"
400
Cargo company does not provide mutual barcodes
500
Internal error: 3 kere hata alınırsa mevcut etiket yapısı ile devam edilmelidir.

İptal Bilgisi Gönderme

Bu metod merchantların sipariş için iptal bilgisini göndermesine olanak sağlar.
Sadece statüsü open olan siparişler için geçerlidir. Yani bir sipariş paketlenirse bu endpoint kullanılamaz. Eğer siparişin paketi var ise önce paket bozulup daha sonra bu endpoint çağırılmalıdır.

IPTAL CEZA KOŞULLARI
Sipariş iptali yapmanız halinde, ürünün satışını yapan farklı bir mağaza varsa sipariş yeni satıcıya transfer edilerek aradaki fiyat farkı ve sözleşmenizde bulunan ceza tutarı mağazanıza fatura edilecektir.

  • Ürün satışını yapan alternatif bir mağaza yoksa sözleşmenizde yer alan tutarlarda tarafınıza ceza faturası yansıtılacak ve ürün satışa kilitlenecektir.
  • Müşteri memnuniyetini üst seviyede tutmak için stok ve fiyat takibi konusunda hassasiyet göstermenizi önemle rica ederiz.
  • Bu endpoint için günlük limit 100’dür.
Ürün BedeliFaturalandırılacak Tutar
0-50 TL10 TL
50,01-100 TL30 TL
100,01-200 TL50 TL
200,01-1000 TL100 TL
1000,01-3000 TL300 TL
3000,01-6000 TL600 TL
6000,01-10000 TL1000 TL
10000,01-20000 TL1500 TL
20000,01 TL ve Üzeri2000 TL

Hata Durumları

Hata KoduHata Mesajı
400Bad Request: URL içerisindeki parametreleri kontrol edin.
401Unauthorized: Password ve şifre hatalı girilmiştir. Lütfen kontrol ediniz.
404Not Found: URL hatalı gönderilmiştir. Lütfen kontrol ediniz.
405Not Allowed: Http Protokol hatası. Lütfen kontrol ediniz.
406Not Acceptable: Günlük limiti aştınız.
409Conflict: Kalem iptal edilmiş yada statüsü iptale uygun değildir.
500Internal Server: İstek bilgilerini body ile kontrol etmenizi öneririz. Hata tekrarlı devam ederse ticket ileterek entegrasyon ekibi ile iletişime geçiniz.

Digital Kod Bilgisi Gönderimi

Delivered Status (Teslim Edildi Statüsüne Alma)

  • Dijital kod satışı yapıldığında Kodların son kullanıcıya merchant tarafından gönderimi sağlanır ve sipariş teslim edildiğinde deliver end-pointi üzerinden teslim edildi statüsüne çekilmesi gerekmektedir.
  • Otomatik paketleme kullanılıyor yada kullanılacak ise sipariş içerisindeki kalemlerin “Kalem bazında kargoya hazırlansın” şeklinde otopack’in aktif ettirilmesi gerekir.
  • API ile paketleme uygulanıyor ise yine kalem bazlı paketleme yapılmalı birden fazla kalem tek paket’e eklenmemelidir.
  • Digital kategoride bu endpoint’i kullanabilmek için merchantların ek olarak deliver yetkisi istemesi gerekir. Bunun için merchant panel’den aşagıdaki kırılımdan kayıt açılması gerekir.

“Canlı Ortam Merchant Panel > Yardım > Satıcı Destek Talep Formu > API Entegrasyon > API Entegrasyon Teknik Destek”

Alan Adı

Alan AdıAçıklama
receivedDatePaketin teslim tarihi
receivedByPaketin teslim edildiği kişi bilgisi
digitalCodesMüşteriye gönderilen dijital kod'un bilgisi

Dijital Ürünler kategorisine ait kategori bilgileri aşağıdaki gibidir.

NoAna KategoriAlt Kategori
1BilgisayarOnline Lisanslar
2GameDijital Oyunlar
3GameDijital Ürünler
4KitapOyun Pinleri
5KitapFilm, Dizi, Yayın Paketleri
6KitapOnline Eğitimler
7KitapDijital Oyunlar
8KitapOnline Mimarlık Hizmeti
9KitapFırsat Menüleri
10KitapAkaryakıt ve Oto Paketleri
11KitapE-Kitaplar
12KitapHediye Kartları
13KitapDijital Dergi
14KitapEtkinlik, Aktivite
15KitapOnline Lisanslar
16KitapSesli Kitap
17KitapDijital Ürünler

İptal Sipariş Bilgileri Listeleme

Bu metod satıcıya ait iptal edilen sipariş ve kalem bilgilerine ulaşmanıza olanak tanır. Servisten sadece son 1 aylık dataya erişilebilir.

  • İptal sipariş bilgilerini listeleme endpointinde limit – offset yada beginDate – endDate parametreleri kullanarak istek göndermeniz gerekir.
  • Servisten sadece son 1 aylık dataya erişilebilir.
  • Limit, offset, pagecount, totalcount datalarına response bilgisinden erişim sağlayabilirsiniz.
  • Limit-offset parametresi kullanırken limit maximum 50 olacak şekilde kullanılabilir.

Alan Açıklamaları

Alan Adı Açıklama
orderNumber
Siparişin unique numarasıdır.
lineItemId
Siparişin kaleminin unique ID bilgisidir.
cancelDate
Siparişin iptal edilme tarihidir.
cancelledBy
Siparişin kimin tarafından iptal edildiğinin bilgisini iletir. Alabileceği statüler : Merchant, Customer
cancelReasonCode
Sipariş iptal nedenidir.
merchantId
İptal edilen siparişin hangi merchanta ait olduğunu gösteren merchantıd bilgisidir.
quantity
Siparişin iptal edilen kaleminin kaç adet olduğunu belirtir.
sku
İptal edilen kalemin hepsiburada sku bilgisidir.
merchantSku
İptal edilen kalemin satıcı stok kodu  bilgisidir.

Teslim Edilemedi Siparişlerin Listelenmesi

Bu metod satıcıya ait kargodan teslim edilemeyen sipariş bilgilerine ulaşmanıza olanak tanır.Servisten sadece son 1 aylık dataya erişilebilir.

  • Teslim Edilemedi Siparişlerin Listelenmesi endpointinde limit – offset yada beginDate – endDate parametreleri kullanarak istek göndermeniz gerekir.
  • Servisten sadece son 1 aylık dataya erişilebilir.
  • Limit, offset, pagecount, totalcount datalarına response bilgisinden erişim sağlayabilirsiniz.
  • Limit-offset parametresi kullanırken limit maximum 50 olacak şekilde kullanılabilir.
  • Alan Açıklamaları
    Alan Adı Açıklama
    orderNumber
    Siparişin unique numarasıdır.
    Id
    Teslimatın unique ID bilgisidir.
    UndeliveredDate
    Siparişin teslim edilememe tarihidir.
    UndeliveredReason
    Teslim edilememe nedeni.
    Barcode
    Siparişin kargo barkod numarasıdır.
    merchantId
    Teslim edilemeyen siparişin hangi merchanta ait olduğunu gösteren merchantıd bilgisidir.
    PackageNumber
    Siparişin paket numarasıdır.

    Teslim Edilen Siparişlerin Listelenmesi

    Bu metod satıcıya ait kargodan müşteriye teslim edilen sipariş bilgilerine ulaşmanıza olanak tanır. Servisten sadece son 1 aylık dataya erişilebilir.

  • Teslim Edilen Siparişlerin Listelenmesi endpointinde limit – offset yada beginDate – endDate parametreleri kullanarak istek göndermeniz gerekir.
  • Servisten sadece son 1 aylık dataya erişilebilir. Eski tarihliler çekilemez.
  • Limit, offset, pagecount, totalcount datalarına response bilgisinden erişim sağlayabilirsiniz.
  • Limit-offset parametresi kullanırken limit maximum 50 olacak şekilde kullanılabilir.
  • Alan Açıklamaları
    Alan Adı Açıklama
    orderNumber
    Siparişin unique numarasıdır.
    Id
    Teslimatın unique ID bilgisidir.
    PackageNumber
    Siparişin paket numarasıdır.
    Barcode
    Siparişin kargo barkod numarasıdır.
    merchantId
    Teslim edilemeyen siparişin hangi merchanta ait olduğunu gösteren merchantıd bilgisidir.
    DeliveredDate
    Paketin teslim edildiği tarih bilgisidir.