ShypV Shipment Extension

Preliminary Works

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

• API_URL

• API_USERNAME

• API_PASSWORD

• PARTNER_ID

• REFERENCE_SUFFIX

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 '{EXTENSION_URL}/addresses' \
--header 'x-akinon-request-id: 50dac251-048c-402f-91c9-e5573b5a6057' \
--header 'x-akinon-api-version: 1.0' \
--header 'Authorization: Basic {EXTENSION_BASIC_AUTH_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "1ac38925-6a04-42a5-b3b1-044eb4095e45", // 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": "Turkey"
        },
        "city": {
            "id": 0, // optional
            "name": "Istanbul"
        },
  "township": {
            "id": 0, // optional
            "name": "Kadıköy"
        },
        "district": {
            "id": 0, // optional
            "name": "ACIBADEM"
        },
        "coordinates": {
            "latitude": -80.2031,
            "longitude": 11.2438
        },
        "zipcode": "1724042906",
        "addressLine": "Caferağa Mahallesi, Dr. Esat Işık Caddesi No:35"
    }
}'

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_PASSWORD	API PASSWORD received during the preliminary works phase
PARTNER_ID	PARTNER ID received during the preliminary works phase
REFERENCE_SUFFIX	Additional value appended to the reference code in queries, based on the environment type (e.g., '_1_test' for TEST, '_1' for PROD). For further details, consult ShypV.
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

ShypV 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 ShypV, 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": [] }, "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" } }

Mapping

Mapping is mandatory to use ShypV Shipment Extension properly. There are 1 type of mapper that need to be defined:

Mapper Type	Description
AREA	Value used to map the district_name and township_name fields from the extension into a single AREA identifier recognized by ShypV. The mapping key is constructed using the format {district_name}::{township_name}, where components are separated by a double colon “::”. This mapped AREA value is required for proper communication with the ShypV system. Example: "Dubai::Deira" → "Deira"

Steps to Use the Mapper Method for the AREA:

1. Prepare the Information: First, prepare the district_name, township_name and area information.

2. Format the key: Format the district_name and township_name using format “{district_name}::{township_name}” separated by a double colon (“::”).

3. Map formatted key with area: The mapping method takes three values: type, key, and value.

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

   • Key: Use the formatted district_name and township_name as the key. Example: "Dubai::Deira".

   • Value: Assign the area as the value. Example: Deira.

When a request comes in with a specific district and township information, the outgoing request should include the corresponding area if a mapping exists. For example, if the formatted district_name and township_name "Dubai::Deira" is mapped to ”Deira”, any request with this information should include the area as ”Deira”.

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	Formatted key
Value	Expected value

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"