Integration of 1C-Bitrix with the delivery service SDEK Belarus

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

CDEK operates in Belarus through a local representative office using the same infrastructure and API v2 as in Russia. The key differences when integrating for Belarusian stores are: the currency is the Belarusian ruble (BYN), location codes differ, VAT is 20%, and calculations must account for different tariffs for domestic Belarusian and cross-border shipments.

CDEK API for Belarus: the same, but different

Technically the API is identical to the Russian one: the same endpoints, the same OAuth 2.0, the same request structure. The base URL is the same: https://api.cdek.ru/v2/ (CDEK uses a unified API for all countries). However, when registering in the personal account you need a Belarusian account — client_id and client_secret from a Belarusian contract.

The key difference in calculations: city codes (cityId and code in location) for Belarus differ from Russian ones. Minsk in the CDEK database is not Moscow.

// Get the Minsk city code
$response = $this->apiGet('/v2/location/cities', [
    'country_codes' => ['BY'],
    'city'          => 'Минск',
]);
// $response[0]['code'] — code to use in requests

Calculating costs for domestic Belarusian shipments

protected function calculateConcrete(
    \Bitrix\Sale\Shipment $shipment
): \Bitrix\Sale\Delivery\CalculationResult {
    $result = new \Bitrix\Sale\Delivery\CalculationResult();

    $toCode = $this->getLocationCode($shipment, 'BY');
    if (!$toCode) {
        $result->addError(new \Bitrix\Main\Error('Location not determined'));
        return $result;
    }

    $payload = [
        'type'          => 1,
        'tariff_code'   => 136,
        'from_location' => ['code' => $this->getOption('FROM_LOCATION_CODE')],
        'to_location'   => ['code' => $toCode],
        'packages'      => [[
            'weight' => max($this->getShipmentWeight($shipment), 100),
            'length' => 20,
            'width'  => 20,
            'height' => 20,
        ]],
        'currency'      => 'BYR', // Belarusian ruble
    ];

    $response = $this->apiPost('/v2/calculator/tariff', $payload);

    if (isset($response['errors'])) {
        $result->addError(new \Bitrix\Main\Error($response['errors'][0]['message']));
        return $result;
    }

    $result->setDeliveryPrice((float)$response['total_sum']);
    $result->setPeriodDescription('1–3 days');
    return $result;
}

The currency: BYR parameter ensures the cost is returned in Belarusian rubles and not converted to Russian rubles.

Creating a CDEK order for Belarus

public function createByCdekOrder(\Bitrix\Sale\Shipment $shipment): string
{
    $order = $shipment->getOrder();
    $props = $order->getPropertyCollection();

    // Check: domestic Belarusian delivery or cross-border
    $country = $this->getRecipientCountry($props);
    $tariffCode = $country === 'BY' ? 136 : 137; // 137 - international

    $payload = [
        'type'         => 1,
        'number'       => (string)$order->getId(),
        'tariff_code'  => $tariffCode,
        'from_location' => $this->getFromLocation(),
        'to_location'  => $this->getToLocation($props),
        'recipient'    => [
            'name'   => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
            'phones' => [['number' => $props->getItemByOrderPropertyCode('PHONE')?->getValue()]],
        ],
        'packages'     => $this->buildPackages($shipment),
        'services'     => $this->getAdditionalServices($order),
    ];

    $response = $this->apiPost('/v2/orders', $payload);
    return $response['entity']['uuid'] ?? '';
}

CDEK pickup points in Belarus

Pickup point selection works through the same JavaScript CDEK widget as for Russia. Specify the country when initializing:

window.CDEKWidget.create({
    apiKey: 'YOUR_API_KEY',
    defaultLocation: 'Минск',
    lang: 'rus',
    currency: 'BYR',
    onReady: function() {
        // Widget ready
    },
    onChoose: function(type, tariff, address) {
        document.getElementById('cdek_pvz_code').value = address.code;
    }
});

VAT and customs

For cross-border shipments from Russia to Belarus (or vice versa), a customs declaration must be completed. In the POST /v2/orders request for international tariffs, a seller block with seller information and a packages[].items array with content descriptions, prices, and HS codes are added. This is an EAEU requirement — without a declaration the parcel will be held at customs.

Statuses and webhooks

Fully analogous to the Russian integration. Webhooks are configured in the CDEK personal account — the URL is the same, status mapping is identical. If the store is already integrated with CDEK Russia, the Belarusian representative office is set up as a second delivery service with separate client_id/client_secret and a different FROM_LOCATION_CODE.

Timelines