Carrier Integrations APIs

Modified on Wed, 1 Oct at 8:43 PM

Check OTO Delivery Fee

Endpoint URL

POST https://api.tryoto.com/rest/v2/checkOTODeliveryFee

Example Request Body

Here is an example of a request body:

{
  "originCity": "ar rass",
  "destinationCity": "Riyadh",
  "boxes": [
    {
      "width": 40,
      "length": 40,
      "height": 30,
      "weight": 3,
      "boxName": "Box1"
    },
    {
      "width": 25,
      "length": 25,
      "height": 30,
      "weight": 7,
      "boxName": "Box2"
    }
  ]
}

Request Parameters

Name	Required	Type	Description
originCity	yes	string	pickup city
destinationCity	yes	string	destination city
originLat	no	number	reqired for `bullet` type
originLon	no	number	reqired for `bullet` type
destinationLat	no	number	reqired for `bullet` type
destinationLon	no	number	reqired for `bullet` type
weight\*	yes	number	approximate weight of package(kg)
forReverseShipment	no	boolean	When you set is true, it will list the delivery companies that you can create reverse shipments.
currency	no	string	ISO 4217 code, "SAR","KWD", etc
packageCount	no	number	1
totalDue	no	number	cash on delivery amount
length	no	number	length of the package(cm)
width	no	number	width of the package(cm)
height	no	number	height of the package(cm)
serviceType	no	enum	`express`,`sameDay`, `fastDelivery`, `coldDelivery`,`heavyAndBulky`, `electronicAndHeavy`
deliveryType	no	enum	`toCustomerDoorstep pickupByCustomer toCustomerDoorstepOrPickupByCustomer`

Available Packages : All Packages

This API endpoint calculates shipping prices offered by OTO rates. By providing the origin city, destination city, and package details (such as weight and dimensions), the API computes the price based on the provided request parameters.

##### Important Note:

The prices returned by this API are applicable only to shipping options available under OTO's contracts.

To calculate prices for your own custom contracts, please use the Check Delivery Fee API.

You can see the shipping prices of delivery companies regarding to your account's country information.

##### Pricing Calculation Details:

The price is determined based on the greater value between the actual weight and the volumetric weight of the package.

Be sure to include the larger of these two values in your request.

Request Parameters: |

Check Delivery Fee

Endpoint URL

POST https://api.tryoto.com/rest/v2/checkDeliveryFee

Example Request Body

Here is an example of a request body:

{
  "weight": "50",
  "totalDue": 10,
  "originCity": "Riyadh",
  "destinationCity": "Jeddah",
  "height": 170,
  "width": 50,
  "length": 50
}

Request Parameters

Name	Required	Type	Description
originCity	yes	string	pickup city
destinationCity	yes	string	destination city
weight	yes	number	weight of package
totalDue	no	number	cash on delivery amount
deliveryType	no	enum	`bullet`,`courier`
originLat	no	string	reqired for `bullet` type
originLon	no	string	reqired for `bullet` type
destinationLat	no	string	reqired for `bullet` type
destinationLon	no	string	reqired for `bullet` type

Available Packages: All Packages

This API endpoint calculates contract based pricing using your own rates. By providing the origin city, destination city, and package details such as weight and dimensions, the API determines the price based on the supplied parameters.

Important Note: The prices returned by this API apply exclusively to your own contracts.

Request Parameters: |

Get Delivery Fee

Endpoint URL

POST https://api.tryoto.com/rest/v2/getDeliveryFee

Example Request Body

Here is an example of a request body:

{
  "orderId": "OID-22700-1006"
}

Request Parameters

Name	Required	Type	Description
orderId	yes	string	Id of the order
deliveryCompanySettingsId	no	string	Delivery Company settings id

Available Packages: All Packages

This API endpoint calculates the shipping fee for a specific order in OTO. It offers two methods for price calculation:

1. By Order ID: Provide the orderId, and the API will return all possible shipping rates for each defined shipping company.

