שילוב 1C-Bitrix עם שירות המשלוחים Business Lines

תארו לעצמכם: מנהל חנות מקוונת ממלא ידנית נתוני משלוח בחשבון האישי של Business Lines. הזמנה אחת אורכת עד 15 דקות. עם 50 הזמנות ביום — זה יותר מ-12 שעות של שגרה טהורה. שגיאות בכתובות, סטטוסים שאבדו, מיון שגוי לפי מידות — תמונה אופיינית ללא אינטגרציית API. אנו הופכים תהליך זה לאוטומטי: חישוב עלות, יצירת הזמנה ומעקב באמצעות REST API של Business Lines. לקוח אחד — חנות רהיטים — לאחר ההטמעה צמצם את זמן עיבוד ההזמנה מ-15 ל-2 דקות והוריד את עלויות התפעול הלוגיסטיות ב-15%. חיסכון משמעותי בעלויות עבודה ידנית.

מדוע אוטומציה של משלוחים באמצעות API חשובה

ללא אינטגרציה, חנויות מבזבזות עד 20% מזמן העבודה על עיבוד משלוחים ידני. Business Lines היא חברת התחבורה הגדולה ביותר עם רשת של למעלה מ-2000 טרמינלים. ה-API שלהם עם אימות JWT מאפשר ניהול גמיש של משלוחים. השלמנו למעלה מ-30 פרויקטים של אינטגרציה של 1C-Bitrix עם חברות תחבורה, תוך הבטחת פעילות יציבה ועדכונים כאשר ה-API משתנה. קראו עוד על הפרוטוקול בתיעוד הרשמי של REST API של Business Lines.

כיצד לאוטמט משלוחים באמצעות אינטגרציה עם Business Lines?

כיצד בנוי ה-API של Business Lines? — אינטגרציית 1C-Bitrix

כתובת בסיס: https://api.dellin.ru/v3/. האימות הוא דו-שלבי: ראשית קבלו טוקן סשן דרך /v3/auth/login.json, לאחר מכן השתמשו בו בכותרת Cookie: session=TOKEN או כפרמטר.

private function getSession(): string {
    $cacheKey = 'dellin_session_' . md5($this->appKey);
    $cached = \Bitrix\Main\Data\Cache::createInstance();
    if ($cached->startDataCache(3600 * 8, $cacheKey, '/dellin')) {
        $response = $this->httpPost('/v3/auth/login.json', [
            'appkey' => $this->appKey,
            'login' => $this->login,
            'password' => $this->password,
        ]);
        $session = $response['data']['sessionID'] ?? '';
        $cached->endDataCache(['session' => $session]);
    }
    return $cached->getVars()['session'];
}

הסשן חי 8+ שעות. שמרו אותו במטמון למשך 8 שעות כדי להימנע מאימות בכל חישוב. דוגמה לבקשת חישוב עלות:

private function calcCost( string $fromCity, string $toCity, float $weightKg, float $volumeM3 ): float {
    $response = $this->apiPost('/v3/calculator.json', [
        'appkey' => $this->appKey,
        'sessionID' => $this->getSession(),
        'delivery' => [
            'deliveryType' => ['type' => 'auto'],
            'arrival' => ['variant' => 'address'],
            'dispatch' => ['variant' => 'terminal'],
        ],
        'cargo' => [
            'quantity' => 1,
            'weight' => $weightKg,
            'volume' => $volumeM3,
            'totalEnvelopesWeight' => 0,
        ],
        'members' => [
            'from' => ['terminalID' => $this->findTerminalId($fromCity)],
            'to' => ['city' => $toCity],
        ],
    ]);
    return (float)($response['data']['price'] ?? 0);
}

הפרמטר private function getSession(): string { $cacheKey = 'dellin_session_' . md5($this->appKey); $cached = \Bitrix\Main\Data\Cache::createInstance(); if ($cached->startDataCache(3600 * 8, $cacheKey, '/dellin')) { $response = $this->httpPost('/v3/auth/login.json', [ 'appkey' => $this->appKey, 'login' => $this->login, 'password' => $this->password, ]); $session = $response['data']['sessionID'] ?? ''; $cached->endDataCache(['session' => $session]); } return $cached->getVars()['session']; } פירושו שהחנות עצמה מביאה את המטען לטרמינל. private function calcCost( string $fromCity, string $toCity, float $weightKg, float $volumeM3 ): float { $response = $this->apiPost('/v3/calculator.json', [ 'appkey' => $this->appKey, 'sessionID' => $this->getSession(), 'delivery' => [ 'deliveryType' => ['type' => 'auto'], 'arrival' => ['variant' => 'address'], 'dispatch' => ['variant' => 'terminal'], ], 'cargo' => [ 'quantity' => 1, 'weight' => $weightKg, 'volume' => $volumeM3, 'totalEnvelopesWeight' => 0, ], 'members' => [ 'from' => ['terminalID' => $this->findTerminalId($fromCity)], 'to' => ['city' => $toCity], ], ]); return (float)($response['data']['price'] ?? 0); } — משלוח עד דלת הקונה. שילובי וריאנטים משפיעים על המחיר: טרמינל-טרמינל זול יותר, כתובת-כתובת יקר יותר.

חיפוש טרמינל לפי עיר

