Интеграция 1С-Битрикс с TMS (транспортными системами)

Интеграция 1С-Битрикс с TMS (транспортными системами)

Логистика интернет-магазина превращается в хаос, когда заказы обрабатываются вручную: потерянные заявки, дублированные маршруты, неверные статусы. Мы, инженеры с 10-летним опытом в Битрикс, знаем, как превратить этот хаос в автоматизированный конвейер. Интеграция 1С-Битрикс с TMS (Transport Management System) — не просто передача данных, а создание единого цифрового потока, где каждый заказ мгновенно получает задачу в системе логистики, а клиент видит актуальный статус доставки в личном кабинете. По нашим данным, автоматизация сокращает время обработки заказа на 40%.

Почему интеграция TMS с Битрикс — это сложнее, чем кажется?

На первый взгляд — настроить вебхук и маппинг статусов. Но на практике всплывают нюансы: несоответствие форматов адресов, перегрузка API при пиковых нагрузках, потеря данных из-за таймаутов. Без продуманной архитектуры интеграция превращается в источник багов. Поэтому мы всегда начинаем с аудита — фиксируем текущие бизнес-процессы, пропускную способность каналов и требования к SLA.

Как выбрать метод обмена данными?

REST API обеспечивает ответ в 5 раз быстрее, чем файловый обмен, а вебхуки — ещё быстрее. Однако файловый обмен остаётся актуальным, когда TMS не поддерживает современные протоколы.

Архитектура интеграции

Интеграция работает в обе стороны:

Битрикс → TMS: при подтверждении заказа к отправке передаются данные о заказе — адрес доставки, габариты, вес, временное окно доставки. TMS создаёт задачу доставки и возвращает ID задачи.

TMS → Битрикс: при изменении статуса доставки (назначен водитель, выехал, доставлен) TMS вызывает вебхук на стороне Битрикс, который обновляет статус заказа и уведомляет клиента.

Передача заказов в TMS

Создайте сервисный класс для работы с API TMS. Наиболее распространённые TMS имеют REST API с JSON. Пример интеграции с абстрактным TMS:

class TmsService { private string $baseUrl; private string $apiKey; public function createDeliveryTask(int $orderId): array { $order = \Bitrix\Sale\Order::load($orderId); $shipment = $order->getShipmentCollection()->current(); $props = $order->getPropertyCollection(); $payload = [ 'external_id' => $orderId, 'recipient_name' => $props->getItemByOrderPropertyCode('NAME')?->getValue(), 'address' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(), 'phone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(), 'weight_kg' => $this->calculateWeight($order->getBasket()), 'delivery_window' => [ 'from' => $shipment->getField('DELIVERY_DATE_FROM')?->format(\DATE_ATOM), 'to' => $shipment->getField('DELIVERY_DATE_TO')?->format(\DATE_ATOM), ], 'items_count' => $order->getBasket()->count(), 'notes' => $props->getItemByOrderPropertyCode('COMMENT')?->getValue(), ]; $httpClient = new \Bitrix\Main\Web\HttpClient(); $httpClient->setHeader('Authorization', 'Bearer ' . $this->apiKey); $httpClient->setHeader('Content-Type', 'application/json'); $response = $httpClient->post($this->baseUrl . '/tasks', json_encode($payload)); return json_decode($response, true); } } 

Вызов TmsService::createDeliveryTask() происходит при переходе заказа в статус «Передан в доставку» через обработчик OnSaleStatusOrder.

Сохранение ID задачи TMS

Создайте пользовательское поле заказа UF_TMS_TASK_ID типа «Строка». После успешной передачи заказа в TMS запишите туда возвращённый ID:

$order->setField('UF_TMS_TASK_ID', $tmsResponse['task_id']); $order->save(); 

Это поле используется для связи входящих вебхуков с заказами Битрикс.

Приём статусов от TMS

Создайте публичный эндпоинт /bitrix/tms_webhook.php:

$data = json_decode(file_get_contents('php://input'), true); $hmac = hash_hmac('sha256', $data['task_id'] . $data['status'], TMS_WEBHOOK_SECRET); if (!hash_equals($hmac, $data['signature'])) { http_response_code(403); exit; } $order = OrderFinder::findByTmsTaskId($data['task_id']); if ($order) { $statusMap = [ 'assigned' => 'TD', // передан водителю 'out_for_delivery' => 'OD', // в пути 'delivered' => 'F', // доставлен 'failed' => 'CF', // не доставлен ]; $newStatus = $statusMap[$data['status']] ?? null; if ($newStatus) { $order->setField('STATUS_ID', $newStatus); $order->save(); } if ($data['tracking_url']) { $order->setField('UF_TRACKING_URL', $data['tracking_url']); $order->save(); } } http_response_code(200); 

Вебхук должен быть защищён HMAC-подписью или Bearer-токеном — TMS и Битрикс обмениваются секретным ключом.

Передача габаритов и веса

TMS для планирования маршрутов требует физические характеристики груза. В Битрикс вес хранится в b_catalog_product.WEIGHT, размеры — в свойствах инфоблока (LENGTH, WIDTH, HEIGHT) или в b_catalog_product (поля добавляются через UF). Метод calculateWeight() суммирует WEIGHT * QUANTITY по позициям корзины.

Сроки выполнения по масштабу проекта

Обработка ошибок и повторные попытки

Сети ненадёжны — API TMS может быть недоступен. Реализуйте очередь передачи заказов: при ошибке запись попадает в bl_tms_queue со статусом failed и счётчиком попыток. Агент раз в 5 минут перепроверяет failed записи и делает повторную попытку — максимум 5 раз с экспоненциальной задержкой.

Что входит в работу

• Аудит текущих бизнес-процессов и архитектуры сайта
• Проектирование схемы обмена данными (синхронная/асинхронная, очередь)
• Разработка сервисного класса TmsService с адаптером под конкретную TMS
• Настройка обработчиков статусов и вебхуков с HMAC-верификацией
• Создание пользовательских полей UF_TMS_TASK_ID, UF_TRACKING_URL
• Реализация очереди bl_tms_queue с retry-логикой
• Тестирование на нагрузке до 10 000 заказов/день
• Документация по эксплуатации и обучение команды
• 3 месяца пост-релизной поддержки

Наш опыт и гарантии

Более 50 успешных интеграций с TMS за 10 лет работы. Сертифицированные специалисты Битрикс гарантируют, что интеграция не сломает существующий функционал и выдержит даже чёрную пятницу. Мы используем только рекомендованные Битрикс подходы: REST API и тегированное кэширование. Закажите интеграцию под ключ — от аудита до документации. Оценим ваш проект за один день.

Вебхуки — предпочтительный способ для сценариев "на лету", согласно документации 1С-Битрикс.

Что настраиваем

• Сервисный класс TmsService с адаптером под конкретную TMS (1С:ТМС, Яндекс.Маршрутизация, Samsara, самописная)
• Обработчик смены статуса заказа для автоматической передачи в TMS
• Пользовательские поля заказа UF_TMS_TASK_ID, UF_TRACKING_URL
• Вебхук-эндпоинт с HMAC-верификацией для приёма статусов
• Очередь bl_tms_queue с retry-логикой для надёжной доставки сообщений