Hepsiburada Marketplace Setup Configurations
Last updated
Was this helpful?
Last updated
Was this helpful?
The Marketplace Dashboard application needs to be installed on ACC. To do this, the user should log in to using their username and password.
After logging in, go to the App-Store from the menu, select Hepsiburada, then choose the relevant project and proceed with the installation.
Following the installation process, navigate to My Applications from the left menu, select the relevant application, and enter the application page. Once the necessary build and deployment steps are completed, the Hepsiburada application will appear in the left menu of Omnitron.
After the installation, the database and tables will be created.
Once the deployment of the application is completed on ACC, a sales channel will be automatically created in Omnitron. The fields within this sales channel need to be filled out.
The sales channel can be accessed through Omnitron > Settings > Sales Channels.
Field Name
Description
Example
Information
Requirement
Channel Name
Sales Channel Name
Hepsiburada
Automatically created.
Required (should not be changed)
Catalog Name
Catalog Name Created for Hepsiburada *May vary from brand to brand
Hepsiburada
Automatically created.
Required
Channel Type
Channel Type
*All sales channel types are listed in a dropdown in Omnitron.
Sales Channel
Automatically created.
Required (should not be changed)
Status
The sales channel will not function until it is activated.
Inactive
By default, it is set to inactive (it needs to be activated).
Required
Schema Type
The Sales Channel Settings define the information that needs to be stored for the sales channel. The required information for the operation of this sales channel is brought into Omnitron as a form. A schema containing the minimum necessary information for the sales channel to function is automatically created. You can also add additional information you want to store here (for example, details needed for the ERP integration of the sales channel).
The key-value information that will be included in the Channel Config is provided here. In the value section, the dictionary includes key, label, required, and data_type.
key → Indicates the key through which the information will be accessed in the channel config.
label → Specifies how the information will appear in the form on the Omnitron Sales Channel Settings interface.
required → Indicates whether the value is mandatory (true/false).
data_type → Specifies the data type of the value (list, text, integer, bool, json).
{
"store_code": {
"key": "StoreCode",
"label": "Mağaza Kodu",
"required": false,
"data_type": "text"
},
"base_url": {
"key": "base_url",
"label": "Base Url",
"required": true,
"data_type": "text"
}
}
The default information has been automatically filled in.
Required (Additions can be made, but existing fields should not be changed).
Base Url
The Hepsiburada API URL is used for category retrieval operations.
https://mpop.hepsiburada.com
It is pre-filled by default.
Required
OMS Url
The Hepsiburada API URL is used for order processing operations.
https://oms-external.hepsiburada.com
It is pre-filled by default.
Required
Listing Url
The Hepsiburada API URL is used for product, stock, or price operations.
https://listing-external.hepsiburada.com
It is pre-filled by default.
Required
Username
The merchant ID for the Hepsiburada API is the information provided by Hepsiburada for the seller.
******************
It can be obtained by contacting Hepsiburada.
Required
Password
The password for the Hepsiburada API is the information provided by Hepsiburada for the seller.
******************
It can be obtained by contacting Hepsiburada.
Required
Merchant Id
The merchant ID for the Hepsiburada API is the information assigned to the seller by Hepsiburada.
It can be obtained by contacting Hepsiburada.
******************
It can be obtained by contacting Hepsiburada.
Required
User Agent
The User Agent information assigned by Hepsiburada is:
akinon_dev
It is determined by contacting Hepsiburada.
Required
Category Ids
368234234
234324322
It is pre-filled as empty by default. (This information is obtained from Hepsiburada.)
Required
Feature Flags
It allows the activation or deactivation of running processes. The key point to note here is that, even if the related process will not run, it must still be added here as false. (Detailed information about feature flags is provided in Section 9 under the “Feature Flags” heading below.)
{
"get_orders": true,
"get_cancel_orders": true,
"get_refund_orders": false,
"send_invoice_link": true,
"send_delete_products": true
}
By default, all flags are set to false.
Required
Use Neighborhood
Whether the neighborhood information will be used in the address data when creating an order is determined by this setting. If active, the neighborhood information in the delivery and invoice addresses of the order will be processed during the address creation step in Omnitron.
Inactive
It is pre-filled as inactive by default. If the company's system requires neighborhood information, this field should be activated.
Optional
Use Hb Tracking Number
Whether the barcode information retrieved by Hepsiburada will be used as the tracking number when creating an order is determined by this setting. If active, the barcode information from the Hepsiburada package will be processed as the tracking number for the relevant order.
Inactive
It is pre-filled as inactive by default.
Optional
Refund Reason Mapping
The return reason information on Hepsiburada is matched with the return reason information in Omnitron for the return process. Here, the key refers to the reason value on Hepsiburada (this value can be found under the "Reason" field in the Request Detail Listing section on Hepsiburada), and the value refers to the reason ID in Omnitron. (The ID information can be retrieved using the endpoint: {omnitron_url}/api/v1/channel/{channel_id}/cancellation_reasons/?cancellation_type=refund&is_active=true.)
{
“PoorQuality”:”7” , “SizeTooLarge”: “11”
}
By default, this is left empty. (When left empty, the return reasons will be populated with the "Default Reason Id" information in the previous step when the return information is retrieved from Hepsiburada.)
Optional
Default Reason Id
If the reason ID in the return data retrieved from Hepsiburada is not listed in the Refund Reason Mapping, the Omnitron refund reason ID entered here will be used to pull the refund data and write it to Omnitron. (The ID information can be retrieved using the endpoint: {omnitron_url}/api/v1/channel/{channel_id}/cancellation_reasons/?cancellation_type=refund&is_active=true.)
5
By default, this is left empty.
Required
Refund Start Date
This is the initial start date for when returns will begin to be retrieved. The format is "yyyy-MM-ddTHH:mm:ssZ".
2024-12-01T10:00:00Z
By default, this is left empty.
Optional
Orders Refundable Days
This is the number of days within which an order can be returned after its creation date.
15
It is pre-set to 15 days by default.
Optional (If left empty, the default is 15 days).
Failed Integration
Records with errors during the integration process are temporarily delayed with a penalty. (For detailed information, refer to Section 3: Failed Integration Settings below).
{
"order": {
"RETRY_INTERVAL": 28800,
"EXPIRATION_DATE": 57601,
"MAX_RETRY_COUNT": 3
},
"DEFAULT": {
"RETRY_INTERVAL": 28800,
"EXPIRATION_DATE": 57601,
"MAX_RETRY_COUNT": 2
},
"product": {
"RETRY_INTERVAL": 28800,
"EXPIRATION_DATE": 57601,
"MAX_RETRY_COUNT": 2
},
"productprice": {
"RETRY_INTERVAL": 28800,
"EXPIRATION_DATE": 57601,
"MAX_RETRY_COUNT": 2
},
"productstock": {
"RETRY_INTERVAL": 28800,
"EXPIRATION_DATE": 57601,
"MAX_RETRY_COUNT": 2
},
"sent_to_remote": {
"EXPIRATION_HOUR": 6
}
}
It is pre-filled by default.
Required
Erp Code
The sales channel code is defined for Hepsiburada in the brand.
TY
It is pre-filled as empty by default.
Optional
Send Shipping Info
This setting determines whether Hepsiburada or the brand will manage the shipping process.
Inactive
It is pre-filled as inactive by default. (If inactive or not selected, Hepsiburada manages the shipping process. If active, the brand manages the shipping process.)
Optional
Order Number Format
When pulling order data from Hepsiburada to Omnitron, the order number will be set according to this format. If this value is left empty, the order will be written to Omnitron with the default order number format: "{orderNumber}-{id}".
HB-{orderNumber}-{id}
It is pre-filled as empty by default.
Optional
Cancellation Reason Id
This is the information about which reason ID will be used to write canceled orders to Omnitron when retrieved from Hepsiburada. (The ID information can be obtained using the endpoint: {omnitron_url}/api/v1/channel/{channel_id}/cancellation_reasons/?cancellation_type=cancel&is_active=true)
4
It is pre-filled as empty by default.
Required
Attribute Set Strategy
This is the strategy setting that determines which attribute set the products belong to.
CategoryNode
It is pre-filled by default.
Required (Should not be changed).
Use Channel Id In Address Mapping
If the brand desires, this field can be activated to perform address mapping operations on a channel basis. If this field is activated, the channel ID will be added in front of the address data during the mapping process, and searches will be performed using the sales channel filter with the channelId_address information.
Inactive
It is pre-filled as inactive by default.
Optional
Buffer Stock
This is the value to be deducted from the product's current stock when sending stock data to Hepsiburada. If no value is entered, the product's current stock will be sent to Hepsiburada.
3
It is pre-filled as empty by default.
Optional
Shipping Provider
The mapping required to feed the tracking URL in the Order update flow will be entered in this field. Here, the tracking_number information will be adjusted to match the order_number and tracking number. This allows the automatic creation of the tracking URL.
Special Cases:
Ptt: The tracking number information is separated by a "-" where the part before the "-" is the barcode and the part after is the GUID. The URL is then created as: "barkod=${barkod}&barkod_guid=${barkod_guid}"
Loomis: The tracking number is separated by a "-" and, within the provided mapping, the part before the "-" is used to extract the URL information from the tracking URL. For example, for an order with the tracking number "tur-1234566", the mapping for the tur key in the tracking URL might look like this:
{
"loomis": {
"tracking_url": {
"tur": "https://xxx.com?tracking_number={tracking_number}"
}
}
}
{
"aras": {
"tracking_url": "https://kargotakip.araskargo.com.tr/mainpage.aspx?code={tracking_number}",
"tracking_url_by_tracking_number": ""
},
"k_gelsin": {
"tracking_url": "https://esube.kolaygelsin.com/shipments?trackingId={tracking_number}",
"tracking_url_by_tracking_number": ""
},
"hbexpress": {
"tracking_url": "https://www.hepsijet.com/gonderi-takibi/{tracking_number}",
"tracking_url_by_tracking_number": ""
}
}
It is pre-filled as empty by default.
Optional
Cargo Company Mapping
{
"hepsijet": 3,
"default": 1
}
It is pre-filled as empty by default.
Required
Cancellation Reason Mapping
With the mapping in this field, the cancellation reasons received from Hepsiburada are matched with the defined reasons. When a match is made, cancellations are processed with the corresponding reason.
{
"Other": 3
}
It is pre-filled as empty by default.
Optional
Automatic Packing
When this field is activated, orders are automatically packaged if Hepsiburada's packaging process has not been performed. This process occurs before the order retrieval step in the Marketplace Dashboard application.
True
It is pre-filled as empty by default.
Optional
Check Hepsijet Format Type
This field is used to specify the format of the cargo label.
png
It is pre-filled as empty by default.
Optional
Billing Address Same As Shipping
If this field is active, in micro export orders, the invoice and delivery addresses will be written to Omnitron as the same. Additionally, the invoice address information from the Hepsiburada order will be written to the order's extra_field.
False
It is pre-filled as empty by default.
Optional
Mağaza Hesabı Kargo Firması
If a shipping company is entered in this field, the shipping company information will be included along with the package details in the automatic packaging process. This process will occur if Automatic Packing is active. The list of shipping companies can be found in the documentation at:
YK
It is pre-filled as empty by default.
Optional
Use Cargo Label
The decision of whether the cargo label field will be filled in the order retrieval step can be determined by activating or deactivating this field.
False
It is pre-filled as empty by default.
Optional
During the integration process, records that encounter errors are temporarily delayed with a penalty. The RETRY_INTERVAL and EXPIRATION_DATE values are expressed in seconds.
RETRY_INTERVAL defines how long to wait after an error occurs before trying again.
EXPIRATION_DATE indicates how long attempts will continue after the error occurs.
MAX_RETRY_COUNT represents the maximum number of retry attempts.
sent_to_remote is the setting that specifies how many hours Hepsiburada will keep processing the result after the request is sent to Hepsiburada.
Any updates made to these values will apply to the next process that runs. For example, if a SKU's stock update previously entered the penalty queue with a RETRY_INTERVAL of 3 hours, and the RETRY_INTERVAL is later updated to 2 hours, when the system retries the stock update after the previous 3-hour penalty period and encounters an error again, the new RETRY_INTERVAL of 2 hours will apply, and the SKU will be placed back into the penalty queue with the updated time.
For example: When sending product requests to Hepsiburada, if there is an error on the Omnitron side (such as missing stock, price data, or incomplete mapping) or on Hepsiburada's side (such as the product not being found, or not receiving a response from Hepsiburada within the time specified by sent_to_remote), the product will be penalized according to the current Failed Integration settings. During the penalty period, no further shipment attempts will be made for that product.
As a result, the product will not be retried for submission for a certain period, preventing the error-prone records from blocking the processing of other records.
The category tree is pulled based on the Category Ids added within the sales channel.
Once the category tree is pulled into Omnitron, it can be viewed by selecting Hepsiburada under Sales Channels, and then navigating to the Category Management section.
Once this process is successfully completed (it can be tracked through logs), the flow that retrieves the attributes will be triggered. After the attribute-related processes are finished (for example, the Brands flow has been successfully executed), the next steps can proceed.
Once the category tree retrieval step is completed, the user must perform category mappings through the Mapper.
The Akinon Mapper function in Omnitron allows users to configure and manage the attribute values of the products they want to sell on marketplace sales channels according to the marketplace requirements. Additionally, it provides the ability to check whether the attributes and their values are correct before the products go live for sale.
Products must be added to the relevant category tree on the Hepsiburada side. Each product should only be added to one category. Otherwise, an error may occur during submission on Hepsiburada.
When the Hepsiburada marketplace application is installed on the relevant brand's Omnitron, it will appear as Hepsiburada in the left-side menu.
The dashboard data related to the Hepsiburada marketplace application is available on this screen.
TOTAL SKU IN CATALOG The number of SKUs of type “simple” and with active status that are included in the relevant catalog.
NUMBER OF SKUs ON SALE The number of SKUs that have been sent to the marketplace and are currently on sale.
TOTAL SKU DIFFERENCE The number of SKUs that are included in the catalog but are not on sale in the marketplace. This section compares the products considered saleable in Omnitron with those listed in the marketplace. In this comparison, products that have a price in Omnitron, stock greater than zero, a category, a product image, and are listed in the catalog are taken into account.
NUMBER OF SKUs WITH PRICE DIFFERENCES (CORRECTED) The number of SKUs with price differences between Omnitron and the Marketplace. If a price discrepancy is detected, a separate task is executed to correct the differences.
TOTAL STOCK IN CATALOG The total stock quantity of all products in the Marketplace catalog.
TOTAL STOCK ON SALE The total stock quantity of products that are currently on sale in the marketplace.
TOTAL STOCK DIFFERENCE The stock quantity of products that are in the catalog but not listed for sale in the marketplace.
NUMBER OF SKUs WITH STOCK DIFFERENCES The number of SKUs with stock differences between Omnitron and the Marketplace. If a discrepancy exists, a separate task is executed to resolve the differences.
The screen where logs and reports are located.
The logs of the flows are located on this screen.
Category Node The flow that pulls the full category tree structure, based on the main categories defined in the channel settings, into Omnitron.
Category Attribute and Values The flow that pulls category attributes and their values defined in the channel settings into Omnitron.
Default Attributes The flow that prepares predefined fields (e.g., remote_id, title, etc.) for the mapping process during product submission.
Product Create The flow that sends newly entered products in Omnitron to the marketplace.
Product Update The flow that sends updated products in Omnitron to the marketplace.
Product Delete The flow that removes products deleted from the Omnitron catalog from sale in the marketplace.
Stock The flow that sends updated stock information of products with stock changes in Omnitron to the marketplace.
Price The flow that sends updated price information of products with price changes in Omnitron to the marketplace.
Order Create The flow that pulls orders from the marketplace into Omnitron.
Order Update The flow that updates the order status, invoice, and tracking number in the marketplace based on changes in Omnitron.
Order Cancel The flow that updates the status in Omnitron for orders canceled in the marketplace.
Order Refund The flow that updates the status in Omnitron for orders refunded in the marketplace.
Updated Orders The flow that updates the status in Omnitron for orders whose status has changed in the marketplace.
Split Packages The flow that sends package-splitting requests from Omnitron or another OMS system to the marketplace.
Approve Refunds The flow that sends approved refunds in Omnitron to the marketplace.
Reject Refund The flow that sends rejected refunds in Omnitron to the marketplace.
Unpacked Orders The flow that pulls broken/corrupted packages from the marketplace and performs cancellation in Omnitron.
Compare Attributes The flow that updates the category attribute statuses in Omnitron based on changes in the marketplace.
This is the reporting screen for products that have been added to the catalog in Omnitron but have not been listed for sale on Hepsiburada, showing discrepancies between the price and stock information on Hepsiburada and the data in Omnitron.
The screen for creating, configuring, and viewing alarms related to the flows.
With the Refund Order flow, return requests pulled from the marketplace are created in Omnitron with the status OPEN, and they appear on relevant screens for manual rejection.
If the requests reviewed on these screens are rejected, the RejectRefund flow sends the rejection reason, explanation, and any attached photos to the marketplace.
Return rejection operations are carried out through this screen.
The steps to follow for errors encountered in logs are as follows:
The error “Address is not valid. channel: 137 code: 137_Merkez model: Township city id: .., city name: …” indicates that the Township in the address data of the order needs to be mapped.
The error “Stock data not found” shows that the product does not have stock data. Stock data needs to be added for the relevant product.
The error “Price data not found” indicates that the product does not have price data. Price data needs to be added for the relevant product.
Stopping the shipment of faulty products or resending a product that couldn’t be shipped; Faulty products are attempted to be sent for a period based on the rules defined in the Failed Integration section of the channel settings. According to this rule, a manual trigger is required for products that have stopped being attempted. To remove products from penalties in this situation, go to the Omnitron settings in the right menu, select Sales Channels and the relevant channel. On the page that appears, click the 'Update by Uploading Files' button located to the left of 'Delete Bulk Failed Integration' in the upper-right corner to upload a CSV file.
If too many faulty products accumulate in the queue, since processing is done in batches of 50, the queue may not reach the subsequent products. There are two solutions for this:
The first solution is to immediately fix errors related to mapping, catalog, stock, price, etc., and then trigger the CSV upload.
The second solution is to adjust the Fail Integration settings in the channel settings with proper time intervals.
For the "Failed to suggest product to catalog" error, if the issue is related to attribute values, the Category Attributes flow should be run to pull the current attribute values, and if necessary, the Compare Attributes flow should also be triggered.
The error "The relevant record is not in queue. the item may have been penalized or check product is saleable" received after product triggering:
The products attempted to be sent have already been sent, and since the products are considered as product update rather than product create, such an error is encountered.
This error is also received when a product that is still in the sending process is triggered again.
For the status/solution of orders that cannot be updated on the MPD side via the Order Update (send_update_orders) flow:
If there is a return process opened/ongoing for the order, it will not be updated.
The tracking number value will only be populated if “Send Shipping Info” is actively marked. For details, please refer to the “Feature Flags” section.
The status of the order cannot be updated retrospectively. Therefore, manual intervention in the flows should not be done.
The frequency values are by default as shown in the table below. These values can be modified by the Marketplace team.
Flag
Description
Frequency
get_orders
This flag allows the retrieval of packages from Hepsiburada to Omnitron up to 12 hours prior to the flow's runtime. Before activating this flag, the settings mentioned in the second section (Sales Channel Definition) such as Use Neighborhood, Send Shipping Info, Order Number Format, Use Channel Id In Address Mapping, Cargo Company Mapping, Use Cargo Label, Store Account Cargo Company, Automatic Packing, Billing Address Same As Shipping, Check Hepsijet Format Type, and Use Hb Tracking Number should be properly configured.
The process runs every 5 minutes.
get_cancel_orders
It ensures that the cancelled packages on the Hepsiburada side are retrieved to go back 12 hours from the runtime of Flow, and that a cancellation request is created in Omnitron with a maximum of 6 cancellation plan numbers. Before this flag is activated, the Cancellation Reason Id and Cancellation Mapping settings in the second heading above (Sales Channel Definition) should be properly configured.
It runs every 5 minutes.
get_refund_orders
It ensures that claims with the 'Refunded' status on the Hepsiburada side are retrieved, and the claim lines are fetched to create a refund request in Omnitron. Before this flag is activated, the Default Reason Id, Refund Reason Mapping, Refund Start Date, and Orders Refundable Days settings in the second heading above (Sales Channel Definition) should be properly configured.
It runs every 5 minutes.
send_update_orders
The order status in Omnitron—tracking number, invoice link, and update order statuses (delivered or not delivered)—is populated through this flow.
The tracking number value will be populated only if Send Shipping Info is set to true.
Before activating this flag, the Shipping Provider and Shipping Info settings under the second heading above (Sales Channel Configuration) must be properly configured.
This flow updates the invoice and order status.
The tracking number is sent only if Send Shipping Info is active.
It runs every 5 minutes.
split_packages
It allows orders created on Hepsiburada to be split into multiple packages. It works by sending a request in the specified format to the marketplace endpoint by the OMS.
Omnitron Web Hook Configuration:
Omnitron -> Akinon OMS -> Settings -> Web Hooks -> New Web Hook
Target URL: https://mp_frontend_url/flow-trigger/mp_frontend_url_slug/split_packages
Mp_frontend_url: It is the URL found in Acc -> Projects -> Applications -> Hepsiburada -> Url. Mp_frontend_url_slug is the part before ".lb.akinoncloud.com."
Event Type: order.split_package_{oms_channel_id}
oms_channel_id endpoint: {omnitron_url}/oms/channels/?limit=9999&limit=20&page=1
Note: The channel id here is the channel id in OMS, not the Omnitron channel id.
Additional Headers: {"Authorization":"Token xxx"}
Config: {}
Retry Countdown Config: {"choice":"fixed","kwargs":{"seconds":120}}
It works through an outbound trigger sent by OMS from the outside.
delete_product
It ensures that products removed from the catalog have their stock set to 0 on the Hepsiburada side.
It runs every 5 minutes.
product_update
It ensures that the products that need to be updated are sent to Hepsiburada.
It runs every 5 minutes.
product_create
It ensures that the products added to the catalog, along with their prices and stock, are sent to Hepsiburada. Before this flag is activated, the Buffer Stock setting in the second heading above (Sales Channel Definition) should be properly configured.
It runs every 5 minutes.
get_updated_orders
It ensures that orders with the 'Shipped' or 'Delivered' status on Hepsiburada are retrieved, going back 24 hours from the runtime of Flow, and updated item-wise in Omnitron. Before this flag is activated, the Cargo Company Mapping setting in the second heading above (Sales Channel Definition) should be properly configured.
It runs every morning at 06:00.
approve_refund
It ensures that the generated return request is approved on the Hepsiburada side.
It runs every 5 minutes.
price
It ensures that the product prices that need to be updated are sent to Hepsiburada.
It runs every 5 minutes.
stock
It ensures that the product stocks that need to be updated are sent to Hepsiburada. Before this flag is activated, the Buffer Stock setting in the second heading above (Sales Channel Definition) should be properly configured. If the stock data pulled from Omnitron contains maximumPurchasableQuantity in the extra_field, this information will be added to the stock data sent to Hepsiburada.
It runs every minute.
Reject_refund (This feature will be implemented in the future.)
When this flag is activated, it enables the rejection of cancellation requests listed on the Omnitron marketplace dashboard. Once activated, the process can continue by adding the reason for the rejection, a description, and image information on the panel.
It is done through the Marketplace dashboard.
unpacked_orders
It retrieves the damaged packages on the Hepsiburada side and performs the cancellation process on the Omnitron side. Before this flag is activated, the Cancellation Reason Id in the second heading above (Sales Channel Definition) should be configured.
It runs every 5 minutes.
The main category IDs to be used via the Hepsiburada API at the endpoint are checked and added here.
With this mapping, the shipping information received from Hepsiburada is mapped, determining which shipping company it corresponds to on the Omnitron side. The list of shipping companies can be obtained from the following endpoint: .
. The short name from the documentation should be entered here.
You can find the detailed documentation regarding the Mapper and the necessary configurations to be made in the Mapper in.
The product trigger under the Dashboard is only for creating operations. If a product update is desired, it should be done via CSV by selecting the 'Update Product Version Date in Bulk' section in the top-right of the channel settings, then choosing 'Update by Uploading File.' For trigger operations, this document can be used:
