Зачем интегрировать Яндекс Маршрутизацию с 1С и CRM
Интеграция решает одну конкретную задачу: маршрут строится из заказов, которые уже лежат в учётной системе, без ручного переноса адресов и временных окон. Заказ оформляется в 1С, оттуда в сервис маршрутизации уходят адрес, временное окно и параметры груза, обратно возвращается порядок объезда, назначенный водитель и расчётное время прибытия. Диспетчер не перебивает адреса из документа в карту и не сверяет интервалы глазами.
Практический эффект складывается из трёх вещей. Планирование занимает минуты: сервис сам решает, в каком порядке объехать точки и как распределить их между машинами. Ошибки ввода исчезают вместе с ручным переносом, потому что адрес попадает в маршрут в том виде, в каком хранится в базе. История доставки остаётся в учётной системе, и по ней считают загрузку водителей и стоимость рейса.
Данные для маршрутизации уже есть в типовых конфигурациях. 1С:Управление нашей фирмой 8 закрывает учёт, продажи, закупки и производство в малом бизнесе и поставляется в вариантах On-premise, SaaS, облако и для мобильных ОС (обзор 1С:УНФ 8). В контуре 1С:ERP и 1С:КА2 для работы с клиентами применяют встраиваемый модуль 1С:CRM, зарегистрированный в реестре Минцифры (данные по модулю 1С:CRM для 1С:ERP и 1С:КА2): там же хранятся сделки и контактные лица.
Отраслевые CRM добавляют свои поля. CRM для event-агентства объединяет коммерческую, проектную и клиентскую информацию и хранит сведения о компании-заказчике, формате мероприятия, бюджете, количестве гостей, требованиях к площадке и подрядчиках (описание CRM для event-агентства). Часть этих данных напрямую влияет на приоритет доставки: оборудование на площадку с монтажом в 8:00 нельзя везти в конце маршрута.
Без интеграции появляется разрыв. Диспетчер выгружает заказы, правит адреса, распределяет точки по машинам руками, а готовый маршрут переносит обратно в документы. Каждый такой цикл добавляет задержку и риск расхождения между базой и реальным рейсом.
Ниже описаны архитектура и шаги настройки, которые проверяются на стороне 1С и CRM. Параметры API самого сервиса маршрутизации (точные эндпоинты, лимиты, формат ответа) доступные публичные источники не подтверждают, поэтому эти значения сверяйте в консоли и документации сервиса до того, как закладывать их в код.
Архитектура интеграции: компоненты и потоки данных
Типовая схема состоит из четырёх звеньев. Учётная система (1С:УНФ, 1С:УТ, 1С:ERP) или CRM выступает источником заказов. Промежуточный сервис забирает новые заказы, приводит их к формату API, отправляет пакет на расчёт и записывает результат обратно. API сервиса маршрутизации считает порядок точек и распределение по машинам. Обратный поток возвращает маршрутные листы в учётную систему и уходит водителю.
Сущности, которые участвуют в обмене: заказ, адрес, временное окно, водитель, транспортное средство, маршрутный лист. У каждой должен быть стабильный идентификатор, единый для 1С, CRM и сервиса маршрутизации. На практике берут GUID документа заказа и GUID элемента справочника водителя.
На стороне 1С обмен строят через HTTP-сервисы, веб-сервисы или внешние обработки. CRM отдаёт данные по REST API либо через тот же промежуточный сервис. Формат обмена (JSON или XML) и версию API фиксируют заранее: смена версии посреди проекта ломает маппинг полей. Выбор между синхронным вызовом и событийной схемой описан в сравнении паттернов Request/Reply, Publish/Subscribe и Event-Driven.
Прямая интеграция или через промежуточный сервис: что выбрать
Прямая интеграция: 1С сама вызывает API маршрутизации. Плюсы: минимум компонентов, быстрый старт, не нужен отдельный хост. Минусы: массовые вызовы грузят сервер 1С, при недоступности API сеанс зависает, повторы и обработку ошибок приходится писать внутри конфигурации, а доработанную типовую конфигурацию сложнее обновлять.
Промежуточный сервис: микросервис, скрипт или шина данных между 1С и API. Плюсы: буферизация запросов, кэш геокодирования, повторные попытки, централизованное логирование, защита учётной системы от всплесков нагрузки. Минусы: дополнительный хост, его мониторинг и компетенции для поддержки.
Практическое правило: при объёме примерно до 100 заказов в сутки и одном источнике данных прямая интеграция из 1С закрывает задачу. Если источников несколько (1С и CRM), заказов сотни в день или нужна отказоустойчивость, выносят промежуточный слой. Похожий приём используют в готовых решениях: в составе Cloud 1C обмен между Microsoft Dynamics AX и 1С выполняет отдельный интеграционный модуль, а не прямые вызовы из учётных систем (описание решения Cloud 1C).
Какие данные и в каком направлении передаются
Из 1С и CRM в сервис маршрутизации уходят:
- идентификатор заказа, обычно GUID документа;
- адрес доставки, при возможности сразу с координатами;
- временное окно, то есть интервал, в который должен приехать водитель;
- вес, габариты и количество мест;
- приоритет или тип услуги: срочная доставка, монтаж, забор;
- контактное лицо и телефон для связи.
Обратно из сервиса приходят:
- идентификатор маршрута;
- порядок точек и назначенный водитель;
- расчётное время прибытия по каждой точке;
- статус расчёта: успех, ошибка, частичный результат.
Маппинг справочников делают явным: адрес из 1С сопоставляют с адресной базой сервиса, водителя из 1С связывают с водителем в сервисе по идентификатору. Рассинхронизация появляется там, где справочник правят руками сразу в двух системах. Одну из них назначают ведущей, вторую обновляют только из неё.
Отраслевые поля переносят выборочно. CRM для event-агентства разделяет понятия лид, сделка и проект и ведёт воронку от нового запроса до постпроектной работы (возможности CRM для event-агентства). Статус сделки полезен как признак приоритета, а бюджет и количество гостей сами по себе маршрут не строят.
Способы обмена данными между 1С, CRM и Яндекс Маршрутизацией
На практике применяют четыре варианта: REST API, SOAP, обмен файлами (CSV, XML) и очереди сообщений. REST API подходит для онлайн-обмена. Обмен файлами оставляют для ночной пакетной выгрузки, когда заказов много и реального времени не требуется. Очереди (RabbitMQ, Kafka) снимают пиковую нагрузку и дают повторную обработку: устройство очередей и паттерны разобраны в материале про проектирование очередей сообщений в микросервисах.
Формат обмена привязывают к тому, что уже умеет учётная система. В 1С есть типовые механизмы переноса между конфигурациями: например, модули переноса данных из 1С:УПП 1.3 в 1С:УНФ 3.0 и из 1С:УНФ 3.0 в 1С:УТ 11 (перечень модулей переноса в обзоре 1С:УНФ 8). Логику переноса из этих модулей переносят на обмен с внешним API: та же схема «источник, правила соответствия, приёмник».
Авторизацию продумывают до первого запроса: токен или OAuth, отдельный сервисный аккаунт, права только на нужные методы. Срок жизни токена и порядок его ротации фиксируют в документации интеграции, иначе через месяц обмен встанет из-за истёкшего ключа.
Обмен через REST API: пошаговая настройка на стороне 1С
- Определить точку отправки. Создают HTTP-сервис в конфигурации либо используют внешнюю обработку, подключённую регламентным заданием. Первый вариант удобнее для регулярного обмена, второй не требует менять конфигурацию.
- Настроить аутентификацию. Секрет хранят в константе или защищённом хранилище, а не в тексте модуля.
- Реализовать два метода: отправка заказов и получение маршрутов. Тела запросов и ответов описывают структурами, а не разбором JSON строками вручную.
- Обработать ответы и ошибки. Код ответа, тело и время запроса пишут в журнал обмена, а не в сообщения пользователю.
Логика отправки выглядит так: выбрать документы с нужным статусом, заполнить структуру полями заказа, сериализовать её в JSON, выполнить POST на эндпоинт расчёта, разобрать ответ и записать статус. Точный адрес эндпоинта и состав тела запроса берут из документации сервиса: публичные источники, доступные на момент подготовки статьи, эти параметры не подтверждают. Порядок получения ключа, проверки квот и тестового запроса описан в инструкции по подключению сервиса маршрутизации.
Отладку ведут на копии базы. HTTP-вызовы в рабочей базе на этапе тестов создают реальные маршруты и уведомления водителям, которые потом приходится отменять вручную.
Настройка обмена на стороне CRM
CRM чаще всего выступает источником заказов и получателем статусов. Если CRM встроена в 1С (модуль 1С:CRM для 1С:ERP и 1С:КА2), обмен идёт через те же HTTP-сервисы 1С и отдельный коннектор не нужен. Для внешних отраслевых CRM используют REST API самой CRM или промежуточный сервис, который читает сделки и создаёт заказы на доставку в 1С.
Пример потока: CRM фиксирует историю общения, этапы сделки и базу заказчиков, а при переводе сделки в статус подготовки промежуточный сервис создаёт в 1С заказ на перевозку с адресом площадки и временным окном монтажа. Поля для этого берут из карточки сделки, а не запрашивают у менеджера повторно.
Справочники клиентов и адресов синхронизируют до запуска обмена заказами. Если один и тот же адрес записан в CRM как «Красная 15, корп. 2» и в 1С как «ул. Красная, 15/2», сервис маршрутизации увидит две разные точки и построит лишний круг.
Синхронизация заказов и автоматическое построение маршрутов
Жизненный цикл выглядит так: заказ появился в 1С или CRM, промежуточный сервис забрал новые записи, передал их в сервис маршрутизации, получил оптимизированный маршрут, сохранил результат в учётной системе и отправил задание водителю. Каждый шаг имеет свой статус, и по нему видно, где оборвалась цепочка. Приём, обработку, передачу и хранение удобно проектировать как единый конвейер: принципы его построения разобраны в статье про сквозной конвейер данных.
Для автоматического расчёта достаточно четырёх групп параметров: адреса точек, временные окна, характеристики груза, список доступных машин с их грузоподъёмностью. Пример: 50 заказов на день и 5 машин, часть точек с интервалом до 12:00. Сервис распределит заказы по машинам и вернёт 5 маршрутов с порядком объезда.
Как передать заказы из 1С в Яндекс Маршрутизацию
- Отобрать документы по статусу, например «К доставке», и по дате планирования.
- Заполнить структуру полями: идентификатор, адрес, временное окно, вес, тип услуги.
- Сериализовать структуру в JSON и отправить POST на эндпоинт расчёта маршрута.
- Разобрать ответ, записать идентификатор маршрута и статус в регистр сведений.
В 1С:УНФ источником данных служат документы «Заказ клиента»: оттуда берут контрагента, адрес доставки и состав заказа. Пакет разбивают на части: количество точек в одном запросе ограничено, и превышение лимита вернёт ошибку вместо маршрута. Конкретное значение смотрите в документации сервиса.
Регламентное задание запускают по расписанию, например каждые 15 минут, и оно обрабатывает только новые и изменённые заказы. Признак «отправлен в маршрутизацию» хранят в самом документе или в отдельном регистре.
Получение и сохранение маршрутов обратно в учётную систему
Ответ сервиса содержит идентификаторы заказов, порядок точек, водителя и расчётное время. В 1С эти данные складывают в документ «Маршрутный лист» с табличной частью точек: одна строка на заказ, с номером по порядку и временем прибытия. Альтернатива: регистр сведений, если маршрутный лист формируют другим механизмом.
Запись повторяют идемпотентно. Идентификатор маршрута проверяют перед созданием документа: если он уже есть в системе, данные обновляют, а не создают новую запись. При повторном получении того же ответа дубли не появляются.
Водителю результат уходит либо из сервиса маршрутизации, либо из 1С через мобильное приложение или печатную форму маршрутного листа. Второй вариант привычнее для компаний, где водитель не пользуется отдельным приложением.
Обработка ошибок и обеспечение отказоустойчивости
Типовые сбои обмена: недоступность API, таймауты, ошибка авторизации, неверный адрес, превышение лимита запросов. У каждого свой признак и своя реакция. Сетевой таймаут лечится повтором, ошибка авторизации повтором не лечится, а неверный адрес требует правки данных.
Рабочий набор механизмов: логирование каждого запроса, повторные попытки с нарастающей задержкой, идемпотентные ключи, мониторинг и алерты. Как эти приёмы сочетаются друг с другом, включая Circuit Breaker, Retry, Timeout и идемпотентность, разобрано в статье про типичные ошибки маршрутизации процессов.
Логирование и мониторинг обмена
Журнал обмена хранит дату и время операции, тип операции, идентификатор заказа, код и тело ответа, текст ошибки. Место хранения: регистр сведений в 1С или внешний файл, если записей много. Регистр удобнее тем, что история видна прямо из базы и по ней строят выборки.
Наблюдаемость строят на метриках: число успешных и неуспешных обменов за сутки, доля ошибок, время ответа API, длина очереди необработанных заказов. Резкий рост доли ошибок или очереди служит сигналом для алерта. Метрики собирают в Prometheus и выводят на дашборд, пороги алертов настраивают в Zabbix или Alertmanager.
Повторная отправка и идемпотентность
Каждый заказ получает уникальный идентификатор, который передаётся в сервис маршрутизации при каждой отправке. При повторе сервис распознаёт заказ по этому ключу и не создаёт дубль. В 1С статус отправки хранят рядом с документом: «не отправлен», «отправлен», «маршрут получен», «ошибка».
Если ответ не получен, запрос повторяют с тем же идентификатором и увеличивающейся паузой: например, 1, 5 и 30 секунд. Повтор без ограничения попыток превращает временный сбой API в шторм запросов. После третьей неудачной попытки запись уходит в очередь на ручной разбор и не блокирует остальной обмен.
Типичные проблемы и ограничения при интеграции
Проект чаще всего ломают пять вещей: несовместимость версий 1С, лимиты API, неточные адреса, расхождение справочников и необходимость доработки типовой конфигурации. Ниже разбор двух самых частых групп.
Ограничения API Яндекс Маршрутизации
Проверьте три группы лимитов: число запросов в минуту, количество точек в одном запросе, число маршрутов в сутки. Значения для Яндекс Маршрутизации в доступных публичных источниках не подтверждены, их смотрят в консоли сервиса и актуальной документации. Эти проверки закладывают в интеграцию заранее, а не после первого отказа.
Стратегия обхода лимитов: пакетная отправка вместо одиночных запросов, кэширование геокодирования (один адрес геокодируется один раз), разнесение вызовов по времени и очередь на стороне промежуточного сервиса. При ответе с кодом превышения лимита запрос повторяют после паузы, а не сразу.
Проблемы с адресами и геокодированием
Адрес в 1С и CRM хранится так, как его ввёл оператор: с сокращениями, без индекса, иногда с ошибочным номером дома. Для маршрутизации адрес приводят к координатам. Геокодирование выполняют на стороне сервиса маршрутизации или отдельным сервисом, а результат сохраняют в карточке контрагента или адреса.
Проверка адреса при вводе дешевле, чем разбор неудачного маршрута. Если адрес не геокодируется, заказ помечают как проблемный и не отправляют в расчёт: иначе точка выпадет из маршрута или встанет в конец цепочки.
Чек-лист внедрения и следующие шаги
- Посчитать объём: сколько заказов в сутки, сколько машин, нужен ли расчёт в реальном времени.
- Выбрать способ обмена: прямые вызовы из 1С или промежуточный сервис.
- Зафиксировать маппинг данных и справочников: заказы, адреса, водители, транспорт.
- Сделать обмен заказами и получение маршрутов, включая идемпотентную запись результатов.
- Настроить логирование, метрики и алерты обмена.
- Проверить полный цикл на копии базы: от создания заказа до маршрутного листа.
- Запустить на ограниченном объёме, сравнить результат с ручным планированием, затем расширить охват.
Роли в проекте распределяются так: DevOps-инженер или системный администратор отвечает за промежуточный сервис, сеть, мониторинг и хранение секретов; разработчик 1С дорабатывает обмен и документы; интегратор подключается, если источников несколько и нужна единая шина данных. Базовый сценарий с одним источником заказов и прямыми вызовами реально собрать силами администратора 1С и DevOps-инженера.
Перед стартом сверьтесь с документацией сервиса по трём пунктам: эндпоинты и формат запросов, лимиты, порядок авторизации. Дальше идите по чек-листу: маппинг, обмен, мониторинг, тест на копии. Такой порядок исключает отладку на боевых заказах и потерю реальных маршрутов.