> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/3rd-party-integration/shipment-integrations/carriyo-shipment-extension.md).

# Carriyo 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`
* `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.

```http
curl --location '{{ExtensionUrl}}/addresses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{token}}' \
--data-raw '{
    "id": "<id>",
    "addressName": "TEST8",
    "addressDescription": "test description",
    "phone": "+971501234567",
    "email": "test@akinon.com",
    "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.

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

| **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 | <p>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. </p><p>Example value:</p><p>{"AU": "1002"} // country code and address id</p> |
| OMNITRON\_URL                | <p>Required field. Base URL of the brand’s Omnitron. </p><p>Used to retrieve product price and currency information.</p><p>Example:  https\://{OMNITRON\_URL}.com</p>                                                                                         |
| 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’)                                                                                                                                                                                                                 |

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

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.

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

To add Carriyo, a new shipping provider is added to `SHIPPING_PROVIDERS` in Dynamic Settings through Omnitron.

#### <mark style="color:red;">Example Omnitron Configuration:</mark>

| **Field**           | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Klass               | ExtensionShippingProvider Class                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Urls Code           | <p>{</p><p>    "urls": {</p><p>        "base\_url": "<code>{SHIPMENT\_EXTENSION\_URL}</code>"</p><p>    }</p><p>}</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Serializers         | <p>Order Serializer: ExtensionShippingOrderSerializer Class</p><p>Response Serializer: ExtensionShippingResponseSerializer Class</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Configurations Code | <p>{</p><p>    "strategies": {</p><p>        "query\_type": "SHIPMENT\_ID",</p><p>        "generate\_shipment\_origin\_strategy": "\<addressId>",</p><p>        "generate\_shipment\_product\_strategy": true,</p><p>        "generate\_shipment\_product\_attributes": \[</p><p>            "weight",</p><p>            “unit”</p><p>        ]</p><p>    },</p><p>    "pay\_on\_delivery\_option": false,</p><p>    "delivery\_type": "CUSTOMER",</p><p>    "auth": {</p><p>        "username": "{SHIPMENT\_EXTENSION\_ADMIN\_USERNAME}",</p><p>        "password": "{SHIPMENT\_EXTENSION\_ADMIN\_PASSWORD}"</p><p>    },</p><p>    "is\_active": {</p><p>        "query": true,</p><p>        "send\_shipping\_info": true,</p><p>        "delete\_shipping\_info": true,</p><p>        "query\_by\_order": true</p><p>    },</p><p>    "label\_options": {</p><p>        "file\_extension": "pdf"</p><p>    }</p><p>}</p> |

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

#### <mark style="color:red;">Example Omnitron Configuration:</mark>

| **Field**                  | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Shipping Company           | Extension Cargo                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Shipping Company Auth Code | <p>{</p><p>    "url": "<code>{SHIPMENT\_EXTENSION\_URL}</code>",</p><p>    "username": "<code>{SHIPMENT\_EXTENSION\_ADMIN\_USERNAME}</code>",</p><p>    "password": "<code>{SHIPMENT\_EXTENSION\_ADMIN\_PASSWORD}</code>",</p><p>    “send\_user\_address”: True,</p><p>    “easy\_return\_product\_strategy”: True,</p><p>    "return\_destination\_extension\_id":"<code>{address\_id}</code>"</p><p>    “product\_attributes”: {</p><p>        "description": "description",</p><p>        "name": "<code>{product\_attribute\_code}</code>",</p><p>        "weight": "<code>{product\_attribute\_code}</code>",</p><p>        "unit": "<code>{product\_attribute\_code}</code>",</p><p>        "hs\_code": "<code>{product\_attribute\_code}</code>",</p><p>        "country\_of\_origin": "<code>{product\_attribute\_code}</code>"<br>    }</p><p>}</p> |
| 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     | <p>{</p><p>    "product": {</p><p>        "field\_key": "attributes\_\_easy\_return\_method",</p><p>        "field\_values": \[</p><p>            \[</p><p>                "",</p><p>                null</p><p>            ]</p><p>        ]</p><p>    }</p><p>}</p><p><br></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Status                     | active                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

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

**Useful links:**

* [Carriyo - Payment Method Mapping Document for Cross-Border (COD)](https://docs.google.com/document/d/142fV1ZR_lwN0n--TCa4VWpsbN4QrHv6ng0ot0lPTnww/edit?tab=t.0)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.akinon.com/technical-guides/3rd-party-integration/shipment-integrations/carriyo-shipment-extension.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.
