Hepsijet Shipment Extension

Extension Installation

Preliminary Works

The following information is requested from the provider for the brand-specific and production (live) environment.

• SHIPPING_PROVIDER_BASE_URL
• SHIPPING_PROVIDER_USERNAME
• SHIPPING_PROVIDER_PASSWORD

A secret_key is generated with a minimum length of 41 characters. The generated key must be kept throughout the installation. An example command line to generate a random key:

openssl rand -base64 41

The SKU attribute is a unique identifier assigned to each product for tracking and inventory purposes. This attribute is required and must be unique for every product to ensure accurate inventory management, order processing, and sales tracking.

The deci attribute represents the dimensional weight of a product, calculated using the formula (W*L*H/3000). This value is essential for determining shipping costs, especially for logistics and carriers that base their rates on both weight and volume.

The barcode attribute is crucial for uniquely identifying each product within your inventory, enabling efficient tracking and automation of shipping and inventory processes. Ensure that each product has a unique barcode in a standard format for seamless integration and operation within the Omnitron configuration.

After deployment of the extension, an address ID must be set for the default destination information in easy-return shipments. It can be created using the extension's address creation method (example curl is given below). Ensure that the address ID is accurately configured to facilitate the smooth handling of return shipments within the Omnitron configuration. This generally represents the warehouse of the brand.

curl --location --request POST 'https://{extension_url}/addresses' \
--header 'x-akinon-request-id: d79f11f7-fdda-4ccd-9404-87a68dad406a' \
--header 'x-akinon-api-version: 1.0' \
--header 'Authorization: Basic {Token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "id": "{{akinonUniqueAddress}}",
  "addressName": "<Address Name>",
  "addressDescription": "<Address Description>",
  "phone": "<Phone>",
  "email": "<Email>",
  "type": "CUSTOMER",
  "address": {
    "country": {
      "id": 1,
      "code": "UK",
      "name": "United Kingdom"
    },
    "city": {
      "id": 1,
      "name": "London"
    },
    "district": {
      "id": 1,
      "name": "London"
    },
    "township": {
      "id": 1,
      "name": "London"
    },
    "zipcode": "00000",
    "addressLine": "Test Street No: 7/19"
  }
}'

When the USE_PENDING_ADDRESS environment variable is set to True, addresses are not created directly. Instead, a pending address is created first, and the actual merchant/store registration on HepsiJet happens only after the vknTckn and corporateName details are provided in a second step.

• USE_PENDING_ADDRESS=False (default): Existing behaviour. POST /addresses creates the address and performs the merchant/store create on HepsiJet immediately.
• USE_PENDING_ADDRESS=True: POST /addresses creates a pending address only (no merchant create). The address is completed later via the pending-address endpoints. Once completed, the merchant/store create is performed and the address becomes usable for shipping.

corporateName is sent to HepsiJet for both store and merchant records. If vknTckn is provided, the record is created as a merchant; otherwise it is created as a store.

List Pending Addresses:

GET /pending-addresses

Complete a Pending Address:

PATCH /pending-addresses/{remote_id}

{
  "vknTckn": "1234567890", // 10 or 11 length
  "corporateName": "Test Company Inc."
}

Environment Variables

The extension installed to the relevant project in ACC must have the following environment variables. You can ask the PAT team which extension version you should use while installing. Environment variables can be entered before or after the deployment phase. As changes are made to the environment variables, the deployment process must be performed again.

An example environment variable input during the setup phase:

Variable	Description
Extension-specific
SHIPPING_PROVIDER_BASE_URL	BASE_URL received during the preliminary works phase PROD: https://integration.hepsijet.com/ TEST: https://integration-apitest.hepsijet.com/
SHIPPING_PROVIDER_USERNAME	USERNAME received during the preliminary works phase
SHIPPING_PROVIDER_PASSWORD	PASSWORD received during the preliminary works phase
DISTRICT_IGNORED_KEYS	Optional. To remove specific part from the district string with defined REGEX. For example, the model \s(mah)(\s|\Z) can be used.
SHIPPING_EXPECTED_LABEL_FORMATS	LABEL_FORMATS variable specifies the acceptable formats for shipping labels. This variable is an optional field. Ex: ZPL,PDF
EASY_RETURN_DELIVERY_DATE_GAP	DELIVERY_DATE_GAP variable specifies the number of days between the current date and the expected delivery date for returned items. This variable is optional field
MERCHANT_RECIPIENT_ADDRESS	RECIPIENT_ADDRESS variable contains the seller buyer's address details. This variable is an optional field.
COMPANY_SHORT_PREFIX	A short prefix for forward shipment IDs on the provider side. This variable is an optional field. Ex: PAT
SHIPPING_PROVIDER_DELIVERY_TYPE	Brands using the 'retail' services of the provider must set the value to 'RETAIL'. Other brands should not use this variable.
SHIPPING_PROVIDER_XDOCK_ABBREVIATION_CODE	Brands using the 'retail' services of the provider must set the value to the string given by the provider. Other brands should not use this variable.
SHIPPING_PROVIDER_COMPANY_NAME	Brands using the 'retail' services of the provider must set the value to the string given by the provider. Other brands should not use this variable.
SHIPPING_PROVIDER_COMPANY_ABBREVIATION_CODE	Brands using the 'retail' services of the provider must set the value to the string given by the provider. Other brands should not use this variable.
MERCHANT_CREATE_MODE	This setting is applied during the Merchant Create service operation. Depending on the configured value, the serviceType parameter in the request will be assigned either null or TMH. STD: The merchant supports only standard shipments. XL: The merchant supports only XL shipments (shipments over 41 desi). BOTH: The merchant supports both standard and XL shipments. Example: MERCHANT_CREATE_MODE=BOTH Default: STD
USE_PENDING_ADDRESS
Generic
SECRET_KEY	The generated secret key during the preliminary works phase
ADMIN_EMAIL	The e-mail address of the installer can be entered
ADMIN_PASSWORD	A newly created and extension-specific strong password
ADMIN_USERNAME	A username can be entered (example: ‘akinon’)

