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

От выбора схемы интеграции до промышленной эксплуатации — что нужно знать до начала разработки

CRM передаёт адреса, временные окна и параметры заказов, а Яндекс Маршрутизация возвращает готовые маршруты. Обмен должен контролировать ошибки адресов, повторы запросов и изменения статусов доставки.

«Яндекс Маршрутизация» решает именно эту задачу — строит оптимальные маршруты с учётом дорожной обстановки, временных окон и параметров транспорта. Но сама по себе она не заменяет учётную систему: это отдельный сервис, с которым нужно наладить обмен данными. Статья — для тех, кто планирует такую интеграцию: разработчиков, IT-руководителей и владельцев логистики, которые хотят понимать, что придётся сделать на своей стороне, какие есть готовые решения и где будут основные трудозатраты.

Что такое «Яндекс Маршрутизация» и из чего она состоит

Сервис объединяет два независимых продукта, которые можно использовать вместе или по отдельности [2][4]:

• Планирование маршрутов — рассчитывает оптимальное распределение заказов по машинам и курьерам и последовательность их объезда, с учётом графа дорог и трафика [2].
• Мониторинг маршрутов (сервис исполнения заказов) — отслеживает фактическое выполнение маршрутов, статусы заказов, работу курьеров через мобильное приложение [2][4].

Важно сразу зафиксировать: это разные сервисы с разными API, и данные между ними автоматически не переносятся — если задача построена в Планировании, для отслеживания её нужно отдельно экспортировать в Мониторинг [4].

Работать с обоими сервисами можно двумя способами: через веб-интерфейс с загрузкой Excel-файла заданного формата, либо через API с помощью JSON-запросов [2]. Именно второй вариант — предмет этой статьи, поскольку он и даёт настоящую интеграцию с CRM или учётной системой.

Как это устроено технически

Главный принцип: данные хранятся у вас, а не в сервисе

Это первое, что нужно понять при проектировании архитектуры. Сервис планирования решает задачи независимо и не хранит справочники, настройки и историю маршрутов на своей стороне [4]. Каждый запрос на построение маршрута должен содержать полный набор данных: склад, доступные машины или курьеров, все заказы, настройки оптимизации [4][5]. Это значит, что CRM или учётная система становится единственным «источником правды» — и на неё ложится обязанность:

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

Авторизация: API-ключ и OAuth-токен

Для работы с API Планирования используется API-ключ, который передаётся как параметр apikey в POST-запросе; его тарифицируют, поэтому доступ к нему должен быть ограничен доверенными сотрудниками [3]. Ключ можно получить автоматически при регистрации в веб-интерфейсе сервиса либо через Кабинет Разработчика Яндекса — во втором случае для доступа к рабочему месту логиста нужно будет отдельно связаться с менеджером [3].

Для работы с API Мониторинга и с некоторыми функциями API Планирования (например, геозонами из справочника) применяется OAuth-токен, который должен быть выпущен для пользователя с ролью администратора в компании [3]. Путь запроса при авторизации через токен отличается от пути в спецификации с API-ключом — это частая причина ошибок на старте интеграции [3].

Разные OAuth-токены, выпущенные на разные административные учётные записи, можно использовать, чтобы разделять задачи планирования по регионам или распределительным центрам [3].

Формат обмена: JSON и асинхронные задачи

Взаимодействие с API Планирования полностью асинхронное [7]:

1. Учётная система отправляет запрос на добавление задачи и получает в ответ либо id задачи, либо код ошибки [4][7].
2. Время расчёта зависит от количества точек — сервис указывает, что оптимизация занимает в среднем около 15 минут, на небольших задачах быстрее, на задачах свыше 1000 заказов — дольше [2].
3. Учётная система периодически опрашивает статус задачи по id, пока решение не будет готово [4][7].
4. Если решение потом скорректировали вручную в веб-интерфейсе, у отредактированного решения появляется новый id — и учётной системе нужно уметь запросить именно его [4][7].

