Задает узлы маршрута и их последовательность

Метод устанавливает последовательность узлов заданного маршрута.

  • Заказы, склады и гаражи, которых нет в маршруте, но есть в запросе, создаются и добавляются в маршрут. При этом для гаражей и заказов обязательными полями являются number, address, lat, lon. Для заказов дополнительно необходимо указывать поле time_interval.
  • Заказы, склады и гаражи, которые есть в маршруте, но отсутствуют в запросе, удаляются. Удаление уже посещённых узлов маршрута запрещено.
  • Заказы и гаражи, которые имеются и в маршруте, и в запросе, при наличии дополнительных полей, кроме number, обновляются в соответствии с полученными значениями. Гаражи могут находиться только в начале и конце маршрута. В начале маршрута может быть не больше одного гаража. Если в начале маршрута присутствуют и склад, и гараж, то гараж может быть только перед первым складом. В конце маршрута может быть не больше одного гаража. Если в конце маршрута присутствуют и склад, и гараж, то гараж может быть только после последнего склада.

Request

POST

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

Path parameters

Name

Description

company_id*

Type: integer

ID компании, используемый в запросах к API Мониторинга.

route_id*

Type: integer

ID маршрута, используемый в запросах к API Мониторинга.

Query parameters

Name

Description

mode

Type: string

Определяет режим импорта узлов. Возможные значения: - default — стандартная функциональность, представенная в описании - using_ids — позволяет использовать id для заказов: - если предоставлен только номер, тогда создается новый заказ; - если предоставлен id, то этот заказ изменяется; - этот режим поддерживает неуникальные номера для заказов типа drop-off. Любые другие POST/PATCH методы поддерживают только уникальность номеров, так что они возвращают ошибку unprocessible entity (код 422), если присутствуют повторяющиеся номера в запросе или в системе (которые также присутствуют в запросе).

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",
            "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

Узел маршрута с типом order.

Name

Description

type*

Type: string

Pattern: ^order$

value*

Type: RouteNodeOrder_value

RouteNodeDepot

Узел маршрута с типом "depot".

Name

Description

type*

Type: string

Pattern: ^depot$

value*

Type: RouteNodeDepot_value

RouteNodeGarage

Узел маршрута с типом "garage".

Name

Description

type*

Type: string

Pattern: ^garage$

value*

Type: RouteNodeGarage_value

RouteNodeOrder_value

Name

Description

address

Type: string

Адрес доставки в текстовом формате.

amount

Type: number<float>

Стоимость заказа в рублях.

comments

Type: string

Комментарии к заказу.

customer_name

Type: string

Имя заказчика.

Max length: 1023

description

Type: string

Описание заказа.

Max length: 1023

eta_type

Type: string

Тип ETA. Влияет на время оповещения и автоматического определения доставки. arrival_time — отсчёт ведётся от момента прибытия курьера на точку; delivery_time — отсчёт начинается не раньше начала окна доставки.

id

Type: string

ID заказа, используемый в запросах к API Мониторинга.

Pattern: ^[0-9]+$

lat

Type: number<float>

Широта точки доставки.

lon

Type: number<float>

Долгота точки доставки.

mark_delivered_radius

Type: number<float>

Радиус в метрах. Если null, используется depot.mark_delivered_radius или company.mark_delivered_radius. Заказ помечается как доставленный автоматически, если значение mark_delivered_enabled равно true, а курьер провел не менее mark_delivered_service_time_coefficient * (order.service_duration_s + order.shared_service_duration_s) секунд в пределах mark_delivered_radius метров от местоположения заказа.

Max value: 10000

notifications

Type: OrderNotification[]

Список настроек push-уведомлений.

number

Type: string

Номер заказа. Используется для синхронизации с учетной системой компании, выполняющей доставку.

Max length: 80

payment_type

Type: string

Способ оплаты. Возможные значения:

  • cash — оплата наличными курьеру.
  • card — оплата банковской картой курьеру.
  • prepaid — предоплата (заказ был оплачен ранее).
  • yandex_pay — оплата заказа через Яндекс Пэй. Снаружи этот способ оплаты задать нельзя.

