Экспресс-доставка

Экспресс-доставка или доставка по запросу (On Demand) — это доставка заказа в день оформления. Как правило, это доставка готовой еды и продуктов или оказание срочных услуг, таких как тех. поддержка, ремонт или клининг.

Особенность экспресс-доставки в том, что новые заказы поступают непрерывно, и их нужно оперативно обрабатывать и распределять между курьерами. Для этого используется допланирование — добавление заказов в спланированный ранее маршрут и оптимизация (пересчет) оставшейся части маршрута. Подробнее о допланировании можно прочитать в разделе Периодическое допланирование маршрута.

Сценарий экспресс-доставки (периодического допланирования) можно реализовать только через API. Порядок работы описан в разделе Допланирование в пути. Спланированные решения логисты могут смотреть на карте.

Рассмотрим возможности сервиса Маршрутизации, порядок внедрения и работы по сценарию экспресс-доставки.

Возможности Яндекс Маршрутизации

Яндекс Маршрутизация состоит из двух независимых сервисов:

  • Планирование — это «калькулятор», он распределяет заказы между курьерами и строит оптимальные маршруты. Маршрут содержит последовательность выполнения заказов, для каждого заказа рассчитывается время прибытия курьера. Планировать маршруты можно либо через веб-интерфейс (данные вносятся в шаблон Excel), либо через API (данные передаются в формате JSON).

  • Мониторинг — контролирует выполнение маршрутов и заказов. Статусы заказов и местоположение курьеров можно отслеживать в реальном времени, для этого курьеры устанавливают бесплатное мобильное приложение Яндекс Курьер. Клиентам можно отправлять сообщения об ожидаемом времени прибытия курьера.

Сервис Планирования заменить нельзя. Вы можете отправлять запросы к API Планирования из вашей системы.

Вместо сервиса Мониторинга и приложения Яндекс Курьер вы можете использовать собственные разработки или сторонние системы. Вы можете совсем отказаться от мониторинга данных о фактическом местоположении курьеров, но это ухудшит качество планирования.

Алгоритм работы

  1. В начале рабочего дня вы планируете первый маршрут с поступившими к этому моменту заказами.
  2. В течение рабочего дня вы отправляете запросы на допланирование маршрутов с учетом новых заказов и текущих данных от курьеров.

Что делает Яндекс Маршрутизация:

  • Сервис Планирования планирует оптимальные маршруты на основе переданных данных.
  • Сервис Мониторинга отображает построенные маршруты и статусы заказов, подсвечивает возможные опоздания, собирает статистику и формирует отчеты. При использовании мобильного приложения Яндекс Курьер данные о статусах заказов и местоположении курьеров обновляются автоматически.

На текущий момент сервис Маршрутизации не умеет принимать заказы от клиентов, аккумулировать их и распределять на курьеров в фоновом режиме. Эту логику вам придется реализовать самостоятельно.

Что делает ваша компания:

  1. Регистрирует заказы.
  2. Управляет списком доступных курьеров.
  3. Отправляет запросы на планирование маршрутов через API.
  4. Получает результаты планирования через API.
  5. Обрабатывает результаты расчетов, хранит нужные данные.
  6. Создает, добавляет и редактирует маршруты и заказы в Мониторинге через API.
  7. Получает и обрабатывает нужные данные из Мониторинга через API.

Схема ↗️

Какие данные хранит Яндекс Маршрутизация

В сервисе Планирования каждый запрос на составление маршрутов выполняется независимо и ни на что не влияет, пока вы не начнете использовать его результаты. Информация по запросам (исходные данные и полученный результат) хранится 1 год. Если вы запомните уникальный идентификатор запроса task_id, вы сможете обратиться к нему позднее. В интерфейсе логиста этот раздел называется История планирований.

После того как запрос на планирование маршрута отправлен, удалить или отредактировать запрос или остановить его выполнение невозможно.

Данные хранятся на серверах Яндекса ограниченное время:

  • Треки движения курьеров: 1 месяц от даты маршрута.
  • Фотографии, присланные курьерами для подтверждения доставки: 3 месяца от даты добавления фотографии.
  • Данные мониторинга (заказы, маршруты): 1 год после окончания оплачиваемого периода или периода тестирования.
  • Данные для построения отчетов План / Факт: 18 месяцев.
  • Ссылка на отслеживание заказа в клиентском виджете: 1 неделя.
  • Трек движения курьера в клиентском виджете: 1 сутки.

Обратиться к ним можно либо через API, либо через Рабочее Место Логиста (сокращенно — РМЛ).

Каждый загружаемый объект в Мониторинге имеет поля:

  • id — уникальный идентификатор, который автоматически присваивается сервисом и используется в запросах к API Мониторинга;
  • number — в этом поле вы можете передать идентификатор объекта в вашей базе данных, для интеграции между вашей системой и сервисом Мониторинга.

