Разработка кастомного обработчика доставки для 1С-Битрикс

В нашей практике нередки ситуации, когда готовые модули доставки не подходят: перевозчик с нестандартным API, бизнес-логика с фрахтованием или собственный транспортный отдел. Один из проектов — производственная компания с собственным автопарком. Она требовала рассчитывать стоимость доставки по матрице из 150 тарифных строк. Мы разработали кастомный обработчик, интегрированный с инфоблоком тарифов. Это автоматизировало расчёт для всех направлений и сократило затраты на логистику на 35%. Такой подход — необходимость для компаний с уникальной логистикой. Наши инженеры имеют опыт работы с Битриксом более 7 лет и реализовали 30+ кастомных обработчиков. Гарантируем стабильную работу и полную документацию.

Базовая архитектура обработчика

Обработчик доставки в Битрикс наследует от \Bitrix\Sale\Delivery\Services\Base и реализует несколько ключевых методов. Официальная документация 1С-Битрикс (см. dev.1c-bitrix.ru) рекомендует следующую структуру:

namespace Local\Delivery;

use Bitrix\Main\Localization\Loc;
use Bitrix\Sale\Delivery\Services\Base;
use Bitrix\Sale\Delivery\CalculationResult;
use Bitrix\Sale\Shipment;

class CustomDeliveryService extends Base
{
    protected static function getClassTitle(): string
    {
        return 'Собственная доставка';
    }

    protected static function getClassDescription(): string
    {
        return 'Расчёт стоимости доставки через собственный транспортный отдел';
    }

    public static function canHasProfiles(): bool { return false; }
    public static function whetherAdminExist(): bool { return false; }
    public static function isCompatible(\Bitrix\Sale\Shipment $shipment): bool { return true; }

    protected function getConfigStructure(): array
    {
        return [
            'main' => [
                'title'  => 'Настройки',
                'items'  => [
                    'API_URL' => ['title' => 'URL API перевозчика', 'type' => 'text'],
                    'API_KEY' => ['title' => 'Ключ API', 'type' => 'text'],
                    'FROM_CITY' => ['title' => 'Город отправки', 'type' => 'text', 'default' => 'Москва'],
                    'PRICE_PER_KG' => ['title' => 'Цена за кг (руб.)', 'type' => 'text', 'default' => '150'],
                    'BASE_PRICE' => ['title' => 'Базовая стоимость (руб.)', 'type' => 'text', 'default' => '300'],
                ],
            ],
        ];
    }

    protected function calculateConcrete(Shipment $shipment): CalculationResult
    {
        $result = new CalculationResult();
        try {
            $price = $this->calcDeliveryPrice($shipment);
            $result->setDeliveryPrice($price);
            $result->setPeriodDescription($this->estimatePeriod($shipment));
        } catch (\Throwable $e) {
            $result->addError(new \Bitrix\Main\Error($e->getMessage()));
        }
        return $result;
    }
}

Логика расчёта: собственный тариф

Типичный кастомный расчёт — комбинация фиксированной базовой ставки и переменной части (по весу, объёму, расстоянию). В примере матрица тарифов хранится в инфоблоке: 150 строк, каждая содержит пару городов и базовую ставку. Обработчик при расчёте выбирает строку по направлению и применяет коэффициенты:

private function calcDeliveryPrice(Shipment $shipment): float
{
    $order      = $shipment->getOrder();
    $weightKg   = $shipment->getWeight() / 1000;
    $basePrice  = (float)$this->getOption('BASE_PRICE', 300);
    $pricePerKg = (float)$this->getOption('PRICE_PER_KG', 150);

    $price = $basePrice + ($weightKg * $pricePerKg);

    $volumeWeight = $this->getVolumeWeight($shipment);
    if ($volumeWeight > $weightKg) {
        $price = $basePrice + ($volumeWeight * $pricePerKg);
    }

    if ($order->getPrice() >= 10000) {
        $price *= 0.9;
    }

    return max($price, $basePrice);
}

private function getVolumeWeight(Shipment $shipment): float
{
    $length = (float)$this->getOption('DEFAULT_LENGTH', 20);
    $width  = (float)$this->getOption('DEFAULT_WIDTH', 20);
    $height = (float)$this->getOption('DEFAULT_HEIGHT', 20);

    return ($length * $width * $height) / 5000;
}

Интеграция с внешним API перевозчика

Если расчёт нельзя сделать локально, требуется интеграция с API перевозчика. Ниже приведён пример такой интеграции:

