Інтеграція 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();
    }
    // ... запит та кешування
}

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

Інтеграція доставки: від розрізнених API до єдиного калькулятора за 5 днів

Покупець кидає кошик на етапі доставки — не бачить розрахунку або бачить свідомо невірну ціну. Кожен такий випадок втрачає конверсію. Автоматизація логістики в 1С-Бітрікс вирішує цю проблему: ми підключаємо служби доставки так, щоб ціна показувалася миттєво, а трекінг оновлювався без участі менеджера. Більше 50 реалізованих проєктів з каталогами від 500 до 100 000 SKU, досвід понад 8 років. Середній час підключення однієї транспортної компанії — 4 дні.

Як прискорити підключення служб доставки до 1С-Бітрікс?

Головна складність — не сам виклик API, а адаптація до логіки кожного перевізника. СДЕК, Boxberry, Нова пошта, ПЕК, DPD — у кожного свій формат запиту, тарифікація та обробка помилок. Ми використовуємо готові адаптери під кожну ТК, що скорочує час інтеграції втричі порівняно з реалізацією з нуля. Розгорнутий кейс: інтернет-магазин товарів для дому (15 000 товарів) — підключили СДЕК та Boxberry за 5 днів, автоматизували розрахунок та створення замовлень. Звернення до підтримки з доставки знизилися на 60%, середній чек зріс на 8% за рахунок індикатора безкоштовної доставки.

Чому API кожної транспортної компанії — окремий квест?

СДЕК — об'ємна вага та карта ПВЗ

API v2 (/api/v2/calculator/tarifflist) приймає габарити, вагу та адреси — повертає всі доступні тарифи. Підводні камені: об'ємна вага розраховується за формулою (Д × Ш × В) / 5000. Якщо фізична вага 2 кг, а об'ємна 8 кг — СДЕК бере по об'ємній. Не врахуєте в калькуляторі — покупець побачить одну ціну, а заплатить іншу. Карта ПВЗ завантажується через /deliverypoints. Віджет СДЕК можна вбудувати, але він конфліктує зі стилями Бітрікс — малюємо свою карту на Яндекс.Картах. Автоматичне створення замовлення через /api/v2/orders — при оформленні заявка летить у СДЕК, повертається трек-номер. Друк накладних та етикеток з адмінки — через /api/v2/print/orders. Тарифи: склад-склад, склад-двері, двері-двері, експрес, постамат.

Boxberry — широка мережа ПВЗ в регіонах

Найширша мережа пунктів видачі в малих містах. API простіше, ніж у СДЕК, але є нюанси з післяплатою та частковим викупом. Типові помилки при інтеграції: відсутність фільтрації ПВЗ за ознакою onlyPrepaid → помилки при післяплаті; ігнорування параметра partialReturn → ламає частковий викуп. API повертає код міста у форматі "770000000000" — потрібне маппінг на index міста.

Нова пошта — лідер українського ринку

Для України — обов'язкове підключення Нової пошти через API v2. Розрахунок вартості, створення ЕН, друк накладної, трекінг. Карта відділень з фільтрацією (поштомати, прийом платежів). Асинхронне оновлення статусів через агент Бітрікс кожні 15 хвилин.

ПЕК — важкі вантажі та збір

Коли потрібно відправити диван або обладнання. Розрахунок збірних вантажів, страхування, обрешітка. Доставка до терміналу та від дверей до дверей. Індекси терміналів ПЕК підвантажуємо в інфоблок для автопідстановки.

DPD — експрес-доставка з часовими слотами

DPD по Україні та за кордон. Доставка у вибраний часовий інтервал, повернення підписаних документів. У розрахунку враховуємо об'ємну вагу за формулою (Д×Ш×В)/4000 — відмінність від СДЕК. Документація DPD: volumetric weight factor 4000.

Як об'єднати різні ТК в єдиному калькуляторі?

Використовуємо гібридний підхід: модуль-агрегатор, який маршрутизує запити до різних API та нормалізує відповіді. Він обробляє запити в 5 разів швидше, ніж окремі інтеграції, завдяки паралельним викликам через curl_multi. У відповіді модуля — єдина структура: назва тарифу, ціна, термін, тип доставки. Кешування теговане: при зміні налаштувань модуля очищується лише кеш розрахунку для обраного міста, решта залишається. Подію OnBeforeDeliveryCalculate вішаємо на кастомний обробник — так підміняємо стандартну логіку доставки.

Розрахунок вартості: які граблі зустрічаються?

