Интеграция служб доставки по API в 1С-Битрикс

Покупатель дошёл до корзины, ввёл город — и хочет увидеть, сколько стоит доставка СДЭК до его пункта выдачи, когда посылка приедет и во что обойдётся Почта России. Если магазин показывает вместо этого «стоимость доставки уточнит менеджер», часть заказов теряется прямо на этом шаге. В 1С-Битрикс всё это решается интеграцией служб доставки по API: расчёт тарифа в реальном времени, выбор ПВЗ на карте, автоматическое создание отправления и трек-номер, который сам подтягивает статусы.

Ниже — практический разбор, как подключить СДЭК, Почту России, Boxberry и агрегаторы доставки к 1С-Битрикс: где брать тарифы, как не уронить оформление заказа таймаутом внешнего сервиса, как хранить трек-номера и показывать статусы посылки. Это выжимка из наших проектов по интеграции 1С-Битрикс с внешними сервисами — с акцентом на надёжность, а не на «лишь бы заработало на демо».

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

Доставка — это тот шаг воронки, где покупатель принимает финальное решение. Он уже выбрал товар, но хочет понимать три вещи: сколько стоит доставка именно до него, куда её можно получить и когда она приедет. Если магазин отвечает на эти вопросы мгновенно и точно, конверсия оформления растёт; если заставляет ждать звонка менеджера — часть корзин просто закрывается.

Ручной режим («менеджер посчитает и перезвонит») работает только на малых объёмах. Как только заказов становится десятки в день, а перевозчиков — несколько, ручной расчёт превращается в источник ошибок: неверная зона, устаревший тариф, забытый трек-номер, потерянная посылка. Интеграция по API снимает всю эту рутину и переносит её в код, который считает одинаково точно и в час ночи, и в пик распродажи.

Ключевое отличие интеграции по API от «модуля, который просто есть» — в контроле. Прямое подключение к API перевозчика даёт вам управление кэшированием, таймаутами, форматом ярлыков, набором статусов и логикой фолбэков. Вы не ждёте, пока автор стороннего модуля обновит его под новую версию API СДЭК, и не тащите в проект десяток функций, которые вам не нужны. Для среднего и крупного магазина это выигрыш и по скорости страницы, и по совокупной стоимости владения.

Наконец, API-интеграция — это фундамент автоматизации всей логистики. Однажды связав магазин с перевозчиками, вы получаете возможность автоматически создавать отправления при переходе заказа в статус «Собран», печатать ярлыки пачками, отдавать покупателю живой трекинг и сводить аналитику по срокам и стоимости доставки в разрезе перевозчиков. Всё это невозможно, пока доставка живёт в голове менеджера и в мессенджере.

Что даёт API перевозчика: четыре сценария

Чтобы проектировать интеграцию осознанно, полезно разложить её на независимые сценарии. У всех крупных перевозчиков API устроено похоже и закрывает одни и те же четыре задачи.

• Расчёт стоимости и срока. По городу назначения, весу, габаритам и объявленной стоимости API возвращает тариф и ориентировочный срок. Это то, что видит покупатель в корзине.
• Справочник пунктов выдачи (ПВЗ). Список точек самовывоза с координатами, адресами, режимом работы и ограничениями по весу/габаритам. Нужен для выбора ПВЗ на карте.
• Создание отправления. Регистрация заказа у перевозчика: магазин отдаёт данные отправителя, получателя и вложения, а в ответ получает номер отправления (трек-номер) и, как правило, печатную форму ярлыка.
• Отслеживание статусов. Получение текущего статуса посылки по трек-номеру: либо вебхуками (перевозчик сам шлёт события), либо опросом (магазин спрашивает статусы по расписанию).

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

Архитектура интеграции доставки в 1С-Битрикс

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

• Слой транспорта. Единый HTTP-клиент к API перевозчика: авторизация, таймауты, ретраи, разбор ошибок. Один на каждого перевозчика, с общим интерфейсом.
• Слой нормализации. Приводит разные ответы перевозчиков к единой внутренней модели «вариант доставки»: код службы, тариф, срок, тип (курьер/ПВЗ/постамат). Благодаря ему витрина не знает, чей это тариф — СДЭК или Boxberry.
• Слой кэша. Тарифы и справочники ПВЗ, которые не нужно тянуть на каждый запрос. Тарифы — на часы, справочник ПВЗ — на сутки и дольше.
• Слой интеграции с ядром. Обработчики служб доставки Битрикса, свойства заказа и отгрузки, события на смену статуса заказа, агенты и очереди.
• Слой представления. Компонент оформления заказа, виджет карты ПВЗ, блок трекинга в личном кабинете.

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