В отличие от Планирования, данные в Мониторинге динамичные — их можно редактировать и удалять.

Управление курьерами

Все курьеры, переданные в запросе на планирование маршрута, считаются доступными для выполнения заказов. Если курьер прекратил работу или новый курьер готов приступить к выполнению заказов, нужно актуализировать список курьеров с помощью запроса API. Другого способа указать, что курьер вышел на линию или ушел с линии, нет.

Примечание

Управлять списком курьеров нужно в той системе, из которой отправляются запросы в сервис Планирования.

Текущие координаты курьера могут передаваться в Маршрутизацию с помощью приложения Яндекс Курьер, GPS-трекера или стороннего курьерского приложения.

Обычно при допланировании не нужно знать текущий статус курьера — свободен или на маршруте. Достаточно знать статус заказов в маршруте, а для более точного планирования — текущие координаты курьера. Используя эту информацию, сервис Планирования сам определит тех курьеров, которые успевают выполнить новые заказы.

Логика распределения заказов

Логикой распределения заказов управляете вы, используя параметры алгоритма маршрутизации, которые вы передаете в запросе на планирование. Например, вы можете планировать маршруты так, чтобы заказы равномерно распределялись между всеми курьерами. Можете минимизировать пробег автомобилей или скорость доставки заказов. Можете распределить курьеров по географическим зонам (например, районам города).

Логика распределения заказов может меняться от запроса к запросу, достаточно передать новые параметры вместе с исходными данными.

О том, как работает алгоритм Планирования, вы можете прочитать в разделе Алгоритм маршрутизации.

В документации можно изучить параметры планирования и значения по умолчанию, а также комбинации параметров, которые используются в типовых сценариях планирования.

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

Частота отправки запросов API на допланирование маршрутов зависит от особенностей вашего бизнеса:

  • расстояний между заказами;
  • частоты поступления новых заказов;
  • срочности заказов.

Используйте параметры заказов для указания временных окон доставки, времени готовности заказа на складе (или в ресторане, если это еда), максимально допустимого времени нахождения заказа у курьера.

В общем случае чем больше заказов в запросе на планирование, тем выше оптимизация маршрутов. Методом тестирования определите максимально возможное время накопления заказов, при котором система позволит спланировать все заказы без опозданий — это и будет оптимальный интервал планирований для вас.

Не стоит распределять заказы вручную без необходимости, это сделает маршруты менее оптимальными.

Примечание

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

Авторизация

Для работы по API с сервисами Планирования и Мониторинга необходим OAuth-токен. Сгенерировать его можно по инструкции.

Для работы с сервисом Мониторинга необходимо зарегистрировать вашу компанию и получить ее уникальный номер company_id. Для регистрации компании обратитесь к вашему менеджеру.

Состав и формат данных

Как правило, для сценария экспресс-доставки достаточно использовать небольшое количество параметров планирования.

При подготовке данных для планирования:

  • Подготовьте точные координаты заказов. Если на текущий момент у вас есть только адреса, предварительно используйте API геокодера, доступ к нему можно получить через менеджера. Изучите советы по геокодированию.

  • Обеспечивайте уникальность идентификаторов заказов. Так как заказы хранятся в Мониторинге длительное время, они должны быть уникальны не только в рамках одного дня, но и в рамках всего периода. Например, к идентификатору заказа можно добавлять дату: Order1 2024-01-01. Идентификаторы курьеров и складов наоборот не должны меняться.

  • Учитывайте особенности формата JSON.

Структура тела запроса в API Планирования:

{
    "depots": [
        // Описывает склады
    ],
    "locations": [
        // Описывает заказы
    ],
    "vehicles": [
        // Описывает курьеров и автомобили
    ],
    "initial_routes": [
        // Описывает маршруты, спланированные на предыдущем этапе планирования
    ],
    "options": {
        // Описывает опции маршрутизации

        "incompatible_load_types": [
            // Описывает несовместимые типы заказов. Необязательный раздел
        ],
        "location_groups": [
            // Описывает группы заказов. Необязательный раздел
        ]
    },
    "zones": [
        // Описывает геозоны (если не используются геозоны из интерфейса). Необязательный раздел
    ]
}

Раздел initial_routes предназначен для допланирования, он содержит текущие маршруты (спланированные на предыдущем этапе). Этот раздел используется во всех запросах планирования, кроме первого. Первое планирование выполняется в начале рабочего дня.

