Get delivery options (for Russia)

  • Return methods for each delivery option.
  • Each option contains the price, the time interval for picking up the parcel at point A, and the time interval for delivery to point B.
  • After reviewing the delivery options, you can select the best one and create an order using the selected option.
  • Delivery options are available only in Russia.

Request

POST

b2b.taxi.yandex.net/b2b/cargo/integration/v2/offers/calculate

Service URL

Headers

Name

Description

Accept-Language*

Type: string

Preferred response language. Examples: "en" — English

Example: en

Body

application/json
{
    "items": [
        {
            "size": {
                "length": 0.1,
                "width": 0.2,
                "height": 0.3
            },
            "weight": 2.105,
            "quantity": 1,
            "pickup_point": 1,
            "dropoff_point": 2
        }
    ],
    "route_points": [
        {
            "id": 1,
            "coordinates": [
                0.1,
                0.1
            ],
            "fullname": "One Central Building 5, Trade Center Second, Dubai"
        }
    ],
    "requirements": {
        "taxi_classes": [
            "cargo"
        ],
        "cargo_type": "lcv_m",
        "cargo_loaders": 1,
        "pro_courier": false,
        "cargo_options": [
            "thermobag"
        ],
        "skip_door_to_door": false,
        "due": "2020-01-01T00:00:00+00:00"
    }
}

Name

Description

route_points*

Type: RoutePointWithAddress[]

Route points. Sorted in order of visits A-B1....BN

Min items: 2

items

Type: Item[]

Item parameters

Min items: 1

requirements

Type: OfferRequirements

Delivery requirements

RoutePointWithAddress

Name

Description

coordinates

Type: number[]

Coordinates of points in the form of an array of two real numbers: longitude and latitude — exactly in that order.

Example: 0.1,0.1

Max items: 2

Min items: 2

fullname

Type: string

Full address with an indication of the city, street, and house number.
You don't need to specify the flat, the entrance number, or the floor.

Example: One Central Building 5, Trade Center Second, Dubai

id

Type: integer<int64>

Numeric point id (int64). The parameter is mandatory if there are multiple delivery points in the order

Example: 1

Item

Name

Description

quantity*

Type: integer<int64>

Number of items

Example: 1

Min value: 1

dropoff_point

Type: integer<int64>

ID of the point (int64) to deliver the item to.
It can be any number. Must match the route_points[].id value of the destination point.
The parameter is mandatory if there are multiple delivery points in the order.

Example: 2

pickup_point

Type: integer<int64>

ID of the point (int64) to pick up the item from.
It can be any number. Must match the route_points[].id value of the dispatch point.
The parameter is mandatory if there are multiple delivery points in the order.

Example: 1

size

Type: CargoItemSizes

Unit dimensions in meters. The actual values should be added to the fields.

If the dimensions aren't added, the order is placed, taking into account
the maximum dimensions allowed for the selected rate.

If the actual characteristics of the unit exceed the allowed dimensions,
the courier has the right to refuse to fulfill the order on site.
In this case, the minimum fee will be withheld.

Courier: up to 0.80 m × 0.50 m × 0.50 м
Express: up to 1.00 m × 0.60 m × 0.50 m
Cargo:

  • Small body: up to 1.70 m × 0.96 m × 0.90 m
  • Medium body: up to 2.60 m × 1.30 m × 1.50 m
  • Large body: up to 3.80 m × 1.80 m × 1.80 m

weight

Type: number

Item weight in kilograms.
Example: 2.105

Example: 2.105

OfferRequirements

Delivery requirements

Name

Description

cargo_loaders

Type: integer<int64>

Number of loaders for the cargo rate.
Possible values: 0, 1, 2.

For an exact list of possible values for a particular geo point,
use the method for obtaining rates tariffs

Example: 1

cargo_options

Type: string[]

List of additional rate options.

Possible separate options:

  • auto_courier (a courier with a vehicle only)
  • thermobag (a courier with a thermobag)

