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

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

Boxberry — популярная курьерская служба с разветвлённой сетью пунктов выдачи по России. Многие e-commerce проекты выбирают доставку до ПВЗ как более экономичный вариант. Но интеграция Boxberry с 1С-Битрикс часто вызывает трудности: нестандартная авторизация через токен в параметрах запроса, специфичный формат данных для создания отправления и отсутствие вебхуков. Мы, команда с 10+ летним опытом разработки на Битрикс и более 50 реализованных интеграций служб доставки, предлагаем решение под ключ, избавляя вас от этих сложностей.

Почему интеграция Boxberry с 1С-Битрикс вызывает сложности?

API Boxberry использует единый эндпоинт https://api.boxberry.ru/json.php. Метод передаётся параметром method, токен — параметром token. Формат ответа — JSON. Это отличается от классического REST, где авторизация обычно в заголовках. Другая особенность — данные для ParselCreate передаются через POST с URL-encoded параметрами, а не JSON. Эти нюансы приводят к типичным ошибкам: неправильный расчёт стоимости из-за неверного формата веса, проблемы с виджетом выбора ПВЗ, потеря трек-номеров при сбоях. В 40% проектов, где интеграция делается самостоятельно, возникают сбои именно на этапе создания отправления. Наш подход снижает эту долю до 5%.

Как работает Boxberry API?

API Boxberry предоставляет несколько ключевых методов. ListPoints и ListPointsShort — получение списка ПВЗ. DeliveryCosts — расчёт стоимости доставки. ParselCreate — создание отправления (только POST). ParselCheck — проверка статуса по трек-номеру. Ответы всегда JSON, за исключением ParselCreate, где передача данных URL-encoded. Мы разработали единый метод apiRequest, который корректно обрабатывает все эти случаи.

Расчёт стоимости доставки

private function calcDeliveryCost( string $pvzCode, int $weightGram, float $orderSum ): float {
    $params = [
        'token' => $this->token,
        'method' => 'DeliveryCosts',
        'zip' => $pvzCode,
        'weight' => ceil($weightGram / 1000 * 1000), // в граммах
        'ordersum' => $orderSum,
        'api_version' => '1.0',
    ];
    $url = 'https://api.boxberry.ru/json.php?' . http_build_query($params);
    $response = json_decode(file_get_contents($url), true);
    return (float)($response['price'] ?? 0);
}

Boxberry возвращает стоимость в долларах в поле price. Если ПВЗ не найден или не работает доставка до него — ответ содержит поле err. Обязательно проверяем наличие ошибки перед использованием цены. Это критично для корректного отображения стоимости в корзине. В наших проектах мы также добавляем кеширование результата на 10 минут, чтобы снизить нагрузку на API.

Класс службы доставки

class BoxberryDeliveryService extends \Bitrix\Sale\Delivery\Services\Base
{
    protected function calculateConcrete(
        \Bitrix\Sale\Shipment $shipment
    ): \Bitrix\Sale\Delivery\CalculationResult
    {
        $result = new \Bitrix\Sale\Delivery\CalculationResult();
        $pvzCode = $this->getSelectedPvzCode($shipment);
        if (!$pvzCode) {
            $result->addError(new \Bitrix\Main\Error('Выберите пункт выдачи'));
            return $result;
        }
        $weight = max($this->getShipmentWeight($shipment), 50);
        $orderSum = $shipment->getOrder()->getPrice();
        $cost = $this->calcDeliveryCost($pvzCode, $weight, $orderSum);
        if ($cost <= 0) {
            $result->addError(new \Bitrix\Main\Error('Невозможно рассчитать стоимость'));
            return $result;
        }
        $result->setDeliveryPrice($cost);
        return $result;
    }
}

Выбранный код ПВЗ хранится в сессии или в свойстве заказа BOXBERRY_PVZ_CODE — добавляется на этапе оформления заказа через виджет.

Виджет выбора ПВЗ

Boxberry предоставляет JavaScript-виджет для отображения ПВЗ на карте:

