Варианты схем интеграции

Выбор схемы

При выборе архитектуры интеграции и при проектировании доработок учетной системы учитывайте следующие моменты:

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

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

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

Загрузить данные в сервисы и получить данные из них можно через Excel или по API. Вы можете открыть задачу планирования из интерфейса Маршрутизации и экспортировать ее в Мониторинг.

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

Базовые варианты интеграции с сервисами Маршрутизации

Способ\Сервис	Планирование	Мониторинг	Интеграция Планирования и Мониторинга
Через Excel	Планирование через Excel	Ручной через Excel необходимо заполнить лист Routes	Планирование через Excel, ручной экспорт в Мониторинг. Подробнее
По API	API Планирования	API Мониторинга	Планирование по API, ручной экспорт в Мониторинг. Подробнее Полная интеграция по API. Подробнее

Геокодирование

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

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

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

При геокодировании качество адреса имеет существенное значение. Вероятность получения неточных координат увеличивается в следующих случаях:

• адрес хранится в неструктурированном виде — указана сплошная адресная строка, в которой недостаточно информации (название населенного пункта очень распространенное, но для него не указана область или городской округ; название улицы приведено без названия города), либо информация избыточна для определения координат (например, указаны номер квартиры и код домофона);

• в строке с адресом содержится дополнительная информация: телефоны, комментарии.

Рекомендуем:

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

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

• для ограничения области поиска координат использовать в геокодере параметр bbox;

• при получении ответа от геокодера использовать признак точности определения дома — значение тега precision. Если точность не равна exact или number, рекомендуется сообщить пользователю о необходимости уточнить адрес.

Планирование через Excel, ручной экспорт в Мониторинг

Где подойдет этот способ

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

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

Схема

Как реализовать интеграцию

1. Выгрузите из учетной системы файл Excel заданного формата.

2. Загрузите полученный файл в веб-интерфейс Планирования и запустите задачу. Адреса в файле будут автоматически геокодированы.

3. При необходимости откорректируйте решение в веб-интерфейсе.

4. Полученный на шаге 3 результат (с учетом ваших изменений) выгрузите в Excel. Как вариант, можно реализовать загрузку файла в учетную систему для получения информации по плановым маршрутам.

5. Полученный на шаге 3 результат экспортируйте в Мониторинг.

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

Планирование по API, ручной экспорт в Мониторинг

Где подойдет этот способ

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

Схема

Как реализовать интеграцию

1. Перед запуском задачи учетная система отправляет адреса на геокодирование. Геокодер возвращает координаты и признак точности.

2. Если координаты недостаточно точные, скорректируйте их вручную.

3. Получив координаты, учетная система отправляет запрос на добавление задачи — начало планирования.

   Сервис должен вернуть один из ответов:

   • код успешной постановки задачи в очередь и id задачи;

   • код ошибки.

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

   Примечание

   На этом этапе можно открыть решение по ссылке: https://yandex.ru/courier/companies/<company_id>/depots/all/mvrp/<task_id>, где:

   • <company_id> — идентификатор компании, который можно найти в разделе Настройки → Компания → Идентификатор компании.

   • <task_id> — id задачи.

4. При необходимости откорректируйте решение в веб-интерфейсе.

5. Конечный id задачи зависит от того, корректировалось ли решение:

   • Если решение не менялось, то информацию о маршрутах можно получить по исходному id задачи.

   • Если решение было отредактировано, то id задачи изменился. Для получения информации по отредактированному решению нужно использовать API.

6. Полученный на шаге 4 результат экспортируйте в Мониторинг.

7. По итогам работы курьеров данные о качестве работы можно выгрузить в Excel.

Полная интеграция по API

Где подойдет этот способ

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

Схема

Как реализовать интеграцию

1. Перед запуском задачи учетная система отправляет адреса на геокодирование. Геокодер возвращает координаты и признак точности.

2. Если координаты недостаточно точные, скорректируйте их вручную.

3. Получив координаты, учетная система отправляет запрос на добавление задачи — начало планирования.

   Сервис должен вернуть один из ответов:

   • код успешной постановки задачи в очередь и id задачи;

   • код ошибки.

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

   Примечание

   На этом этапе можно открыть решение по ссылке: https://yandex.ru/courier/companies/<company_id>/depots/all/mvrp/<task_id>, где:

   • <company_id> — идентификатор компании, который можно найти в разделе Настройки → Компания → Идентификатор компании.

   • <task_id> — id задачи.

