# Porter Express 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\_EMAIL**
* **API\_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
```
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.
```bash
curl --location 'https:///addresses' \
--header 'x-akinon-request-id: ' \
--header 'x-akinon-api-version: 1.0' \
--header 'Authorization: Basic ' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": , // return_destination_extension_id in Omnitron config,
"addressName": "Jacobs Group",
"addressDescription": "totam quisquam qui",
"phone": "+90 216 555 1234",
"email": "Marlee42@example.net",
"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": { // optional
"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 Porter Express, the product attribute with the code names\
“weight” 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\_EMAIL | API EMAIL received from Porter Express during the preliminary works phase. |
| API\_PASSWORD | API PASSWORD received from Porter Express during the preliminary works phase. |
| AREA\_TYPE | AREA\_TYPE may be set to one of the two values: TOWNSHIP (default) or CITY. If the TOWNSHIP option is chosen, It is optional to add as environment variable Encrypted Ids of Areas are sent. TOWNSHIP mapping should be done. Otherwise (CITY option is chosen): It is mandatory to add as environment variable Country Code, City Name and AreaName (as NA) are sent. CITY mapping should be done. |
| 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**
Porter Express 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 Porter Express, 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": "\", "generate\_shipment\_product\_strategy": true, "generate\_shipment\_product\_attributes": \[ "weight" ] }, "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}`**", "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 Porter Express Shipment Extension properly. There are 3 types of mapper. You need to define CITY, TOWNSHIP and ORIGIN\_ID mapper:
| Mapper Type | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CITY | It is mandatory if the AREA\_TYPE environment variable is set to CITY. Country code and city name coming from omnitron/oms. **Key** should be formatted as “**`{country_code}::{city_name}`**”. Example: “KW::Ahmadi” for Ahmadi and for Kuwait. CITY name provided by the Porter Express GetCities service. **Value** should be written as “**`{name}`**”. Example: “AHMADI” for AHMADI (KW parameter retrieves cities from Kuwait) |
| TOWNSHIP | It is mandatory if the AREA\_TYPE environment variable is not added or it is set to TOWNSHIP. Country code, city name and township name coming from omnitron/oms. **Key** should be formatted as “**`{country_code}::{city_name}::{township_name}`**”. Example: “KW::Ahmadi::Abdulla Harbour” for Abdulla Harbour, for Ahmadi and for Kuwait. Area encryptedId provided by the Porter Express GetAreas service. **Value** should be written as “**`{encryptedId}`**”. Example: “8a25920e-72f0-47f2-9de4-e4eeed140e00” for ABDULLA HARBOUR (72883b70-8490-4de2-a665-7132f97ba7ba parameter is AHMADI’s encryptedId and it retrieves areas from AHMADI) |
| Notes | |
| *\* In the Porter Express Delivery Module, the address flow is defined in the sequence of Country, City, Township. \*\* Below are examples of the requests that need to be sent to the Porter Express Delivery Module to obtain the information specified here.* | |
#### **Steps to Use the Mapper Method for the CITY:**
1. **It is mandatory to do CITY mapping if AREA\_TYPE is set as CITY.**
2. **Map City formatted name with Porter Express defined name:** The mapping method takes three values: type, key, and value.
* **Type:** Currently, the type is fixed as `CITY`.
* **Key:** Use the omnitron/oms values as the key. Example: `KW::Ahmadi`
* **Value:** Assign the `City name` taken from Porter Express GetCities service as the value. Example: `AHMADI`
When a request comes in with a specific city, the outgoing request should include the corresponding city name if a mapping exists. For example, if the country is Kuwait and the city is Ahmadi, the city is mapped to AHMADI.
| 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: CITY |
| Key | CountryCode::CityName coming from omnitron/oms |
| Value | City Name retrieved from Porter Express GetCities service |
#### **Steps to Use the Mapper Method for the TOWNSHIP:**
1. **It is mandatory to do CITY mapping if AREA\_TYPE is set as CITY.**
2. **Map Township formatted name with Porter Express defined encryptedId:** The mapping method takes three values: type, key, and value.
* **Type:** Currently, the type is fixed as `TOWNSHIP`.
* **Key:** Use the omnitron/oms values as the key. Example: `KW::Ahmadi::Abdulla Harbour`
* **Value:** Assign the `Township encryptedId` taken from Porter Express GetAreas service as the value. Example: `8a25920e-72f0-47f2-9de4-e4eeed140e00`
When a request comes in with a specific city, the outgoing request should include the corresponding city name if a mapping exists. For example, if the country is Kuwait and the city is Ahmadi, the city is mapped to AHMADI.
| 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: TOWNSHIP |
| Key | CountryCode::CityName::TownshipName coming from omnitron/oms |
| Value | Area Encrypted ID retrieved from Porter Express GetAreas service |
### Example Requests
#### **Generate Mapping Request:**
```bash
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.
```bash
curl -X PATCH "{{extension_url}}/mapper/" \
-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.
```bash
curl -X GET "{{extension_url}}/mapper?key=" \
-u username:password \
-H "Content-Type: application/json"
```
#### **Delete Mapping Request:**
```bash
curl -X DELETE "{{extension_url}}/mapper/" \
-u username:password \
-H "Content-Type: application/json"
```
## **Additonal Notes**
* Porter Express Services:
* GetCities for CITY mapping: id parameter is country code.
* GetAreas for TOWNSHIP mapping: id parameter is the encryptedId of the city.