Integration of 1C-Bitrix with the delivery service Autolightexpress (Belarus)

Integrating 1C-Bitrix with AutoLightExpress Delivery Service (Belarus)

AutoLightExpress is a Belarusian courier service specializing in deliveries primarily in Minsk and major Belarusian cities. It focuses on same-day urgent courier delivery and intercity express shipments. Unlike Belpochta and Boxberry, speed is its priority rather than pickup point coverage. It is used for stores with fast delivery requirements.

AutoLightExpress API

The API is provided under contract. The interface is REST JSON, with authorization via an API key in the header or request parameter. Documentation is provided upon connection. Base URL: https://api.alexpress.by/v1/ (confirmed with the account manager upon connection).

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;
}

Cost calculation

AutoLightExpress calculates cost based on delivery zones. Minsk is one zone, other cities are different zones with a multiplying coefficient.

public function calcDeliveryCost(
    string $city,
    int $weightGram,
    bool $express = false
): float {
    $response = $this->apiRequest('POST', '/calculate', [
        'city'    => $city,
        'weight'  => $weightGram,
        'express' => $express, // same-day urgent delivery
    ]);

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

Two delivery services are created in 1C-Bitrix: "AutoLightExpress" (standard) and "AutoLightExpress Express" (same-day) — with different costs and delivery periods.

Creating a request

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'   => 'Goods from online store',
        ],
        'paymentType' => 'prepaid', // prepaid or cash on delivery
    ];

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

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

    return $orderId;
}

Limitation: Belarus addresses only

AutoLightExpress operates exclusively within Belarus. The delivery service class must restrict the coverage zone:

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

This prevents the service from being shown to customers with addresses outside Belarus.

Tracking

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

Polling via an agent 2–3 times per day for active shipments. For express orders — every hour during business hours.

Timelines