Интеграция 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 против других служб доставки
По сравнению с СДЭК, интеграция Boxberry требует больше ручного контроля из-за отсутствия вебхуков. Однако Boxberry выигрывает в стоимости — тарифы на 15-20% ниже при доставке до ПВЗ. А скорость обработки запросов API в 2 раза выше, чем у Почты России (среднее время ответа 200 мс против 400 мс). Это делает Boxberry оптимальным выбором для интернет-магазинов с большим количеством заказов в регионах.
Как настроить виджет Boxberry за 5 шагов?
- Получить токен в личном кабинете Boxberry.
- Подключить JS-скрипт виджета на страницу оформления заказа.
- Добавить скрытое поле для хранения кода ПВЗ.
- Создать обработчик callback, который сохраняет код ПВЗ и пересчитывает доставку.
- Интегрировать с системой доставки Битрикс для расчёта стоимости.
Эти шаги мы автоматизируем в рамках интеграции, поэтому вам не придётся разбираться в деталях.
Что входит в работу?
Мы предоставляем полный пакет: настройка API Boxberry, разработка виджета выбора ПВЗ, создание службы доставки в Битрикс, реализация расчёта стоимости, создание отправлений и трекинг. Дополнительно — документация по интеграции, обучение ваших менеджеров и техподдержка в течение месяца после запуска. Сроки от 4 дней. Boxberry API документация подтверждает корректность реализованных методов.
Сроки
| Состав | Срок |
|---|---|
| Расчёт + виджет ПВЗ + создание отправления | 4–5 дней |
| + Polling статусов + маппинг | +2 дня |
| + Этикетка для печати | +1 день |
Как заказать интеграцию?
Свяжитесь с нами для бесплатной консультации. Мы проанализируем ваш проект, подготовим коммерческое предложение и спланируем работы. Закажите интеграцию Boxberry с 1С-Битрикс — получите надёжную доставку без головной боли.
Наши инженеры реализовали десятки подобных интеграций. Обращайтесь — поможем настроить Boxberry быстро и без сюрпризов.