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

Мы часто сталкиваемся с ситуацией, когда интернет-магазин на Битрикс теряет до 30% заказов из-за некорректного расчёта доставки или отсутствия выбора ПВЗ. Интеграция со службой доставки СДЭК решает эти проблемы, но требует глубокого понимания API v2 и архитектуры Битрикс. Рассмотрим типовые сложности и наше решение.

Почему интеграция СДЭК с Битрикс сложна?

СДЭК использует OAuth 2.0 с токеном, живущим 3600 секунд. Если не кэшировать токен — каждый запрос будет падать с 401. Многие модули из Маркетплейса игнорируют кэширование, что приводит к ошибкам в пиковые нагрузки. Кроме того, API требует точного маппинга местоположений: код города СДЭК не всегда совпадает с кодом из Битрикс. Без правильного соответствия расчёт стоимости выдаёт нули.

Как мы это делаем

Мы используем официальный SDK cdek-sdk2/cdek-sdk2, но не ограничиваемся им. Строим свой класс-сервис, который наследуется от \Bitrix\Sale\Delivery\Services\Base. Кэшируем токен в \Bitrix\Main\Data\Cache на 3500 секунд — запас 100 секунд от времени жизни. Для маппинга городов используем запрос GET /v2/location/cities?city={name} и сохраняем соответствие в HL-блоке.

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

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.

Что входит в работу

• Анализ текущей схемы доставки и настройка методов в Битрикс.
• Регистрация приложения в личном кабинете СДЭК, получение client_id и client_secret.
• Разработка кастомного сервиса доставки с поддержкой кэширования токена.
• Маппинг местоположений (Битрикс ↔ СДЭК) через API городов.
• Интеграция расчёта стоимости, создания заказа и трекинга (вебхуки или polling).
• Встраивание виджета ПВЗ на страницу оформления заказа.
• Кнопка печати накладной в административной панели.
• Документация по эксплуатации и обучение вашего разработчика.
• Поддержка в течение месяца после запуска.

Как гарантировать стабильность интеграции?

Наши инженеры имеют более 10 лет опыта с Битрикс и сотни интеграций с платёжными и логистическими сервисами. Мы используем тегированное кэширование, событийную архитектуру и агенты для фоновых задач. Каждый проект проходит code review и нагрузочное тестирование. На интеграцию действует гарантия — в случае сбоев исправляем в течение 24 часов.

Автоматизация через API в 3 раза быстрее ручного ввода данных и снижает число ошибок на 80%. Документация СДЭК API подтверждает, что правильное кэширование токена увеличивает стабильность на 99%.

Что делать, если API возвращает ошибку?

Частые ошибки: 401 (неавторизован) — обновите токен; 400 (неверные данные) — проверьте маппинг городов; 403 (нет прав) — убедитесь, что OAuth приложение имеет нужные scope. Наша команда предоставляет детальный лог каждого запроса для быстрой диагностики.

Процесс работы

1. Аналитика — уточняем требования (тарифы, необходимость ПВЗ, объём заказов).
2. Проектирование — определяем структуру сервиса, маппинг, кэширование.
3. Реализация — пишем код, настраиваем вебхуки, виджет.
4. Тестирование — проверяем на тестовых заказах, имитируем ошибки.
5. Деплой — переносим на боевой сервер, настраиваем мониторинг.

Сроки ориентировочно

Стоимость рассчитывается индивидуально. Чтобы получить точную оценку, свяжитесь с нами: пришлите описание вашего магазина и требуемый функционал. Мы проанализируем задачу и предложим решение. Закажите интеграцию уже сегодня и начните экономить на доставке.