Інтеграція 1С-Бітрікс зі службою доставки СДЕК Білорусь

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

СДЕК працює в Білорусі через місцеве представництво з тією самою інфраструктурою та тим самим API v2, що і в Росії. Принципові відмінності при інтеграції для білоруських магазинів: валюта — білоруський рубль (BYN), коди локацій інші, ПДВ 20%, і при розрахунках потрібно враховувати різні тарифи для внутрішньобілоруських і транскордонних відправлень.

API СДЕК для Білорусі: те саме, але інше

Технічно API ідентичне російському: ті самі ендпоінти, той самий OAuth 2.0, та сама структура запитів. Базовий URL той самий: https://api.cdek.ru/v2/ (СДЕК використовує єдиний API для всіх країн). Але при реєстрації в особистому кабінеті потрібен білоруський акаунт — client_id і client_secret від білоруського договору.

Ключова відмінність при розрахунку: коди міст (cityId і code у location) для Білорусі відрізняються від російських. Мінськ у базі СДЕК — це не Москва.

// Отримуємо код Мінська
$response = $this->apiGet('/v2/location/cities', [
    'country_codes' => ['BY'],
    'city'          => 'Минск',
]);
// $response[0]['code'] — код для використання в запитах

Розрахунок для внутрішньобілоруських відправлень

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('Місцезнаходження не визначено'));
        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', // білоруський рубль
    ];

    $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 дні');
    return $result;
}

Параметр currency: BYR гарантує, що вартість повернеться в білоруських рублях, а не перерахується в російські.

Створення замовлення СДЕК для Білорусі

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

    // Перевіряємо: доставка в Білорусі або транскордонна
    $country = $this->getRecipientCountry($props);
    $tariffCode = $country === 'BY' ? 136 : 137; // 137 - міжнародний

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

ПВЗ СДЕК у Білорусі

Вибір ПВЗ працює через той самий JavaScript-віджет СДЕК, що і для Росії. При ініціалізації вказуємо країну:

window.CDEKWidget.create({
    apiKey: 'YOUR_API_KEY',
    defaultLocation: 'Минск',
    lang: 'rus',
    currency: 'BYR',
    onReady: function() {
        // Віджет готовий
    },
    onChoose: function(type, tariff, address) {
        document.getElementById('cdek_pvz_code').value = address.code;
    }
});

ПДВ і митниця

Для транскордонних відправлень з Росії до Білорусі (або навпаки) необхідно заповнювати митну декларацію. У запиті POST /v2/orders для міжнародних тарифів додається блок seller з даними продавця та масив packages[].items з описом вмісту, цінами та кодами УКТ ЗЕД. Це вимога ЄАЕС — без декларації посилка затримається на митниці.

Статуси та вебхуки

Повністю аналогічно російській інтеграції. Вебхуки налаштовуються в особистому кабінеті СДЕК — URL той самий, маппінг статусів ідентичний. Якщо магазин вже інтегровано з СДЕК Росія, білоруське представництво налаштовується як друга служба доставки з окремими client_id/client_secret та іншим FROM_LOCATION_CODE.

Терміни