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

Boxberry считает стоимость доставки на своей стороне: магазин передаёт параметры отправления, а служба возвращает цену и срок. Поэтому корректный расчёт в 1С-Битрикс зависит не от таблицы тарифов, а от того, какие данные о заказе вы отдаёте в API. Разберём, как подключить Boxberry, из чего складывается цена и почему без веса и габаритов расчёт «поедет».

Как Boxberry рассчитывает стоимость

Boxberry — служба доставки с сетью пунктов выдачи (ПВЗ) и курьерской доставкой «до двери». Тариф она считает не по фиксированным зонам местоположений, а динамически через API: в этом ключевое отличие от штатных служб Битрикс, где вы сами заводите таблицу цен по весу и региону.

В основе тарифа лежит вес, но Boxberry сравнивает физический вес с объёмным — произведением габаритов коробки, делённым на коэффициент объёмного веса, — и берёт большее значение. Габаритный груз (лёгкая, но крупная коробка) считается по объёму, поэтому передавать в запрос один только вес недостаточно: недостающую разницу служба досчитает уже на складе, и цена в корзине разойдётся с фактической.

• До ПВЗ — клиент забирает заказ в пункте выдачи, тариф ниже;
• Курьером до двери — доставка по адресу, считается по индексу города получателя;
• Наложенный платёж — если клиент платит при получении, в расчёт добавляется комиссия за перевод денег.

Что нужно до настройки в Битрикс

Интеграция работает через личный кабинет Boxberry и API-токен. До того как открывать настройки Битрикс, подготовьте три вещи:

1. Заключить договор с Boxberry и получить доступ в личный кабинет;
2. В разделе интеграции сгенерировать API-токен — он авторизует все запросы магазина к сервису;
3. Определить код точки приёма (склада отправки) — он понадобится в расчёте как параметр отправителя.

Токен — это ключ ко всем методам API, поэтому хранить его нужно как пароль и не выводить в клиентский код витрины. В Битрикс он прописывается в настройках службы доставки на стороне сервера.

Установка модуля и профили доставки

Boxberry подключают двумя путями: официальным модулем из Маркетплейс 1С-Битрикс (партнёрское решение Boxberry) или собственным обработчиком доставки на базе класса \Bitrix\Sale\Delivery\Services\Base. Модуль ставится штатно через Marketplace → Установить решение; после установки сбросьте кэш и убедитесь, что модуль активен.

Дальше в разделе Магазин → Настройки → Службы доставки появляются профили Boxberry. Обычно их два:

• Доставка до ПВЗ — с выбором пункта выдачи на карте;
• Курьерская доставка Boxberry — до адреса получателя.

В настройках службы указывают токен, код точки приёма и сопоставляют свойства заказа (город, индекс, код ПВЗ) с параметрами, которые уходят в API. Без корректного маппинга свойств расчёт вернёт ошибку или нулевую цену — это самая частая причина «молчания» службы после установки.

Метод DeliveryCosts и параметры запроса

Стоимость считает метод DeliveryCosts JSON-API по адресу https://api.boxberry.ru/json.php. Запрос авторизуется токеном, а результат зависит от переданных параметров:

В ответе приходят итоговая цена, срок доставки и разбивка по услугам; модуль подставляет их в корзину. Чтобы цена совпадала с фактической отгрузкой, у товаров каталога должны быть заполнены вес и габариты — иначе объёмный вес посчитается неверно.

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

Для доставки до пункта клиент обязан выбрать конкретный ПВЗ: без его кода (параметр target) расчёт невозможен. Boxberry предоставляет готовый JS-виджет выбора пункта на карте — он вызывается методом boxberry.open() и по выбору возвращает код ПВЗ, который магазин сохраняет в свойство заказа.

Список пунктов отдаёт метод ListPoints, а PointsForParcels вернёт только те ПВЗ, что принимают посылки нужных габаритов. У каждого пункта есть код, адрес, режим работы, лимит по весу и признак приёма оплаты картой. Эти ограничения важны: часть пунктов не принимает тяжёлые или крупные отправления, и такой ПВЗ не должен предлагаться клиенту, иначе заказ «зависнет» на этапе передачи в службу.

Кэш пунктов выдачи и агенты

Пунктов выдачи у Boxberry — тысячи, и запрашивать полный ListPoints на каждом хите нельзя: это медленно и упирается в лимиты API. Список кэшируют локально и обновляют по расписанию — обычно агентом Битрикс раз в сутки, а на боевых проектах агенты выносят на cron для предсказуемого запуска.

Схема простая: агент раз в сутки тянет актуальные списки пунктов и городов (ListPoints, ListCities) и складывает их в собственную таблицу или кэш модуля. Витрина и виджет карты работают уже с этими данными, а к живому API обращается только расчёт стоимости конкретного заказа.

• Меньше запросов к API — не упираетесь в ограничения по частоте обращений;
• Быстрее отклик корзины — карта ПВЗ не ждёт ответа внешнего сервиса;
• Устойчивость — кратковременная недоступность Boxberry не роняет оформление заказа.

Диагностика: доставка не считается

Если Boxberry не отдаёт цену, разбирайте по цепочке запроса:

1. Токен. Неверный или тестовый токен в боевых настройках — API вернёт ошибку авторизации. Проверьте значение в настройках службы доставки.
2. Не выбран ПВЗ. Для доставки до пункта без кода target метод DeliveryCosts не отработает — убедитесь, что свойство с кодом ПВЗ реально заполняется при выборе на карте.
3. Пустые вес и габариты. Если у товара нет веса, в API уходит ноль, и цена получается некорректной или нулевой.
4. Сервер не видит api.boxberry.ru. Проверьте исходящий HTTPS с консоли: curl -I https://api.boxberry.ru/json.php. Firewall и заблокированный исходящий трафик — типичная причина тишины.

Итог

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

Если нужно подключить Boxberry с нуля, увязать расчёт с весами и габаритами из 1С или доработать выбор ПВЗ под ваш шаблон корзины, мы настраиваем интеграцию и сопровождаем её, чтобы стоимость в корзине сходилась с фактической отгрузкой.