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

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

Boxberry — курьерская служба с развитой сетью пунктов выдачи заказов по России. Основной сценарий использования в e-commerce — доставка до ПВЗ, что дешевле доставки до двери. API Boxberry достаточно специфично: авторизация через токен в параметрах запроса (не в заголовке), часть методов работает через GET с JSON в query string. Есть нюансы с расчётом стоимости и передачей данных о товарах.

Особенности API Boxberry

Boxberry API работает через единый эндпоинт: https://api.boxberry.ru/json.php. Метод передаётся параметром method, токен — параметром token. Формат ответа — JSON.

Ключевые методы:

• ListPoints — список ПВЗ
• ListPointsShort — краткий список ПВЗ (быстрее)
• DeliveryCosts — расчёт стоимости
• ParselCreate — создание отправления
• ParselCheck — статус отправления по трек-номеру

Нетипичный момент: данные для ParselCreate передаются через POST, но параметры — URL-encoded, не JSON. Это надо учитывать при построении запросов.

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

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. Обязательно проверяем наличие ошибки перед использованием цены.

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

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

Сроки