Enum: cash, card, prepaid, yandex_pay, null

phone

Type: string

Телефон получателя.

related_orders

Type: RelatedOrdersByNumber[]

Объект, хранящий информацию о заказе, связаном с точкой, и действии с этими заказом.

route_id

Type: integer

ID маршрута, используемый в запросах к API Мониторинга.

service_duration_s

Type: integer

Ожидаемое время, потраченное курьером на отгрузку товара получателю, в том числе чтобы подняться на этаж и получить оплату. Значение по умолчанию: 600 секунд.

shared_service_duration_s

Type: integer

Продолжительность обслуживания в точке доставки, которая может быть разделена с другими заказами в том же месте. Общая продолжительность обслуживания может включать такие операции, как парковка, доставка документов и другие. Значение по умолчанию: 0 секунд.

shared_with_company_ids

Type: number[]

ID компаний, которые могут получить доступ к информации о заказе. Предоставляется следующая информация:

  • Полная информация о заказе.
  • Общее описание маршрута, частью которого является заказ.
  • Общее описание склада, используемого в заказе.
  • Общая информация о компании, выполняющей доставку (название и логотип). Если определены оба поля shared_with_company_numbers и shared_with_company_ids, используется shared_with_company_numbers.

status

Type: string

Текущий статус заказа. Возможные значения:

  • new - заказ был создан.
  • confirmed - установлен срок доставки заказа (подтверждено получателем).
  • finished - заказ доставлен.
  • partially_finished - заказ был доставлен только частично. Для установки статуса заказа в partially_finished флаг company.partially_finished_status_enabled должен иметь значение true.
  • cancelled - заказ был отменен.
  • postponed - заказ отложен или курьер не смог связаться с клиентом.

time_interval

Type: string

Желаемое окно доставки заказа. Поддерживаются следующие форматы:

  • "T - T" или "T-T", где T - это время в формате ЧЧ, ЧЧ:ММ, или ЧЧ:ММ:СС.
  • ISO 8601, например, 2018-09-06T10:15:00+03:00/2018-09-06T12:45:00+03:00.

type

Type: string

Тип обслуживания заказа.

Enum: pickup, drop_off, delivery

volume

Type: number<float>

Объем заказа.

weight

Type: number<float>

Вес заказа.

RouteNodeDepot_value

Name

Description

number*

Type: string

Номер склада.

related_orders

Type: RelatedOrdersByNumber[]

Объект, хранящий информацию о заказе, связаном с точкой, и действии с этими заказом.

status

Type: string

Текущий статус посещения склада. Возможные значения:

  • unvisited - непосещенный.
  • visited - посещенный.

RouteNodeGarage_value

Name

Description

number*

Type: string

Номер гаража.

address

Type: string

Адрес гаража в текстовом формате.

lat

Type: number<float>

Широта точки расположения гаража.

lon

Type: number<float>

Долгота точки расположения гаража.

OrderNotification

Name

Description

type

Type: string

Тип уведомления.

Enum: before_arrival

RelatedOrdersByNumber

Объект, хранящий информацию о заказе, связаном с точкой, и действии с этими заказом.

Name

Description

action

Type: RelatedOrderAction

Действие, выполняемое над заказом: * pickup — погрузить для доставки в другой пункт назначения (можно погрузить со склада, гаража и pickup-заказа);

  • delivery — доставить в этот пункт назначения (может быть складом, гаражом и drop-off заказом).

Enum: pickup, delivery

number

Type: string

Номер заказа.

RelatedOrderAction

Действие, выполняемое над заказом: * pickup — погрузить для доставки в другой пункт назначения (можно погрузить со склада, гаража и pickup-заказа);

  • delivery — доставить в этот пункт назначения (может быть складом, гаражом и drop-off заказом).

Type

Description

RelatedOrderAction

Enum: pickup, delivery

Responses

200 OK

Операция успешно завершена.

400 Bad Request

Недопустимый JSON в теле сообщения.

404 Not Found

Маршрут не найден.

422 Unprocessable Entity

Неверный ввод.

Предыдущая
Редактирует маршрут
Следующая
Возвращает последовательность заказов