Omnitron Settings

Explanations on how these settings can be configured are detailed in the sections below. Please note that these two operations are independent and optional. Additionally, an easy return option can be defined to enable easy return methods.

Settings for Forward Shipments

Hepsijet can be selected as the Shipment Provider in Omnitron to integrate with the extension installed.

Installation:

• Hepsijet cargo company was added to Omnitron.
• The shipping option is entered for the added cargo company
• SHIPPING_PROVIDERS dynamic settings are entered for the cargo company

If it is to be used, the warehouse address from which the package will be received

must be added to the omnitron and the extension. The generate_shipment_origin_strategy

value must be the omnitron address id. The installation steps of the shipment with OMS can be accessed from this link: OMS Shipping Management tutorial.

Example Omnitron Settings:

{
   "hepsijet": {
       "Klass": "omnitron.orders.shipping_providers.extension_cargo.ExtensionShippingProvider",
       "urls": {
           "base_url": "http://extension_url.akinon.net",
	  “tracking_url” : “https://hepsijet.com/gonderi-takibi/{tracking_number}”,
       },
       "serializers": {
           "order_serializer": "omnitron.orders.shipping_providers.serializers.ExtensionShippingOrderSerializer",
           "response_serializer": "omnitron.orders.shipping_providers.serializers.ExtensionShippingResponseSerializer"
       },
       "conf": {
           "strategies": {
               "generate_shipment_origin_strategy": "1112",
               "query_type": "SHIPMENT_ID",
               "generate_shipment_product_strategy": true,
               "generate_shipment_product_attributes": [
                   "deci",
                   "category"
               ]
           },
           "pay_on_delivery_option": false,
           "delivery_type": "CUSTOMER",
           "auth": {
               "username": "akinon",
               "password": "akinon"
           },
           "is_active": {
               "query": true,
               "send_shipping_info": true,
               "delete_shipping_info": false,
               "query_by_order": true
           },
           "label_options": {
               "file_extension": "pdf"
           }
       }
   }
}

Field	Field Type	Notes
shipping_company	<enum 'ShippingCompany'>	This value must be the shipping company enum value. Ex: aramex
generate_shipment_product_strategy	boolean	If product details will be sent, it should be set to `true`.
generate_shipment_product_attributes	list	The attributes of the product to be sent must be entered as a list. (Must be the features on the Product) Ex: integration_category
generate_shipment_origin_strategy	string	This address must be predefined in omnitron. This value is the id value of the address information kept in the omnitron. Ex: 231

Settings for Reverse Shipments (Easy Return)

One easy return shipping option must be defined in Omnitron to be specific for the extension installed. Explanations on how the settings should be made at this stage are in the table below.

Field	Description
Shipping Company	Extension Cargo
Shipping Company Auth Code	{ "url": "{extension_url}", "username": "{ADMIN_USERNAME}", "password": "{ADMIN_PASSWORD}", "send_user_address": true, "return_destination_extension_id": "{destination_id}", "easy_return_product_strategy": true, "product_attributes": { "barcode": “{atrribute_name}", "sku": “{atrribute_name}", "deci": “{atrribute_name} } }
Start Date Gap	This variable is used to delay the start date for using the return code. If this value is set to 0, the customer can request a refund on the same day.
Delivery Time	The delivery_time variable indicates the duration for which the return code will be valid and usable. If the product is not shipped by the customer within this period, the code becomes invalid.
Shipping Company Prefix	If a prefix is to be added to the return code, this field should contain the short name of the brand. This short name can be any value determined by the brand.
Shipping Company Rules	"product": { "field_key": "attributes__easy_return_method", "field_values": [ [ "", null ] ] }
Status	active

Important Notes

• There may be cases where the products in the OMS package send the desi information as zero. In this case, the desi value of each product is increased to 2. Therefore, twice the number of products is delivered to Hepsijet as a desi value.
• According to Hepsijet's brand-specific definitions, parcels within certain desi ranges are accepted. Therefore, necessary precautions must be taken as an error (appropriate service not found error) will occur while creating the cargo of the order for order packages that reach a desi amount that Hepsijet does not accept.
• Brands using the marketplace model of Hepsijet should ensure that each stock location is created once in the database of the provider. Please contact the provider and the transaction data in the extension if there is any doubt.