Интеграция 1С-Битрикс со службой доставки СДЭК Беларусь

Интеграция 1С-Битрикс со службой доставки СДЭК Беларусь

СДЭК работает в Беларуси через белорусское юридическое лицо — ООО «СДЭК-БЕЛ». С точки зрения технической интеграции это тот же API СДЭК v2, что и для России, но с рядом отличий: белорусские маршруты, местные тарифы, расчёт в белорусских рублях, и требования белорусского законодательства к документообороту.

Отличия СДЭК Беларусь от РФ

Технически API идентичен: https://api.cdek.ru/v2, та же OAuth 2.0, те же эндпоинты. Разница в конфигурации:

• from_location должен содержать код белорусского города СДЭК
• Тарифные коды могут отличаться от российских — уточнять в личном кабинете партнёра
• Валюта расчёта — белорусский рубль (BYN)
• Документы: накладная СДЭК + товарно-транспортная накладная (ТТН) по форме ТТН-1 для перевозки внутри Беларуси

Инициализация клиента

class CdekByHandler extends \Bitrix\Sale\Delivery\Services\Base
{
    private function getApiClient(): CdekApiClient
    {
        // Белорусские credentials из личного кабинета СДЭК-БЕЛ
        return new CdekApiClient(
            clientId:     $this->getOption('CLIENT_ID_BY'),
            clientSecret: $this->getOption('CLIENT_SECRET_BY'),
            apiUrl:       'https://api.cdek.ru/v2', // URL тот же
            testMode:     (bool)$this->getOption('TEST_MODE')
        );
    }

    protected function calculateConcrete(
        \Bitrix\Sale\Shipment $shipment
    ): \Bitrix\Sale\Delivery\CalculationResult {
        $result = new \Bitrix\Sale\Delivery\CalculationResult();
        $client = $this->getApiClient();

        $toCode = $this->getByLocationCode($shipment);
        if (!$toCode) {
            $result->addError(new \Bitrix\Main\Error('Город не найден в базе СДЭК'));
            return $result;
        }

        $tariff = $client->calculateTariff([
            'tariff_code'   => (int)$this->getOption('TARIFF_CODE_BY', 136),
            'from_location' => ['code' => $this->getOption('FROM_LOCATION_CODE_BY')],
            'to_location'   => ['code' => $toCode],
            'packages'      => [[
                'weight' => max($shipment->getWeight(), 100),
                'length' => (int)$this->getOption('DEFAULT_LENGTH', 20),
                'width'  => (int)$this->getOption('DEFAULT_WIDTH', 20),
                'height' => (int)$this->getOption('DEFAULT_HEIGHT', 20),
            ]],
        ]);

        $result->setDeliveryPrice($tariff['total_sum']);
        $result->setPeriodDescription($tariff['period_min'] . '–' . $tariff['period_max'] . ' рабочих дней');

        return $result;
    }
}

ПВЗ СДЭК в Беларуси

Список ПВЗ запрашивается стандартно через GET /v2/deliverypoints?country_codes=BY. СДЭК предоставляет официальный JavaScript-виджет для выбора ПВЗ на карте — он корректно работает для белорусских точек.

public function getBelarusOfficePoints(): array
{
    $cache = \Bitrix\Main\Data\Cache::createInstance();

    if ($cache->initCache(3600 * 6, 'cdek_pvz_by', '/cdek/')) {
        return $cache->getVars();
    }

    $points = $this->getApiClient()->getDeliveryPoints([
        'country_codes' => 'BY',
        'have_cashless'  => true,
    ]);

    $cache->startDataCache();
    $cache->endDataCache($points);

    return $points;
}

ТТН-1 для белорусского рынка

При внутрибелорусских перевозках законодательство требует оформления ТТН-1. СДЭК-БЕЛ может формировать этот документ — уточняйте условия в договоре. При необходимости самостоятельного формирования ТТН-1 интегрируем генерацию PDF с данными заказа и отправления.

Кейс

Магазин электроники с основной аудиторией в Беларуси, использует СДЭК для доставки по стране и в Россию. Проблема: один обработчик доставки показывал российские тарифы для белорусских заказов. Решение: разделили на два отдельных обработчика — CdekRuHandler и CdekByHandler, каждый со своими credentials и кодами локаций. Переключение происходит автоматически по стране из адреса доставки.

Сроки