Example of a list of options: ["auto_courier"].

For an exact list of possible values for a particular geo point,
use the method for obtaining rates tariffs

Example: thermobag

cargo_type

Type: CargoType

Body type (size) for the cargo rate.
Possible values:
- van ("Small body")
- lcv_m ("Medium body")
- lcv_l ("Large body").

For an exact list of possible values for a particular geo point,
use the method for obtaining rates tariffs

Example: lcv_m

Enum: van, lcv_m, lcv_l, lcv_xl

due

Type: string<date-time>

Estimated time of arrival of the courier (you can postpone the estimated time of delivery by 30-60 minutes from the current ) — default value.

Example: 2020-01-01T00:00:00+00:00

pro_courier

Type: boolean

Enable the "Pro" option for "Express" and "Courier" rates.
In this case, we will look only for experienced couriers.

skip_door_to_door

Type: boolean

Disable door-to-door delivery (disable the "Door-to-door" option).

Possible values:

  • true (the courier will deliver the order only at the entrance outside)
  • false (the courier will deliver the order at the door)

taxi_classes

Type: string[]

Delivery vehicle class.
Possible values: courier, express, cargo.

For an exact list of possible values for a particular geo point,
use the method for obtaining rates tariffs

Delivery vehicle class.
Possible values: courier, express, cargo.

For an exact list of possible values for a particular geo point,
use the method for obtaining rates tariffs

Example: cargo

Min items: 1

CargoItemSizes

Unit dimensions in meters. The actual values should be added to the fields.

If the dimensions aren't added, the order is placed, taking into account
the maximum dimensions allowed for the selected rate.

If the actual characteristics of the unit exceed the allowed dimensions,
the courier has the right to refuse to fulfill the order on site.
In this case, the minimum fee will be withheld.

Courier: up to 0.80 m × 0.50 m × 0.50 м
Express: up to 1.00 m × 0.60 m × 0.50 m
Cargo:

  • Small body: up to 1.70 m × 0.96 m × 0.90 m
  • Medium body: up to 2.60 m × 1.30 m × 1.50 m
  • Large body: up to 3.80 m × 1.80 m × 1.80 m

Name

Description

height*

Type: number

Height in meters

Example: 0.3

length*

Type: number

Length in meters

Example: 0.1

width*

Type: number

Width in meters

Example: 0.2

CargoType

Body type (size) for the cargo rate.
Possible values:
- van ("Small body")
- lcv_m ("Medium body")
- lcv_l ("Large body").

For an exact list of possible values for a particular geo point,
use the method for obtaining rates tariffs

Type

Description

CargoType

Example: lcv_m

Enum: van, lcv_m, lcv_l, lcv_xl

Responses

200 OK

OK

Body

application/json
{
    "offers": [
        {
            "price": {
                "total_price": "673.0",
                "total_price_with_vat": "807.6",
                "base_price": "611.8",
                "surge_ratio": 1.1,
                "currency": "AED"
            },
            "taxi_class": "express",
            "pickup_interval": {
                "from": "2023-07-17T08:02:26.607358+00:00",
                "to": "2023-07-17T08:42:26.607358+00:00"
            },
            "delivery_interval": {
                "from": "2023-07-17T08:02:26.607358+00:00",
                "to": "2023-07-17T09:15:43.607358+00:00"
            },
            "description": "express_30min_longer",
            "payload": "5e2TPP5f7Yqyv19yRZ+QVas4JK+lhwa17ncxA3VCGI8hvnFS+CIySbmfHQlR6vhC2S4XsW+M7TbEV0EQl1/1Z0PO3QQX8KbGb6rtKay",
            "offer_ttl": "2020-01-02T00:00:00+00:00"
        }
    ]
}

Name

Description

offers*

Type: CalculatedOffer[]

An array of delivery offers
Delivery options

CalculatedOffer

Delivery options