Одновременно можно запускать несколько задач планирования — ограничения на параллельные запуски нет [7].

Геокодирование — отдельная задача

Важный нюанс, о котором часто забывают на старте: встроенный геокодер в веб-интерфейсе работает только при загрузке данных через Excel. Запросы к API геокодером не обрабатываются — при обращении через API в запросе нужно передавать уже готовые координаты, а не адреса [4][5]. Если адреса доставки часто меняются, потребуется отдельная интеграция с сервисом геокодирования, например с Яндекс Геокодером [4][5].

На точность координат стоит обратить особое внимание: если адрес хранится одной неструктурированной строкой вперемешку с комментариями и телефонами, вероятность ошибок геокодирования выше. Рекомендуется разделять поля ввода адреса и остальной информации, подключать проверку адреса на этапе ввода и учитывать признак точности (precision) в ответе геокодера [4].

Российская специфика

Персональные данные клиентов и курьеров

Интеграция маршрутизации по определению работает с адресами доставки, а нередко и с геолокацией курьеров в реальном времени. По 152-ФЗ «О персональных данных» персональными данными признаются любые сведения, относящиеся к физическому лицу, включая адрес [11]. Передача адреса доставки курьеру или в сторонний сервис формально считается обработкой персональных данных [12] — а значит, компания, которая строит такую интеграцию, выступает оператором персональных данных со всеми вытекающими обязанностями: определить цель обработки, ограничить состав и сроки хранения данных, обеспечить их защиту.

На практике это означает как минимум: включить передачу адресов и геоданных в политику обработки персональных данных компании, ограничить круг сотрудников и систем, которые видят полные адреса клиентов, и предусмотреть в архитектуре интеграции защищённую передачу данных (HTTPS, ограничение доступа к API-ключам и токенам).

Готовый модуль для 1С

Если учётная система — 1С, разработчик Яндекса предоставляет готовую внешнюю обработку для интеграции, которая существует в двух вариантах — для управляемых и для обычных форм [4][9]. Модуль поддерживает конфигурации «Управление торговлей 11», «ERP», «Бухгалтерия предприятия 3.», «Комплексная автоматизация 2.» (более новая версия) и «Управление торговлей 10.», «Комплексная автоматизация 1.», «Управление производственным предприятием» (более старая версия) [9].

Важная оговорка от самого разработчика: модуль предоставляется «как есть», корректная работа в нетиповой (доработанной) конфигурации не гарантируется, а обслуживание модуля не осуществляется — техподдержка Яндекса помогает только по вопросам самих сервисов Планирования и Мониторинга, а не по доработкам обработки [9]. Кроме того, при обновлении модуля все индивидуальные доработки в нём теряются [9] — это стоит сразу заложить в план работ, если планируется кастомизация.

Модуль умеет: заполнять справочники машин и складов, геокодировать адреса заказов (в том числе тестово — случайными координатами), отправлять запрос на планирование, показывать результат и передавать его в Мониторинг, а также работать с пресетами настроек и получать отчёты «План/Факт» и «Качество работы курьеров» [9].

Для CRM (amoCRM, Bitrix24, retailCRM и других) готовых модулей интеграции с «Яндекс Маршрутизацией» на момент подготовки статьи в открытых источниках обнаружить не удалось. Официальная документация прямо говорит: «для других систем (не 1С) готовые модули для интеграции в текущий момент отсутствуют» [5]. Это значит, что для CRM интеграцию нужно строить с нуля через REST API — либо силами штатных разработчиков, либо с привлечением интегратора.

Лицензирование и тарификация

Доступ к API и лицензирование «Яндекс Маршрутизации» строятся на годовой лицензии с минимальным платежом, который включает определённое количество единиц тарификации (транспортных средств/курьеров в сутки либо распределённых на маршрут заказов — в зависимости от выбранного тарифа), и отдельной ценой за превышение этого объёма [10]. Тарифная сетка периодически пересматривается, поэтому конкретные суммы имеет смысл уточнять непосредственно в личном кабинете или у менеджера сервиса на момент подключения — ориентироваться на цифры из статей полугодовой давности не стоит.

