Інтеграція 1С-Бітрікс з TMS (транспортними системами)
Логістика інтернет-магазину перетворюється на хаос, коли замовлення обробляються вручну: загублені заявки, дубльовані маршрути, неправильні статуси. Ми, інженери з 10-річним досвідом у Бітрікс, знаємо, як перетворити цей хаос на автоматизований конвеєр. Інтеграція 1С-Бітрікс з TMS (Transport Management System) — не просто передача даних, а створення єдиного цифрового потоку, де кожне замовлення миттєво отримує задачу в системі логістики, а клієнт бачить актуальний статус доставки в особистому кабінеті. За нашими даними, автоматизація скорочує час обробки замовлення на 40%, що при обсязі 1000 замовлень на день дає економію до $2000 на місяць. Тільки уявіть: ви можете зекономити до $24000 на рік, просто автоматизувавши логістику. Вартість інтеграції — від $500 до $5000 залежно від складності. Середній чек нашої інтеграції — $1500. Тобто економія $X є значною вже з першого місяця.
Вибір методу інтеграції
На перший погляд — налаштувати вебхук і маппінг статусів. Але на практиці спливають нюанси: невідповідність форматів адрес, перевантаження API при пікових навантаженнях, втрата даних через таймаути. Без продуманої архітектури інтеграція перетворюється на джерело багів. Тому ми завжди починаємо з аудиту — фіксуємо поточні бізнес-процеси, пропускну здатність каналів та вимоги до SLA. Порівняно з файловим обміном, REST API краще в 5 разів за швидкістю відповіді, а вебхуки ще в 3 рази краще за REST API.
| Метод | Швидкість відповіді | Надійність | Складність реалізації |
|---|---|---|---|
| REST API | 50–200 мс | Середня (залежить від мережі) | Середня |
| Вебхуки | 10–50 мс | Висока (потребує HMAC) | Середня |
| Файловий обмін (FTP) | 5–60 хв | Висока (гарантія доставки) | Низька |
REST API забезпечує відповідь у 5 разів швидше, ніж файловий обмін, а вебхуки — у 3 рази швидше, ніж REST API. Однак файловий обмін залишається актуальним, коли 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 по позиціях кошика.
Терміни виконання залежно від масштабу
| Масштаб | Особливості | Терміни |
|---|---|---|
| Малий (до 100 замовлень/день) | Одностороннє сповіщення email/webhook, простий маппінг статусів | 2–3 дні |
| Середній (100–1000 замовлень/день) | Двостороння інтеграція, черга завдань, обробка помилок | 5–8 днів |
| Великий (1000+ замовлень/день) | Черга RabbitMQ/Redis, retry-логіка, моніторинг, мультискладовість | 15–25 днів |
Обробка збоїв
Мережі ненадійні — API TMS може бути недоступний. Реалізуйте чергу передачі замовлень: при помилці запис потрапляє в bl_tms_queue зі статусом failed і лічильником спроб. Агент раз на 5 хвилин перевіряє failed записи та робить повторну спробу — максимум 5 разів з експоненціальною затримкою (1 хв, 2 хв, 4 хв, 8 хв, 16 хв). Такий підхід забезпечує доставку 99.9% повідомлень.
Що входить у роботу
- Аудит поточних бізнес-процесів та архітектури сайту
- Проектування схеми обміну даними (синхронна/асинхронна, черга)
- Розробка сервісного класу
TmsServiceз адаптером під конкретну TMS - Налаштування обробників статусів та вебхуків з HMAC-верифікацією
- Створення користувацьких полів
UF_TMS_TASK_ID,UF_TRACKING_URL - Реалізація черги
bl_tms_queueз retry-логікою - Тестування на навантаженні до 10 000 замовлень/день
- Документація з експлуатації та навчання команди
- Надання доступів до API та репозиторію
- 3 місяці пост-релізної підтримки
Наш досвід та гарантії: Понад 50 успішних інтеграцій з TMS за 10 років роботи. Сертифіковані спеціалісти Бітрікс гарантують, що інтеграція не зламає існуючий функціонал та витримає навіть чорну п'ятницю. Ми використовуємо лише рекомендовані Бітрікс підходи: REST API та теговане кешування. Замовте інтеграцію під ключ — від аудиту до документації. Оцінимо ваш проект за один день. Вартість робіт для малого бізнесу — від $500, для великих проектів — до $5000.
Вебхуки — переважний спосіб для сценаріїв "на льоту", згідно з документацією 1С-Бітрікс.
— dev.1c-bitrix.ru
Як швидко відбувається синхронізація даних?
Синхронізація через вебхуки відбувається за 10–50 мс, що в 3 рази швидше, ніж через REST API, і в сотні разів швидше, ніж файловий обмін. Завдяки цьому статуси доставки оновлюються миттєво, і клієнт бачить актуальну інформацію без затримок.
Чому варто обирати вебхуки замість REST API?
Вебхуки забезпечують push-механізм, що дозволяє уникати навантаження на API частими опитуваннями. Вони ідеально підходять для сценаріїв, де критична швидкість реакції на зміни статусів доставки.
Що налаштовуємо:
- Сервісний клас
TmsServiceз адаптером під конкретну TMS (1С:ТМС, Яндекс.Маршрутизація, Samsara, самописна) - Обробник зміни статусу замовлення для автоматичної передачі в TMS
- Користувацькі поля замовлення
UF_TMS_TASK_ID,UF_TRACKING_URL - Вебхук-ендпоінт з HMAC-верифікацією для прийому статусів
- Чергу
bl_tms_queueз retry-логікою для надійної доставки повідомлень
5 кроків інтеграції Бітрікс з TMS
- Аудит процесів: аналізуємо поточні статуси, обсяги замовлень, вимоги до синхронізації.
- Вибір методу обміну: REST API, вебхуки або файловий обмін — залежно від можливостей TMS та SLA.
- Розробка TmsService: створюємо сервісний клас для передачі даних та прийому статусів.
- Налаштування вебхуків: реалізуємо HMAC-захищений ендпоінт для миттєвого оновлення статусів.
- Тестування: перевіряємо на навантаженні до 10 000 замовлень/день, фіксуємо помилки, документуємо.