Hepsiburada Order Management Technical Scope
The purpose of this document is to give good understanding how orders download and shipping orders should work as part of Hemi.
The full documentation is available here
Hepsiburada provide a test environment using the following end points: https://oms-stub-external-sit.hepsiburada.comhttps://oms-external-sit.hepsiburada.com
1. Authentication
API, HTTP Basic Auth so the client must send the username and password in the HTTP Authorization Header information.
Authorization: Basic base64(username:password)
We will also have a parameter called:
Merchantid - A unique identifier for each vendor.
2.Download Orders
NOTE: Only orders whose payment has been completed are flowed through the API. On the Merchant Panel, on the other hand, it is given for money transfer payments that remain at the last part of the New Orders page. It is flowed over the API right after the payment is completed in the orders that are bulk. In order to get the paid orders we will need to use GET request with
Once we received the paymentStatus = Received we set our tool status on RFS
Header
Authorization: Basic base64(username:password)
Content-Type: application/jsonParameters
- Merchantid (required, guid, b2910839-83b9-4d45-adb6-86bad457edcb) is a unique identifier for each vendor.
-
https://oms-external-sit.hepsiburada.com/orders/merchantid/ {merchantid} ? begindate = {yyyy-MM-dd HH: mm} & enddate = {yyyy-MM-dd HH: mm}
NOTE: When you use the optional begindate and enddate parameters, you can list your orders with Open and Unpacked status between a certain date.
For get order we will be using order read table from we will take the begindate and the enddate will be NOW() After successful request this is what we get:
{
"dueDate": "2020-06-25T09:15:17.735",
"lastStatusUpdateDate": "2020-06-24T09:15:18.332",
"id": "5ef2ef76-8155-6900-0118-59a906060606",
"sku": "HBV000003K29J",order_item.ChannelItemID
"orderId": "5ef2ef76-8155-6900-0118-59ab06060606",order_item.item_trans_id
"orderNumber": "0941441341", orders.id
"orderDate": "2020-06-24T09:15:17.735", orders.order_created_time
"quantity": 1,
"merchantId": "ac2a8cdd-5608-433e-8922-14c8a3db9de3",
"totalPrice": {
"currency": "TRY",
"amount": 301.39999
},
"unitPrice": {
"currency": "TRY",
"amount": 301.39999
},
"hbDiscount": {
"totalPrice": {
"currency": "TRY",
"amount": 0
},
"unitPrice": {
"currency": "TRY",
"amount": 0
}
},
"vat": 0,
"vatRate": 0,
"customerName": "Test User Test User", orders.shipping_buyer_name
"status": "Open",
"shippingAddress": {
"addressId": "e66765b3-d37d-488c-ae15-47051245dc9b",
"address": "Trump Towers Sisli İstanbul", orders.shipping_street1 and orders.shipping_street2 (we split at 35 characters) we also need to trim the city from the address
"name": "Hepsiburada Office",
"email": "customer@hepsiburada.com.tr", orders.buyer_mail
"countryCode": "TR", orders.shipping_country_name and orders.shipping_country_code
"phoneNumber": "902822613231", orders.shipping_phone
"alternatePhoneNumber": "045321538212",
"district": "Kustepe",shipping.stateProvince
"city": "İstanbul", orders.shipping_city
"town": "Sisli"
},
"invoice": {
"turkishIdentityNumber": "1234567890",
"taxNumber": "12345", orders.billing_tax_number
"taxOffice": "İstanbul",orders.billing_tax_office
"address": {
"addressId": "AE3AF886-F7E7-4E71-83F5-B6066735EF42",
"address": "Trump Towers Şişli İstanbul", orders.billing_street1 and orders.billing_street2 (we split at 35 characters) we also need to trim the city from the address
"name": "Hepsiburada Office",
"email": "customer@hepsiburada.com.tr",
"countryCode": "TR", billing.countryName and orders.billing_country_code
"phoneNumber": "902121234567", orders.billing_phone
"alternatePhoneNumber": "045321538212",
"district": "Kustepe", orders.billing_state_province
"city": "İstanbul", orders.billing_cityname
"town": "Sisli"
}
},
"sapNumber": "123450",
"dispatchTime": 1,
"commission": {
"currency": "TRY",
"amount": 1
},
"paymentTermInDays": 30,
"commissionType": 0,
"cargoCompanyModel": {
"id": 1,
"name": "Yurtiçi Kargo",
"shortName": "YK", orders.shipping_carrier
"logoUrl": "http://images.hepsiburada.com/assets/cargo-logo/yurtici.svg",
"trackingUrl": "http://selfservis.yurticikargo.com/reports/SSWDocumentDetail.aspx?DocId={0}"
},
"cargoCompany": "Yurtiçi Kargo",
"customizedText01": "",
"customizedText02": "",
"customizedText03": "",
"customizedText04": "",
"customizedTextX": "",
"creditCardHolderName": null,
"isCustomized": false,
"canCreatePackage": true,
"isCancellable": true,
"isCancellableByHbAdmin": true,
"deliveryType": "StandardDelivery",
"deliveryOptionId": 1,
"slot": null,
"pickUpTime": null,
"discountInfo": [],
"merchantSKU": "",
"purchasePrice": {
"currency": "TRY",
"amount": 0
},
"deliveryNote": {}
}
]Please note we will need to add the order item lines as well! We will need to have get modified orders cron as well as we wont cancel orders directly from Hemi so we will need to be able to do status updates.
GET Modified Order
This method allows you to list the details of the items for an order.
Parameters
- Merchantid (required, guid, b2910839-83b9-4d45-adb6-86bad457edcb) A unique identifier for each vendor.
- Ordernumber (required, int, 004563585) A unique identifier for each order.
Header
Authorization: Basic base64(username:password)
Content-Type: application/json
Request
https://oms-external-sit.hepsiburada.com/orders/merchantid/ {merchantid} / ordernumber / {ordernumber}
Error Situations
- An error message will be returned when a request is submitted with an incomplete order number. Message: No results found for this order, please check the order's payment status.
{
"orderId": "601908c3-8e7b-9e28-d210-e5c706060606",
"orderNumber": "0555286999", orders.id
"paymentStatus": "Received", orders.order_status
"orderDate": "2021-02-02T11:09:39",
"createdDate": "2021-02-02T11:09:39.743",
"customer": {
"customerId": "f26fd8d5-38bb-4a81-bf77-e0cd224dcb06", buyerUserId
"name": "MAHMUT AKBOLAT" buyerName
},
"invoice": {
"turkishIdentityNumber": "",
"taxNumber": "",
"taxOffice": null,
"address": {
"addressId": "9ab9678f-15ca-416c-8c6d-49e5c77a7f3f",
"address": "KIŞLALAR MAH. KARA YUSUF AĞA CAD. IŞIL AYKAÇ KONUTLARI A4/4 MERKEZ DÖRTYOL Hatay", orders.billing_street1 and orders.billing_street2 (we split at 60 characters)
"name": "MAHMUT AKBOLAT",
"email": "makbolat@hotmail.com",
"countryCode": "TR",orders.billing_country_name and orders.billing_country_code
"phoneNumber": "5076067757", orders.billing_phone
"alternatePhoneNumber": "5076067757",
"district": "MERKEZ",orders.billing_state_province
"city": "Hatay", orders.billing_cityname
"town": "DÖRTYOL"
}
},
"deliveryAddress": {
"addressId": "6e8b94f9-ef4c-4776-b455-305d4fb29c12",
"address": "KIŞLALAR MAH. KARA YUSUF AĞA CAD. IŞIL AYKAÇ KONUTLARI A4/4 MERKEZ DÖRTYOL Hatay", shipping.street1 and shipping.street2 (we split at 35 characters) we also need to trim the city from the address
"name": "MAHMUT AKBOLAT",
"email": "makbolat@hotmail.com", orders.buyer_mail
"countryCode": "TR", orders.shipping_country_code and orders.shipping_country_name
"phoneNumber": "5076067757", orders.shipping_phone
"alternatePhoneNumber": "5076067757",
"district": "MERKEZ", orders.shipping_state_province
"city": "Hatay", orders.shipping_city
"town": "DÖRTYOL"
},
"orderNote": {},
"items": [
{
"dueDate": "2021-02-10T16:00:00",
"lastStatusUpdateDate": "2021-02-02T11:09:40.286",
"id": "601908c3-8e7b-9e28-d210-e5c606060606", order_item. item_order_line_id
"sku": "HBV00000K116O", order_item.ChannelItemID
"orderId": "601908c3-8e7b-9e28-d210-e5c706060606",order_item.item_trans_id
"orderNumber": "0555286999",
"orderDate": "2021-02-02T11:09:39",
"quantity": 1,order_item.item_quantity
"merchantId": "75c3c271-ba3c-40ef-bfc5-8e66418a7f10",
"totalPrice": {
"currency": "TRY", orders.currency
"amount": 2999 orders.order_total_amount
},
"unitPrice": {
"currency": "TRY",
"amount": 2999 order_item.item_trans_price
},
"hbDiscount": {
"totalPrice": {
"currency": "TRY",
"amount": 0
},
"unitPrice": {
"currency": "TRY",
"amount": 0
}
},
"vat": 457.47,
"vatRate": 18,
"customerName": "MAHMUT AKBOLAT",
"status": "Open",
"shippingAddress": {
"addressId": "6e8b94f9-ef4c-4776-b455-305d4fb29c12",
"address": "KIŞLALAR MAH. KARA YUSUF AĞA CAD. IŞIL AYKAÇ KONUTLARI A4/4 MERKEZ DÖRTYOL Hatay",
"name": "MAHMUT AKBOLAT",
"email": "makbolat@hotmail.com",
"countryCode": "TR",
"phoneNumber": "5076067757",
"alternatePhoneNumber": "5076067757",
"district": "MERKEZ",
"city": "Hatay",
"town": "DÖRTYOL"
},
"invoice": {
"turkishIdentityNumber": "",
"taxNumber": "", orders.Tax Number
"taxOffice": null, orders.Tax Office
"address": {
"addressId": "9ab9678f-15ca-416c-8c6d-49e5c77a7f3f",
"address": "KIŞLALAR MAH. KARA YUSUF AĞA CAD. IŞIL AYKAÇ KONUTLARI A4/4 MERKEZ DÖRTYOL Hatay",
"name": "MAHMUT AKBOLAT",
"email": "makbolat@hotmail.com",
"countryCode": "TR",
"phoneNumber": "5076067757",
"alternatePhoneNumber": "5076067757",
"district": "MERKEZ",
"city": "Hatay",
"town": "DÖRTYOL"
}
},
"sapNumber": "000010",
"dispatchTime": 6,
"commission": {
"currency": "TRY",
"amount": 299.89999
},
"paymentTermInDays": 14,
"commissionType": 0,
"cargoCompanyModel": {
"id": 1,
"name": "Yurtiçi Kargo",
"shortName": "YK", orders.shipping_carrier
"logoUrl": "https://images.hepsiburada.net/assets/cargo-logo/yurtici.svg",
"trackingUrl": "http://selfservis.yurticikargo.com/reports/SSWDocumentDetail.aspx?DocId={0}"
},
"cargoCompany": "Yurtiçi Kargo",
"customizedText01": "",
"customizedText02": "",
"customizedText03": "",
"customizedText04": "",
"customizedTextX": "",
"creditCardHolderName": null,
"isCustomized": false,
"canCreatePackage": true,
"isCancellable": true,
"isCancellableByHbAdmin": true,
"deliveryType": "StandardDelivery",
"deliveryOptionId": 1,
"slot": null,
"pickUpTime": null,
"discountInfo": [],
"merchantSKU": "248367-01", order_item.item_SKU and order_item.item_title
"purchasePrice": {
"currency": "TRY",
"amount": 0
},
"deliveryNote": {},
"merchantSku": "248367-01"
}
],
"shipments": [
{
"packageNumber": "071853593", orders.mercado_shipping_id
"barcode": "6210718535938"
}
]
}When we download an order we must make sure the paymentStatus we received is “Recieved“ only then we can procced and mark the orders as RFS.
| MP Status (Hemi Item Status) | Comment | Hemi Status |
|---|---|---|
| Open | Open order. | waiting_for_dispatch |
| Packaged | Packaged order. | waiting_for_dispatch |
| CanceledByMerchant | Order canceled by Merchant. | cancelled |
| Delivered | The delivered order. | dispatched |
| InTransit | Order in cargo. | dispatched |
| ClaimCreated | Demand opened pen. | Do nothing |
| CanceledByCustomer | Order canceled by the customer. | cancelled |
| CanceledBySap | Occurs when an order canceled by SAP is Fraud etc. | cancelled |
3.Orders Ship
HepsiBurada’s process flow is actually different from the standard one. This is due to the fact that HepsiBurada’s business model is set for HepsiBurada to take care of everything around the delivery. So when an order is placed HepsiBurada would be expecting the retailer to prepare that order(pick and pack) and then HepsiBurada will request the label from the shipping vendor when the retailer marks the order as packed. This is done over API using the call: Create Package. After that there is a step when the retailer can obtain the tracking number for the shipment provided by the shipping vendor. This can be done over API using the call: List Shipping information and we should be looking for orders with status: InTransit Only when the status is InTransit then we mark the order as shipped.
Basically when we Create the Package we will have to check for orders on RFS and with emypu shippingID then we will receive the package number which we will store in orders.shippmentID. When the order is on RFS, with shipping id and update shipping pending we can List the Shipping Information using the package number and mark the order as shipped if inTransit.
POST Create Package:
Header
Authorization: Basic base64(username:password)
Content-Type: application/json
Parameters
- Merchantid (required, guid, b2910839-83b9-4d45-adb6-86bad457edcb) A unique identifier for each vendor.
Objects
- LineitemId (required, guid, 32910839-83b9-4545-adb6-76dad457edc4) The item to be sent in the package.
- Quantity (required, int, 2) The number of pieces of the item in the package.
- https://oms-external-sit.hepsiburada.com/packages/merchantid/{merchantid}
We will also have to specify the body:
{ "parcelQuantity":2, "deci":10, "lineItemRequests": [ { "id": "471e7231-f9b5-460b-9a56-983ef737b3e0", "quantity":"1" } ] }parcelQuantity will always be 1 deci will be always 10 id is ourorderIdquantity the total order quantity
After successful 201 create package in the response we will get:
{ { "packageNumber": "697823915", "barcode": "6226978239158" } }
The packageNumber is stored in orders.shippingID field.
The barcode need to be stored as well but at the moment we do not store it even with Cresco.
Please note that the order still remains as RFS.
The second step in the shipping cron is: POST Listing Shipping Information for the Package Header
Authorization: Basic base64(username:password)
Content-Type: application/json
Parameters
- Merchantid (required, guid, b2910839-83b9-4d45-adb6-86bad457edcb) A unique identifier for each vendor.
- packagenumber (required, int, 00548648) A unique identifier for each package.
(Request)
https://oms-external-sit.hepsiburada.com/packages/merchantid/{merchantid}/packagenumber/{packagenumber}
We simply give our merchantID and the package number which we already have. After successful request 200 we will get:
[
{
"packageNumber": "064855652",
"barcode": "623333333333",
"status": "InTransit", //orders.fullfilment_status
"cargoCompany": "Yurtiçi Kargo",
"trackingInfoCode": "176162533695", //orders.shipping_track_num
"trackingInfoUrl": "http://selfservis.yurticikargo.com/reports/SSWDocumentDetail.aspx?DocId=176162533695" //orders.shipping_tracking_url
}
]And we mark our tool_order status as Shipped.
4.Error Messages
HTTP Status Codes Check the accuracy of your 401 username and password, if it is correct and you get an error.
403 Indicates that the request was created correctly, but you are not authorized to act on the relevant account.
404 Check the end-point address you send your request to.
405 You are sending a request with the wrong method, check the documentation.