Sets route nodes and their sequence in the route

Method sets a sequence of route nodes for the route.

  • Orders, depots and garages presented in the request body are created if they are not in the route yet. In this case fields number, address, lat, lon are required for orders and garages. Additionally field time_interval is required for orders.
  • Orders, depots and garages already existing in the route are deleted if they are not presented in the request body. Deletion of visited nodes is forbidden.
  • Orders and garages presented both in the route and in the request body are updated if they have additional fields, except for number. Garages are only allowed to appear at the beginning and at the end of the route. There can be at most one garage at the beginning of the route. If both depot and garage are present at the beginning of the route, then the garage must be before the first depot. There can be at most one garage at the end of the route. If both depot and garage are present at the end of the route, then the garage must be after the last depot.

Request

POST

https://courier.yandex.ru/api/v1/companies/{company_id}/routes/{route_id}/nodes

Path parameters

Name

Description

company_id*

Type: integer<int64>

Company ID used in requests to the Track & Trace API.

route_id*

Type: integer<int64>

Route ID used in requests to the Track & Trace API.

Query parameters

Name

Description

mode

Type: string

Defines mode of handling nodes import. Valid values are: - default — default behavior presented in description. - using_ids — you can provide ids for orders: - if only number is provided, the system creates new order; - if id is provided, the system patches existing order; - this mode supports not unique drop-off order numbers. Any other POST/PATCH methods support only unique order numbers, so they return unprocessible entity error (code 422) if there are any duplicated numbers in the request or in the system (presented in request).

Default: default

Enum: default, using_ids

Body

application/json
[
    {
        "type": "string",
        "value": {
            "id": "string",
            "type": "pickup",
            "address": "string",
            "amount": 0,
            "comments": "string",
            "customer_name": "string",
            "customer_number": "string",
            "description": "string",
            "lat": 0,
            "lon": 0,
            "number": "string",
            "payment_type": "cash",
            "phone": "string",
            "route_id": 0,
            "service_duration_s": 0,
            "shared_service_duration_s": 0,
            "status": "string",
            "volume": 0,
            "weight": 0,
            "shared_with_company_ids": [
                0
            ],
            "mark_delivered_radius": null,
            "eta_type": null,
            "time_interval": "string",
            "notifications": [
                {
                    "type": "before_arrival"
                }
            ],
            "related_orders": [
                {
                    "number": "string",
                    "action": "pickup"
                }
            ]
        }
    }
]

(RouteNodeOrder or RouteNodeDepot or RouteNodeGarage)[]

RouteNodeOrder

Route node with type order.

Name

Description

type*

Type: string

Pattern: ^order$

value*

Type: RouteNodeOrder_value

RouteNodeDepot

Route node with type "depot".

Name

Description

type*

Type: string

Pattern: ^depot$

value*

Type: RouteNodeDepot_value

RouteNodeGarage

Route node with type "garage".

Name

Description

type*

Type: string

Pattern: ^garage$

value*

Type: RouteNodeGarage_value

RouteNodeOrder_value

Name

Description

address

Type: string

Delivery address in text format.

amount

Type: number<float>

Order price in rubles.

Min value: 0

comments

Type: string

Order comments.

customer_name

Type: string

Recipient's name.

Max length: 1023

customer_number

Type: string

Customer's number in the delivery company database.

Max length: 128

description

Type: string

Order description.

Max length: 1023

eta_type

Type: string

ETA type. Affects the time of notification and automatic delivery detection. arrival_time — Countdown starts from the moment the courier arrives at the point; delivery_time — Countdown does not start until the start of the delivery window.

Default: null

id

Type: string

The ID of the order that is used in requests to the Track & Trace API.

Pattern: ^[0-9]+$

lat

Type: number<float>

Latitude of the delivery point.

lon

Type: number<float>

Longitude of the delivery point.

mark_delivered_radius

Type: number<float>

