# Fero AI Shipment Extension
## **Extension Installation**
### **Preliminary Works**
The following information is requested from the provider for the brand-specific and production (live) environment.
* **API\_URL**
* **CUSTOMER**
* **API\_TOKEN**
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 --request POST '{{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": , // return_destination_extension_id in Omnitron config,
"addressName": "Test Address Name",
"addressDescription": "Test Description",
"phone": "+971547932376",
"email": "testuser@example.net",
"type": "DISTRIBUTION_POINT",
"address": {
"country": {
"id": , // optional
"code": "AE",
"name": "AE"
},
"city": {
"id": , // optional
"name": "Dubai"
},
"township": {
"id": , // optional
"name": "Al Raffa"
},
"district": {
"id": , // optional
"name": "Al Quoz Industrial Area 4"
},
"zipcode": "Al Quoz Industrial Area 4",
"addressLine": "6thStreet, 6thStreet DC, 6thStreet No 14 B, Al Raffa, Dubai, AE"
}
}'
```
{% hint style="info" %}
"district" field is optional.
{% endhint %}
In order to send the correct data to Fero AI, the product attributes with the code names "name", “height”, “width”, “length” and “weight” should be defined.
**UAT API\_URL**: [https://ferointegrationuat.feroai.com](https://ferointegrationuat.feroai.com/)
**PROD API\_URL**: [https://ferointegration.feroai.com](https://ferointegration.feroai.com/)
### **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) |
| CUSTOMER | CUSTOMER received during the preliminary works phase. It is customer code/username |
| API\_TOKEN | API TOKEN received during the preliminary works phase |
| CLOSING\_TIME | Closing time of warehouse/store. This is the latest time it should be picked up by the courier. HH:MM |
| READY\_AT\_TIME | Opening time of warehouse/store. This is the earliest time it should be picked up by the courier. HH:MM |
| LANDMARK\_MAPPING | Defines which landmark mapping should be used. Default is TOWNSHIP Values: CITY, TOWNSHIP |
| CREDENTIALS | Can be set for multiple credentials support. JSON, Ex: {“customer\_1”:“token\_1”,“customer\_2”:“token\_2”} |
| TRACKING\_URL | Used for obtaining the tracking url for the shipment. Example: |
| 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**
Fero AI 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 Fero AI, 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}`**", "tracking\_url": "[https://skyexpressinternational.com/Home/Tracking?trackingType=AWB\&tid={waybill\_number}](https://skyexpressinternational.com/Home/Tracking?trackingType=AWB\&tid={tracking_number})" } } |
| 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": \[ “length”: “**{product\_length}**”, “width”: “**{product\_width}**”, “height”: “**{product\_height}**”, “weight”: “**{product\_height}**” ] }, "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”: { “length”: “**{product\_length}**”, “width”: “**{product\_width}**”, “height”: “**{product\_height}**”, “weight”: “**{product\_height}**” } } |
| 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**
This method is used to assign a country, city, landmark, and city\_credential to a specific format. Required if these field values aren't the same as Omnitron or OMS .
**Map Address Value with** `country/city_code/city_landmark/township_landmark/`city\_credential\*\*:\*\* The mapping method takes three values: type, key, and value.
* **Type:** `COUNTRY|CITY_CODE|CITY_LANDMARK|TOWNSHIP_LANDMARK|CITY_CREDENTIAL`.
* **Key:** Use the Omnitron/OMS value as the key.
* **Value:** Use the `Fero AI Equivalent` as the value.
**Examples:**
1. * **Type:** COUNTRY
* **Key:** UAE
* **Value:** AE
2. * **Type:** CITY\_CODE
* **Key:** DUBAI
* **Value:** DBX
3. * **Type:** TOWNSHIP\_LANDMARK
* **Key:** Al-Raffa
* **Value:** Al Raffa
4. * **Type:** CITY\_LANDMARK
* **Key:** Abu Dhabi
* **Value:** ABU DHABI
5. * **Type:** `CITY_CREDENTIAL`
* **Key:** DUBAI
* **Value:** AL1234
To get cities for CITY\_LANDMARK from Fero AI, use:
```bash
curl --location 'https://ferointegrationuat.feroai.com/api/v1/integration/location/' \
--header 'Token:
```
To get townships for TOWNSHIP\_LANDMARK from Fero AI, use:
```bash
curl --location 'https://ferointegrationuat.feroai.com/api/v1/integration/area/' \
--header 'Token:
```
To get cities for CITY\_CODE from Fero AI, use:
```bash
curl --location 'https://ferointegrationuat.feroai.com/api/v1/integration/location/' \
--header 'Token:
```
| 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 | COUNTRY |
| Key | Omnitron/OMS value of the field |
| Value | Fero AI value of the field or customer value for the city-credentials mapping. |
#### **Generate Mapping Request:**
```bash
curl -X POST {{extension_url}}/mapper \
-u username:password \
-H "Content-Type: application/json" \
-d '{
"type": "",
"key": "",
"value": ""
}'
```
#### **Example:**
```bash
curl -X POST {{extension_url}}/mapper \
-u username:password \
-H "Content-Type: application/json" \
-d '{
"type": "CITY_CREDENTIAL",
"key": "DUBAI",// city data in Omnitron
"value": "customer_1" // defined in env. var.
}'
```
#### **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"
```
## **OMS Settings**
For OMS, “strategies” field in Shipping Management must be defined accordingly:
```
{"send_product_info":true,"product_attributes":["length","width","height","weight"]}
```
## **Additional Notes**
* There are no endpoints that allow for a "customer address" change.
* If the CREDENTIALS variable doesn’t provided in .env or a city doesn’t have any mapping with CITY\_CREDENTIAL, extension uses default credentials as CUSTOMER and API\_TOKEN
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.akinon.com/technical-guides/3rd-party-integration/shipment-integrations/fero-ai-shipment-extension.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.