Подключаем КСЭ к 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С-Битрикс специалисты. Оценим ваш проект бесплатно — напишите, и мы пришлём коммерческое предложение в течение дня.

Сроки

Свяжитесь с нами — обсудим детали. Мы подберём оптимальный тариф и сроки именно под ваш магазин. Получите консультацию уже сегодня.