Интеграция 1С-Битрикс со службой доставки КСЭ

Интеграция 1С-Битрикс со службой доставки КСЭ

КСЭ (Курьерская Служба Экспресс) — российский логистический оператор, специализирующийся на доставке для интернет-торговли. Сеть охватывает более 600 городов. Особенность: собственные ПВЗ и постаматы, широкое покрытие в регионах, поддержка наложенного платежа и частичной выдачи.

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 — отмена

Модуль доставки в Битрикс

Класс наследует \Bitrix\Sale\Delivery\Services\Base. Основные настройки в b_sale_delivery_service_params:

• KSE_API_KEY — ключ доступа
• SENDER_CITY_ID — ID города-отправителя в классификаторе КСЭ
• SENDER_ADDRESS — адрес склада
• COD_ENABLED — наложенный платёж включён

Справочник городов

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

Расчёт стоимости

$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 (позиции заказа), КСЭ поддерживает частичную выдачу: покупатель может отказаться от части товаров прямо при получении. Курьер фиксирует принятые позиции в своём приложении.

При получении вебхука с частичной выдачей пересчитываем заказ в Битрикс:

1. Удаляем позиции из b_sale_basket (или помечаем возвращёнными).
2. Пересчитываем итоговую сумму.
3. Если была предоплата — создаём возврат через модуль оплаты.

Отслеживание статусов

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

Сроки