Второй принцип — изоляция перевозчиков за единым интерфейсом. Каждый перевозчик прячется за адаптером с одинаковыми методами: calculate(), getPickupPoints(), createShipment(), getStatus(). Витрина и бэк-офис работают с абстрактной «службой доставки», а не с particularities СДЭК или Почты. Добавить нового перевозчика или заменить прямую интеграцию на агрегатор становится вопросом одного адаптера, а не переписывания половины проекта. Про то, как очереди и надёжность связаны с интеграциями в целом, мы подробно писали в материале про API, очереди и надёжность интеграций в Битрикс.

СДЭК, Почта России, Boxberry: что у них в API

У каждого перевозчика свои особенности авторизации, форматов и ограничений. Знать их полезно ещё на этапе оценки, чтобы не наткнуться на сюрпризы в середине проекта. Ниже — обобщённая картина по трём самым частым перевозчикам российского e-commerce.

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

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

Boxberry исторически строит API вокруг единой точки входа, где нужный метод задаётся параметром. Это чуть непривычно, но покрывает весь цикл: расчёт, справочник ПВЗ и городов, создание посылки, получение ярлыка и статусов. Хорошо подходит, когда основной канал — выдача в пунктах, а не курьер.

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

Агрегаторы доставки против прямых интеграций

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

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

Расчёт стоимости: тарифы, кэш и таймауты

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

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

Второе правило — кэшировать по осмысленному ключу. Тариф зависит от города назначения, суммарного веса, габаритов и объявленной стоимости. Ключ кэша складывается из этих параметров. Два покупателя из одного города с одинаковой по весу корзиной получают тариф из кэша, а не два отдельных запроса к перевозчику.

Третье правило — жёсткий таймаут и фолбэк. Любой синхронный вызов API оборачивайте таймаутом в 2–5 секунд. Если перевозчик не ответил вовремя, витрина не должна зависать: показываете последний закэшированный тариф, фиксированную ставку по зоне или сообщение «стоимость уточнится при подтверждении», но заказ оформить даёте. Недоступность внешнего сервиса — это нормальная, ожидаемая ситуация, и интеграция обязана её переживать.

Пункты выдачи (ПВЗ) и карта в оформлении заказа

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

Правильная схема работы с ПВЗ выглядит так:

1. Загрузите справочник ПВЗ в своё хранилище. По расписанию (агент/cron) выгружайте актуальный список пунктов из API перевозчиков в highload-блок или служебную таблицу: код точки, координаты, адрес, город, режим работы, ограничения по весу и габаритам.
2. Отдавайте ПВЗ на фронт из своего хранилища. При оформлении заказа фильтруйте точки по выбранному городу (по коду КЛАДР/ФИАС или названию) и отдавайте их JSON-ом для карты — быстро и без обращения к перевозчику.
3. Нарисуйте карту. Виджет карт показывает точки, покупатель выбирает удобную. По клику подставляется её код и адрес.
4. Сохраните выбор в отгрузку. Код выбранного ПВЗ и его адрес пишутся в свойство отгрузки, чтобы потом уйти в API при создании отправления.
5. Обновляйте справочник регулярно. Точки открываются и закрываются, поэтому раз в сутки-неделю справочник перезагружается, а «мёртвые» точки помечаются недоступными.

Хранение ПВЗ в highload-блоке даёт ещё один бонус: точки можно обогащать своими полями — например, отметкой «есть примерочная», «принимает оплату картой», приоритетом показа. Витрина работает с вашим нормализованным справочником, а не с сырым ответом перевозчика, и это делает выбор ПВЗ и быстрым, и гибким.

Трек-номера, статусы и вебхуки

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

Где хранить трек-номер. Номер отправления получают в ответе на создание отправления и сохраняют в свойство отгрузки (а часто дублируют в свойство заказа для удобства). Отдельная служебная таблица трекинга хранит историю статусов: когда, какой статус, от какого перевозчика. История нужна и для покупателя (живой трекинг), и для аналитики сроков.

Как получать статусы. Есть два подхода, и они не равнозначны:

• Вебхуки (push). Перевозчик сам присылает событие о смене статуса на ваш URL. Это лучший вариант: статусы обновляются почти мгновенно и без лишней нагрузки. Требует публичного эндпоинта, проверки подписи и идемпотентной обработки (одно и то же событие может прийти дважды).
• Опрос (pull). Магазин сам спрашивает статусы по трек-номерам. Делать это надо не поштучно и не синхронно, а пакетно, по расписанию: агент или cron берёт активные отправления батчами и запрашивает их статусы. Опрос — фолбэк для перевозчиков без вебхуков и страховка на случай пропущенных событий.

Оптимальная схема — комбинировать: основной канал вебхуки, а раз в несколько часов пакетный опрос «подчищает» отправления, по которым событий давно не было. Каждое изменение статуса пишется в историю, и на ключевых переходах («Прибыл в пункт выдачи», «Вручён») покупателю уходит уведомление. Так трекинг остаётся достоверным, даже если один вебхук потерялся.

