Integration of 1C-Bitrix with TMS (transport systems)

Integration of 1С-Bitrix with TMS (Transport Management Systems)

TMS (Transport Management System) is specialized software for logistics management: route planning, driver assignment, vehicle tracking, delivery cost accounting. When store has own fleet or complex delivery structure, TMS integration with Bitrix allows automatically transmitting orders to logistics system and receiving statuses and tracking data back.

Integration architecture

Integration works both directions:

Bitrix → TMS: on order confirmation to ship, order data transmitted — delivery address, dimensions, weight, delivery time window. TMS creates delivery task and returns task ID.

TMS → Bitrix: on delivery status change (driver assigned, departed, delivered) TMS calls webhook on Bitrix side, updating order status and notifying customer.

Transmitting orders to TMS

Create service class for working with TMS API. Most common TMS have REST API with JSON. Example integration with abstract 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);
    }
}

Call TmsService::createDeliveryTask() happens on order status transition to "Shipped to delivery" via OnSaleStatusOrder handler.

Saving TMS task ID

Create custom order field UF_TMS_TASK_ID type "String". After successful order transmission to TMS write returned ID there:

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

This field used for linking incoming webhooks with Bitrix orders.

Receiving statuses from TMS

Create public endpoint /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',  // assigned to driver
        'out_for_delivery' => 'OD',  // in transit
        'delivered' => 'F',   // delivered
        'failed'    => 'CF',  // not delivered
    ];

    $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);

Webhook must be protected by HMAC signature or Bearer token — TMS and Bitrix exchange secret key.

Transmitting dimensions and weight

TMS for route planning requires physical cargo characteristics. In Bitrix weight stored in b_catalog_product.WEIGHT, dimensions in infoblock properties (LENGTH, WIDTH, HEIGHT) or in b_catalog_product (fields added via UF). Method calculateWeight() sums WEIGHT * QUANTITY by basket items.

Execution timeline by project scale

Error handling and retries

Networks are unreliable — TMS API may be unavailable. Implement order transmission queue: on error record goes to bl_tms_queue with status failed and attempt counter. Agent every 5 minutes rechecks failed records and makes retry — maximum 5 times with exponential backoff.

What we configure

• Service class TmsService with adapter for specific TMS (1C:TMS, Yandex.Routing, Samsara, custom)
• Order status change handler for automatic TMS transmission
• Custom order fields UF_TMS_TASK_ID, UF_TRACKING_URL
• Webhook-endpoint with HMAC verification for receiving statuses
• Queue bl_tms_queue with retry logic for reliable message delivery