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

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

TMS (Transport Management System) — это специализированное ПО для управления логистикой: планирование маршрутов, назначение водителей, трекинг транспортных средств, учёт расходов на доставку. Когда у магазина есть собственный автопарк или сложная структура доставки, интеграция 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 (1С:ТМС, Яндекс.Маршрутизация, Samsara, самописная)
• Обработчик смены статуса заказа для автоматической передачи в TMS
• Пользовательские поля заказа UF_TMS_TASK_ID, UF_TRACKING_URL
• Вебхук-эндпоинт с HMAC-верификацией для приёма статусов
• Очередь bl_tms_queue с retry-логикой для надёжной доставки сообщений