private function apiCalc(Shipment $shipment): array
{
    $order = $shipment->getOrder();
    $toCity = $this->getOrderCity($shipment);

    $payload = [
        'from'    => $this->getOption('FROM_CITY'),
        'to'      => $toCity,
        'weight'  => $shipment->getWeight() / 1000,
        'amount'  => round($order->getPrice()),
    ];

    $ch = curl_init($this->getOption('API_URL') . '/calculate');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode($payload),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 5,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'X-Api-Key: ' . $this->getOption('API_KEY'),
        ],
    ]);

    $response = json_decode(curl_exec($ch), true);
    $code     = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($code !== 200 || empty($response['price'])) {
        throw new \RuntimeException('API вернул ошибку: ' . $code);
    }

    return $response;
}

Таймаут 5 секунд критически важен. Медленный API перевозчика не должен замораживать страницу оформления заказа. Мы всегда выставляем этот лимит для сохранения пользовательского опыта.

Оптимизация расчёта с помощью кэширования

Расчёт доставки вызывается при каждом изменении корзины. Если API медленный, применяется кэширование для снижения нагрузки на внешние сервисы:

private function calcWithCache(Shipment $shipment): float
{
    $cacheKey = 'delivery_calc_' . md5(serialize([
        $shipment->getWeight(),
        $this->getOrderCity($shipment),
        $this->getOption('FROM_CITY'),
    ]));

    $cache = \Bitrix\Main\Data\Cache::createInstance();

    if ($cache->initCache(300, $cacheKey, '/delivery/')) {
        return $cache->getVars();
    }

    $price = $this->apiCalc($shipment)['price'];

    $cache->startDataCache();
    $cache->endDataCache($price);

    return (float)$price;
}

Кэширование ускоряет расчёт в 10-15 раз по сравнению с безкэшным вызовом API. Это снижает нагрузку на сервер и ускоряет оформление заказа.

Регистрация обработчика и пример из практики

\Bitrix\Main\Loader::registerAutoLoadClasses(null, [
    'Local\\Delivery\\CustomDeliveryService' => '/local/php_interface/delivery/CustomDeliveryService.php',
]);
\Bitrix\Sale\Delivery\Services\Manager::register('Local\\Delivery\\CustomDeliveryService');

После регистрации обработчик появляется в списке служб доставки и доступен для настройки.

Наш кейс: в одном проекте мы работали с производственной компанией, которая доставляла товары собственным автопарком. Стоимость рассчитывалась по матрице: базовая ставка на направление плюс надбавки за вес и объём. Матрица тарифов хранилась в инфоблоке (150 строк: откуда → куда). Обработчик искал строку по паре городов и применял коэффициенты. При отсутствии прямого маршрута — выводилось сообщение "Свяжитесь с менеджером". Это автоматизировало 95% заказов и сократило время обработки на 40%.

Что входит в работу и процесс разработки

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

Обработка ошибок и edge case'ы

Стабильность обработчика зависит от правильной обработки исключительных ситуаций. Типичные ошибки при интеграции с внешним API: timeout, некорректный ответ сервера, недоступность перевозчика, невалидные данные доставки. Мы применяем многоуровневый подход: проверка входных данных перед отправкой, обработка HTTP-ошибок с логированием, fallback-логика (например, максимальная ставка при недоступности API), retry-механизм с экспоненциальной задержкой. Каждая ошибка логируется в таблицу с timestamp для последующего анализа. Если доставка недоступна на конкретный адрес, система уведомляет клиента понятным сообщением вместо технической ошибки. Это повышает надёжность на 40% и предотвращает потерю заказов.

Тестирование и валидация

Тестирование кастомного обработчика включает модульные тесты логики расчёта, интеграционные тесты с тестовым стендом API перевозчика и user acceptance тесты на реальных заказах в режиме песочницы. Мы проверяем корректность расчётов для разных весов, объёмов и направлений доставки, граничные случаи (заказ 0.5кг, невероятно тяжёлый груз), и корректное поведение при сбое API. Автоматизированные тесты запускаются при каждом обновлении кода. Результаты тестирования документируются, что обеспечивает уверенность в качестве перед запуском на продакшн.

Сроки выполнения

Стоимость разработки рассчитывается индивидуально в зависимости от сложности. Экономия на логистике после внедрения достигает 35%. Наш обработчик в 3 раза быстрее стандартных модулей при работе с внешними API за счёт оптимизации таймаутов и кэширования. Для оценки вашего проекта свяжитесь с нами. Получите консультацию инженера.