# Monist Shipment Extension

## <mark style="color:red;">**Extension Installation**</mark>

### <mark style="color:red;">**Preliminary Works**</mark>

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

* **API\_URL**
* **AUTH\_TOKEN**
* **ACCOUNT\_ID**
* **PRICE\_LIST**
* **DELIVERY\_TYPE**

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://8ad8dd652c004daeb009293f10def9ff.lb.akinoncloud.com/addresses' \
--header 'x-akinon-request-id: 50dac251-048c-402f-91c9-e5573b5a6057' \
--header 'x-akinon-api-version: 1.0' \
--header 'Authorization: Basic YWtpbm9uOmFraW5vbg==' \
--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": "+90 216 555 1234",
    "email": "Marlee42@example.net",
    "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"
    }
}'
```

In order to send the correct data to Monist, the product attribute with the code names\
“barcode”, "description" and “name” must be defined.

### <mark style="color:red;">**Environment Variables**</mark>

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.

<table><thead><tr><th width="227.22265625">Variable</th><th>Description</th></tr></thead><tbody><tr><td>Extension-specific</td><td></td></tr><tr><td>API_URL</td><td>URL received during the preliminary works phase (without a trailing slash at the end)</td></tr><tr><td>AUTH_TOKEN</td><td>AUTH TOKEN received during the preliminary works phase</td></tr><tr><td>ACCOUNT_ID</td><td>ACCOUNT ID received during the preliminary works phase</td></tr><tr><td>PRICE_LIST</td><td>"MPL" value is used for shipments that apply Monist pricing when the company is processing transactions through their own current accounts. "OPL" value is used for other pricing scenarios not involving Monist pricing.</td></tr><tr><td>RECIPIENT_EMAIL</td><td>Default email address to be used in the recipient information</td></tr><tr><td>DELIVERY_TYPE</td><td>“1” value is used for “Standard Delivery”, “2” value is used for “Next Day Delivery” and “3” value is used for “Same Day Delivery”.</td></tr><tr><td>Generic</td><td></td></tr><tr><td>SECRET_KEY</td><td>The generated secret key during the preliminary works phase</td></tr><tr><td>ADMIN_EMAIL</td><td>The e-mail address of the installer can be entered</td></tr><tr><td>ADMIN_PASSWORD</td><td>A newly created and extension-specific strong password</td></tr><tr><td>ADMIN_USERNAME</td><td>A username can be entered (example: ‘akinon’)</td></tr></tbody></table>

## <mark style="color:red;">**Omnitron Settings**</mark>

Monist 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.

### <mark style="color:red;">**Shipping Provider**</mark>

To add Monist, a new shipping provider is added to SHIPPING\_PROVIDERS in Dynamic Settings through Omnitron.

#### **Example Omnitron Configuration:**

<table><thead><tr><th width="191.00390625">Field</th><th>Description</th></tr></thead><tbody><tr><td>Klass</td><td>ExtensionShippingProvider Class</td></tr><tr><td>Urls Code</td><td>{ "urls": { "base_url": "<strong><code>{SHIPMENT_EXTENSION_URL}</code></strong>" } }</td></tr><tr><td>Serializers</td><td>Order Serializer: ExtensionShippingOrderSerializer Class Response Serializer: ExtensionShippingResponseSerializer Class</td></tr><tr><td>Configurations Code</td><td>{ "strategies": { "query_type": "SHIPMENT_ID", "generate_shipment_origin_strategy": "&#x3C;addressId>", "generate_shipment_product_strategy": true, "generate_shipment_product_attributes": [ "barcode", “description”, “name” ] }, "pay_on_delivery_option": false, "delivery_type": "CUSTOMER", "auth": { "username": "<strong><code>{SHIPMENT_EXTENSION_ADMIN_USERNAME}</code></strong>", "password": "<strong><code>{SHIPMENT_EXTENSION_ADMIN_PASSWORD}</code></strong>" }, "is_active": { "query": true, "send_shipping_info": true, "delete_shipping_info": true, "query_by_order": true }, "label_options": { "file_extension": "pdf" } }</td></tr></tbody></table>

### <mark style="color:red;">**Easy Return Shipping Option**</mark>

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:**

<table><thead><tr><th width="226.43359375">Field</th><th>Description</th></tr></thead><tbody><tr><td>Shipping Company</td><td>Extension Cargo</td></tr><tr><td>Shipping Company Auth Code</td><td>{ "url": "<strong><code>{SHIPMENT_EXTENSION_URL}</code></strong>", "username": "<strong><code>{SHIPMENT_EXTENSION_ADMIN_USERNAME}</code></strong>", "password": "<strong><code>{SHIPMENT_EXTENSION_ADMIN_PASSWORD}</code></strong>", “send_user_address”: True, “easy_return_product_strategy”: True, "return_destination_extension_id":"<strong><code>{address_id}</code></strong>" “product_attributes”: { "barcode": "<strong><code>{product_barcode_attribute}</code></strong>", "description": "<strong><code>{product_description_attribute}</code></strong>", "name": "<strong><code>{product_name_attribute}</code></strong>" } }</td></tr><tr><td>Start Date Gap</td><td>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.</td></tr><tr><td>Delivery Time</td><td>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.</td></tr><tr><td>Shipping Company Prefix</td><td>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.</td></tr><tr><td>Shipping Company Rules</td><td>{ "product": { "field_key": "attributes__easy_return_method", "field_values": [ [ "", null ] ] } }</td></tr><tr><td>Status</td><td>active</td></tr></tbody></table>

## <mark style="color:red;">**Mapping**</mark>

Mapping is mandatory to use Monist Shipment Extension properly. There are 2 types of mapper that need to be defined:

<table><thead><tr><th width="246.0546875">Mapper Type</th><th>Description</th></tr></thead><tbody><tr><td>ADDRESS</td><td>ADDRESS value formatted using the address values provided by the Monist Delivery Module. It is used for extension’s address information. Key must be formatted as “<strong><code>{akinon_country_name}//{akinon_city_name}//{akinon_township_name}</code></strong>”. Value must be formatted as “<strong><code>{country_name}$${country_id}//{city_name}$${city_id}//{district_name}$${district_id}</code></strong>”. Example: <code>{“Turkey//Istanbul//Kadikoy”: “TÜRKİYE$$1//İSTANBUL$$34//KADIKÖY$$455”}</code></td></tr><tr><td>ORIGIN_ID</td><td>WAREHOUSE ID value provided by the Monist 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 Monist Warehouse ID.</td></tr><tr><td><mark style="background-color:red;">Notes</mark></td><td><em>* In the Monist Delivery Module, the address flow is defined in the sequence of Country, City, District. To ensure the correct utilization of this flow, the TOWNSHIP information is equated to the DISTRICT information. ** Below are examples of the requests that need to be sent to the Monist Delivery Module to obtain the information specified here.</em></td></tr></tbody></table>

#### **Countries:**

```bash
curl --location 'https://api.delivery.monist.co/getCountries' \
--header 'auth_token: {auth_token}' \
--header 'account_id: {account_id}'
```

#### **Cities:**

```bash
curl --location 'https://api.delivery.monist.co/getCities \
--header 'auth_token: {auth_token}' \
--header 'account_id: {account_id}'
```

#### **Districts:**

```bash
curl --location 'https://api.delivery.monist.co/getDistricts' \
--header 'auth_token: {auth_token}' \
--header 'account_id: {account_id}'
```

#### **Warehouses:**

```bash
curl --location 'https://api.delivery.monist.co/getWarehouses' \
--header 'auth_token: {auth_token}' \
--header 'account_id: {account_id}'
```

#### **Steps to Use the Mapper Method for the ORIGIN ID:**

1. **Get the Warehouse Information:** First, access the warehouse information by using the Monist Delivery Module’ s “getWarehouses” method, an example of which is provided above.
2. **Create an Address:** Create an address using accessed warehouse information and obtain its ID.
3. **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` 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.