Минимальный набор параметров по каждому из разделов

  • склады depots:

    • идентификатор id;
    • координаты point.lat, point.lon;
    • временное окно time_window или несколько временных окон time_windows, если склад работает с перерывами.

  • заказы locations:

    • идентификатор id;
    • координаты point.lat, point.lon;
    • временное окно выполнения заказа time_window или несколько временных окон time_windows;
    • жесткость временного окна hard_window;
    • сервисное время (время на выполнение заказа) service_duration_s.

  • курьеры и автомобили vehicles:

    • идентификатор id;
    • способ передвижения (пешком, на общественном транспорте, на легковом или грузовом автомобиле) routing_mode;
    • необходимость возврата на склад после завершения маршрута return_to_depot.

  • параметры алгоритма планирования options:

    • часовой пояс time_zone.

  • маршруты, запланированные на предыдущей итерации initial_routes. Параметры можно посмотреть в разделе Периодическое допланирование маршрута.

Чтобы упростить интеграцию сервисов Маршрутизации со сторонними приложениями, часть параметров планирования можно оформить в виде пресетов.

Что нужно учесть в параметрах планирования

Время запуска задачи планирования

При планировании алгоритм учитывает только параметры, которые вы передаете в запросе API. Время запуска запроса не учитывается. Поэтому при неправильно заданных параметрах алгоритм может спланировать маршрут, который начинается в прошлом. Например, вы указали временное окно склада (ресторана) с 9:00 до 21:00. Если вы отправляете запрос на планирование в 9:30, алгоритм может построить маршрут с выездом курьера в 9:20. Чтобы этого не происходило, используйте один из способов:

  • В каждом запросе на планирование начало временного окна склада указывайте равным моменту планирования: если вы отправляете запрос в 9:30, указывайте временное окно склада с 9:30 до 21:00, и т.д.

  • Для каждого заказа указывайте время готовности depot_ready_time. Это время должно быть в будущем (не в прошлом).

Время начала маршрутов курьеров

По умолчанию признак гибкого времени начала маршрутов для курьеров flexible_start_time равен false. Этот параметр указывается для склада и распространяется на всех курьеров, которые стартуют с этого склада. Для подбора оптимального времени выезда курьеров мы рекомендуем установить flexible_start_time равным true.

Посещение складов курьерами

Если в одном запросе планируются заказы с разных складов и курьерам разрешено посещать разные склады в одном рейсе, для каждого курьера нужно перечислить разрешенные склады в поле depot_id, см. Дозагрузка на промежуточном складе.

Способ передвижения курьеров

Для курьеров важно указать способ передвижения — на легковом или грузовом автомобиле, общественном транспорте или пешком.

Для курьеров, которые передвигаются на велосипедах или самокатах, указывайте способ передвижения пешком routing_mode = walking и используйте коэффициент корректировки скорости travel_time_multiplier. Для каждого курьера стоит вывести индивидуальный коэффициент корректировки. Это можно сделать с помощью мониторинга и отчета План-факт — сравнить фактическое время в пути для курьера на велосипеде или самокате с плановым временем в пути, рассчитанным для передвижения пешком.

Количество заказов у курьеров

Если вы хотите ограничить количество заказов, которое может выполнять курьер, используйте параметры вместимости capacity.units:

  • для каждого заказа укажите location.shipment_size.units = 1;
  • для курьера в поле vehicle.capacity.units укажите максимально допустимое количество заказов, которое он может выполнить за один рейс.

Балансировка нагрузки

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

Балансировка выполняется только в рамках текущей задачи планирования, которая может не включать в себя ранее доставленные заказы. Чтобы при балансировке по количеству заказов учитывались все заказы за день, нужно обеспечить подсчет заказов, доставленных каждым курьером.

Если вы используете сервис Мониторинга, для подсчета количества заказов, доставленных курьером, можно использовать отчет о качестве работы курьеров. Если вы не используете сервис Мониторинга, вам нужно самостоятельно обеспечить подсчет этого показателя.

Тогда можно использовать формулу стоимости курьера cost:

(locations + orders_count) * (locations + orders_count) - locations * locations, где:

  • locations — количество новых заказов в задаче на допланирование, которое рассчитывается автоматически;
  • orders_count — количество заказов, которые были запланированы курьеру ранее в этот день, включая уже доставленные заказы. Этот параметр нужно предварительно рассчитать и подставить в формулу.

Эта формула подходит, если в задачу допланирования отправляются только новые заказы.

Пример 1

Ранее в этот день Курьер 1 доставил 10 заказов (orders_count = 10), Курьер 2 — 5 заказов, Курьер 3 — 8 заказов. Тогда в текущей задаче планирования в формуле расчета стоимости cost добавятся слагаемые:

  • для Курьера 1: (locations + 10) * (locations + 10) - 100
  • для Курьера 2: (locations + 5) * (locations + 5) - 25
  • для Курьера 3: (locations + 8) * (locations + 8) - 64

Добавление одного нового заказа в маршрут будет стоить:

  • для Курьера 1: (1 + 10) * (1 + 10) - 100 = 21 единицу;
  • для Курьера 2: (1 + 5) * (1 + 5) - 25 = 11 единиц;
  • для Курьера 3: (1 + 8) * (1 + 8) - 64 = 17 единиц.