Для целей проектирования интеграции важнее другое: тарификация не зависит от того, как именно реализована интеграция (Excel, частично через API или полностью через API) — платится за использование самого сервиса маршрутизации, а не за способ подключения [10]. Отдельного тестового окружения (sandbox) у API нет: тестовые и продуктивные запросы технически ничем не отличаются, поэтому для обкатки интеграции рекомендуется завести отдельный тестовый ключ на отдельном аккаунте [5].

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

Официальная документация описывает четыре базовые схемы — от простой к максимально автоматизированной [4].

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

Данные выгружаются из учётной системы в Excel-шаблон, логист вручную загружает файл в веб-интерфейс, запускает планирование, при необходимости корректирует решение и экспортирует результат обратно в Excel и в Мониторинг [4]. Подходит для быстрого пилотного запуска на небольших объёмах; не рекомендуется для сценариев с допланированием или если процесс требует много ручных операций [4].

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

Учётная система сама отправляет запрос на добавление задачи через API и получает результат, но логист может доработать решение через веб-интерфейс, а в Мониторинг маршруты передаются вручную [4]. Хороший промежуточный вариант — то, что можно сделать быстрее полной интеграции, но уже без ручной выгрузки в Excel.

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

Максимальная гибкость: и Планирование, и Мониторинг работают через API без участия человека в передаче данных между системами [4]. Плановые маршруты при этом обязательно должны сохраняться в учётной системе — именно она становится источником данных для назначения конкретных курьеров и для последующего допланирования [4].

4. Допланирование — на складе и в пути

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

• Допланирование на складе — когда часть заказов известна заранее, а машины ещё не выехали. Новые заказы нужно включать в уже построенные маршруты, при этом передавая данные всех предыдущих итераций планирования и привязку заказов к машинам, чтобы не переломать уже согласованные маршруты [4].
• Допланирование в пути — когда курьеры уже в дороге, а заказы продолжают поступать. Здесь дополнительно нужно передавать текущее местоположение машины (обычно — данные о последнем выполненном заказе) и последовательность ближайших точек маршрута, чтобы курьер не сбивался с уже пройденного пути [4].

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

Практические этапы внедрения

Официальная методология внедрения включает шесть шагов, из которых собственно интеграция — только один, четвёртый [5]. Это важно держать в голове: до написания кода стоит пройти более ранние шаги.

1. Ознакомление с продуктом — понимание возможностей и ограничений сервиса.
2. Тестирование продукта — прогон реальных данных компании через веб-интерфейс, до какой-либо разработки.
3. Проезд по маршрутам — проверка, что построенные маршруты реалистичны на местности.
4. Интеграция — встраивание сервиса в свои информационные системы.
5. Опытная эксплуатация — использование на реальных заказах с доработкой шероховатостей.
6. Промышленное использование (тиражирование) — масштабирование на все склады/площадки.

На шаге интеграции документация рекомендует выполнить следующее [5]:

• выбрать схему взаимодействия (Excel, API с UI логиста или API без UI — то есть с собственным интерфейсом логиста);
• решить вопрос с получением координат — заранее геокодировать разово или подключить геокодер для часто меняющихся адресов;
• при нескольких складах — внедрять последовательно, начиная со склада со средними показателями по объёму заказов, а не с самого крупного или проблемного;
• выделить ресурсы разработчиков не только на саму интеграцию, но и на следующий этап — опытную эксплуатацию, когда обычно всплывают дополнительные требования к параметрам маршрутизации;
• изучить спецификацию API и порядок обработки ошибок до начала разработки;
• если учётная система — 1С, использовать готовый модуль как стартовую точку;
• организовать тестовый ключ API для разработчиков отдельно от продуктивного.

Типовые доработки на стороне CRM или учётной системы