Автоматичний калькулятор підсумовує фізичну та об'ємну вагу товарів у кошику, додає вагу упаковки, обирає найбільшу. Звучить просто, але:

• Габарити мають бути заповнені у кожного товару. Немає габаритів — немає розрахунку. На каталозі в 10 000 SKU обов'язково знайдуться товари без розмірів — для них заводимо дефолтні значення (наприклад, 0.1×0.1×0.1 м) і попереджаємо менеджера через поштову подію.
• Промоакції та пороги безкоштовної доставки — гнучке налаштування: за сумою замовлення, для VIP-клієнтів, при конкретному способі оплати. Реалізуємо через користувацькі властивості кошика.
• Індикатор «До безкоштовної доставки залишилося N» — проста річ, але піднімає середній чек на 5–12%. Обчислюємо за сумою кошика та найближчим порогом, виводимо в шаблоні кошика.

Як автоматизувати трекінг, самовивіз та кур'єрську доставку?

Трекінг. Автоматичне опитування API транспортних компаній — агент Бітрікс кожні 30 хвилин перевіряє статуси замовлень, у яких STATUS_DELIVERY != 'DELIVERED'. При зміні — оновлення статусу замовлення в системі та повідомлення покупцеві (email, SMS, push). Вбудована сторінка трекінгу в особистому кабінеті — покупцю не потрібно йти на сайт ТК. Карта з поточним місцезнаходженням, прогнозована дата доставки, можливість переадресації.

Самовивіз. Власні точки видачі на карті: адреси, графік, контакти. Пошук найближчої за адресою покупця. Перевірка наявності в реальному часі, бронювання до певної години. QR-код для швидкого отримання та SMS про готовність до видачі.

Кур'єрська доставка. Зони доставки з різною вартістю. 2-годинні слоти, управління розкладом кур'єрів, обмеження замовлень на слот. Доставка день у день — прийом до 14:00, експрес за 2-4 години з націнкою за терміновість. Інтеграція з навігацією для оптимізації маршрутів.

Мультисклад. Декілька складів з адресами та зонами обслуговування. Автоматичний вибір складу відвантаження за адресою покупця — пріоритет найближчому, де є всі товари замовлення. Якщо на одному складі всього немає — розділення замовлення по складах (мультидоставка). Синхронізація залишків через 1С або WMS (CommerceML), використовуємо події OnBeforeBasketAdd для перевірки доступності.

Порівняння транспортних компаній

Етапи підключення служб доставки

1. Аналіз логістики (1–2 дні) — географія, середня вага, обсяг замовлень, інтеграція з 1С. Рекомендуємо комбінацію ТК.
2. Підключення API (3–5 днів на ТК) — налаштування розрахунків, карт ПВЗ, автоматичне створення замовлень через агенти та події.
3. Налаштування трекінгу (1–2 тижні) — агенти оновлення статусів, шаблони повідомлень, сторінка трекінгу.
4. Тестування (2–3 дні) — перевірка на реальних адресах, порівняння тарифів, контроль помилкових розрахунків, навантажувальне тестування.
5. Деплой та навчання (1 день) — вивантаження модуля, передача доступів, навчання менеджерів.
6. Гарантійна підтримка (1 місяць) — виправлення багів, коригування конфігурацій, доналаштування кешування.

Що входить у вартість інтеграції

• Документація зі схемою обміну (логістичні маршрути, тарифні зони).
• Налаштовані доступы до API кожної ТК, ключі, вебхуки.
• Шаблони повідомлень (email, SMS, push) для статусів доставки.
• Навчання менеджерів: робота з адмінкою, друк документів, обробка помилок.
• Півроку технічної підтримки після запуску.

Орієнтовні терміни реалізації

Терміни залежать від кількості ТК, складності каталогу та необхідності інтеграції з 1С/ERP. Вартість розраховується індивідуально — орієнтуйтеся на економію: зниження операційних витрат на доставку до 40% та скорочення звернень до підтримки на 60%. Наприклад, один із клієнтів з магазином електроніки (20 000 товарів) повернув інвестиції за 3 місяці за рахунок зменшення кількості «забутих» замовлень. Середня економія наших клієнтів — 15 000 грн на місяць на логістиці.

Готові прискорити логістику вашого інтернет-магазину? Зв'яжіться з нами — допоможемо підібрати оптимальну комбінацію ТК під ваш асортимент та бюджет. Замовте консультацію — і ми підготуємо пропозицію за 1 робочий день.