Таким образом, при прочих равных условиях выгоднее добавить заказ Курьеру 2.

Пример JSON
...
"vehicles": [
  {
    "cost": {
      "route": " (locations + 10) * (locations + 10) - 100",
      "run": "duration_h*100 + distance_km*8"
    },
    "id": "Курьер 1",
    "routing_mode": "driving",
    "shifts": [],
    "tags": [],
    "visited_locations": []
  },
  {
    "cost": {
      "route": " (locations + 5) * (locations + 5) - 25",
      "run": "duration_h*100 + distance_km*8"
    },
    "id": "Курьер 2",
    "routing_mode": "driving",
    "shifts": [],
    "tags": [],
    "visited_locations": []
  },
  {
    "cost": {
      "route": " (locations + 8) * (locations + 8) - 64",
      "run": "duration_h*100 + distance_km*8"
    },
    "id": "Курьер 3",
    "routing_mode": "driving",
    "shifts": [],
    "tags": [],
    "visited_locations": []
  }
],
...

Пример 2

То же, что в примере 1, но каждому курьеру за день спланировано 10 заказов в сумме по уже завершенным рейсам и текущему рейсу:

  • Курьер 1 доставил 10 заказов в предыдущем рейсе;
  • Курьер 2 доставил 5 заказов в предыдущем рейсе и 5 запланировано в текущем рейсе, всего 10 заказов за день;
  • Курьер 3 доставил 8 заказов в предыдущем рейсе и 2 запланировано в текущем рейсе, всего 10 заказов за день.

Тогда стоимость добавления нового заказа в текущий рейс для всех курьеров будет одинаковой:

  • для Курьера 1 это будет 1-ый заказ в текущем рейсе (и 11-ый заказ за день): (1 + 10) * (1 + 10) - 100 = 21;
  • для Курьера 2 — 6-ой заказ в текущем рейсе (и 11-ый за день): (1 + 5 + 5) * (1 + 5 + 5) - 100 = 21;
  • для Курьера 3 — 3-ий заказ в текущем рейсе (и 11-ый за день): (1 + 2 + 8) * (1 + 2 + 8) - 100 = 21.

Таким образом, обычная опция балансировки не потребуется.

Очередь курьеров

Если вы хотите распределять новые заказы в первую очередь на тех курьеров, которые уже закончили свои предыдущие маршруты, вам нужно учитывать несколько факторов:

  1. Необходимо определять, какие курьеры уже закончили маршрут, а какие нет. Для этого используйте один из способов:

    • При планировании указывайте, что по окончании маршрута курьер должен вернуться на склад. Укажите координаты склада с помощью метода nodes для узлов depot (склад).

      Чтобы курьер вручную отмечал завершение предыдущего маршрута и готовность брать новые заказы, задайте для склада очень большое сервисное время service_duration_s, например, 9999999. Тогда автоматическое посещение склада не будет регистрироваться никогда, и кнопка для ручной отметки посещения склада будет доступна курьеру длительное время. Эта кнопка доступна лишь при включенном GPS и активном соединении. Если связь потеряется или сигнал не будет ловить, кнопка может пропадать.

    • Ориентируйтесь на плановое время прибытия курьера в точки маршрута. Однако имейте в виду, что плановое время может отличаться от фактического. Например, если курьер задержался в пути или при передаче заказа клиенту.

  2. Если вы хотите, чтобы курьеры соблюдали очередь (тот, кто раньше вернулся на склад, первым получит новые заказы), используйте дополнительный коэффициент при расчете стоимости курьера cost.

    Например, Курьер 1 вернулся на склад в 13:00, Курьер 2 — в 13:05, Курьер 3 — в 13:10. Пусть каждая минута ожидания курьера на складе стоит 10 единиц. В 13:15 вы запускаете новую задачу планирования, в которой распределяются новые заказы. Тогда для Курьера 1 стоимость маршрута cost будет уменьшена на 150 единиц за 15 минут ожидания, для Курьера 2 — на 100 единиц за 10 минут ожидания и для Курьера 3 – на 50 единиц за 5 минут ожидания.

    Таким образом, при прочих равных условиях Курьер 1 получает приоритет перед Курьером 2, а Курьер 2 — перед Курьером 3.

    Если использовать эти коэффициенты совместно с коэффициентами для балансировки нагрузки, выбор курьера будет еще более оптимальным.

Планирование маршрутов

Отправьте подготовленные данные на планирование, сделав POST-запрос к ресурсу mvrp.

Для допланирования включите в запрос блок initial_routes.

Ответ на запрос планирования:

{
    "id": "<task_id>",
    "status": {
        "estimate": <ориентировочное время решения задачи>,
        "queued": <время, когда задача поставлена в очередь на решение>
    },
    "yt_operations": [],
    "message": "Task queued"
}

