> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/3rd-party-integration/shipment-integrations/hepsijet-shipment-extension.md). # 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. ```json 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": "
", "addressDescription": "
", "phone": "", "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:** ```json 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:
TEST:

| | 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 {% hint style="danger" %} 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](/tutorials/oms/shipping-management.md) tutorial. {% endhint %} **Example Omnitron Settings:** ```json { "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 | \ | 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.akinon.com/technical-guides/3rd-party-integration/shipment-integrations/hepsijet-shipment-extension.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.