Реализация в 1С-Битрикс: модули и компоненты

Разберём, где именно в 1С-Битрикс живут части интеграции доставки. Платформа даёт готовый каркас служб доставки, и грамотная интеграция встраивается в него, а не воюет с ним.

• Модуль «Интернет-магазин» (sale). Ядро логики заказов, отгрузок и служб доставки. Именно здесь регистрируется своя служба доставки и обработчик расчёта.
• Обработчик службы доставки. Класс-наследник базового обработчика доставки, который реализует расчёт стоимости и срока. В нём вы и вызываете свой адаптер перевозчика (через кэш и таймаут).
• Свойства заказа и отгрузки. Здесь хранятся выбранный ПВЗ, его код и адрес, трек-номер, служебные идентификаторы отправления.
• События (EventManager). Обработчик на смену статуса заказа (например, «Собран» → создать отправление) и на сохранение заказа.
• Агенты и cron. Пакетный опрос статусов, обновление справочника ПВЗ, повторная отправка неудавшихся операций из очереди.
• Highload-блоки. Хранилище справочника ПВЗ и, при необходимости, зон и тарифов.
• Компоненты витрины. Кастомизированный шаблон sale.order.ajax (оформление заказа) с виджетом карты ПВЗ и блоком выбора способа доставки.

Типичный поток внедрения выглядит так. Расчёт: регистрируете свою службу доставки, обработчик через адаптер и кэш возвращает тарифы, компонент оформления показывает их покупателю. ПВЗ: агент наполняет highload-блок, шаблон оформления рисует карту и сохраняет выбор в свойство отгрузки. Отправления: событие на статус «Собран» кладёт задачу в очередь, воркер создаёт отправление у перевозчика, пишет трек-номер в отгрузку. Статусы: вебхук-эндпоинт и агент обновляют историю трекинга и статус отгрузки.

Важно не изобретать своё там, где Битрикс уже даёт каркас. Служба доставки, отгрузки, свойства и события — штатные механизмы, и опираться нужно на них. Ваш код — это адаптеры к перевозчикам, слой кэша/нормализации и очередь. Такой баланс делает интеграцию совместимой с обновлениями платформы и понятной следующему разработчику.

Как это выглядит в админке 1С-Битрикс

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

Ключи API (токены СДЭК, Boxberry, ключ авторизации Почты) хранят в настройках своего модуля интеграции или в защищённом конфиге, а не в коде компонента. Для каждого перевозчика полезно предусмотреть переключатель «тестовый / боевой контур», чтобы безопасно отлаживать создание отправлений, не регистрируя реальные посылки. Про типовые проблемы и способы диагностики интеграций мы отдельно писали в материале про интеграцию грузовых транспортных компаний в B2B на Битрикс — многие приёмы применимы и к курьерской доставке.

Надёжность: очереди, ретраи и фолбэки

Интеграция с внешним сервисом надёжна ровно настолько, насколько она готова к его сбоям. API перевозчика будет иногда медленным, иногда недоступным, иногда возвращать ошибку — это не форс-мажор, а штатная реальность. Хорошая интеграция проектируется вокруг этого факта.

• Очередь для тяжёлых операций. Создание отправления, печать ярлыка, массовая выгрузка не должны блокировать пользователя. Ставьте задачу в очередь, а воркер выполняет её фоном с ретраями.
• Ретраи с экспоненциальной задержкой. Временную ошибку (таймаут, 5xx, сетевой сбой) повторяют не сразу и не бесконечно, а с растущими паузами и ограничением попыток. Постоянную ошибку (неверные данные, 4xx) повторять бессмысленно — её отправляют в разбор.
• Идемпотентность. Повторный запуск операции не должен создавать дубль отправления. Используйте ключ идемпотентности или проверку «отправление по этой отгрузке уже создано».
• Фолбэк на витрине. Расчёт не ответил — показываем кэш или фиксированный тариф. Справочник ПВЗ недоступен — отдаём последнюю выгрузку. Витрина деградирует мягко, а не падает.
• Circuit breaker. Если перевозчик стабильно падает, временно перестаём его дёргать и переключаемся на фолбэк, чтобы не копить зависшие запросы.

Эти принципы — не «золочение», а необходимый минимум для боевого магазина. Разница между «интеграция иногда роняет оформление заказа» и «покупатель ничего не замечает при сбое перевозчика» — это как раз очередь, ретраи и фолбэки. Подробнее про очереди и устойчивость интеграций — в отдельной статье про API, очереди и надёжность в Битрикс.

Безопасность ключей и данные покупателя

Интеграция доставки работает с персональными данными (ФИО, адрес, телефон получателя) и с секретами (токены и ключи перевозчиков). И то, и другое требует аккуратного обращения.