Name

Description

delivery_interval*

Type: DeliveryTimeInterval

Delivery time interval (for point B)

payload*

Type: string

payload of the delivery offer. To order delivery using the selected offer, pass the payload in the method claims/create.

Example: 5e2TPP5f7Yqyv19yRZ+QVas4JK+lhwa17ncxA3VCGI8hvnFS+CIySbmfHQlR6vhC2S4XsW+M7TbEV0EQl1/1Z0PO3QQX8KbGb6rtKay

pickup_interval*

Type: PickupTimeInterval

Pick-up time interval (for point A)

price*

Type: CalculatedOfferPrice

Delivery cost

taxi_class*

Type: string

Rate

Example: express

description

Type: string

Delivery option description. Example: express_30min_longer (Express with a 30-minute delay)

Example: express_30min_longer

offer_ttl

Type: string<date-time>

Time until which the offer can be used to create a claim. If
a claim is created after that moment, its
status will change to 'estimating_failed'

Example: 2020-01-02T00:00:00+00:00

DeliveryTimeInterval

Delivery time interval (for point B)

Name

Description

from*

Type: string<date-time>

Interval start (UTC)

Example: 2023-07-17T08:02:26.607358+00:00

to*

Type: string<date-time>

Interval end (date and time)

Example: 2023-07-17T09:15:43.607358+00:00

PickupTimeInterval

Pick-up time interval (for point A)

Name

Description

from*

Type: string<date-time>

Interval start (UTC)

Example: 2023-07-17T08:02:26.607358+00:00

to*

Type: string<date-time>

Interval end (date and time)

Example: 2023-07-17T08:42:26.607358+00:00

CalculatedOfferPrice

Delivery cost

Name

Description

currency*

Type: string

Three-digit code of the payment currency

Example: AED

Min length: 3

Max length: 3

surge_ratio*

Type: number

Order cost growth factor (depending on the system load)

Example: 1.1

total_price*

Type: string

Price including order cost growth factor (without VAT)

Example: 673.0

Pattern: ^-?[0-9]{1,14}(\.[0-9]{0,4})?$

total_price_with_vat*

Type: string

Price including order cost growth factor (including VAT)

Example: 807.6

Pattern: ^-?[0-9]{1,14}(\.[0-9]{0,4})?$

base_price

Type: string

Базовая цена доставки

Example: 611.8

Pattern: ^-?[0-9]{1,14}(\.[0-9]{0,4})?$

400 Bad Request

Invalid request

Body

application/json
{
    "code": "bad_request",
    "message": "bad request"
}

Name

Description

code*

Type: string

Error code

Example: bad_request

Enum: bad_request, address_not_found, validation_error

message*

Type: string

Error description

Example: bad request

409 Conflict

Couldn't calculate offers

Body

application/json
{
    "code": "estimating.requirement_unavailable",
    "message": "requirement unavailable"
}

Name

Description

code*

Type: string

Error code

Example: estimating.requirement_unavailable

Enum: errors.suitable_offer_not_found, estimating.cargocorp_payment_failure, estimating.limited_by_claims_creation_overflow, estimating.no_pickup_point, estimating.payment_method_cant_order, estimating.permitted_tariffs_not_enough, estimating.requirement_unavailable, estimating.route_too_long, estimating.tariff.no_categories_in_zone, estimating.tariff.no_sdd_tariff, estimating.too_large_linear_size, estimating.too_many_loaders, estimating.warning.too_heavy_item, estimating.warning.too_large_item, estimating.zone_unavailable, estimating.payment_method_zone_unavailable

message*

Type: string

Error description

Example: requirement unavailable

429 Too Many Requests

Too many requests

Body

application/json
{
    "code": "too_many_requests",
    "message": "Too many requests"
}

Name

Description

code*

Type: string

Error code

Example: too_many_requests

Enum: too_many_requests

message*

Type: string

Error description

Example: Too many requests