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ı

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

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ı

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ı​

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ı

Hata Durumları

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

Hara Durumları

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ı

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ı

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ı

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ı

Alan Açıklamaları

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

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ı

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ı

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

Hata Durumları

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ı

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

İ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ı

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