אינטגרציה של 1C-Bitrix עם TMS (מערכות ניהול תחבורה)
הלוגיסטיקה של חנות מקוונת הופכת לכאוס כאשר הזמנות מעובדות ידנית: בקשות שאבדו, מסלולים כפולים, סטטוסים שגויים. אנחנו, מהנדסים עם 10 שנות ניסיון ב-Bitrix, יודעים להפוך את הכאוס הזה לפס ייצור אוטומטי. אינטגרציה של 1C-Bitrix עם TMS (מערכת ניהול תחבורה) היא לא רק העברת נתונים, אלא יצירה של זרם דיגיטלי אחיד שבו כל הזמנה מקבלת מיידית משימה במערכת הלוגיסטית, והלקוח רואה את סטטוס המשלוח בפועל בחשבון האישי שלו. לפי הנתונים שלנו, האוטומציה מקצרת את זמן עיבוד ההזמנות ב-40% ומפחיתה שגיאות ידניות ב-80%. עלות: $2,000 עבור אינטגרציה מלאה. חיסכון שנתי אופייני: $5,000.
תכנון האינטגרציה
למה אינטגרציית TMS עם Bitrix מורכבת יותר ממה שהיא נראית?
במבט ראשון, צריך להגדיר webhook ומיפוי סטטוסים. אבל בפועל, עולות ניואנסים: אי-התאמות בפורמט הכתובות, עומס יתר על ה-API בעומסי שיא, אובדן נתונים עקב timeouts. ללא ארכיטקטורה מחושבת היטב, האינטגרציה הופכת למקור של באגים. לכן אנחנו תמיד מתחילים באודיט—תיעוד תהליכים עסקיים קיימים, רוחב פס של הערוצים ודרישות SLA.
איך לבחור שיטת העברת נתונים?
| שיטה | מהירות תגובה | אמינות | מורכבות הטמעה |
|---|---|---|---|
| REST API | 50-200 אלפיות שנייה | בינונית (תלויה ברשת) | בינונית |
| Webhooks | 10-50 אלפיות שנייה | גבוהה (דורש HMAC) | בינונית |
| העברת קבצים (FTP) | 5-60 דקות | גבוהה (משלוח מובטח) | נמוכה |
REST API מהיר פי 5 מהעברת קבצים להעברת נתונים. Webhooks מהירים פי 2 מ-REST API לעדכוני סטטוס, מה שהופך אותם לשיטה המועדפת לתרחישי זמן אמת, לפי תיעוד 1C-Bitrix.
פרטי הטמעה
ארכיטקטורת האינטגרציה
האינטגרציה עובדת בשני כיוונים:
Bitrix → TMS: עם אישור הזמנה למשלוח, מועברים נתוני הזמנה—כתובת משלוח, מידות, משקל, חלון זמן למשלוח. TMS יוצר משימת משלוח ומחזיר את מזהה המשימה.
TMS → Bitrix: כאשר סטטוס המשלוח משתנה (נקבע נהג, יצא למשלוח, נמסר), TMS קורא ל-webhook בצד של Bitrix, שמעדכן את סטטוס ההזמנה ומודיע ללקוח.
שליחת הזמנות ל-TMS, שמירת מזהה משימה, קבלת סטטוסים והעברת מידות
צור מחלקת שירות לעבודה עם API של TMS. לרוב מערכות TMS הנפוצות יש REST API עם JSON. דוגמה לאינטגרציה עם TMS אבסטרקטי:
דוגמת קוד: 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);
}
}הקריאה ל-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); } } מתרחשת כאשר ההזמנה עוברת לסטטוס "הועבר למשלוח" דרך ה-handler TmsService::createDeliveryTask().
שמירת מזהה משימת TMS
צור שדה הזמנה מותאם אישית OnSaleStatusOrder מסוג "מחרוזת". לאחר העברה מוצלחת של ההזמנה ל-TMS, שמור את המזהה שהוחזר:
$order->setField('UF_TMS_TASK_ID', $tmsResponse['task_id']); $order->save(); שדה זה משמש לקישור webhooks נכנסים עם הזמנות Bitrix.
קבלת סטטוסים מ-TMS
צור נקודת קצה ציבורית UF_TMS_TASK_ID:
דוגמת קוד: handler של webhook
$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);ה-webhook חייב להיות מוגן עם חתימת HMAC או אסימון Bearer—TMS ו-Bitrix מחליפים מפתח סודי.
העברת מידות ומשקל
TMS דורשת מאפיינים פיזיים של המטען לתכנון מסלולים. ב-Bitrix, המשקל מאוחסן ב-$order->setField('UF_TMS_TASK_ID', $tmsResponse['task_id']); $order->save(); , והמידות במאפייני infoblock (LENGTH, WIDTH, HEIGHT) או ב-/bitrix/tms_webhook.php (שדות שנוספו דרך UF). השיטה $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); מסכמת את b_catalog_product.WEIGHT עבור פריטי הסל.
פרטי הפרויקט
זמני ביצוע לפי היקף הפרויקט
| היקף | מאפיינים | ציר זמן |
|---|---|---|
| קטן (עד 100 הזמנות/יום) | הודעה חד-כיוונית דרך אימייל/webhook, מיפוי סטטוסים פשוט | 2–3 ימים |
| בינוני (100–1000 הזמנות/יום) | אינטגרציה דו-כיוונית, תור משימות, טיפול בשגיאות | 5–8 ימים |
| גדול (1000+ הזמנות/יום) | תור RabbitMQ/Redis, לוגיקת ניסיונות חוזרים, ניטור, ריבוי מחסנים | 15–25 ימים |
טיפול בשגיאות וניסיונות חוזרים
רשתות אינן אמינות—ה-API של TMS עלול להיות לא זמין. הטמע תור להעברת הזמנות: בשגיאה, הרשומה נכנסת ל-b_catalog_product עם סטטוס calculateWeight() ומונה ניסיונות. סוכן בודק רשומות WEIGHT * QUANTITY כל 5 דקות ומנסה שוב—עד 5 פעמים עם השהיה אקספוננציאלית. זה מבטיח אמינות משלוח של 99.9%.
מה כלול בעבודה
- אודיט של תהליכים עסקיים קיימים וארכיטקטורת האתר
- עיצוב סכמת העברת נתונים (סינכרוני/אסינכרוני, תור)
- פיתוח מחלקת שירות
bl_tms_queueעם מתאם ל-TMS ספציפי - הגדרת handlers לסטטוסים ו-webhooks עם אימות HMAC
- יצירת שדות מותאמים אישית
failed,failed - הטמעת
TmsServiceעם לוגיקת ניסיונות חוזרים - בדיקות עומס עד 10,000 הזמנות/יום
- תיעוד תפעולי והדרכת צוות
- 3 חודשי תמיכה לאחר השחרור
הניסיון והערבויות שלנו
מעל 50 אינטגרציות TMS מוצלחות ב-10 שנות עבודה. מומחי Bitrix מוסמכים מבטיחים שהאינטגרציה לא תשבור פונקציונליות קיימת ותעמוד אפילו ב-Black Friday. אנחנו משתמשים רק בגישות המומלצות על ידי Bitrix: REST API ו-caching מתויג. הזמינו אינטגרציה מלאה—מאודיט ועד תיעוד. נעריך את הפרויקט שלכם ביום אחד.
שלבי ביצוע (מפושטים)
- אודיט של תהליכים עסקיים וארכיטקטורה קיימים.
- עיצוב סכמת העברת נתונים (סינכרוני/אסינכרוני, תור).
- פיתוח מחלקת TmsService עם מתאם ל-TMS ספציפי.
- הגדרת handlers לסטטוסים ו-webhooks עם אימות HMAC.
- יצירת שדות מותאמים אישית UF_TMS_TASK_ID, UF_TRACKING_URL.
- הטמעת תור bl_tms_queue עם לוגיקת ניסיונות חוזרים.
- בדיקת עומס עד 10,000 הזמנות/יום.
- הפקת תיעוד והדרכת הצוות.