2. By Delivery Option ID: Provide the deliveryOptionId to calculate the shipping fee for a specific shipping company. You can get this information from checkOTODeliveryFee or from checkDeliveryFee endpoints.

Request Parameters: |

Get Delivery Estimation

Endpoint URL

POST https://api.tryoto.com/rest/v2/getDeliveryEstimation

Example Request Body

Here is an example of a request body:

{
  "calculationData": {
    "originAddress": {
      "city": "Riyadh",
      "country": "SA",
      "lat": 45,
      "lon": 45,
      "district": ""
    },
    "destinationAddress": {
      "city": "Riyadh",
      "country": "SA",
      "lat": 45,
      "lon": 45,
      "district": ""
    }
  },
  "deliveryCompanySettingsId": 1233,
  "slaMethodType": "CITY_BASED"
}

Request Parameters

Name	Required	Type	Description
calculationData	yes	JSONObject	Attributes will be used to calculate estimations
deliveryCompanySettingsId	no	number	To ask for specific contract
slaMethodType	no	enum	To filter contracts based on the SLA Calculation Method. Enum list: \["BULLET_KM","CITY_BASED","DISTRICT_BASED","KM_BASED","TIER_BASED"\]
Name	Required	Type	Description
city	yes	string	Pickup city and destination city separately
country	yes	string	Pickup country and destination country separately
lat	no	number	Reqired for bullet type
lon	no	number	Reqired for bullet type
district	no	number	Reqired for dtistrict based sla

Available Packages: Scale Package, Enterprise Package, Marketplaces

This API endpoint allows you to access estimated delivery dates, times, and other last mile process details by utilizing the SLA configurations of your shipping partners. By providing key information such as the pickup and customer addresses, you can retrieve precise delivery and pickup date estimates. This capability enhances the accuracy of your shipping operations and proves invaluable for businesses and logistics providers aiming to streamline workflows and deliver reliable delivery timelines to their customers.

Request Parameters: |

Request Paramaters: originAddress and destinationAddress |

Check Coverage

Endpoint URL

POST https://api.tryoto.com/rest/v2/checkCoverage

Example Request Body

Here is an example of a request body:

{
  "lat": "24.28738403",
  "lon": "46.44305038",
  "city": "Riyadh"
}

Request Parameters

Name	Required	Type	Description
city	yes	string	City to check coverage
lat	yes	long	Latitude
lon	yes	long	Longitude
packageSize	no	string	`small`,`medium`,`large`,`simcard`,`iphone13`,

Available Packages : Starter Package, Scale Package, Enterprise Package, Marketplaces

This API endpoint allows you to verify whether the location provided in your request is within the coverage area defined by your OTO settings, including the coverage configurations for delivery companies and the branches.

Request Parameters: |

Available Cities

Endpoint URL

POST https://api.tryoto.com/rest/v2/availableCities

Example Request Body

Here is an example of a request body:

{
  "limit": 3
}

Request Parameters

Name	Required	Type	Description
page	no	number	Number of page, default is 1
limit	no	number	Number of cities in a single page, default is 100

Available Packages : Starter Package, Scale Package, Enterprise Package, Marketplaces

This API endpoint retrieves a list of cities available for delivery based on your coverage settings for active delivery companies you have contracts with. To obtain results, ensure that the delivery companies' coverage areas are configured by adding cities through the OTO UI.

Request Parameters: |

Available Time Slots

Endpoint URL

POST https://api.tryoto.com/rest/v2/availableTimeslots

Example Request Body

Here is an example of a request body:

{
  "serviceType": "bullet",
  "packageSize": "simCard",
  "lat": "24.00",
  "lon": "46.00"
}

Request Parameters

Name	Required	Type	Description
lat	no	string	Latitude
lon	no	string	Longitude
serviceType	yes	string	Possible values: `bullet`,`courier`
packageSize	no	string

