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": "Saint Petersburg, Bol'shaya Monetnaya Street, 1f1A"
    },
    {
      "id": 1,
      "coordinates": [
        0.1,
        0.1
      ],
      "fullname": "Saint Petersburg, Bol'shaya Monetnaya Street, 1f1A"
    }
  ],
  "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

Example
[
  {
    "id": 1,
    "coordinates": [
      0.1,
      0.1
    ],
    "fullname": "Saint Petersburg, Bol'shaya Monetnaya Street, 1f1A"
  },
  {
    "id": 1,
    "coordinates": [
      0.1,
      0.1
    ],
    "fullname": "Saint Petersburg, Bol'shaya Monetnaya Street, 1f1A"
  }
]

items

Type: Item[]

Item parameters

Min items: 1

Example
[
  {
    "size": {
      "length": 0.1,
      "width": 0.2,
      "height": 0.3
    },
    "weight": 2.105,
    "quantity": 1,
    "pickup_point": 1,
    "dropoff_point": 2
  }
]

requirements

Type: OfferRequirements

Delivery requirements

Example
{
  "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"
}

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

length

Type: number

Length in meters

width

Type: number

Width in meters

Example
{
  "length": 0.1,
  "width": 0.2,
  "height": 0.3
}

Item

Name

Description

quantity

Type: integer

Number of items

Min value: 1

dropoff_point

Type: integer

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.

pickup_point

Type: integer

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.

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
Example
{
  "length": 0.1,
  "width": 0.2,
  "height": 0.3
}

weight

Type: number

Item weight in kilograms.
Example: 2.105

Example
{
  "size": {
    "length": 0.1,
    "width": 0.2,
    "height": 0.3
  },
  "weight": 2.105,
  "quantity": 1,
  "pickup_point": 1,
  "dropoff_point": 2
}

Point

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

Type: number[]

Min items: 2

Max items: 2

Example
[
  0.1,
  0.1
]

AddressFullname

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.

Type: string

Example: Saint Petersburg, Bol'shaya Monetnaya Street, 1f1A

RoutePointWithAddress

Name

Description

coordinates

Type: Point

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

Min items: 2

Max items: 2

Example
[
  0.1,
  0.1
]

fullname

Type: AddressFullname

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: Saint Petersburg, Bol'shaya Monetnaya Street, 1f1A

id

Type: integer

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

Example
{
  "id": 1,
  "coordinates": [
    0.1,
    0.1
  ],
  "fullname": "Saint Petersburg, Bol'shaya Monetnaya Street, 1f1A"
}

CargoType

Body type (size) for the cargo rate.\nPossible values:

  • van ("Small body")
  • lcv_m ("Medium body")
  • lcv_l ("Large body")
  • lcv_xl ("XL body")
    For an exact list of possible values for a particular geo point,\nuse the method for obtaining rates tariffs

Type: string

Enum: van, lcv_m, lcv_l, lcv_xl

CargoOptions

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

Type: string[]

Example
[
  "thermobag"
]

OfferRequirements

Delivery requirements

Name

Description

cargo_loaders

Type: integer

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

cargo_options

Type: CargoOptions

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.\nPossible values:

  • van ("Small body")
  • lcv_m ("Medium body")
  • lcv_l ("Large body")
  • lcv_xl ("XL body")
    For an exact list of possible values for a particular geo point,\nuse the method for obtaining rates tariffs

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)

Default: false

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

Min items: 1

Example
[
  "cargo"
]
Example
{
  "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"
}

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": "RUB"
      },
      "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

Example
[
  {
    "price": {
      "total_price": "673.0",
      "total_price_with_vat": "807.6",
      "base_price": "611.8",
      "surge_ratio": 1.1,
      "currency": "RUB"
    },
    "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"
  }
]

Currency

Three-digit code of the payment currency

Type: string

Min length: 3

Max length: 3

Example: RUB

CalculatedOfferPrice

Delivery cost

Name

Description

currency

Type: Currency

Three-digit code of the payment currency

Min length: 3

Max length: 3

Example: RUB

surge_ratio

Type: number

Order cost growth factor (depending on the system load)

total_price

Type: string

Price including order cost growth factor (without VAT)

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

Example: 673.0

total_price_with_vat

Type: string

Price including order cost growth factor (including VAT)

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

Example: 807.6

base_price

Type: string

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

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

Example: 611.8

Example
{
  "total_price": "673.0",
  "total_price_with_vat": "807.6",
  "base_price": "611.8",
  "surge_ratio": 1.1,
  "currency": "RUB"
}

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

Example
{
  "from": "2023-07-17T08:02:26.607358+00:00",
  "to": "2023-07-17T08:42:26.607358+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

Example
{
  "from": "2023-07-17T08:02:26.607358+00:00",
  "to": "2023-07-17T09:15:43.607358+00:00"
}

CalculatedOffer

Delivery options

Name

Description

delivery_interval

Type: DeliveryTimeInterval

Delivery time interval (for point B)

Example
{
  "from": "2023-07-17T08:02:26.607358+00:00",
  "to": "2023-07-17T09:15:43.607358+00:00"
}

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)

Example
{
  "from": "2023-07-17T08:02:26.607358+00:00",
  "to": "2023-07-17T08:42:26.607358+00:00"
}

price

Type: CalculatedOfferPrice

Delivery cost

Example
{
  "total_price": "673.0",
  "total_price_with_vat": "807.6",
  "base_price": "611.8",
  "surge_ratio": 1.1,
  "currency": "RUB"
}

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

Example
{
  "price": {
    "total_price": "673.0",
    "total_price_with_vat": "807.6",
    "base_price": "611.8",
    "surge_ratio": 1.1,
    "currency": "RUB"
  },
  "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"
}

400 Bad Request

Invalid request

Body

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

Name

Description

code

Type: string

Error code

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

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

Const: too_many_requests

Example: too_many_requests

message

Type: string

Error description

Example: Too many requests

No longer supported, please use an alternative and newer version.