task_id — это уникальный номер задачи, который присваивается алгоритмом.

Последовательность запросов подробно разбирается в разделе Пример.

Длительность расчетов в Планировании

Решение задачи планирования занимает от нескольких секунд до десятков минут. В основном это зависит от количества заказов в запросе. Таблица с примерными оценками времени есть в разделе Время обработки запроса. В общее время решения задачи включено время на расчеты, скачивание карт и получение информации о пробках.

Примерное время окончания расчета указано в ответе на запрос планирования в поле estimate.

Если у вас есть объективный дедлайн по времени расчета, а стандартное время на расчет слишком велико, в запросе на планирование укажите время в секундах, которым вы хотите ограничить расчет — в блоке options в параметре solver_time_limit_s. Это время не включает время на скачивание карт и информации о пробках, его уменьшить нельзя.

Мы не рекомендуем использовать параметр solver_time_limit_s без необходимости, так как его ограничение ухудшает качество планирования.

Просмотр решения

Результаты планирования можно посмотреть на карте по ссылке вида https://yandex.ru/courier/mvrp-map#<task_id>, где <task_id> — уникальный номер задачи, см. раздел Планирование маршрутов. Ссылка доступна после завершения расчета. Описание карты можно посмотреть в разделе Просмотр решения на карте.

Исходный запрос в формате JSON доступен по ссылке вида https://courier.yandex.ru/vrs/api/v1/log/request/<task_id>.

Результат планирования в формате JSON, включая метрики решения, можно посмотреть по ссылке вида https://courier.yandex.ru/vrs/api/v1/result/<task_id>.

Результат планирования можно выгрузить в Excel по ссылке вида https://yandex.ru/courier/companies/<company_id>/depots/all/mvrp/<task_id>/export/excel, где <company_id> — идентификатор вашей компании в сервисе Маршрутизации, см. раздел Авторизация.

Что делать с нераспределенными заказами

Некоторые заказы могут не войти в маршрут и остаться нераспределенными из-за слишком строгих ограничений, указанных при планировании. Например, если задано слишком узкое временное окно для выполнения заказа или вместимости автомобиля недостаточно для доставки груза. Подробнее см. Возможные причины нераспределенных заказов.

В решении задачи планирования нераспределенные заказы можно посмотреть в ответе JSON в блоке dropped_locations. Чтобы в решении не было нераспределенных заказов, попробуйте следующие способы:

  • исправьте причину попадания заказа в нераспределенные — например, увеличьте временное окно или используйте дополнительных курьеров;
  • передайте заказ в стороннюю службу доставки, например, Яндекс Доставку, используя их API;
  • оставьте заказы нераспределенными и отмените их.

После исправления условий отправьте задачу на повторное планирование.

Что делать с нерентабельными маршрутами

Если для очередной итерации планирования накопилось мало заказов, полученные маршруты могут оказаться для вас нерентабельны. Вы можете:

  • оставить полученные маршруты как есть;
  • подождать появления новых заказов и выполнить планирование повторно;
  • отменить недоставленные заказы.

При оценке рентабельности можно опираться на стоимость маршрута, рассчитанную по вашей формуле.

Ограничения на количество запросов

В сервисе Планирования есть два типа лимитов:

  • по количеству запросов в сутки. При необходимости этот лимит может быть увеличен до любого необходимого значения. Для этого обратитесь к вашему менеджеру.

  • по количеству одновременно выполняемых запросов. Если вы не собираетесь отправлять одновременно большое количество запросов (например, для разных городов или складов), это ограничение не будет влиять на вашу работу.

Для решения каждой задачи рассчитывается потребление вычислительных ресурсов Яндекса в юнитах (квотах). Количество юнитов, необходимых для задачи, зависит от многих параметров:

  • количества заказов;
  • периода планирования (количества отрезков времени);
  • количества задач (task_count);
  • количества вариантов (потоков) расчета для каждой задачи (thread_count);
  • качества (quality) решаемых задач (задачи с низким качеством обычно решаются локально).

Заранее сложно предсказать, какой объем ресурсов будет задействован, и как следствие — сколько задач одновременно сможет решать компания.

Чтобы снизить потребление вычислительных ресурсов:

  • разделите одну объемную задачу на несколько более мелких. Например, поделите курьеров на группы и планируйте маршруты отдельно для каждой группы. Планируйте маршруты не на весь день, а отдельно для первой и второй смены.

  • задайте ограничение на время поиска оптимального маршрута в параметре solver_time_limit_s. Алгоритм будет решать задачу планирования локально.

Если из-за особенностей вашего бизнеса необходимо запускать одновременно большое количество задач, организуйте очередь так, чтобы отправлять новый запрос к сервису только после того, как будет получен ответ на предыдущий. Оценивайте время выполнения запроса.

Если после всех принятых мер доступные лимиты все равно мешают решению ваших бизнес-задач, обратитесь к менеджеру и попросите увеличить квоты для вашей компании.

