Інтеграція 1С-Бітрікс зі службою доставки Автолайтекспрес (Білорусь)

Інтеграція 1С-Бітрікс зі службою доставки АвтоЛайтЕкспрес (Білорусь)

АвтоЛайтЕкспрес — білоруська кур'єрська служба з доставкою переважно по Мінську та великих містах Білорусі. Спеціалізується на терміновій кур'єрській доставці день-в-день та міжміських експрес-відправленнях. На відміну від Белпошти та Boxberry, акцент робиться на швидкості, а не на охопленні ПВЗ. Використовується для магазинів з вимогами до швидкої доставки.

API АвтоЛайтЕкспрес

API надається за договором. Інтерфейс — REST JSON, авторизація через API-ключ у заголовку або параметрі запиту. Документація видається при підключенні. Базовий URL: https://api.alexpress.by/v1/ (уточнюється у менеджера при підключенні).

private function apiRequest(string $method, string $path, array $data = []): array
{
    $url = 'https://api.alexpress.by/v1' . $path;
    $ch = curl_init($method === 'GET' ? $url . '?' . http_build_query($data) : $url);

    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-Api-Key: ' . $this->getOption('API_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => $method !== 'GET' ? json_encode($data, JSON_UNESCAPED_UNICODE) : null,
    ]);

    $response = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $decoded = json_decode($response, true);
    if ($code >= 400 || ($decoded['success'] ?? true) === false) {
        throw new \RuntimeException('ALE API error: ' . ($decoded['message'] ?? $response));
    }

    return $decoded['data'] ?? $decoded;
}

Розрахунок вартості

АвтоЛайтЕкспрес розраховує вартість на основі зон доставки. Мінськ — одна зона, інші міста — інші зони з підвищувальним коефіцієнтом.

public function calcDeliveryCost(
    string $city,
    int $weightGram,
    bool $express = false
): float {
    $response = $this->apiRequest('POST', '/calculate', [
        'city'    => $city,
        'weight'  => $weightGram,
        'express' => $express, // термінова доставка день-в-день
    ]);

    return (float)($response['price'] ?? 0);
}

У 1С-Бітрікс створюються дві служби доставки: «АвтоЛайтЕкспрес» (стандарт) і «АвтоЛайтЕкспрес Експрес» (день-в-день) — з різною вартістю та терміном доставки.

Створення заявки

public function createPickup(\Bitrix\Sale\Shipment $shipment, bool $express = false): string
{
    $order = $shipment->getOrder();
    $props = $order->getPropertyCollection();

    $payload = [
        'externalOrderId' => (string)$order->getId(),
        'express'         => $express,
        'pickupDate'      => date('Y-m-d', strtotime($express ? 'today' : '+1 day')),
        'sender' => [
            'name'    => $this->getOption('SENDER_NAME'),
            'address' => $this->getOption('SENDER_ADDRESS'),
            'phone'   => $this->getOption('SENDER_PHONE'),
            'city'    => $this->getOption('SENDER_CITY'),
        ],
        'recipient' => [
            'name'    => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
            'phone'   => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
            'address' => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(),
            'city'    => $props->getItemByOrderPropertyCode('CITY')?->getValue(),
        ],
        'cargo' => [
            'weight'        => $this->getWeight($shipment),
            'declaredValue' => $order->getPrice(),
            'description'   => 'Товар з інтернет-магазину',
        ],
        'paymentType' => 'prepaid', // передоплата або накладений платіж
    ];

    $response = $this->apiRequest('POST', '/orders', $payload);
    $orderId = (string)($response['id'] ?? '');

    $props->getItemByOrderPropertyCode('ALE_ORDER_ID')?->setValue($orderId);
    $order->save();

    return $orderId;
}

Обмеження: тільки білоруські адреси

АвтоЛайтЕкспрес працює виключно по Білорусі. У класі служби доставки необхідно обмежити зону використання:

public function isCompatible(\Bitrix\Sale\Shipment $shipment): bool
{
    $location = $this->getShipmentLocation($shipment);
    $country = $this->getCountryByLocation($location);
    return $country === 'BY';
}

Це запобігає показу служби покупцям з адресами за межами Білорусі.

Трекінг

public function getStatus(string $orderId): string
{
    $response = $this->apiRequest('GET', '/orders/' . $orderId);
    return $response['status'] ?? '';
}

Polling агентом 2–3 рази на день для активних відправлень. Для експрес-замовлень — щогодини в робочий час.

Терміни