Подключение КСЭ

КСЭ (Курьер Сервис Экспресс) — курьерская и складская логистика с широкой сетью ПВЗ, которую удобно подключать к магазину на 1С-Битрикс через API. В Битрикс нет встроенного обработчика для КСЭ, поэтому службу добавляют либо готовым модулем из Маркетплейса, либо собственным обработчиком доставки поверх подсистемы Sale. Разберём оба пути, подготовку договора и типичные ошибки расчёта.

Что даёт интеграция КСЭ

КСЭ везёт курьерскую доставку «до двери», самовывоз из пунктов выдачи и складскую логистику для B2B. Для интернет-магазина интеграция закрывает три задачи: онлайн-расчёт стоимости и срока в корзине, выбор пункта выдачи на карте и передачу заказа в личный кабинет перевозчика без ручного оформления накладных.

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

Два способа подключения

Выбор зависит от бюджета, требований к логике и того, есть ли у вас разработчик. Сравним варианты:

• Готовый модуль — быстрый старт для типового магазина: ставится через Marketplace → Установленные решения, добавляет службу доставки и профили тарифов.
• Собственный обработчик — когда нужны нестандартные правила (наценка, округление срока, свои зоны), интеграция с 1С и полный контроль над запросами к API КСЭ.

Подготовка: договор и доступ к API

Любой способ подключения начинается не в админке Битрикс, а на стороне перевозчика. Нужно заключить договор и получить технические доступы:

1. Заключите договор с КСЭ и получите номер клиента (договора).
2. В личном кабинете КСЭ запросите доступ к API — обычно это пара логин/пароль или токен (API-ключ) для сервисных методов.
3. Уточните у менеджера актуальный список методов: расчёт стоимости, получение справочника ПВЗ и городов, создание заявки на отгрузку.
4. Согласуйте склад отгрузки и город отправителя — от них считается плечо доставки.

Эти данные затем вносятся в настройки модуля или в конфиг обработчика. Храните ключи вне публичной части: в local/php_interface или в настройках модуля, но не в шаблоне и не в репозитории в открытом виде.

Установка и настройка модуля

Готовое решение ставится штатно. После установки служба доставки появляется в списке, и её нужно настроить под ваши города и тарифы:

• Установите решение и активируйте лицензию в Marketplace.
• Откройте Магазин → Настройки → Службы доставки (/bitrix/admin/sale_delivery_service_list.php) — там появится КСЭ.
• Введите доступы к API (логин, пароль или токен) и номер договора в настройках службы.
• Выберите режимы доставки: курьер до двери и/или самовывоз из ПВЗ — как отдельные профили.
• Настройте ограничения: по весу, габаритам, сумме и по местоположениям через подсистему Delivery\Restrictions.

Многие модули умеют кэшировать справочник ПВЗ и городов на стороне сайта. Обязательно настройте регулярное обновление кэша (агент или cron), иначе новые пункты выдачи КСЭ не появятся у покупателей, а закрытые останутся в выборе.

Свой обработчик доставки

Если модуля мало, доставку описывают классом-обработчиком поверх подсистемы Sale. Базовый класс — \Bitrix\Sale\Delivery\Services\Base; профиль (курьер, ПВЗ) наследуют от него отдельно. Обработчик регистрируют через событие onSaleDeliveryHandlersClassNamesBuildList и размещают в local/php_interface или в своём модуле.

Ключевые методы, которые вы реализуете:

• calculateConcrete() — обращается к API КСЭ, возвращает Delivery\CalculationResult со стоимостью и сроком по весу, габаритам и городам отправитель/получатель.
• getConfigStructure() и getConfig() — поля настроек (ключи API, склад, наценка), которые редактор видит в карточке службы.
• isCalculatePriceImmediately() — считать ли цену сразу при показе способа доставки.

Запросы к API оборачивайте в try/catch и таймаут: если КСЭ недоступна, метод должен вернуть аккуратную ошибку расчёта, а не «уронить» оформление заказа. Ответ парсите и приводите вес/габариты к единицам, которые ждёт перевозчик.

Расчёт тарифа и выбор ПВЗ

Для самовывоза КСЭ покупателю нужно выбрать конкретный пункт выдачи, а тариф считается до этого ПВЗ. Технически это два справочника: список городов/районов и список ПВЗ с координатами. Их получают из API и кэшируют локально, чтобы не дёргать перевозчика на каждый шаг корзины.

• На шаге доставки покупатель выбирает город — подтягивается список ПВЗ КСЭ.
• Пункты показывают на карте (Яндекс.Карты) с адресом, режимом работы и сроком.
• Выбранный ПВЗ пишется в свойство заказа, а его код уходит в заявку при создании отгрузки.

Расчёт стоимости зависит от фактического и объёмного веса: КСЭ, как и большинство перевозчиков, берёт больший из двух. Поэтому в карточках товаров важно заполнять вес и габариты — без них API вернёт минимальный тариф или ошибку. Логику объёмного веса удобно вынести в отдельную статью по расчёту доставки по весу и габаритам, а здесь достаточно передавать корректные размеры коробки.

Тестирование и типичные ошибки

Перед боевым запуском прогоните расчёт на реальных сценариях: разные города, лёгкая посылка и тяжёлая, курьер и ПВЗ, доставка за пределы зоны обслуживания. Смотрите ответы API в логе — Битрикс удобно писать через Bitrix\Main\Diag\Debug::writeToFile() в защищённый файл.

Итог

Подключение КСЭ к 1С-Битрикс сводится к трём шагам: получить договор и доступ к API, добавить службу доставки (модулем или своим обработчиком) и настроить расчёт с выбором ПВЗ и ограничениями. Готовый модуль быстрее для типового магазина, собственный обработчик на базе \Bitrix\Sale\Delivery\Services\Base даёт полный контроль и переживает обновления. Успех интеграции держится на мелочах: корректные вес и габариты, актуальный кэш ПВЗ и аккуратная обработка ошибок API.

Мы в B2Bsite подключаем КСЭ и другие службы доставки под ключ — от согласования API с перевозчиком до автоматической передачи заказов и интеграции с 1С. Если нужен онлайн-расчёт, карта ПВЗ и стабильная работа корзины без ручных накладных, поможем спроектировать и внедрить решение под ваш каталог.