4. При необходимости откорректируйте решение в веб-интерфейсе.

5. Конечный id задачи зависит от того, корректировалось ли решение:

   • Если решение не менялось, то информацию о маршрутах можно получить по исходному id задачи.

   • Если решение было отредактировано, то id задачи изменился. Для получения информации по отредактированному решению нужно использовать API.

6. Сохраните плановые маршруты на стороне учетной системы. Для отдельных случаев можно выполнить планирование с абстрактными курьерами.

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

   • точный график работы собственных курьеров пока неизвестен;

   • используется наемный транспорт.

7. После назначения конкретных курьеров передайте данные о маршрутах в Мониторинг с помощью API Мониторинга. Учитывайте особенности работы API, обновляя следующие данные:

   • склады;

   • курьеры и номера телефонов курьеров;

   • маршруты;

   • заказы.

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

   • Информация о заказах на определенную дату

   • Информация о текущем состоянии заказа

   • Уведомления о заказе

   • Информация о качестве доставки

Допланирование на складе (машины еще не выехали)

Где подойдет этот способ

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

Особенности

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

• Частота и периодичность допланирования зависят от конкретной бизнес-модели.

Схема

Как реализовать интеграцию

1. Учетная система отправляет задачу на первичное планирование через API Планирования и получает результат.

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

3. Учетная система отправляет задачу на допланирование через API Планирования. В том числе учетная система должна передать:

   • данные заказов из первичного планирования и предыдущих допланирований;

   • привязку заказов к машинам по результатам предыдущих планирований (чтобы ранее созданные маршруты не были изменены);

   • данные новых заказов.

4. Сохраните новую версию плановых маршрутов на стороне учетной системы для последующих итераций допланирования. В это время продолжают накапливаться новые заказы.

5. Повторите шаги 3 и 4 необходимое количество раз до получения итоговой версии решения.

6. Учетная система отправляет итоговую версию маршрутов через API Мониторинга.

Допланирование в пути

Где подойдет этот способ

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

Особенности

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

• Частота и периодичность допланирования зависят от конкретной бизнес-модели.

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

Схема

Как реализовать интеграцию

1. Учетная система отправляет задачу на первичное планирование через API Планирования и получает результат.

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

3. Информация о маршрутах отправляется через API Мониторинга.

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

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

6. Учетная система отправляет задачу на допланирование через API Планирования. В составе задачи должны быть:

   • привязка заказов к машинам по результатам предыдущих планирований (чтобы ранее созданные маршруты не были изменены);

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

   • другие выполненные заказы, если это pickup-заказы, которые должны быть учтены для расчета грузоподъемности;

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

7. Сохраните новую версию плановых маршрутов на стороне учетной системы для последующих итераций допланирования. В это время продолжают накапливаться новые заказы.

8. Учетная система обновляет информацию о маршрутах через API Мониторинга. Повторите шаги 6 и 7 необходимое количество раз до получения итоговой версии решения.

Пример последовательности ближайших заказов

Курьер выполнял заказы 1–5 и поступил новый заказ 6. На момент допланирования уже выполнены заказы 1–3, поэтому в запрос на допланирование следует передать информацию о заказе 3 (это точка старта машины) и заказах 4–6.

При этом необходимо:

• привязать к курьеру заказы 3–5, поскольку они ранее уже были назначены на него;

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

Так курьер сможет завершить заказ 4, а сервис определит последовательность выполнения заказов 5 и 6 оптимальным образом.

Интеграция с приложением Яндекс Курьер

Где подойдет этот способ

Этот способ интеграции подходит для упрощения работы курьеров с приложением Яндекс Курьер.

Особенности

• Номер телефона и логин курьера должны совпадать и иметь формат +7хххххххххх.

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

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

Как реализовать интеграцию

1. Добавьте номера телефонов курьеров, которым нужно работать с приложением Яндекс Курьер, через Рабочее место логиста или через API.

2. Спланируйте маршруты:

   • через Excel — в полях Логин курьера и Телефон укажите номер телефона курьера. Чтобы номер телефона с символом + загрузился в Мониторинг корректно, в начале ячейки введите символ ' (одинарная кавычка).

   

   • через API — в полях vehicles.id и vehicles.phone укажите номер телефона курьера.

3. Полученный на шаге 2 результат экспортируйте в Мониторинг.

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

Написать в службу поддержки