Developing Bitrix24 Integration with Logistics Systems
Logistics is one of the bottlenecks in companies where sales managers and the delivery department work in different systems. The manager closes a deal in the CRM, passes the data via Excel or phone, logistics staff manually create a request in their own system — and the chain is broken. Integrating Bitrix24 with a TMS (Transport Management System) or WMS (Warehouse Management System) closes this gap.
Common Logistics Systems and Their APIs
1C:TMS Logistics. 1C HTTP services, data format — JSON or XML. Key operations: creating a transport request, retrieving status, attaching documents.
MoySklad. REST API with OAuth 2.0. Rich documentation, sandbox. Supports order management, shipments, stock, and returns.
CDEK API v2. REST API, JWT authentication. Rate calculation, order creation, tracking, list of pickup points.
Yandex.Delivery / DPD / Boxberry / PEK. Each has its own REST API with different data structures and authentication mechanisms. For a universal integration with multiple carriers we use the "adapter" pattern: a unified interface within the application, with a separate implementation for each carrier.
WMS systems (Manhattan, SAP Extended Warehouse Management, 1C:WMS). Typically SOAP or a proprietary API. Integration is more complex due to legacy protocols.
Integration Scenarios
Deal → delivery request. The deal in Bitrix24 moves to the "Transferred for shipment" stage — a webhook fires, the adapter creates a request in the logistics system. The request number (UF_LOGISTICS_ORDER_ID) and tracking number are written back to the deal card.
Delivery statuses in CRM. The logistics system sends a webhook when the status changes: "Accepted at warehouse", "In transit", "Delivered", "Return". The adapter updates the deal stage via crm.deal.update and adds a comment to the timeline via crm.timeline.comment.add.
Delivery cost calculation. At the order placement stage (in the deal or the online store) — a request to the carrier API to calculate cost by weight, dimensions, and address. The result goes into the deal or invoice field.
Pickup point selection. For integrations with CDEK, Boxberry, and Russian Post — a pickup point selection widget on a map inside the deal card. Implemented as a Bitrix24 embedded application with a map (Leaflet + pickup point data from the carrier API).
Returns. The customer initiates a return — a "Return" smart process is created in the CRM, which triggers a procedure in the logistics system: collection from the buyer, receipt at warehouse, item inspection status.
Adapter Architecture
We build a PHP application that:
- Listens for Bitrix24 webhooks (deal stage change event)
- Maps deal data to the logistics system format
- Calls the logistics API
- Writes the response back to Bitrix24
Bitrix24 (stage change webhook)
↓
Adapter (validation, data transformation)
↓
Logistics system API
↓ (async — via callback or polling)
Adapter (status processing)
↓
Bitrix24 REST API (crm.deal.update, crm.timeline.comment.add)
For reliability — a queue (Redis + worker process or Bitrix built-in agents). The webhook is received instantly; processing is asynchronous.
Field Mapping
Typical set of fields to pass to logistics:
| Bitrix24 field | Logistics field | Comment |
|---|---|---|
CONTACT.NAME + CONTACT.LAST_NAME |
recipient.name |
Recipient full name |
UF_DELIVERY_ADDRESS |
recipient.address |
Structured address or string |
UF_DELIVERY_PHONE |
recipient.phone |
Recipient phone number |
Deal products (crm.deal.productrows.get) |
cargo.items[] |
List of items, weight, dimensions |
UF_DELIVERY_TYPE |
service_code |
Delivery type (courier/pickup point) |
UF_PVZ_CODE |
to_location.code |
Pickup point code, if pickup was selected |
Weight and dimensions are a separate challenge. In Bitrix24 they are stored in the product card (catalogue), but in a CRM deal they are fetched from crm.product.list by PRODUCT_ID. If the warehouse or 1C integration is not configured, weight characteristics may be missing — a fallback is needed (default values by product category or manual entry).
Tracking and Customer Notifications
Once a tracking number is received, we build a notification chain. A Bitrix24 robot sends an SMS or email to the customer (via integration with a mailing service): "Your order has been handed over for delivery, tracking number: XXX." At each status change — the same. This reduces the load on the call centre and improves customer satisfaction.
For automatically receiving delivery statuses we use two approaches:
- Webhook from the carrier — the carrier notifies us when the status changes. The best option, but not supported by everyone.
- Polling — a Bitrix agent requests status every N minutes by tracking number. Works with any carrier but creates API load.
Exception Handling
Logistics APIs are unstable and have specific limitations:
- Request limits (rate limiting) — maintain delays between requests, cache reference data (pickup point list, rates)
- Address errors — the carrier cannot determine the delivery zone from the address. A UI is needed for manual correction with a manager notification
- Blocked requests — if logistics has blocked the request (incorrect data), the manager must see this in the CRM rather than hearing about it from the customer
Development Stages
| Stage | Content | Duration |
|---|---|---|
| Analysis | Carrier selection, scenarios, specification | 3–5 days |
| Adapter development | Core API connectors | 1–2 weeks |
| CRM integration | Fields, smart processes, automations | 1 week |
| Pickup point widget | Map with point selection | 3–5 days |
| Notifications | SMS/email by status | 3–5 days |
| Testing | Live requests in test environment | 1 week |
A finished integration reduces the time from deal placement to delivery request creation from several hours to seconds — and eliminates data entry errors for recipient details.