Kolay Gelsin Shipment Extension

Extension Installation

Preliminary Works

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

• API_URL

• API_USERNAME

• API_TOKEN

• CUSTOMER_ID

• ADDRESS_ID

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

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.

curl --location '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(str)>, // return_destination_extension_id in Omnitron config,
    "addressName": "Jacobs Group",
    "addressDescription": "totam quisquam qui",
    "phone": "[phone]",
    "email": "[e-mail]",
    "type": "PICK_UP_LOCATION",
    "address": {
        "country": {
            "id": 0, // optional
            "code": "TR",
            "name": "Türkiye"
        },
        "city": {
            "id": 0, // optional
            "name": "Istanbul"
        },
  "township": {
            "id": 0, // optional
            "name": "Kadıköy"
        },
        "district": {
            "id": 0, // optional
            "name": "Acıbadem"
        },
        "zipcode": "34100",
        "addressLine": "Caferağa Mahallesi, Dr. Esat Işık Caddesi No:35"
    }
}'

In order to send the correct data to Kolay Gelsin, the product attribute with the code names “deci” 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)
API_USERNAME	API USERNAME received during the preliminary works phase
API_TOKEN	API TOKEN received during the preliminary works phase. It should be retrieved from Kolay Gelsin, on a yearly basis.
CUSTOMER_ID	CUSTOMER ID received during the preliminary works phase.
ADDRESS_ID	Sender ADDRESS ID received during the preliminary works phase. The address should be added via Kolay Gelsin Dashboard. After adding the address, the ID should be mapped to the same address in OMS/Omnitron using ORIGIN_ID mapping as explained in the Mapping section of this document.
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

Kolay Gelsin 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 Kolay Gelsin, 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": [ "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": "html" } }

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}", "description": "{product_description_attribute}", "name": "{product_name_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 Kolay Gelsin Shipment Extension properly. There are 2 types of mapper. City mapper is defined for you. You need to define ORIGIN_ID mapper:

Mapper Type	Description
CITY	CITY value provided by the Kolay Gelsin Delivery Module. Must be formatted as “{city_id}”. Example: “34” for İstanbul. Plate numbers should be used as value (city_id). These are already added into fixtures, if more needed, it can be added via mapper defined below.
ORIGIN_ID	WAREHOUSE ID value provided by the Kolay Gelsin Delivery Module. It is used for mapping the extension's address_id information, which corresponds to the addresses designated as the departure point for shipments and/or the destination for returns, to the Kolay Gelsin Warehouse ID.
Notes
* In the Kolay Gelsin Delivery Module, the address flow is defined in the sequence of Country, City, Township, and District. ** Below are examples of the requests that need to be sent to the Kolay Gelsin Delivery Module to obtain the information specified here.

Steps to Use the Mapper Method for the ORIGIN ID:

1. Create an Address: Create an address according to your warehouse information and obtain its ID.

2. Map Address ID with warehouse_id: The mapping method takes three values: type, key, and value.

   • Type: Currently, the type is fixed as ORIGIN_ID.

   • Key: Use the created address ID as the key. Example: 61b2f0d5-42a2-4746-a090-c162099a0809.

   • Value: Assign the warehouse_id taken from Kolay Gelsin as the value. Example: 1.

When a request comes in with a specific address ID, the outgoing request should include the corresponding warehouse_id if a mapping exists. For example, if the address ID 61b2f0d5-42a2-4746-a090-c162099a0809 is mapped to 1, any request with this address ID should include warehouse_id as 1.

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 Address Name for Address Information or Address ID for Origin ID
Value	Formatted address name and id for Address Information or Warehouse ID for Origin ID

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

1. API_TOKEN should be retrieved from Kolay Gelsin or its dashboard, on a yearly basis.

2. fixtures.json should be loaded for city mapping. For further needed mappings, a CITY mapping should be added via mapper.

3. There are two actions to be taken on the dashboard Webhook > Webhook Settings:

   1. Webhook should be passivized (“Web servisime geri bildirim istiyorum” should be False)

   2. The most cargo statuses (Kargo Aksiyonları) should be checked for both FORWARD and REVERSE shipment; however the below statuses shouldn’t be checked for both of them (if they are checked, they should be unchecked):

      1. Gönderen bilgisi değişti

      2. Zimmet Bırakıldı

      3. Görev tamamlandı

      4. Hatalı Sevk Okutması Yapıldı

      5. Müşteri Kaynaklı Hatalı Sevk

      6. Kolay Gelsin Kaynaklı Hatalı Sevk

      7. Hatalı Sevk Değil