Available Packages : Starter Package, Scale Package, Enterprise Package, Marketplaces

This API endpoint retrieves the available delivery time slots for delivery companies based on their specified working hours.

Request Parameters: |

DC List

Endpoint URL

POST https://api.tryoto.com/rest/v2/dcList

Available Packages: Starter Package, Scale Package, Enterprise Package, Marketplaces

This API endpoint provides a list of all delivery companies integrated with OTO. If you have a contract with any of these companies, you can connect your account to OTO. Use the company's unique code to configure settings through the DC Activation and DC Config API endpoints.

If a delivery company you have a contract with is not listed, please notify us to initiate the integration process.

DC Config

Endpoint URL

POST https://api.tryoto.com/rest/v2/dcConfig

Example Request Body

Here is an example of a request body:

{
  "code": "aramex"
}

Request Parameters

Name	Required	Type	Description
code	yes	string	The integration name obtained from the DC List.

Available Packages : Starter Package, Scale Package, Enterprise Package, Marketplaces

This API endpoint allows you to view the required account credentials and the template for the delivery company specified in the request, which are needed for the next step: DC activation.

Retrieve the delivery company configuration template.

Use this template to create a valid configuration object, similar to the given `exampleJson`.

This configuration object is then used to activate the delivery company with the `DC Activation` API endpoint.

Request Parameters: |

DC Activation

Endpoint URL

POST https://api.tryoto.com/rest/v2/dcActivation

Example Request Body

Here is an example of a request body:

{
  "code": "aramex",
  "deliveryOptionName": "api test aramex",
  "settings": {
    "ClientInfo": {
      "UserName": "apitest@example.com",
      "Version": "v1",
      "AccountPin": "123",
      "AccountCountryCode": "SA",
      "AccountEntity": "RUH",
      "Source": 24,
      "Password": "123abc",
      "AccountNumber": "123456"
    },
    "productType": "CDS"
  }
}

Request Parameters

Name	Required	Type	Description
code	yes	string	The integration name obtained from the `DC List.`
deliveryOptionName	yes	string	A name you assign to easily identify this configuration.
brandId	no	number	id of the brand created by `Create Brand` endpoint
settings	yes	object	A configuration object created based on the example provided by the `DC Config` endpoint.

Available Packages: Starter Package, Scale Package, Enterprise Package, Marketplaces

This API endpoint is used to perform Delivery Company (DC) activation. It enables you to activate a delivery company by providing the required configuration details.

Request Parameters: |

Note: You can activate 1 DC for the Free package and 3 DC for the Starter package and unlimited for other packages.

Get Delivery Options

Endpoint URL

GET https://api.tryoto.com/rest/v2/getDeliveryOptions

Request Parameters

Name	Required	Type	Description
city	no	string	Check coverage in the city.
orderId	no	string	Check coverage for that specific order.

Available Packages: Starter Package, Scale Package, Enterprise Package, Marketplaces

This API endpoint allows you to check coverage for your active delivery company contracts by providing either the `orderId` or the `city` details. Follow these guidelines:

Important: Do not include both `orderId` and `city` in the same request, as this will result in an error.

Ensure your request contains only one of these parameters to proceed successfully.

Request Parameters: |

Get Cities

Endpoint URL

POST https://api.tryoto.com/rest/v2/getCities

Example Request Body

Here is an example of a request body:

{
  "country": "SA",
  "perPage": 10,
  "page": 1
}

Request Parameters

Name	Required	Type	Description
country	yes	string	The country for which cities are to be retrieved.
perPage	no	integer	The number of cities to be displayed per page. Default value is 100, max value is 500.
page	no	integer	The page number for pagination.

Available Packages: All Packages

This API endpoint is used to retrieve a list of cities of a given country.

Request Parameters: |

Example Response:

``` json

{

"getCities": {

"totalCount": 1,

"perPage": 1,

"Cities": [

{

"name": "Riyadh"

}

]

}

```