Інтеграція 1С-Бітрікс зі службою доставки КСЕ

Інтеграція 1С-Bitrix зі службою доставки КСЕ

КСЕ (Курьєрська Служба Експрес) — російський логістичний оператор, спеціалізуючись на доставці для інтернет-торговлі. Мережа охоплює понад 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

Клас успадковує \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. У адміністративній частині Bitrix додаємо кнопку «Завантажити етикетку КСЕ» у карточку замовлення.

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

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

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

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

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

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

Графік