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

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

СДЭК — одна из крупнейших логистических сетей в России и СНГ. Интеграция с Битрикс охватывает расчёт стоимости доставки по тарифам, создание заказов, получение накладных и трекинг. СДЭК предоставляет официальный SDK для PHP (cdek-sdk2/cdek-sdk2), что упрощает работу с API v2, но не убирает необходимость правильно встроить это в архитектуру Битрикс.

API СДЭК v2: базовые принципы

СДЭК использует OAuth 2.0 для авторизации. Токен получается через POST /v2/oauth/token с client_id и client_secret из личного кабинета. Токен действует 3600 секунд — кэшируем его в Битрикс-кэше (\Bitrix\Main\Data\Cache), не запрашиваем при каждом вызове.

Основные эндпоинты:

• POST /v2/calculator/tariff — расчёт стоимости по одному тарифу
• POST /v2/calculator/tarifflist — расчёт по всем тарифам
• POST /v2/orders — создание заказа
• GET /v2/orders?cdek_number={n} — статус заказа
• POST /v2/print/orders — генерация накладной PDF

Модуль доставки СДЭК в Битрикс

class CdekDeliveryService extends \Bitrix\Sale\Delivery\Services\Base
{
    protected static function getClassTitle(): string
    {
        return 'СДЭК';
    }

    protected function calculateConcrete(
        \Bitrix\Sale\Shipment $shipment
    ): \Bitrix\Sale\Delivery\CalculationResult {
        $result = new \Bitrix\Sale\Delivery\CalculationResult();

        $toLocation = $this->getLocationCode($shipment);
        if (!$toLocation) {
            $result->addError(new \Bitrix\Main\Error('Местоположение не определено'));
            return $result;
        }

        $price = $this->calcPrice($shipment, $toLocation);
        $result->setDeliveryPrice($price);
        $result->setPeriodDescription('2-5 дней');

        return $result;
    }
}

Метод getLocationCode() конвертирует местоположение Битрикс в код города СДЭК. Конвертация строится через таблицу b_sale_location — по коду КЛАДР или названию города. Для корректного маппинга используем GET /v2/location/cities?city={name}.

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

private function calcPrice(\Bitrix\Sale\Shipment $shipment, string $toCode): float
{
    $order = $shipment->getOrder();
    $weight = max($shipment->getWeight(), 100); // минимум 100г

    $payload = [
        'type'          => 1, // 1-интернет-магазин
        'tariff_code'   => 136, // 136-доставка до двери
        'from_location' => ['code' => $this->getOption('FROM_LOCATION_CODE')],
        'to_location'   => ['code' => $toCode],
        'packages'      => [
            [
                'weight' => $weight,
                'length' => $this->getOption('DEFAULT_LENGTH') ?: 20,
                'width'  => $this->getOption('DEFAULT_WIDTH') ?: 20,
                'height' => $this->getOption('DEFAULT_HEIGHT') ?: 20,
            ],
        ],
        'services' => $this->getAdditionalServices($order),
    ];

    $response = $this->apiPost('/v2/calculator/tariff', $payload);
    return $response['total_sum'] ?? 0;
}

Тарифный код 136 — «Посылка склад-дверь». Для доставки до ПВЗ используется 136 или 138 («Посылка склад-склад»). Актуальный список тарифов: GET /v2/calculator/tarifflist.

Создание заказа СДЭК

private function createCdekOrder(\Bitrix\Sale\Shipment $shipment): string
{
    $order = $shipment->getOrder();
    $propertyCollection = $order->getPropertyCollection();

    $payload = [
        'type'          => 1,
        'number'        => (string)$order->getId(),
        'tariff_code'   => 136,
        'from_location' => $this->getFromLocation(),
        'to_location'   => $this->getToLocation($propertyCollection),
        'recipient'     => [
            'name'   => $propertyCollection->getItemByOrderPropertyCode('FIO')?->getValue(),
            'phones' => [['number' => $propertyCollection->getItemByOrderPropertyCode('PHONE')?->getValue()]],
        ],
        'packages'      => $this->buildPackages($shipment),
        'comment'       => 'Заказ #' . $order->getId(),
    ];

    $response = $this->apiPost('/v2/orders', $payload);

    // Сохраняем ID заказа СДЭК в свойствах заказа Битрикс
    $propertyCollection->getItemByOrderPropertyCode('CDEK_ORDER_UUID')
        ?->setValue($response['entity']['uuid']);

    $order->save();

    return $response['entity']['uuid'];
}

Статусы и трекинг

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

При отсутствии белого IP — polling агентом каждые 2 часа для активных отправлений.

ПВЗ на сайте

СДЭК предоставляет JavaScript-виджет для выбора ПВЗ на карте. Виджет вызывается в шаблоне компонента доставки, передаёт выбранный код ПВЗ в скрытое поле формы. При создании заказа вместо to_location с адресом используется delivery_point с кодом ПВЗ.

window.open_cdek_map = function() {
    window.CDEKWidget.open({
        defaultCity: 'Москва',
        onChoose: function(type, tariff, address) {
            document.getElementById('cdek_pvz_code').value = address.code;
            document.getElementById('cdek_pvz_name').value = address.name;
        }
    });
};

Накладная и штрих-код

После создания заказа в СДЭК доступна генерация накладной: POST /v2/print/orders с UUID заказа. Ответ содержит ссылку для скачивания PDF. Реализуем кнопку в административной части заказа Битрикс: менеджер нажимает «Печать накладной СДЭК» — открывается PDF.

Сроки