public function findTerminalId(string $cityName): string {
    $response = $this->apiPost('/v3/public/terminals.json', [
        'appkey' => $this->appKey,
    ]);
    foreach ($response['data']['terminals'] ?? [] as $terminal) {
        if (mb_stripos($terminal['city']['name'], $cityName) !== false) {
            return $terminal['id'];
        }
    }
    return '';
}

רשימת הטרמינלים גדולה — שמרו את תוצאת החיפוש במטמון למשך יום.

יצירת הזמנה

public function createOrder(\Bitrix\Sale\Shipment $shipment): string {
    $order = $shipment->getOrder();
    $props = $order->getPropertyCollection();
    $payload = [
        'appkey' => $this->appKey,
        'sessionID' => $this->getSession(),
        'delivery' => [
            'deliveryType' => ['type' => 'auto'],
            'dispatch' => ['variant' => 'terminal'],
            'arrival' => [
                'variant' => 'address',
                'address' => [
                    'search' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(),
                ],
            ],
        ],
        'cargo' => $this->buildCargo($shipment),
        'members' => [
            'from' => ['terminalID' => $this->getOption('FROM_TERMINAL_ID')],
            'to' => [
                'contactPersons' => [[
                    'name' => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
                    'phone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
                ]],
            ],
        ],
        'payment' => [
            'type' => 'cash',
            'payer' => 'receiver',
        ],
    ];
    $response = $this->apiPost('/v3/orders.json', $payload);
    return (string)($response['data']['orderID'] ?? '');
}

הפרמטר delivery.dispatch.variant: terminal פירושו שהמשלוח משולם על ידי הנמען. arrival.variant: address — על ידי השולח (החנות). הבחירה תלויה במודל העסקי של החנות.

מעקב אחר הזמנה

public function getOrderState(string $orderId): array
{
    $response = $this->apiPost('/v3/orders/state.json', [
        'appkey' => $this->appKey,
        'sessionID' => $this->getSession(),
        'orders' => [['orderID' => $orderId]],
    ]);

    $state = $response['data'][0] ?? [];

    return [
        'status' => $state['orderState']['name'] ?? '',
        'deliveryDate' => $state['deliveryDate'] ?? '',
    ];
}

Business Lines אינה תומכת ב-webhooks למעקב. סוכן Bitrix בודק את הסטטוס של משלוחים פעילים כל 3–4 שעות.

מהן השיקולים המיוחדים למטען חריג?

Business Lines תומכת במשלוחי משטחים. עבור חנויות רהיטים או חומרי בניין, יש לפצל משלוחים למספר חלקים עם מידות אישיות. השדה public function findTerminalId(string $cityName): string { $response = $this->apiPost('/v3/public/terminals.json', [ 'appkey' => $this->appKey, ]); foreach ($response['data']['terminals'] ?? [] as $terminal) { if (mb_stripos($terminal['city']['name'], $cityName) !== false) { return $terminal['id']; } } return ''; } משמש לחלקים לא סטנדרטיים (>80 ק"ג או >3 מ' אורך). בפרויקט אחד לחנות רהיטים מקוונת, נתקלנו בבעיה בחישוב מידות שגוי: סחורה הגיעה פגומה. לאחר הטמעת אינטגרציה עם פרמטרים של public function createOrder(\Bitrix\Sale\Shipment $shipment): string { $order = $shipment->getOrder(); $props = $order->getPropertyCollection(); $payload = [ 'appkey' => $this->appKey, 'sessionID' => $this->getSession(), 'delivery' => [ 'deliveryType' => ['type' => 'auto'], 'dispatch' => ['variant' => 'terminal'], 'arrival' => [ 'variant' => 'address', 'address' => [ 'search' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(), ], ], ], 'cargo' => $this->buildCargo($shipment), 'members' => [ 'from' => ['terminalID' => $this->getOption('FROM_TERMINAL_ID')], 'to' => [ 'contactPersons' => [[ 'name' => $props->getItemByOrderPropertyCode('FIO')?->getValue(), 'phone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(), ]], ], ], 'payment' => [ 'type' => 'cash', 'payer' => 'receiver', ], ]; $response = $this->apiPost('/v3/orders.json', $payload); return (string)($response['data']['orderID'] ?? ''); } וקיבוץ משטחים, מספר ההחזרות ירד ב-15%.

כיצד תהליך האינטגרציה עובד: שלב אחר שלב

1. ניתוח — אנו לומדים את הקטלוג שלכם, סוגי המשלוחים, הגדרות 1C-Bitrix.
2. עיצוב — אנו בוחרים שיטות API, מגדירים מיפוי שדות.
3. הטמעה — אנו כותבים קוד לחישוב, יצירת הזמנות, מעקב.
4. בדיקות — אנו בודקים על הזמנות לדוגמה, מודדים זמן תגובה.
5. פריסה — אנו מעלים לסביבת הייצור, מגדירים סוכנים.
6. תיעוד והדרכה — אנו מספקים הוראות, מאמנים מנהלים.

מה כלול בעבודת האינטגרציה?

• רישום אפליקציה בחשבון האישי של Business Lines.
• הגדרת אימות ושמירת סשן במטמון.
• הטמעת חישוב עלות בעמוד העגלה.
• יצירת הזמנות מלוח הניהול.
• מעקב עם התראות על שינוי סטטוס.
• תמיכה טכנית למשך 30 יום לאחר ההשקה.

כמה זמן אורכת אינטגרציה?

מהן הטעויות האופייניות שנעשות במהלך אינטגרציה?