Integration of 1C-Bitrix with the KSE delivery service

1C-Bitrix Integration with KSE Delivery Service

KSE (Express Courier Service) is a Russian logistics operator specializing in e-commerce delivery. Network covers over 600 cities. Distinctive features: own pickup points and lockers, wide regional coverage, support for cash on delivery and partial pickup.

KSE API

KSE provides REST API. Base URL: https://api.kse.ru (check partner documentation). Authorization by API key in Authorization: Token {api_key} header. Data format — JSON.

Key methods:

• POST /orders/create — create request
• GET /orders/{id} — request status and data
• POST /orders/calculate — calculate cost
• GET /pvz/list — list of pickup points
• POST /orders/{id}/cancel — cancel

Delivery Module in Bitrix

Class inherits \Bitrix\Sale\Delivery\Services\Base. Main settings in b_sale_delivery_service_params:

• KSE_API_KEY — access key
• SENDER_CITY_ID — ID of sender city in KSE classifier
• SENDER_ADDRESS — warehouse address
• COD_ENABLED — cash on delivery enabled

Cities Dictionary

KSE uses its own city dictionary with identifiers. On first run, load it via GET /cities and save locally (infoblock or HL-block). Search city by string when ordering — either via GET /cities?search={query} or from local cache.

Cost Calculation

$calcData = [
    'from_city_id'   => $senderCityId,
    'to_city_id'     => $recipientCityId,
    'weight'         => $weightKg,
    'length'         => $lengthCm,
    'width'          => $widthCm,
    'height'         => $heightCm,
    'declared_value' => $declaredValue,
    'delivery_type'  => 'courier', // or 'pvz'
];

$result = $httpClient->post('/orders/calculate', $calcData);
$cost   = $result['delivery_cost'];
$days   = $result['delivery_days'];

For PVZ delivery, pass pvz_id instead of delivery_type = pvz — then calculation accounts for specific pickup point.

Creating Request and Label

$orderPayload = [
    'external_id'    => 'SHOP-' . $bitrixOrderId,
    'from_city_id'   => $senderCityId,
    'to_city_id'     => $recipientCityId,
    'delivery_type'  => $deliveryType,
    'pvz_id'         => $pvzId, // if type is pvz
    'recipient' => [
        'name'  => $fullName,
        'phone' => $phone,
    ],
    'address'     => $addressString,
    'weight'      => $weightKg,
    'dimensions'  => ['length' => $l, 'width' => $w, 'height' => $h],
    'declared_value' => $declaredValue,
    'cod_amount'  => $codAmount, // 0 if prepaid
    'comment'     => $comment,
    'items'       => $items, // list of items for partial pickup
];

In response receive order_id and tracking_number. Request label separately: GET /orders/{id}/label — returns PDF. In Bitrix admin part, add "Download KSE Label" button in order card.

Partial Pickup

If items (order positions) passed in request, KSE supports partial pickup: customer can decline part of goods right upon receipt. Courier records accepted items in their app.

Upon receiving webhook with partial pickup, recalculate order in Bitrix:

1. Remove items from b_sale_basket (or mark as returned).
2. Recalculate total sum.
3. If prepaid — create refund via payment module.

Status Tracking

KSE supports webhooks: on request status change, sends POST to registered URL. Mapping:

Timeline