Тарификация

Тарификация по сервисам Планирования и Мониторинга производится отдельно. Для сценария экспресс-доставки (On Demand) используется тарификация по количеству заказов за период. С описанием правил расчет можно ознакомиться в документации.

В сервисах нельзя установить жесткий лимит по количеству заказов за период. При превышении вашего тарифного пакета сервисы не будут заблокированы, но за превышение будет выставлен счет согласно условий вашего договора. Чтобы не превышать лимиты приобретенного пакета и не переплачивать за превышение, внимательно следите за биллингом в кабинете разработчика.

Пример последовательности запросов для допланирования

Разберем последовательность запросов при использовании сервисов Планирования и Мониторинга. Если вы не используете сервис Мониторинга, запросы API Мониторинга нужно заменить на другие методы.

Схема процесса от инициализации до передачи маршрутов курьерам ↗️

Шаг 0. Создание справочников

Схема создания справочников ↗️

Создание справочника складов

Создать справочник складов в Мониторинге можно через веб-интерфейс или с помощью метода depots-batch.

Схема работы со справочником складов ↗️

Создаем два склада, указав очень большое сервисное время, чтобы курьеры отмечали посещение в приложении вручную, см. Состав и формат данных.

curl -H "Content-Type: application/json" -H "Authorization: OAuth <ваш-токен>" -X POST -d @<Путь_до_файла_в_кодировке_UTF-8> https://courier.yandex.ru/api/v1/companies/<company-id>/depots-batch

[
  {
    "number":"777",
    "name":"Основной склад",
    "address":"ул. Льва Толстого, 16",
    "lat": 55.733974,
    "lon": 37.587093,
    "time_interval":"09:00 - 21:00",
    "service_duration_s": 999999
  }, 
  {
    "number":"888",
    "name":"Склад 2",
    "address":"ул. Льва Толстого, 17",
    "lat": 55.7448,
    "lon": 37.6729,
    "time_interval":"11:00 - 23:00",
    "service_duration_s": 999999
  }
]

Создание справочника курьеров

Создать справочник курьеров в Мониторинге можно через веб-интерфейс или с помощью метода couriers-batch.

Схема работы со справочником курьеров ↗️

  • Добавляем двух курьеров. В поле number указывайте логин курьера, под которым нужно будет ежедневно входить в приложение Яндекс Курьер. Это может быть любой уникальный номер, например, номер автомобиля или номер телефона.

    curl -H "Content-Type: application/json" -H "Authorization: OAuth <ваш-токен>" -X POST -d @<Путь_до_файла_в_кодировке_UTF-8> https://courier.yandex.ru/api/v1/companies/<company-id>/couriers-batch

    [
  {
    "number":"х456нт",
    "phone":"+79051112233",
    "name":"Иван"
  },
  {
    "number":"е322тт",
    "phone":"+79034445566",
    "name":"Сергей"
  }
]

  • Чтобы курьеры могли использовать мобильное приложение Яндекс Курьер, нужно зарегистрировать номера их мобильных телефонов. Это также можно сделать через веб-интерфейс или с помощью метода app-user.

    Добавляем два номера телефона, сделав для этого два отдельных запроса:

    curl -H "Content-Type: application/json" -H "Authorization: OAuth <ваш-токен>" -X POST -d @<Путь_до_файла_в_кодировке_UTF-8> https://courier.yandex.ru/api/v1/companies/<company-id>/app-user

    {
  "login":"+79051112233"
}

    {
  "login":"+79034445566"
}

Примечание

Перед переходом к основным этапам планирования проверьте себя по чек-листу.

Шаг 1. Первое планирование в начале рабочего дня

Подготовьте исходные данные и отправьте POST-запрос на планирование методом add-mvrp.

Схема планирования маршрута ↗️

В 9:00 отправляем на планирование первые 2 заказа, которые появились на основном складе. Оба курьера свободны и находятся на складе.

curl -H "Content-Type: application/json" -H "Authorization: OAuth <ваш-токен>" -X POST -d @<Путь_до_файла_в_кодировке_UTF-8> https://courier.yandex.ru/api/v1/vrs/add/mvrp

