Інтеграція 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'] ?? '',
    ];
}

Ділові Лінії не підтримують вебхуки для трекінгу. Агент 1С-Бітрікс раз на 3–4 години опитує статус активних відправлень.

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

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

Терміни