Інтеграція 1С-Бітрікс зі службою доставки Boxberry

Інтеграція 1С-Бітрікс зі службою доставки Boxberry

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

Особливості API Boxberry

API Boxberry працює через єдиний ендпоінт: 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

Терміни