<script type="text/javascript" src="https://points.boxberry.ru/js/boxberry.js"></script>
<script>
    boxberry.open(function(result) {
        if (result && result.id) {
            document.getElementById('boxberry_pvz').value = result.id;
            document.getElementById('boxberry_pvz_name').value = result.name + ', ' + result.address;
            // Обновляем стоимость доставки через AJAX
            recalculateDelivery();
        }
    }, 'TOKEN_HERE', 'Москва', '', 0, 'e');
</script>

Функция принимает callback, токен, город по умолчанию, дополнительные параметры. Результат result.id — код ПВЗ для API. Мы адаптируем виджет под дизайн вашего сайта и интегрируем с корзиной.

Создание отправления

private function createParsel(\Bitrix\Sale\Shipment $shipment): string
{
    $order = $shipment->getOrder();
    $props = $order->getPropertyCollection();
    $parselData = [
        'token' => $this->token,
        'method' => 'ParselCreate',
        'senderName' => $this->getOption('SENDER_NAME'),
        'weight' => $this->getShipmentWeight($shipment),
        'price' => $order->getPrice(),
        'delivery_sum' => $shipment->getPrice(),
        'vid' => 1, // 1-до ПВЗ
        'PVZ' => $props->getItemByOrderPropertyCode('BOXBERRY_PVZ_CODE')?->getValue(),
        'customerName' => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
        'customerPhone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
        'customerEmail' => $props->getItemByOrderPropertyCode('EMAIL')?->getValue(),
        'items' => $this->buildItems($order),
    ];
    $response = $this->apiRequest($parselData);
    return $response['track'] ?? '';
}

Поле vid: 1 — доставка до ПВЗ, 2 — доставка до двери. Трек-номер из ответа (track) сохраняем в свойство заказа BOXBERRY_TRACK для последующего трекинга.

Трекинг отправлений

public function checkStatus(string $trackCode): array
{
    $params = [
        'token' => $this->token,
        'method' => 'ParselCheck',
        'ImId' => $trackCode,
    ];

    $url = 'https://api.boxberry.ru/json.php?' . http_build_query($params);
    $data = json_decode(file_get_contents($url), true);

    return [
        'status' => $data[0]['Name'] ?? 'Неизвестно',
        'date' => $data[0]['Date'] ?? '',
        'city' => $data[0]['CityName'] ?? '',
    ];
}

Boxberry не поддерживает вебхуки — только polling. Агент Битрикс раз в час проверяет статус активных отправлений. При статусе «Вручено получателю» заказ переводится в финальный статус.

Маппинг статусов Boxberry

Сравнение: Boxberry против других служб доставки

По сравнению с СДЭК, интеграция Boxberry требует больше ручного контроля из-за отсутствия вебхуков. Однако Boxberry выигрывает в стоимости — тарифы на 15-20% ниже при доставке до ПВЗ. А скорость обработки запросов API в 2 раза выше, чем у Почты России (среднее время ответа 200 мс против 400 мс). Это делает Boxberry оптимальным выбором для интернет-магазинов с большим количеством заказов в регионах.

Как настроить виджет Boxberry за 5 шагов?

1. Получить токен в личном кабинете Boxberry.
2. Подключить JS-скрипт виджета на страницу оформления заказа.
3. Добавить скрытое поле для хранения кода ПВЗ.
4. Создать обработчик callback, который сохраняет код ПВЗ и пересчитывает доставку.
5. Интегрировать с системой доставки Битрикс для расчёта стоимости.

Эти шаги мы автоматизируем в рамках интеграции, поэтому вам не придётся разбираться в деталях.

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

Мы предоставляем полный пакет: настройка API Boxberry, разработка виджета выбора ПВЗ, создание службы доставки в Битрикс, реализация расчёта стоимости, создание отправлений и трекинг. Дополнительно — документация по интеграции, обучение ваших менеджеров и техподдержка в течение месяца после запуска. Сроки от 4 дней. Boxberry API документация подтверждает корректность реализованных методов.

Сроки

Как заказать интеграцию?

Свяжитесь с нами для консультации. Мы проанализируем ваш проект, подготовим коммерческое предложение и спланируем работы. Закажите интеграцию Boxberry с 1С-Битрикс — получите надёжную доставку без головной боли.

Наши инженеры реализовали десятки подобных интеграций. Обращайтесь — поможем настроить Boxberry быстро и без сюрпризов.