Horoz Lojistik Shipment Extension

Extension Installation

Preliminary Works

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

  • API_URL

  • PROCESS_KEY

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

For easy-return and forward shipments, an address ID must be set for the default destination and origin information. This ID can be created using the extension's address creation method (an example cURL command is provided below). Ensure that the address ID is accurately configured to facilitate the smooth handling of return and forward shipments within the Omnitron configuration.

curl --location --request GET 'https://{{extension_url}}/addresses' \
--header 'x-akinon-request-id: {{guid}}' \
--header 'x-akinon-api-version: 1.0' \
--header 'Authorization: Basic {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "<id>",
    "addressName": "ADDRESS NAME",
    "addressDescription": "...",
    "phone": "639-228-8456",
    "email": "akinon@akinon2.com",
    "address": {
        "country": {
            "id": 1,
            "code": "TC",
            "name": "TÜRKİYE"
        },
        "city": {
            "id": 1,
            "name": "İSTANBUL"
        },
        "district": {
            "id": 1,
            "name": "ESENLER"
        },
        "township": {
            "id": 1,
            "name": "PENDİK"
        },
        "zipcode": "1724588042",
        "addressLine": "771 Kyleigh Via"
    },
    "type": "DISTRIBUTION_POINT"}'

In order to send the correct data to Horoz Lojistik, the product attribute with the code names “barcode”, "weight", “deci“ and “name” must be defined.

Environment Variables

The extension installed to the relevant project in ACC must have the following environment variables. 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.

Variable
Description

Extension-specific

API_URL

URL received during the preliminary works phase (without a trailing slash at the end)

PROCESS_KEY

Process Key received during the preliminary works phase.

COMPANY_NAME

The recipient title and sender title information in the data sent during easy return and forward shipment.

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

Horoz can be selected as the Shipment Provider in Omnitron to integrate with the extension installed. Additionally, an easy return option can be defined to enable easy return methods. Explanations on how these settings can be configured are detailed in the sections below. Please note that these two operations are independent and optional.

Shipping Provider

To add Horoz Lojistik, a new shipping provider is added to SHIPPING_PROVIDERS in Dynamic Settings through Omnitron.

Example Omnitron Configuration:

Field
Description

Klass

ExtensionShippingProvider Class

Urls Code

{ "urls": { "base_url": "{SHIPMENT_EXTENSION_URL}" } }

Serializers

Order Serializer: ExtensionShippingOrderSerializer Class Response Serializer: ExtensionShippingResponseSerializer Class

Configurations Code

{ "strategies": { "query_type": "SHIPMENT_ID", "generate_shipment_origin_strategy": "<addressId>", "generate_shipment_product_strategy": true, "generate_shipment_product_attributes": [ "barcode", “description”, “name”, “weight”, “deci” ] }, "pay_on_delivery_option": false, "delivery_type": "CUSTOMER", "auth": { "username": "{SHIPMENT_EXTENSION_ADMIN_USERNAME}", "password": "{SHIPMENT_EXTENSION_ADMIN_PASSWORD}" }, "is_active": { "query": true, "send_shipping_info": true, "delete_shipping_info": true, "query_by_order": true }, "label_options": { "file_extension": "pdf" } }

Easy Return Shipping Option

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

Example Omnitron Configuration:

Field
Description

Shipping Company

Extension Cargo

Shipping Company Auth Code

{ "url": "{SHIPMENT_EXTENSION_URL}", "username": "{SHIPMENT_EXTENSION_ADMIN_USERNAME}", "password": "{SHIPMENT_EXTENSION_ADMIN_PASSWORD}", “send_user_address”: True, “easy_return_product_strategy”: True, "return_destination_extension_id":"{address_id}" “product_attributes”: { "barcode": "{product_barcode_attribute}", "name": "{product_name_attribute}" “weight”: "{product_weight_attribute}" “deci”: "{product_deci_attribute}" } }

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

Mapping

Mapping is mandatory to use Horoz Lojistik Shipment Extension properly. There are 2 types of mapper that need to be defined:

Mapper Type
Description

CITY

CITY value provided by the Horoz listCounties service.

TOWNSHIP

TOWNSHIP value provided by the Horoz listCounties service.

City and Township:

curl --location --request GET '{api_url}' \
--header 'processKey: {process_key}' \
--header 'Accept: application/json'
Field
Description

Extension URL

The URL of the shipment extension

Username

Extension user's name for authorization

Password

Extension user's password for authorization

Type

Mapping type

Key

Desired city/township name

Value

The cargo side equivalent of the city/township specified as key

Generate Mapping Request:

curl -X POST {{extension_url}}/mapper \
     -u username:password \
     -H "Content-Type: application/json" \
     -d '{
           "type": "",
           "key": "",
           "value": ""
         }'

Update Mapping Request:

* The values for key, type, and value should be updated.

curl -X PATCH "{{extension_url}}/mapper/<id>" \
     -u username:password \
     -H "Content-Type: application/json" \
     -d '{
           "type": "",
           "key": "",
           "value": ""
         }'

Get Mapping Request:

* When making a query request, it can be filtered by the fields type, key, value, created_date and modified_date.

curl -X GET "{{extension_url}}/mapper?key=<key>" \
     -u username:password \
     -H "Content-Type: application/json"

Delete Mapping Request:

curl -X DELETE "{{extension_url}}/mapper/<id>" \
     -u username:password \
     -H "Content-Type: application/json"

Additional Notes

  • The fields used in the payload for the "createShipping" method in integrations vary on the Horoz side depending on the customer and client, as well as the values passed to these fields.

Last updated

Was this helpful?