Radius in meters. If null, depot.mark_delivered_radius or company.mark_delivered_radius is used instead. Order is marked as delivered automatically if mark_delivered_enabled is true and courier spent at least mark_delivered_service_time_coefficient * (order.service_duration_s + order.shared_service_duration_s) seconds within mark_delivered_radius meters from the order's location.

Default: null

Min value: 0

Max value: 10000

notifications

Type: OrderNotification[]

List of push notification settings.

number

Type: string

Order number. Used for syncing with the delivery company's system.

Max length: 80

payment_type

Type: string

Payment method. Possible values:

  • cash — Payment to the courier in cash.
  • card — Payment to the courier by bank card.
  • prepaid — Prepayment (paid in advance).
  • yandex_pay — Payment via Yandex Pay. Can only be set internally.

Enum: cash, card, prepaid, yandex_pay, null

phone

Type: string

The recipient's phone number.

related_orders

Type: RelatedOrdersByNumber[]

An object that stores information about the order associated with the point and the action with these orders.

route_id

Type: integer<int64>

Route ID used in requests to the Track & Trace API.

service_duration_s

Type: integer

Expected time the courier will need to pass the order to the recipient, including going up to the floor and receiving payment. Default value: 600 seconds.

shared_service_duration_s

Type: integer

Service duration at the location, which can be shared with other orders at the same location. Shared service duration can include operations as parking a car, delivering documents, etc. Default value: 0 seconds.

shared_with_company_ids

Type: number[]

IDs of the companies that can access the order information. The following information is provided:

  • Full information about the order.
  • General description of the route this order is a part of.
  • General description of the depot used in this order.
  • General information about the delivery company (name and logo). If both shared_with_company_numbers and shared_with_company_ids are specified shared_with_company_numbers is used.

status

Type: string

The current order status. Possible values:

  • new — The order was created.
  • confirmed — The order delivery time was set (confirmed with recipient).
  • finished — The order was delivered.
  • partially_finished — The order was delivered only partially. Order status can be set to partially_finished only for companies with company.partially_finished_status_enabled flag equals true.
  • cancelled — The order was canceled.
  • postponed — The order is postponed or the courier couldn't contact the customer.

time_interval

Type: string

Desired delivery time interval. The following formats are supported:

  • "T - T" or "T-T", where T is the time in HH, HH:MM, or HH:MM:SS format.
  • ISO 8601, for example, 2018-09-06T10:15:00+03:00/2018-09-06T12:45:00+03:00.

type

Type: string

Type of order service.

Enum: pickup, drop_off, delivery

volume

Type: number<float>

Order volume.

weight

Type: number<float>

Order weight.

RouteNodeDepot_value

Name

Description

number*

Type: string

Depot number.

related_orders

Type: RelatedOrdersByNumber[]

An object that stores information about the order associated with the point and the action with these orders.

status

Type: string

The current depot visit status. Possible values:

  • unvisited
  • visited

RouteNodeGarage_value

Name

Description

number*

Type: string

Garage number.

address

Type: string

Garage address in text format.

lat

Type: number<float>

Latitude of garage location.

lon

Type: number<float>

Longitude of garage location.

OrderNotification

Name

Description

type

Type: string

Notification type.

Enum: before_arrival

RelatedOrdersByNumber

An object that stores information about the order associated with the point and the action with these orders.

Name

Description

action

Type: RelatedOrderAction

The action performed on the order: * pickup — load for delivery to another destination (it can be loaded from the depot, garage and pickup order);

  • delivery — deliver to this destination (can be a depot, garage and drop-off order).

Enum: pickup, delivery

number

Type: string

Order number.

RelatedOrderAction

The action performed on the order: * pickup — load for delivery to another destination (it can be loaded from the depot, garage and pickup order);

  • delivery — deliver to this destination (can be a depot, garage and drop-off order).

Type

Description

RelatedOrderAction

Enum: pickup, delivery

Responses

200 OK

Operation succeeded.

400 Bad Request

Invalid JSON in the post body.

404 Not Found

Route not found.

422 Unprocessable Entity

Incorrect input.

Previous
Edits route
Next
Gets order sequence