Независимо от выбранной схемы, практика показывает набор доработок, которые почти всегда нужны при интеграции через API [7]:

• Инициация задачи пользователем. Обычно отправку запроса на планирование запускает сотрудник вручную через форму или кнопку — с выбором заказов и машин для планирования и настроек оптимизации; запуск по расписанию используется редко [7].
• Хранение новых атрибутов. Переход на автоматическую маршрутизацию требует формализовать то, что раньше держалось «в голове» у логиста: совместимость заказов и машин, сервисное время на точке, временные окна доставки и т. п. Под это нередко нужно добавлять новые поля в существующие справочники или заводить отдельные [7].
• Преобразование данных в JSON с проверкой на полноту (обязательные поля не пусты) и корректность (например, сервисное время не равно нулю) [7].
• Обработка полученного решения — как правило, результат маршрутизации преобразуют в объекты учётной системы, например маршрутные листы [7].
• Хранение логов запросов, включая идентификаторы задач — это заметно ускоряет диагностику проблем и общение с техподдержкой сервиса [7].
• Дополнительно, в зависимости от сценария: получение отредактированного в веб-интерфейсе решения по новому id, поддержка параллельных запусков с разными настройками по складам, поддержка допланирования [7].

Ограничения, ошибки и риски

Как устроена обработка ошибок

API возвращает JSON и стандартные коды ответа. Редкие проблемы на стороне серверов Яндекса дают ошибку с кодом 50x; все ошибки валидации данных и бизнес-логики приходят в теле ответа с кодом 200 и должны обрабатываться на стороне клиента отдельно [8]. Практически это значит, что нельзя ориентироваться только на HTTP-код — нужно разбирать содержимое ответа.

Официальная документация выделяет несколько категорий типичных ошибок [8]:

• отсутствие обязательного параметра (например, не указан vehicle/vehicles или time_zone);
• недопустимое значение параметра (некорректный формат даты, отрицательный объём груза, разнотипные ID машин);
• неуникальные идентификаторы — совпадающие ID заказов, машин или групп балансировки;
• ссылки на неопределённые идентификаторы — например, указание shift_id, которого нет в запросе;
• взаимоисключающие параметры — например, одновременное указание depot и depots, или hard_window и hard_time_window.

Отдельная категория — ошибки, связанные с самим решением (часть заказов не удалось распределить по машинам); для них в документации есть отдельный разбор типичных причин нераспределённых заказов [8].

Устойчивость к сбоям связи

Для кратковременных сетевых проблем рекомендуется настраивать таймауты (около 10 секунд) и повторные запросы с экспоненциально растущей задержкой и случайной добавкой (jitter), пока интервал между повторами не достигнет 30–60 секунд — дальше его можно не увеличивать [8]. Это стандартная практика для интеграций такого рода, и её стоит закладывать в архитектуру с самого начала, а не добавлять постфактум после первого сбоя в проде.

Другие ограничения, которые стоит учитывать заранее

• Отсутствие готового модуля для большинства CRM — типовую разработку через API нельзя оценить «по аналогии с 1С», трудозатраты будут выше.
• Геокодирование не входит в API Планирования — это отдельная интеграция и отдельная статья расходов, если адреса часто меняются.
• Хранение всей истории маршрутов и справочников — ответственность учётной системы, а не сервиса; при потере этих данных заново «поднять» состояние планирования будет нечем.
• 1С-модуль официально не поддерживается разработчиком при доработках и теряет кастомизацию при обновлении — если критично сохранить изменения, стоит вести отдельный git/версионирование доработанного кода обработки.

Как выбрать вариант реализации

Не в каждом случае нужна дорогостоящая полная интеграция по API. Логику выбора можно свести к нескольким вопросам:

