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

Інтеграція 1С-Bitrix з TMS (транспортними системами)

TMS (Transport Management System) — це спеціалізоване ПО для управління логістикою: планування маршрутів, призначення водіїв, трекінг транспортних засобів, облік витрат на доставку. Коли в магазину є власний автопарк або складна структура доставки, інтеграція TMS з Bitrix дозволяє автоматично передавати замовлення в логістичну систему та отримувати назад статусу та трек-дані.

Архітектура інтеграції

Інтеграція працює в обидва боки:

Bitrix → TMS: при підтвердженні замовлення до відправки передаються дані про замовлення — адреса доставки, габарити, вага, часове вікно доставки. TMS створює задачу доставки та повертає ID задачі.

TMS → Bitrix: при змінці статусу доставки (призначено водія, виїхав, доставлено) TMS викликає вебхук на стороні Bitrix, який оновлює статус замовлення та сповіщає клієнта.

Передача замовлень у 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();

Це поле використовується для зв'язку вхідних вебхуків з замовленнями Bitrix.

Прием статусів від 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 та Bitrix обмінюються секретним ключем.

Передача габаритів та ваги

TMS для планування маршрутів потребує фізичні характеристики вантажу. У Bitrix вага зберігається в 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-логікою для надійної доставки сообщень