Интеграция 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-логикой для надёжной доставки сообщений