Расчёт доставки через сторонний API-агрегатор

Когда магазин работает сразу с несколькими перевозчиками, удобно получать тарифы из единой точки. Агрегатор доставки отдаёт стоимость и сроки по API, а задача Битрикса — корректно собрать данные отправления, запросить расчёт и показать цену покупателю в корзине.

Зачем считать доставку через агрегатор

Прямая интеграция с каждой службой (СДЭК, Boxberry, DPD, Почта России) — это отдельные ключи, форматы и обработчики. Агрегатор вроде единого API логистики берёт эту работу на себя: вы отправляете один запрос с параметрами отправления и получателя, а в ответ приходит список тарифов от подключённых у агрегатора перевозчиков.

В 1С-Битрикс такой расчёт реализуется как собственная служба доставки с типом «Расчёт по обработчику». Обработчик в момент оформления заказа обращается к API и возвращает цену. Это даёт три выигрыша:

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

Как устроен расчёт доставки в Битрикс

Расчётом отгрузки в D7 занимается служба доставки — наследник \Bitrix\Sale\Delivery\Services\Base. Ключевой метод — calculateConcrete(Shipment $shipment), который обязан вернуть объект \Bitrix\Sale\Delivery\CalculationResult.

Внутри результата вы устанавливаете цену и срок:

• setDeliveryPrice() — итоговая стоимость доставки;
• setPeriodDescription() — текст срока («2–4 дня»);
• addError() — если расчёт невозможен, служба скроется из списка.

Из объекта Shipment доступны все данные корзины: вес через getWeight() (в граммах), сумма товаров через getPrice(), коллекция позиций и связанный заказ через getCollection()->getOrder(). Местоположение получателя берётся из свойств заказа или из выбранного местоположения доставки. Именно эти значения превращаются в тело запроса к агрегатору.

Свой обработчик как служба доставки

Регистрируется обработчик через событие onSaleDeliveryHandlersClassNamesBuildList модуля sale. В обработчике события вы возвращаете массив вида «код класса → путь к файлу», после чего служба появляется в списке при создании доставки в Магазин → Настройки → Службы доставки.

Минимальный каркас класса:

• getClassTitle() и getClassDescription() — название в админке;
• getConfigStructure() — поля настроек: URL API, токен, идентификатор договора, склад отправления, наценка;
• isCalculatePriceImmediately() — вернуть true, если цена нужна сразу в списке служб;
• calculateConcrete() — сам расчёт.

Если агрегатор отдаёт несколько тарифов (курьер, ПВЗ, постамат), удобнее сделать профильную службу: родитель наследует Base, а профили-потомки соответствуют типам доставки. Тогда покупатель видит их как отдельные варианты с разными ценами.

Формирование запроса к API агрегатора

Внутри calculateConcrete() собирается payload. Типовой набор полей для расчёта:

Запрос отправляется через штатный \Bitrix\Main\Web\HttpClient (или JsonHttpClient). Обязательно задайте разумные таймауты — setTimeout() и waitResponse(), — потому что запрос выполняется синхронно в момент оформления заказа и «висящий» агрегатор напрямую тормозит корзину. Ответ парсится через \Bitrix\Main\Web\Json::decode(), из него выбирается нужный тариф, применяется наценка и результат кладётся в setDeliveryPrice().

Кэш, таймауты и обработка ошибок

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

• ключ кэша = хэш от города, веса, габаритов и суммы заказа;
• хранилище — \Bitrix\Main\Data\Cache с TTL 10–30 минут;
• при совпадении параметров отдаём цену из кэша без обращения к API.

Отдельно продумайте поведение при сбое. Если агрегатор недоступен или вернул ошибку, метод не должен ронять оформление заказа. Разумные стратегии:

1. вернуть CalculationResult с addError() — служба просто исчезнет из списка;
2. подставить резервный фиксированный тариф (fallback), чтобы покупатель всё же оформил заказ;
3. записать причину в журнал через \Bitrix\Main\Diag\FileExceptionHandlerLog или свой логгер для последующего разбора.

Ограничения, профили и цена в корзине

Не для каждого заказа расчёт через агрегатор уместен. Чтобы служба показывалась только там, где нужно, используйте штатные ограничения доставки (\Bitrix\Sale\Delivery\Restrictions): по местоположению, весу, сумме или способу оплаты. Это дешевле, чем гонять API ради заведомо неподходящих отправлений.

Когда агрегатор возвращает несколько вариантов, покажите их корректно:

• для доставки в ПВЗ и постаматы понадобится выбор точки на карте — цена может зависеть от конкретного пункта;
• наценку и округление применяйте единообразно, чтобы цифра в корзине совпадала с чеком;
• срок из setPeriodDescription() выводите рядом со стоимостью — это снижает вопросы в поддержку.

Итоговая стоимость доставки автоматически попадает в компонент оформления заказа sale.order.ajax и пересчитывается при изменении состава корзины, так что отдельно верстать её обычно не требуется.

Итог

Расчёт доставки через агрегатор в 1С-Битрикс — это собственная служба доставки, где calculateConcrete() собирает параметры отправления, запрашивает тариф по API через HttpClient и возвращает CalculationResult. Надёжность решения держится на трёх вещах: кэшировании ответов, коротких таймаутах и аккуратном fallback при сбоях агрегатора.

Если нужно спроектировать такой обработчик, увязать его с профилями, ПВЗ и наценками или разобрать нестабильные ответы стороннего API, мы помогаем с интеграционной разработкой на Битрикс — от расчёта тарифов до создания накладных и трек-номеров.