#### **Steps to Use the Mapper Method for the Address Information:**

1. **Get the Address Information:** First, access the desired address type’ s information by using the Monist Delivery Module’ s methods, examples of which are provided above. *Example: The “getCities” method can be used to obtain the defined city list out of Monist Delivery Module. Obtained city list includes item\_id and name information.*
2. **Prepare the Mapper Key:** Mapper key must include all three desired address information sorted as *Country*, *City*, *Township* separated by *Double Slash* (“*//*”). Example: `“Turkiye//Istanbul//Kadikoy”`.
3. **Prepare the Mapper Value:** Mapper value must include the name and the id values of desired address information in a specific format: `{name}$${item_id}` *Example: Obtained city list before includes Istanbul’ s information; “İSTANBUL” as name and 34 as item\_id. The value for Istanbul can be formatted as “İSTANBUL$$34”.* Address value must include all three address information. The final value example: `“TÜRKİYE$$1//İSTANBUL$$34//KADIKÖY$$455”`
4. **Map Address Key with Formatted Value:** The mapping method takes three values: type, key, and value.
   1. **Type:** Currently, the type is fixed as `ADDRESS`.
   2. **Key:** Use the formatted address key as the key. Example: `“Turkiye//Istanbul//Kadikoy”`.
   3. **Value:** Assign the formatted value as the value. Example: `“TÜRKİYE$$1//İSTANBUL$$34//KADIKÖY$$455”`.

When a request comes in with a specific address key, the outgoing request should include the corresponding name and item\_id of all address information if a mapping exists. For example, if the address key `“Turkiye//Istanbul//Kadikoy”` is mapped to `“TÜRKİYE$$1//İSTANBUL$$34//KADIKÖY$$455”`, any request with this address key should include “TÜRKİYE” as country name, 1 as country id, “İSTANBUL” as city name, 34 as city id, “KADIKÖY” as district name, 455 as district id.

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

#### **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/<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.

```bash
curl -X GET "{{extension_url}}/mapper?key=<key>" \
     -u username:password \
     -H "Content-Type: application/json"
```

#### **Delete Mapping Request:**

```bash
curl -X DELETE "{{extension_url}}/mapper/<id>" \
     -u username:password \
     -H "Content-Type: application/json"
```

## <mark style="color:red;">**Additional Notes**</mark>

* There is no endpoint that allows for a created easy-return to delete. Unused easy-return deliveries will be deleted automatically by the Monist Delivery Module.


---

# 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/monist-shipment-extension.md?ask=<question>
```

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.