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

Если ваш магазин на Битрикс доставляет в Беларусь через СДЭК, вы уже сталкивались с сюрпризом: российские тарифы, неверный расчёт в BYN, отсутствие ТТН-1. Мы настроили десятки таких интеграций и знаем, где подвох. СДЭК работает в Беларуси через белорусское юрлицо — ООО «СДЭК-БЕЛ». API тот же v2, но конфигурация принципиально другая: коды локаций, тарифы, валюта и юридические документы. Разберём технические отличия и готовое решение для Битрикс. В среднем неправильная настройка обработчика доставки приводит к расхождению цены на 20–30% и задержкам в обработке заказов до 2 дней.

Чем интеграция СДЭК Беларусь отличается от российской?

Технически API идентичен: https://api.cdek.ru/v2, та же OAuth 2.0, те же эндпоинты. Но есть ключевые различия, которые необходимо учитывать:

Для работы с белорусским API необходимо получить отдельные учетные данные в личном кабинете СДЭК-БЕЛ. Без этого все запросы будут отклонены с ошибкой 401. Также важно учитывать, что при обмене с 1С через CommerceML используются отдельные справочники номенклатуры для Беларуси.

Почему единый обработчик доставки не подходит?

Если использовать один CdekRuHandler для всех заказов, для белорусских адресов он применит российские тарифы и валюту. В результате клиент из Минска увидит стоимость в долларах РФ, а реальная цена будет в BYN — расхождение до 30%. Мы сталкивались с проектами, где из-за единого обработчика клиенты получали счета в долларах РФ вместо BYN, и перерасчёт занимал несколько дней. Наша реализация с двумя обработчиками позволяет избежать этого. Переключение происходит автоматически по стране из адреса доставки через событие OnBeforeCalculate.

Как настроить обработчик для Беларуси?

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

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',
            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-виджет для выбора на карте — он корректно работает для белорусских точек. Данные кешируются на 6 часов для ускорения загрузки.

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. СДЭК-БЕЛ может формировать её автоматически — уточните условия в договоре. Если нужна самостоятельная генерация, мы интегрируем формирование PDF с данными заказа и отправления. На практике игнорирование ТТН-1 приводит к штрафам до 20 базовых величин при проверках. Наша реализация автоматизирует формирование документа, экономя до 40% времени менеджеров.

Кейс из нашей практики

Один из клиентов — магазин электроники с аудиторией в Беларуси и России — использовал единый обработчик. Проблема: российские тарифы для белорусских заказов, путаница с BYN. Решение: два отдельных обработчика CdekRuHandler и CdekByHandler, переключение по стране через OnBeforeCalculate. Результат: корректные тарифы в BYN, ТТН-1 формируется, скорость обработки заказов выросла в 2 раза, количество ошибок снизилось на 25%. Объём заказов клиента — до 1500 в день. Документация API СДЭК v2.

Что входит в работу?

Ориентировочные сроки: базовая интеграция (расчёт + заказ) — 3-4 дня, с ПВЗ — до 5 дней, полный цикл с ТТН-1 — до 7 рабочих дней. Стоимость рассчитывается индивидуально под ваш объём и сложность.

Почему стоит доверить интеграцию нам?

Мы работаем с Битрикс более 10 лет и выполнили свыше 50 проектов по интеграции СДЭК. Среди них — как малые интернет-магазины, так и крупные каталоги с тысячами заказов в день. Гарантируем: корректную работу API, актуальные тарифы и полное сопровождение после релиза. Предоставляем гарантию на все работы — бесплатное исправление ошибок в течение 30 дней после сдачи.

Пример кэширования списка ПВЗ:

public function getBelarusOfficePoints(): array
{
    $cache = \Bitrix\Main\Data\Cache::createInstance();
    if ($cache->initCache(3600 * 6, 'cdek_pvz_by', '/cdek/')) {
        return $cache->getVars();
    }
    // ... запрос и кэширование
}

Хотите, чтобы доставка работала без сбоев? Запишитесь на консультацию — оценим ваш проект и предложим оптимальное решение.