Інтеграція 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.

Терміни