Інтеграція 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% — у 8 разів менше помилок.
Як працює Boxberry API?
API Boxberry надає кілька ключових методів. ListPoints та ListPointsShort — отримання списку ПВЗ. DeliveryCosts — розрахунок вартості доставки. ParselCreate — створення відправлення (тільки POST). ParselCheck — перевірка статусу за трек-номером. Відповіді завжди JSON, за винятком ParselCreate, де передача даних URL-encoded. Ми розробили єдиний метод apiRequest, який коректно обробляє всі ці випадки. За офіційною документацією Boxberry API, рекомендується використовувати api_version=1.0 для сумісності.
Розрахунок вартості доставки
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 та прискорити роботу на 30%.
Клас служби доставки
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();
}
}, 'ВАШ_ТОКЕН', 'Київ', '', 0, 'e');
</script>
Функція приймає callback, токен, місто за замовчуванням, додаткові параметри. Результат result.id — код ПВЗ для API. Ми адаптуємо віджет під дизайн вашого сайту та інтегруємо з кошиком.
Детальніше про налаштування віджета
Віджет Boxberry дозволяє також задати обмеження за типом ПВЗ (курьєр, постомат) та радіусом пошуку. Ми налаштовуємо ці параметри для оптимізації досвіду користувача.Створення відправлення
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 для інтернет-магазину меблів з обсягом понад 200 замовлень на день. До інтеграції створення відправлення займало до 8 секунд через ручне введення даних. Після автоматизації час скоротився до 1.2 секунд — у 6,7 разів швидше, а кількість помилок при передачі даних зменшилася на 90%. Проєкт реалізовано за 6 днів, включаючи віджет, розрахунок і трекінг. Вартість інтеграції починається від 500 доларів, що окупається за 2-3 місяці за рахунок економії часу менеджерів.
Етапи роботи
- Збір даних та аналіз вашої конфігурації Бітрікс.
- Аудит поточних процесів доставки.
- Проєктування архітектури інтеграції.
- Оцінка та узгодження обсягу робіт.
- Розробка та налаштування.
- Тестування на тестовому середовищі.
- Запуск та моніторинг.
Що входить в роботу?
- Налаштування API Boxberry (отримання токена, методи).
- Розробка віджета вибору ПВЗ з адаптацією під дизайн.
- Створення служби доставки в Бітрікс з розрахунком вартості.
- Реалізація створення відправлень при оформленні замовлення.
- Трекінг статусів через polling та мапінг статусів.
- Документація та навчання менеджерів.
- Техпідтримка протягом місяця після запуску.
Орієнтири за термінами
- Базова інтеграція (розрахунок + віджет + створення відправлення): 4–5 днів.
- Додавання трекінгу та мапінгу статусів: +2 дні.
- Етикетка для друку: +1 день.
- Повний цикл: до 7 днів.
Як замовити інтеграцію?
Зв'яжіться з нами для безкоштовної консультації. Ми проаналізуємо ваш проєкт, підготуємо комерційну пропозицію та сплануємо роботи. Замовте інтеграцію Boxberry з 1С-Бітрікс — отримайте надійну доставку без головного болю.
Наші інженери — сертифіковані фахівці з 10+ роками досвіду на ринку. Ми гарантуємо якість робіт та супровід після запуску. Звертайтеся — допоможемо налаштувати Boxberry швидко та без сюрпризів.