{
  "depot": {
    "id": "777",
    "point": {
      "lat": 55.733974,
      "lon": 37.587093
    },
    "time_window": "09:00-21:00",
    "flexible_start_time": true
  },
  "locations": [
    {
      "id": "order_1",
      "point": {
        "lat": 55.723420,
        "lon": 37.558939
      },
      "address":"Учебный переулок, 4с1",
      "title": "Иван",
      "phone": "89005893211",
      "comments": "3 подъезд, домофон 321",
      "service_duration_s": 300,
      "time_window": "09:15-09:35",
      "hard_window": true,
      "depot_ready_time": "09:10",
      "type": "delivery"
    },
    {
      "id": "order_2",
      "point": {
        "lat": 55.736265,
        "lon": 37.586989
      },
      "address":"улица Тимура Фрунзе, 28",
      "title": "Анна",
      "phone": "89998884422",
      "comments": "зайти в магазин косметики",
      "service_duration_s": 300,
      "time_window": "09:10-09:30",
      "hard_window": true,
      "depot_ready_time": "09:05",
      "type": "delivery"
    }
  ],
  "vehicles": [
    {
      "id": "х456нт",
      "return_to_depot": true,
      "routing_mode": "driving"
    },
    {
      "id": "е322тт",
      "return_to_depot": true,
      "routing_mode": "driving"
    }
  ],
  "options": {
    "time_zone": 3
  }
}

Если запрос отправлен корректно, получаем ответ вида:

{
    "id": "<task_id>",
    "status": {
        "estimate": <ориентировочное время решения задачи>,
        "queued": <время, когда задача поставлена в очередь на решение>
    },
    "yt_operations": [],
    "message": "Task queued"
}

В параметре estimate содержится примерное время окончания расчета. В это время можно пробовать получать результат, см. шаг 2.

Оценочное время решения задачи может меняться в процессе решения. Оценка верна примерно в 75% случаев (задачи решаются за 5-15 секунд до estimate). Для некоторых задач фактическое время решения может быть больше, чем указано в estimate (обычно, не более чем на 3 минуты).

Примечание

Обязательно сохраните значение параметра id — номер задачи task_id. По этому номеру вы сможете получить результат планирования на шаге 2.

Если в запросе были ошибки, в ответе будет сообщение о них. Если вы не можете понять суть ошибки, обратитесь в чат поддержки.

Шаг 2. Получение результата планирования

Чтобы получить результат планирования, отправьте GET-запрос методом mvrp.

curl -H "Content-Type: application/json" -H "Authorization: OAuth <ваш-токен>" -X GET https://courier.yandex.ru/api/v1/vrs/result/mvrp/<task_id>

Если во время решения задачи отправить GET-запрос, в ответе приходит сообщение о том, что задача решается.

{
    "id": "<task_id>",
    "status": {
        "estimate": <ориентировочное время решения задачи>,
        "queued": <время, когда задача поставлена в очередь на решение>,
        "started": <время начала решения задачи>,
        "matrix_downloaded": <время загрузки матрицы решения>
    },
    "yt_operations": [],
    "message": "Task is running and available for polling",
    "matrix_statistics": {
        ...
    }
}

Мы рекомендуем отправлять повторные GET-запросы ближе к ориентировочному времени решения задачи, не чаще одного раза в 10 секунд.

При получении ответа с кодом 200 в результате JSON появляется объект result. Описание полей ответа можно посмотреть в документации.

После получения ответа с кодом 200 можно сформировать ссылку на просмотр результата на карте: https://yandex.ru/courier/mvrp-map#<task_id>.

Шаг 3. Анализ результата

В ответе в объекте result содержится информация о маршрутах и их метриках.

В поле solver_status возвращается статус задачи:

  • SOLVED — задача полностью решена в рамках заданных ограничений;
  • PARTIAL_SOLVED — задача решена, но некоторые заказы остались нераспределенными;
  • UNFEASIBLE — невозможно найти решение, удовлетворяющее всем строгим ограничениям.

Проанализируйте данные, которые желательно проверить до отправки маршрутов курьерам: стоимость решения, количество используемых курьеров, количество опозданий.

Шаг 4. Сохранение результата

Если результат вас устраивает, сохраните его в вашей учетной системе для следующих планирований:

  • массив routes объекта result;
  • номер задачи task_id.

Схема анализа и сохранения маршрута ↗️

Шаг 5. Отправка маршрутов в Мониторинг

Передайте спланированные маршруты курьерам.

Схема отправки маршрутов в Мониторинг ↗️

