Типовые доработки при интеграции через API
Взаимодействие системы-источника и API Яндекс Маршрутизации происходит следующим образом:
-
Система-источник отправляет запрос на маршрутизацию.
-
В ответе приходит ID — уникальный идентификатор решения.
-
Сервис в течение некоторого времени оптимизирует маршруты. Система-источник периодически запрашивает статус решения по ID.
-
Когда планирование маршрутов завершено, система-источник может получить результат.
Формат обмена данными — JSON. Взаимодействие асинхронное: на планирование можно запускать несколько задач одновременно.
Ниже рассказано, какие доработки обычно требуется выполнить на стороне системы-источника при интеграции с Яндекс Маршрутизацией через API.
Основные доработки
Запуск задачи маршрутизации
Как правило, систему-источник дорабатывают так, чтобы отправку данных в сервис планирования инициировал пользователь. (Запуск процесса маршрутизации по расписанию — редко используемый вариант.) Поэтому обычно для отправки задачи создается форма или кнопка. Возможный набор инструментов в форме:
-
определение выборки объектов (заказов, машин/курьеров) для планирования;
-
указание настроек оптимизации;
-
кнопка запуска задачи.
Хранение новых атрибутов
При переходе на автоматическую маршрутизацию нужно формализовать знания логистов, не отраженные в учетной системе. К таким знаниям могут относиться сведения о совместимости заказов и машин, совместимости заказов между собой, сервисном времени, временных окнах и т. д. Для хранения такого рода информации нужно добавить атрибуты в существующие справочники или, в некоторых случаях, создать новые справочники.
Преобразование исходных данных в JSON
Система-источник должна преобразовать исходные данные (информацию о заказах, машинах/курьерах, складе, настройках задачи) в формат JSON и сформировать запрос к сервису. Чтобы результат маршрутизации был реалистичным, важно предусмотреть проверку данных на предмет:
-
полноты (обязательные поля не должны быть пустыми);
-
корректности (например, сервисное время не может быть равно нулю).
Обработка полученного решения
Результаты оптимизации нужно получить и обработать. Как правило, выданное сервисом решение преобразуют в объекты системы-источника (например, маршрутные листы).
Хранение логов
Ведение истории обращений к сервису позволяет диагностировать ошибки на стороне учетной системы. Также при взаимодействии с технической поддержкой по поводу конкретного запуска планирования нужно сообщать ID задачи (для предметного рассмотрения вопроса). При наличии логов доступ к идентификаторам задач всегда есть.
Другие возможные доработки
Получение решения, отредактированного в веб-интерфейсе
Если построенные сервисом маршруты скорректировать в веб-интерфейсе, то ID измененного решения будет отличаться от ID исходной задачи. Поэтому, чтобы система-источник могла получить отредактированный результат, в ней предусматривают возможность указать новый идентификатор и запросить соответствующее ему скорректированное решение.
Особенности одновременных запусков (с разными настройками для разных складов)
Часто настройки оптимизации зависят от склада, подаваемого на вход задачи. Чтобы выполнять параллельные запуски с разными складами, может потребоваться доработка, которая будет изменять настройки решения в зависимости от выбранного склада.
Поддержка допланирования
Когда выполняется допланирование (или планирование волнами), в составе исходных данных для новой задачи нужно передать результаты выполненной ранее маршрутизации (подробнее см. раздел Периодическое допланирование). В схеме запроса для этой цели предусмотрены специальные параметры, заполнение которых требует изменений на стороне системы-источника.