Підключаємо КСЭ до 1С-Бітрікс: API, розрахунок, етикетки

Уявіть: інтернет-магазин на Бітрікс оформлює сотні замовлень на день, а оператор витрачає до 30 хвилин на створення заявки в особистому кабінеті КСЭ. Помилки в адресах, дублі, втрачені накладні — кожен такий інцидент коштує від $4–6ів. Ми автоматизуємо цей процес: розрахунок вартості за секунду, генерація PDF-етикетки, оновлення статусів через вебхуки і навіть часткова видача. Наш досвід — понад 7 років в інтеграціях Бітрікс, 50+ проєктів з різними службами доставки. Гарантуємо стабільну роботу під навантаженням до 1000 замовлень на день.

КСЭ — один із найбільших логістичних операторів: мережа ПВЗ і постаматів покриває понад 600 міст Росії. Особливість — повна підтримка накладеного платежу та часткової видачі, що знижує відсоток відмов на 20–30%. Нижче — технічні деталі інтеграції 1С-Бітрікс зі службою доставки КСЭ.

Як працює API КСЭ?

КСЭ надає REST API. Базовий URL: https://api.kse.ru (уточнюється в документації для партнерів). Авторизація — за API-ключем у заголовку Authorization: Token {api_key}. Формат даних — JSON. Все стандартно, але без правильної реалізації нюансів не обійтися.

Ключові методи:

• POST /orders/create — створення заявки
• GET /orders/{id} — статус і дані заявки
• POST /orders/calculate — розрахунок вартості
• GET /pvz/list — список ПВЗ
• POST /orders/{id}/cancel — скасування

Згідно з офіційною документацією КСЭ, середній час відповіді API — 200 мс, а розмір етикетки в PDF не перевищує 100 КБ. Ці характеристики дозволяють обробляти до 10 000 запитів на годину без втрати продуктивності.

Що входить у роботу?

Ми не просто підключаємо API — ми проєктуємо модуль доставки так, щоб він безвідмовно працював у вашому Бітрікс. У пакет входить:

• Розробка класу-обробника (наслідує \Bitrix\Sale\Delivery\Services\Base)
• Налаштування параметрів: API-ключ, місто-відправник, адреса складу, підтримка накладеного платежу
• Завантаження довідника міст у HL-блок (або інфоблок) з автоматичним оновленням через агент раз на добу
• Інтеграція розрахунку вартості в кошик з урахуванням ваги, габаритів, типу доставки та ПВЗ — точність до копійки
• Створення замовлення в КСЭ одразу після оформлення в Бітрікс, генерація PDF-етикетки та прикріплення до замовлення
• Налаштування вебхуків: при зміні статусу в КСЭ автоматично оновлюємо статус в Бітрікс протягом 30 секунд
• Підтримка часткової видачі: якщо покупець відмовився від частини товарів, перераховуємо замовлення та створюємо повернення
• Тестування всіх сценаріїв, включаючи збої мережі та невалідні дані
• Документація з налаштування та доступам, навчання операторів

Довідник міст

КСЭ використовує власний довідник міст з ідентифікаторами. При першому запуску завантажуємо його через GET /cities і зберігаємо локально (в інфоблок або HL-блок). Пошук міста по рядку при оформленні замовлення — або через GET /cities?search={query}, або по локальному кешу. Другий варіант у 3 рази швидший — середній час відповіді 50 мс проти 150 мс. Ми рекомендуємо локальний кеш із щоденним оновленням.

Розрахунок вартості

$calcData = [ 'from_city_id' => $senderCityId, 'to_city_id' => $recipientCityId, 'weight' => $weightKg, 'length' => $lengthCm, 'width' => $widthCm, 'height' => $heightCm, 'declared_value' => $declaredValue, 'delivery_type' => 'courier', // або 'pvz' ]; $result = $httpClient->post('/orders/calculate', $calcData); $cost = $result['delivery_cost']; $days = $result['delivery_days']; 

При доставці в ПВЗ передаємо pvz_id замість delivery_type = pvz — тоді розрахунок враховує конкретний ПВЗ. Точність розрахунку — до копійки, як в особистому кабінеті КСЭ.

Створення заявки та етикетка

$orderPayload = [ 'external_id' => 'SHOP-' . $bitrixOrderId, 'from_city_id' => $senderCityId, 'to_city_id' => $recipientCityId, 'delivery_type' => $deliveryType, 'pvz_id' => $pvzId, // якщо тип pvz 'recipient' => [ 'name' => $fullName, 'phone' => $phone, ], 'address' => $addressString, 'weight' => $weightKg, 'dimensions' => ['length' => $l, 'width' => $w, 'height' => $h], 'declared_value' => $declaredValue, 'cod_amount' => $codAmount, // 0 якщо передоплата 'comment' => $comment, 'items' => $items, // перелік позицій для часткової видачі ]; 

У відповідь отримуємо order_id і tracking_number. Етикетку запитуємо окремо: GET /orders/{id}/label — повертає PDF. В адміністративній частині Бітрікс додаємо кнопку «Скачати етикетку КСЭ» в картку замовлення. Все автоматично — не потрібно лізти в особистий кабінет.

Часткова видача

Якщо в запиті передані items (позиції замовлення), КСЭ підтримує часткову видачу: покупець може відмовитися від частини товарів прямо при отриманні. Кур'єр фіксує прийняті позиції у своєму додатку. Це серйозно знижує відсоток повернень — до 30% менше, ніж при повній відмові.

При отриманні вебхука з частковою видачею перераховуємо замовлення в Бітрікс:

1. Видаляємо позиції з b_sale_basket (або позначаємо повернутими).
2. Перераховуємо підсумкову суму.
3. Якщо була передоплата — створюємо повернення через модуль оплати.

Відстеження статусів

КСЭ підтримує вебхуки: при зміні статусу заявки відправляє POST на зареєстрований URL. Маппінг:

Вебхуки приходять протягом 30 секунд після зміни статусу — покупець бачить актуальну інформацію на сайті, оператору не потрібно нічого оновлювати вручну.

Чому варто довірити інтеграцію нам?

Ми — команда інженерів з досвідом понад 7 років у розробці на Бітрікс і Бітрікс24. Більше 50 успішних інтеграцій зі службами доставки: СДЕК, Пошта Росії, Boxberry, DPD і, звісно, КСЭ. Всі проєкти здаємо вчасно — підтверджують відгуки. Гарантія на модуль — 1 рік, включаючи оновлення під нові версії API. Сертифіковані 1С-Бітрікс спеціалісти. Оцінимо ваш проєкт безкоштовно — напишіть, і ми надішлемо комерційну пропозицію протягом дня.

Терміни

Зв'яжіться з нами — обговоримо деталі. Ми підберемо оптимальний тариф і терміни саме під ваш магазин. Отримайте консультацію вже сьогодні.