Carriyo 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_CLIENT_ID
• API_CLIENT_SECRET
• API_KEY
• TENANT_ID
• MERCHANT_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 '{{ExtensionUrl}}/addresses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{token}}' \
--data-raw '{
    "id": "<id>",
    "addressName": "TEST8",
    "addressDescription": "test description",
    "phone": "[phone]",
    "email": "[e-mail]",
    "address": {
        "country": {
            "id": 34,
            "code": "AE",
            "name": "AE"
        },
        "city": {
            "id": 34,
            "name": "DUBAI"
        },
        "district": {
            "id": 1,
            "name": "DUBAI"
        },
        "township": {
            "id": 1,
            "name": "DUBAI"
        },
        "zipcode": "1725275012",
        "addressLine": "082 Padberg Island"
    }
}'

In order to send correct data to Carriyo, product attributes with code names "weight" and "unit" need to 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_CLIENT_ID	CLIENT_ID value to be received by Carriyo
API_CLIENT_SECRET	CLIENT_SECRET value to be received by Carriyo
API_KEY	API_KEY value to be received by Carriyo
TENANT_ID	TENANT_ID value to be received by Carriyo
MERCHANT_ID	MERCHANT_ID value to be received by Carriyo
ORDER_TYPE_FORWARD	Optional. The value to send to Carriyo for the order type during forward shipments.
ORDER_TYPE_REVERSE	Optional. The value to send to Carriyo for the order type during reverse shipments.
DELIVERY_TYPE_FORWARD	Optional. The value to send to Carriyo for the delivery type during forward shipments.
DELIVERY_TYPE_REVERSE	Optional. The value to send to Carriyo for the delivery type during reverse shipments.
CROSS_BORDER_COUNTRY_CODE	Optional. Use it if you need to specify addresses already created in the extension. As a result, cross border returns will be redirected to the specified warehouse address. Example value: {"AU": "1002"} // country code and address id
OMNITRON_URL	Required field. Base URL of the brand’s Omnitron. Used to retrieve product price and currency information. Example: https://{OMNITRON_URL}.com
OMNITRON_TOKEN	Required field. Authentication token of the brand’s Omnitron service. Used to retrieve product price and currency information.
PACKAGE_SOURCE	Required field. Specifies the source of product price and currency data. Can be either OMS or OMNITRON. The default value is OMNITRON
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

Carriyo 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 Carriyo, 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": [ "weight", “unit” ] }, "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”: { "description": "description", "name": "{product_attribute_code}", "weight": "{product_attribute_code}", "unit": "{product_attribute_code}", "hs_code": "{product_attribute_code}", "country_of_origin": "{product_attribute_code}" } }
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

Additional

Useful links:

• Carriyo - Payment Method Mapping Document for Cross-Border (COD)