Интеграция 1С-Битрикс со службой доставки Деловые Линии

Интеграция 1С-Битрикс со службой доставки Деловые Линии

Деловые Линии — крупная транспортная компания с терминальной сетью по всей России. Как и ПЭК, специализируется на грузовых перевозках: от небольших посылок до паллетных отправлений. Характерная особенность — в ряде регионов единственная альтернатива Почте России для доставки с нормальными сроками в промышленные центры.

API Деловых Линий — REST с JWT-авторизацией. Документация на русском, покрывает основные операции.

API Деловых Линий: структура

Базовый URL: https://api.dellin.ru/v3/. Авторизация двухэтапная: сначала получаем session token через /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);
}

Параметр delivery.dispatch.variant: terminal означает, что магазин сам привезёт груз на терминал. arrival.variant: address — доставка покупателю до двери. Комбинации variant влияют на цену: терминал-терминал дешевле, адрес-адрес дороже.

Поиск терминала по городу

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'] ?? '');
}

Параметр payment.payer: receiver — доставку оплачивает получатель. sender — отправитель (магазин). Выбор зависит от бизнес-модели магазина.

Трекинг заказов

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'] ?? '',
    ];
}

Деловые Линии не поддерживают вебхуки для трекинга. Агент Битрикс раз в 3–4 часа опрашивает статус активных отправлений.

Особенности для крупногабаритных товаров

Деловые Линии поддерживают паллетные отправления. Для магазинов мебели или строительных материалов нужно разделять отправления на несколько мест с индивидуальными габаритами. Поле cargo.oversizedWeight используется для нестандартных мест (> 80 кг или > 3 м в длину).

Сроки