Интеграция со сторонним агрегатором доставки (API)

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

Что такое агрегатор доставки и когда он нужен

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

В «1С-Битрикс: Управление сайтом» готового обработчика под конкретного агрегатора в коробке нет, поэтому интеграция — это кастомная разработка на модуле sale. Иногда партнёрский модуль есть в Маркетплейс 1С-Битрикс, но чаще под задачи магазина пишется собственный обработчик, чтобы контролировать наценку, кэш и логику выбора перевозчика.

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

Основа интеграции — класс-обработчик, унаследованный от Bitrix\Sale\Delivery\Services\Base (для профилей — Bitrix\Sale\Delivery\Services\Automatic или конфигурируемая база). Регистрируется он на событие onSaleDeliveryHandlersClassNamesBuildList модуля sale, которое возвращает массив вида «код класса → путь к файлу». После регистрации служба появляется в Магазин → Настройки → Службы доставки как обычный обработчик.

В обработчике описывают:

• настройки (метод getConfigStructure()) — токен API агрегатора, идентификатор договора, город-отправитель, режим наценки;
• расчёт (метод calculateConcrete()), возвращающий Bitrix\Sale\Delivery\CalculationResult со стоимостью и сроком;
• профили — если хотите завести отдельные записи под «до двери» и «до ПВЗ» разных перевозчиков.

Внешние запросы выполняйте через Bitrix\Main\Web\HttpClient, а не через прямой curl: это даёт единые таймауты, работу через прокси и корректную обработку заголовков.

Расчёт стоимости и сроков через API

В методе calculateConcrete() вам доступна отгрузка (Bitrix\Sale\Shipment): из неё берут вес и габариты корзины, объявленную ценность, адрес и код местоположения получателя. Эти данные упаковывают в запрос к эндпоинту расчёта агрегатора и разбирают ответ — обычно список вариантов «перевозчик + тариф + цена + срок».

Дальше есть два подхода к выдаче в корзине:

1. Один вариант — минимальная цена или заранее заданный приоритет: обработчик сам выбирает перевозчика и возвращает одну строку доставки. Проще для покупателя.
2. Несколько вариантов — по профилю на перевозчика: каждый тариф агрегатора маппится в свой профиль службы, и в оформлении заказа виден выбор.

Стоимость возвращают через $result->setDeliveryPrice(), срок — через период доставки в результате. Наценку агрегатора и собственную комиссию закладывайте на стороне обработчика, а не «зашивайте» в ответ API.

Ограничения и когда служба доступна

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

Однако главные ограничения агрегатора динамические — они приходят в ответе расчёта. Практика такая: грубые условия (вес до N кг, только по РФ) вешают на ограничения службы, а тонкую фильтрацию делают в обработчике по ответу API. Полезно логировать причины отказа, чтобы понимать, почему по конкретному адресу доставка не предложилась.

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

Пункты выдачи и адресация

Для тарифов «до ПВЗ» покупателю нужно выбрать пункт. Агрегатор отдаёт список ПВЗ по городу через отдельный эндпоинт; его кэшируют и выводят на карте в оформлении заказа. Выбранный пункт сохраняют в свойстве заказа (обычно тип «Строка» или «Местоположение») — его код затем уходит в запрос на создание отправления.

Ключевой момент — маппинг местоположений. Битрикс адресует по своему справочнику местоположений (модуль sale, Bitrix\Sale\Location), а агрегатор — по своим кодам городов или КЛАДР/ФИАС. Нужен слой соответствия: по коду местоположения заказа определить город в системе агрегатора. Часто для этого используют внешние коды местоположений или отдельную таблицу связей.

Создание отправления и трек-номер

Расчёт — половина интеграции. Вторая половина — передача заказа в агрегатора и получение трек-номера. Обычно это делают не в момент оформления, а когда менеджер собрал заказ: по смене статуса отгрузки формируется запрос на создание отправления с адресом, ПВЗ, местами и суммой наложенного платежа.

Технически создание вешают на события модуля sale — например OnSaleShipmentDeducted или OnSaleOrderSaved — либо на периодический агент (Битрикс → Настройки → Агенты), который выбирает готовые отгрузки без трек-номера и создаёт их пакетно. Возвращённый номер и ID отправления сохраняют в свойствах отгрузки.

Кэш, лимиты и отказоустойчивость

API агрегатора — внешняя зависимость в критичном месте (оформление заказа), поэтому надёжность важнее, чем в фоновых обменах. Базовые приёмы:

• Кэш расчётов — результат по ключу «город + вес + габариты» держат несколько минут через Bitrix\Main\Data\Cache, чтобы не дёргать API на каждый пересчёт корзины.
• Таймауты — задавайте разумный таймаут в HttpClient (2–3 секунды на расчёт): корзина не должна «висеть» из-за медленного ответа.
• Деградация — при недоступности API покажите запасной фиксированный тариф или спрячьте службу с понятным сообщением, а не белый экран.
• Лимиты (rate limit) — массовое создание отправлений выносите в фон и обрабатывайте ответы 429/таймауты с повторными попытками.

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

Итог

Интеграция агрегатора доставки в 1С-Битрикс — это собственный обработчик службы на модуле sale: регистрация через событие, расчёт в calculateConcrete(), ограничения службы, выбор ПВЗ с маппингом местоположений и создание отправлений по статусу отгрузки. Отдельного внимания требуют кэш расчётов, таймауты, идемпотентность и журнал обмена — именно на них держится стабильная работа корзины и отсутствие дублей накладных.

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