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

Інтеграція 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 формується, швидкість обробки замовлень зросла вдвічі, кількість помилок знизилася на 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();
    }
    // ... запит та кешування
}

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