• Секреты — вне репозитория. Токены и ключи храните в защищённом конфиге или настройках модуля, а не в коде и не в git. Разграничьте тестовые и боевые ключи.
• Минимум данных наружу. В API перевозчика уходит только то, что нужно для доставки. Не передавайте лишние сведения о покупателе и о содержимом заказа сверх требуемого.
• Проверка входящих вебхуков. Эндпоинт для статусов должен проверять подпись/токен запроса, иначе кто угодно сможет присылать фейковые статусы. Обрабатывайте события идемпотентно.
• HTTPS и валидация. Все вызовы — по HTTPS с проверкой сертификата. Ответы перевозчика валидируйте: не доверяйте формату вслепую.
• Логи без утечек. В логи не пишите полные токены и чувствительные данные покупателя в открытом виде — маскируйте.

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

Метрики и мониторинг интеграции

«Доставка работает» — субъективное ощущение. Чтобы управлять интеграцией, за ней нужно наблюдать. Вот метрики, которые стоит собирать по каждому перевозчику отдельно.

Практический минимум мониторинга: логируйте каждый вызов API с длительностью и кодом ответа, считайте долю ошибок по перевозчику, следите за длиной очереди и числом задач, ушедших в «разбор». Всплеск ошибок конкретного перевозчика вы должны видеть до того, как о нём сообщат покупатели. А сводка «средний срок и стоимость доставки по перевозчикам» помогает бизнесу выбирать, кого продвигать в оформлении заказа.

Частые ошибки при интеграции

• Синхронный вызов API перевозчика на каждый ввод в поле адреса — витрина тормозит и упирается в лимиты запросов.
• Нет таймаута и фолбэка — падение или медленный ответ перевозчика вешает оформление заказа для всех покупателей.
• Справочник ПВЗ тянется из API на каждый заказ вместо периодической выгрузки в highload-блок — лишняя нагрузка и медленная карта.
• Весь справочник в десятки тысяч точек отдаётся на фронт разом — страница оформления раздувается и тормозит на мобильных.
• Статусы опрашиваются поштучно и синхронно вместо вебхуков или пакетного опроса — упор в лимиты и отставание трекинга.
• Создание отправления не идемпотентно — повтор операции или двойной клик плодит дубли посылок у перевозчика.
• Токены и ключи лежат в коде или в git — риск утечки и боль при ротации.
• Нет разделения тестового и боевого контура — отладку ведут на боевом API и регистрируют реальные посылки.
• Не логируются вызовы и ошибки — невозможно понять, какой перевозчик и почему подводит.
• Адрес для Почты уходит без нормализации — отправления отклоняются, менеджеры разбирают вручную.

Чек-лист внедрения

Сведём всё в практический список, по которому удобно принимать готовность интеграции доставки перед запуском:

1. Адаптеры за единым интерфейсом. Каждый перевозчик спрятан за адаптером с методами расчёта, ПВЗ, создания отправления и статусов; витрина работает с абстрактной службой доставки.
2. Расчёт закэширован и защищён. Тарифы кэшируются по осмысленному ключу, вызовы обёрнуты таймаутом с фолбэком; debounce на вводе адреса.
3. Справочник ПВЗ в своём хранилище. Точки выгружаются в highload-блок по расписанию, на фронт отдаются по городу/области карты.
4. Отправления создаются фоново. Событие на статус заказа кладёт задачу в очередь; операция идемпотентна; трек-номер пишется в отгрузку.
5. Статусы обновляются надёжно. Настроены вебхуки с проверкой подписи и пакетный опрос-подстраховка; история статусов пишется.
6. Надёжность заложена. Ретраи с задержкой, ограничение попыток, circuit breaker, мягкая деградация витрины при сбое.
7. Секреты и данные под контролем. Ключи вне кода, HTTPS, минимум данных наружу, логи без утечек, тестовый и боевой контуры разделены.
8. Мониторинг включён. Собираются время ответа, доля ошибок, попадания в кэш, длина очереди по каждому перевозчику.

Вывод

Интеграция служб доставки по API в 1С-Битрикс — это не «поставить модуль», а выстроить четыре устойчивых сценария: быстрый расчёт тарифа через кэш и таймаут, выбор ПВЗ из своего справочника на карте, фоновое создание отправлений с трек-номером и достоверный трекинг через вебхуки. Спрячьте каждого перевозчика — СДЭК, Почту, Boxberry, агрегатор — за единым адаптером, проектируйте от отказа внешнего сервиса, измеряйте метрики по каждому перевозчику. Тогда доставка перестанет быть узким местом воронки и превратится в конкурентное преимущество магазина. Смежные вопросы расчёта и выбора ПВЗ мы также разбираем в статье про доставку СДЭК и Boxberry.