• Объём заказов небольшой, планирование разовое или редкое. Часто достаточно связки веб-интерфейса и Excel-выгрузки из учётной системы — без разработки вообще.
• Учётная система — 1С типовой конфигурации, объём заказов растёт. Разумная отправная точка — готовый модуль-обработка с последующей точечной доработкой под свои процессы.
• Учётная система — CRM (Bitrix24, amoCRM, retailCRM и подобные) без готового решения. Нужна разработка интеграции через REST API с нуля: форма инициации задачи, преобразование данных в JSON, обработка асинхронного ответа, геокодирование, хранение истории.
• Заказы поступают волнами в течение дня, курьеры уже в пути. Без поддержки допланирования не обойтись — это отдельный контур доработок и хранения промежуточных состояний маршрутов.

В части случаев для оценки объёма работ и выбора архитектуры полезен именно технический аудит: посмотреть, как сейчас устроены справочники заказов, машин и адресов в конкретной CRM или 1С, и уже от этого отталкиваться при проектировании обмена данными с сервисом маршрутизации.

Как может помочь «Пятый фактор»

Основная сложность такой интеграции обычно заключается не только в подключении API, но и в сопоставлении данных, обработке ошибок и контроле обмена между системами — особенно если учётная система не 1С и готового модуля просто нет. Команда «Пятого фактора» может изучить существующий процесс работы с заказами и маршрутами, оценить возможные варианты реализации — от доработки готового 1С-модуля до полной интеграции CRM с API «Яндекс Маршрутизации» — и помочь с разработкой или технической консультацией по архитектуре обмена данными.

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

Вывод

Интеграция «Яндекс Маршрутизации» с CRM или учётной системой — это в первую очередь вопрос архитектуры данных, а не только вызова API. Сервис ничего не хранит сам, поэтому вся ответственность за справочники, историю маршрутов и корректность передаваемых данных ложится на учётную систему компании. Для 1С есть готовая отправная точка в виде бесплатного модуля, для остальных систем — только разработка через REST API с нуля. Выбор схемы интеграции — от простой Excel-выгрузки до полной автоматизации с допланированием — стоит делать исходя из реального объёма заказов и того, насколько часто они меняются в течение дня, а не сразу закладывать максимально сложный вариант.

Источники

[1] yandex.ru — Поддержка и документация Яндекс Маршрутизации — https://yandex.ru/routing/support/

[2] yandex.ru — Начало работы с Яндекс Маршрутизацией — https://yandex.ru/routing/doc/ru/vrp/index

[3] yandex.ru — Яндекс Маршрутизация — интеграция с API — авторизация — https://yandex.ru/routing/doc/ru/vrp/authorization

[4] yandex.ru — Яндекс Маршрутизация — выбор схемы интеграции — https://yandex.ru/routing/doc/ru/vrp/integration-variants

[5] yandex.ru — Яндекс Маршрутизация — порядок внедрения — Шаг 4. Интеграция — https://yandex.ru/routing/doc/ru/vrp/integration

[6] yandex.ru — Яндекс Маршрутизация — модули интеграции с 1С — схема взаимодействия с 1С — https://yandex.ru/routing/doc/ru/vrp/1c-interaction

[7] yandex.ru — Яндекс Маршрутизация — интеграция с API — типовые доработки — https://yandex.ru/routing/doc/ru/vrp/api-typical-adaptation

[8] yandex.ru — Яндекс Маршрутизация — интеграция с API — обработка ошибок — https://yandex.ru/routing/doc/ru/vrp/error-handling

[9] yandex.ru — Яндекс Маршрутизация — работа c 1С-обработкой — https://yandex.ru/routing/doc/ru/vrp/1c-guide-uf

[10] yandex.ru — Тарифы и условия использования Яндекс Маршрутизации — https://yandex.ru/routing/doc/ru/tariffs/delivery/prices/

[11] garant.ru — Федеральный закон от 27.07.2006 N 152-ФЗ «О персональных данных» — https://base.garant.ru/12148567/

[12] klerk.ru — 152-ФЗ о персональных данных: что важно знать предпринимателю — https://www.klerk.ru/blogs/roskom24/690780/