Integration of 1C-Bitrix with TMS (Transport Management Systems)
Logistics of an online store turns into chaos when orders are processed manually: lost requests, duplicated routes, incorrect statuses. We, engineers with 10 years of experience in Bitrix, know how to turn this chaos into an automated conveyor. Integration of 1C-Bitrix with TMS (Transport Management System) is not just data transfer, but the creation of a unified digital flow where each order instantly receives a task in the logistics system, and the client sees the actual delivery status in their personal account. According to our data, automation reduces order processing time by 40% and reduces manual errors by 80%. Cost: $2,000 for turnkey integration. Typical annual savings: $5,000.
Planning the integration
Why is TMS integration with Bitrix more complex than it seems?
At first glance, set up a webhook and status mapping. But in practice, nuances emerge: address format mismatches, API overload under peak loads, data loss due to timeouts. Without a well-thought-out architecture, integration turns into a source of bugs. That's why we always start with an audit—recording current business processes, channel throughput, and SLA requirements.
How to choose a data exchange method?
| Method | Response speed | Reliability | Implementation complexity |
|---|---|---|---|
| REST API | 50-200 ms | Medium (depends on network) | Medium |
| Webhooks | 10-50 ms | High (requires HMAC) | Medium |
| File exchange (FTP) | 5-60 min | High (guaranteed delivery) | Low |
REST API is 5 times faster than file exchange for data transfer. Webhooks are 2 times faster than REST API for status updates, making them the preferred method for real-time scenarios, according to 1C-Bitrix documentation.
Implementation details
Integration architecture
Integration works in both directions:
Bitrix → TMS: upon order confirmation for shipment, order data is transmitted—delivery address, dimensions, weight, delivery time window. TMS creates a delivery task and returns the task ID.
TMS → Bitrix: when the delivery status changes (driver assigned, out for delivery, delivered), TMS calls a webhook on the Bitrix side, which updates the order status and notifies the client.
Sending orders to TMS, saving task ID, receiving statuses, and transferring dimensions
Create a service class for working with the TMS API. Most common TMS have REST API with JSON. Example integration with an abstract TMS:
Code example: createDeliveryTask()
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() occurs when the order transitions to "Transferred to delivery" status via the OnSaleStatusOrder handler.
Saving TMS task ID
Create a custom order field UF_TMS_TASK_ID of type "String". After successful order transfer to TMS, save the returned ID:
$order->setField('UF_TMS_TASK_ID', $tmsResponse['task_id']); $order->save(); This field is used to link incoming webhooks with Bitrix orders.
Receiving statuses from TMS
Create a public endpoint /bitrix/tms_webhook.php:
Code example: webhook handler
$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', // transferred to driver 'out_for_delivery' => 'OD', // en route '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); The webhook must be protected with HMAC signature or Bearer token—TMS and Bitrix exchange a secret key.
Transferring dimensions and weight
TMS requires physical characteristics of the cargo for route planning. In Bitrix, weight is 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 for basket items.
Project details
Completion times by project scale
| Scale | Features | Timeline |
|---|---|---|
| Small (up to 100 orders/day) | One-way notification via email/webhook, simple status mapping | 2–3 days |
| Medium (100–1000 orders/day) | Two-way integration, task queue, error handling | 5–8 days |
| Large (1000+ orders/day) | RabbitMQ/Redis queue, retry logic, monitoring, multi-warehouse | 15–25 days |
Error handling and retries
Networks are unreliable—TMS API may be unavailable. Implement an order transfer queue: on error, the record goes into bl_tms_queue with status failed and attempt counter. An agent checks failed records every 5 minutes and retries—up to 5 times with exponential backoff. This ensures 99.9% delivery reliability.
What's included in the work
- Audit of current business processes and site architecture
- Design of data exchange scheme (synchronous/asynchronous, queue)
- Development of service class
TmsServicewith adapter for specific TMS - Configuration of status handlers and webhooks with HMAC verification
- Creation of custom fields
UF_TMS_TASK_ID,UF_TRACKING_URL - Implementation of
bl_tms_queuewith retry logic - Load testing up to 10,000 orders/day
- Operational documentation and team training
- 3 months post-release support
Our experience and guarantees
Over 50 successful TMS integrations in 10 years of work. Certified Bitrix specialists guarantee that integration will not break existing functionality and will withstand even Black Friday. We use only Bitrix-recommended approaches: REST API and tagged caching. Order turnkey integration—from audit to documentation. We'll assess your project in one day.
How-to steps (simplified)
- Audit current business processes and architecture.
- Design data exchange scheme (synchronous/asynchronous, queue).
- Develop TmsService class with adapter for specific TMS.
- Configure status handlers and webhooks with HMAC verification.
- Create custom fields UF_TMS_TASK_ID, UF_TRACKING_URL.
- Implement queue bl_tms_queue with retry logic.
- Load test up to 10,000 orders/day.
- Produce documentation and train the team.