Выполните запросы:

  • Отправьте маршруты в сервис Мониторинга методом routes-batch. Если вместо сервиса Мониторинга вы используете собственную разработку, этот этап выполняется другими способами.

    Каждому маршруту нужно присвоить уникальный номер number. Мы рекомендуем использовать формат <courier_number>-<номер маршрута за сегодняшний день>-<дата маршрута>. Этот номер будет использоваться на следующих шагах.

    В результате планирования мы получили маршрут для одного из двух курьеров. Отправляем маршрут курьеру для выполнения.

    curl -H "Content-Type: application/json" -H "Authorization: OAuth <ваш-токен>" -X POST -d @<Путь_до_файла_в_кодировке_UTF-8> https://courier.yandex.ru/api/v1/companies/<company_id>/routes-batch

    [
  {
    "courier_number":"х456нт",
    "number":"х456нт-1-2024-01-01",
    "date": "2024-01-01",
    "depot_number":"777",
    "route_start": "09:10:00",
    "routing_mode": "driving"
  }
]

  • Добавьте заказы в созданные маршруты методом orders-batch.

    Добавляем в маршрут два заказа:

    curl -H "Content-Type: application/json" -H "Authorization: OAuth <ваш-токен>" -X POST -d @<Путь_до_файла_в_кодировке_UTF-8> https://courier.yandex.ru/api/v1/companies/<company_id>/orders-batch

    [
  {
    "number":"order_2",
    "route_number":"х456нт-1-2024-01-01",
    "status":"confirmed",
    "address":"улица Тимура Фрунзе, 28",
    "customer_name": "Анна",
    "phone": "89998884422",
    "comments": "зайти в магазин косметики",
    "lat": 55.736265,
    "lon": 37.586989,
    "service_duration_s": 300,
    "time_interval": "09:10-09:30",
    "type": "delivery"
  },
  {
    "number":"order_1",
    "route_number":"х456нт-1-2024-01-01",
    "status":"confirmed",
    "address": "Учебный переулок, 4с1",
    "customer_name": "Иван",
    "phone": "89005893211",
    "comments": "3 подъезд, домофон 321",
    "lat": 55.7448,
    "lon": 37.6729,
    "service_duration_s": 300,
    "time_interval":"09:15-09:35",
    "type": "delivery"
  }
]

  • Если курьеры должны выезжать со склада или возвращаться на склад, добавьте склады в начало и конец маршрута.

    Для этого сначала нужно получить идентификаторы маршрутов, которые им присвоены в сервисе Маршрутизации. Получить их можно методом routes.

    Получаем идентификатор маршрута.

    curl -H "Content-Type: application/json" -H "Authorization: OAuth <ваш-токен>" -X GET https://courier.yandex.ru/api/v1/companies/<company_id>/routes

    В ответе в поле id возвращается уникальный идентификатор маршрута route_id.

    Теперь добавьте склады в маршрут методом nodes.

    curl -H "Content-Type: application/json" -H "Authorization: OAuth <ваш-OAuth-токен>" -X POST "https://courier.yandex.ru/api/v1/companies/<company_id>/routes/<route_id>/nodes

    [
  {
    "type": "depot",
    "value": {
      "number": "777"
    }
  },
  {
    "type": "order",
    "value": {
      "number": "order_2"
    }
  },
  {
    "type": "order",
    "value": {
      "number": "order_1"
    }
  },
  {
    "type": "depot",
    "value": {
      "number": "777"
    }
  }
]

Теперь маршруты доступны курьерам в мобильном приложении Яндекс Курьер.

Шаг 6. Получение актуальной информации из Мониторинга

Через некоторое время поступили новые заказы. Их нужно распределить между курьерами и маршрутами. Для этого нужно знать текущий статус маршрутов и заказов и местоположение курьеров.

Есть два варианта допланирования:

  1. Если вы хотите распределять новые заказы между всеми курьерами, включая тех, кто еще выполняет назначенный им маршрут, необходимо:

    • получить статусы всех заказов методом orders.

    • получить последние координаты курьеров методом route-info. Позиция курьера, использованная при последнем обновлении маршрута, передается в last_update_info.courier_position.

    curl -H "Content-Type: application/json" -H "Authorization: OAuth <ваш-токен>" -X GET https://courier.yandex.ru/api/v1/companies/{company_id}/route-info

    Этот вариант допланирования удобно использовать, если курьерам не нужно забирать заказы со склада, например, если курьеры выполняют услуги, а не доставляют заказы.

  2. Если вы хотите назначать новые заказы только на свободных курьеров, которые находятся на складе, нужно получить статусы возврата на склад по всем курьерам методом route-info.

Шаг 7. Допланирование

Для допланирования используйте тот же запрос, который вы отправляли на шаге 1.

Схема допланирования с новыми заказами ↗️

  • Если на шаге 6 вы использовали первый вариант:

    В запросе передайте:

    • старые заказы;
    • новые заказы;
    • текущие маршруты initial_routes — блок routes c шага 4;
    • текущие координаты курьеров.

    Если координаты курьера в запросе не передаются, считается, что курьер находится на складе.

    Если какие-то курьеры ушли с маршрута, а какие-то вышли на маршрут, обновите список курьеров.

    Если какие-то клиенты отменили свои заказы, удалите эти заказы из нового запроса.

  • Если на шаге 6 вы использовали второй вариант:

    В запросе передайте:

    • новые заказы;
    • курьеров, которые находятся на складе (отметили возврат на склад в мобильном приложении Яндекс Курьер).

Затем повторите шаги со 2 по 5:

Если новые заказы распределены в текущие маршруты курьеров, то последовательность выполнения старых заказов в маршруте может измениться.

Предыдущая
Периодическое допланирование маршрута
Следующая
Допланирование (устаревшая версия)