Экспресс-доставка и курьерские интеграции в Битрикс

Покупатель кладёт товар в корзину, видит «доставим завтра» и закрывает вкладку — ему нужно было сегодня к вечеру. В другой раз он выбирает интервал «14:00–16:00», а курьер приезжает в семь вечера, потому что слот никто не ограничивал и на это время набралось тридцать заказов на одного водителя. Экспресс-доставка выигрывает или проваливается на деталях: слотах, зонах, честной стоимости и статусе, который виден в реальном времени. В 1С-Битрикс всё это собирается из модуля sale, собственных служб доставки и интеграций с курьерскими API.

Ниже — практическая схема, как подключить экспресс и собственную курьерку в магазине на 1С-Битрикс: как завести слоты с вместимостью, определить зону по адресу, посчитать стоимость срочной доставки, создать заявку у курьерского сервиса и показать клиенту статус курьера без перезагрузки страницы. Это выжимка из наших проектов по интеграциям 1С-Битрикс с внешними сервисами — без теории ради теории, с оглядкой на нагрузку и сбои внешних API.

Что такое экспресс-доставка и своя курьерка

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

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

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

Архитектура: слои экспресс-доставки в Битрикс

Чтобы проектировать осознанно, держите в голове внутреннее устройство. Экспресс-доставка в 1С-Битрикс — это не один компонент, а несколько слоёв, каждый со своей зоной ответственности.

• Служба доставки (sale). Штатная сущность модуля торгового каталога и магазина. Именно к ней привязан обработчик, который считает стоимость и сроки экспресса в корзине.
• Обработчик доставки. PHP-класс-наследник базового профиля (Bitrix\Sale\Delivery\Services\Base), где живёт логика расчёта, обращения к API и правила зон.
• Каталог слотов. Отдельное хранилище (highload-блок или своя таблица) с интервалами, их вместимостью и текущей занятостью.
• Модель зон. Полигоны или список районов с геокодированием адреса, определяющие доступность и базовый тариф экспресса.
• Интеграционный слой. Клиент к курьерскому API: расчёт, создание заявки, отмена, приём статусов через вебхук.
• Канал реального времени. Модуль Pull (push-and-pull) или лёгкий JSON-эндпоинт, через который статус курьера доезжает до вкладки клиента.

Запрос покупателя проходит по цепочке: на шаге оформления компонент оформления заказа (sale.order.ajax) вызывает обработчик доставки, тот проверяет зону по адресу, спрашивает у каталога слотов доступные интервалы, считает стоимость и возвращает варианты в корзину. После оплаты событие смены статуса создаёт заявку в курьерском сервисе, а входящие вебхуки обновляют статус заказа и толкают его клиенту. Понимание этой цепочки сразу подсказывает, где искать проблему: если тормозит выбор доставки — смотрим обработчик и API, если «прыгают» статусы — смотрим вебхуки и канал Pull.

Слоты и интервалы: вместимость и бронирование

Слот — это конкретный интервал доставки в конкретной зоне с ограниченной пропускной способностью. Именно вместимость отличает честный экспресс от «обещания, которое некому выполнить». Штатного справочника слотов в модуле sale нет, поэтому его заводят отдельно. Практично хранить слоты в highload-блоке или собственной таблице с такими полями:

На шаге оформления заказа компонент показывает только те интервалы, у которых «занято» меньше «вместимости». Ключевой момент — бронирование должно быть атомарным. Если два покупателя одновременно берут последнее место в слоте, без блокировки оба увидят его свободным и оба забронируют. Поэтому увеличение счётчика занятости делают в транзакции с блокировкой строки (SELECT ... FOR UPDATE) или через атомарный UPDATE ... SET busy = busy + 1 WHERE busy < capacity, проверяя число затронутых строк.

1. Сгенерируйте сетку слотов. Агент по расписанию раскатывает интервалы на N дней вперёд для каждой зоны, учитывая режим работы складов и курьеров.
2. Фильтруйте по наличию. Перед показом уберите слоты, которые физически не успеть выполнить: время «отсечки» на сборку и путь до клиента.
3. Показывайте остаток аккуратно. «Осталось 2 места» подстёгивает к заказу, но не выводите точные цифры там, где это создаёт давление или путаницу.
4. Бронируйте атомарно. При подтверждении заказа увеличивайте счётчик в транзакции и проверяйте, что бронь удалась, иначе предложите соседний интервал.
5. Освобождайте при отмене. Отменённый или не оплаченный вовремя заказ должен возвращать место в слот, иначе интервалы «протухают» занятыми.

Зоны доставки и геокодирование адреса

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

Схема работает так: покупатель вводит адрес, сервис геокодирования (карты) возвращает широту и долготу, а дальше алгоритм «точка в полигоне» определяет, в какую зону попал адрес. Если точка не входит ни в одну зону экспресса — показываем только стандартную доставку или пункты выдачи. Такой подход исключает промахи и позволяет рисовать зоны так, как реально ездят курьеры, а не по административным границам.

• Кэшируйте геокодирование. Один и тот же адрес не нужно геокодировать дважды — храните результат по нормализованной строке адреса, это экономит лимиты API карт.
• Подсказывайте адрес. Автодополнение адреса на вводе резко снижает число «нераспознанных» адресов и ошибок доставки.
• Учитывайте этаж и подъезд. Для экспресса важны не только координаты дома, но и детали, влияющие на время: лифт, домофон, пропуск.
• Держите запасной геокодер. Если основной сервис карт недоступен, переключайтесь на резервный или на определение зоны по индексу как грубое приближение.

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

Стоимость экспресса: из чего складывается цена

Цена срочной доставки — это не одно число из таблицы, а сумма нескольких слагаемых, которые обработчик применяет последовательно. Прозрачная формула защищает и магазин (не возите в убыток), и покупателя (нет неприятных сюрпризов на последнем шаге).

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

Экспресс, курьерская служба и своя курьерка — сравнение

Прежде чем писать код, стоит выбрать модель доставки. У каждого варианта своя цена вопроса и свои требования к системе.

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

Интеграции с курьерскими API

Практически любой курьерский сервис отдаёт REST API с тремя ключевыми группами методов: расчёт стоимости и сроков, создание/отмена заявки, получение статусов. В 1С-Битрикс это оформляют как службу доставки со своим обработчиком — классом-наследником Bitrix\Sale\Delivery\Services\Base (или конфигурируемого профиля). Обработчик в методе расчёта обращается к API и возвращает в корзину цену и срок, а создание заявки вешают на событие смены статуса заказа.

Общая логика интеграции повторяется от сервиса к сервису, различаются только эндпоинты и формат данных. Стандартный набор шагов интеграции:

1. Авторизация. Получите токен или ключ API, храните его в настройках службы доставки, а не в коде. Для OAuth-сервисов предусмотрите обновление токена.
2. Расчёт. В методе расчёта обработчика отправьте в API адрес, вес, габариты и желаемый интервал, получите цену и срок, верните их в корзину.
3. Создание заявки. На событие оплаты или смены статуса создайте в сервисе доставку: адреса забора и вручения, состав, контакты, окно.
4. Приём статусов. Отдельный контроллер принимает вебхуки сервиса, проверяет подпись и обновляет статус заказа в Битрикс.
5. Отмена и переназначение. Предусмотрите отмену заявки при отмене заказа и повторное создание при переносе слота.

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

Статусы в реальном времени и вебхуки

Экспресс без живого статуса — половина ценности. Покупатель, который заплатил за доставку «за 2 часа», хочет видеть, что курьер назначен, забрал заказ и едет. Механика здесь двусторонняя: сервис присылает изменения на ваш вебхук, а вы толкаете их в браузер клиента.

Входящая часть: курьерский сервис при каждой смене статуса отправляет POST на заранее зарегистрированный URL. Контроллер принимает событие, проверяет подпись (HMAC или секретный токен), находит заказ по внешнему идентификатору доставки и меняет его статус в Битрикс. Типичная цепочка статусов: «создана» → «назначен курьер» → «курьер забрал» → «в пути» → «доставлен» (или «отменена», «возврат»).

Исходящая часть: как только статус заказа изменился, его нужно показать клиенту без перезагрузки. Штатный способ в Битрикс — модуль Pull (push-and-pull): сервер отправляет сообщение в канал заказа, а открытая вкладка клиента мгновенно обновляет страницу трекинга. Если Pull-сервер не развёрнут, работает более простой fallback: страница трекинга опрашивает лёгкий JSON-эндпоинт каждые 20–30 секунд и обновляет статус и позицию курьера.

Настройка службы доставки пошагово

Соберём практический порядок внедрения экспресс-доставки в магазине на 1С-Битрикс — от создания службы до боевой проверки.

1. Создайте службу доставки. В «Магазин → Настройки → Службы доставки» заведите новую службу и привяжите к ней собственный обработчик (конфигурируемый профиль или класс-наследник базового).
2. Опишите зоны. Задайте полигоны или список районов обслуживания, базовый тариф и время в пути для каждой зоны; подключите геокодирование адреса.
3. Настройте слоты. Создайте хранилище интервалов с вместимостью и агент, который раскатывает сетку слотов на несколько дней вперёд для каждой зоны.
4. Реализуйте расчёт стоимости. В обработчике опишите формулу: базовый тариф зоны, надбавка за срочность, вес/габариты, коэффициент спроса, порог бесплатной доставки.
5. Подключите курьерский API. Настройте авторизацию, метод расчёта и создание заявки на событие оплаты; пропишите вебхук для приёма статусов.
6. Включите канал статусов. Разверните модуль Pull или настройте JSON-эндпоинт для страницы трекинга, чтобы статус курьера обновлялся без перезагрузки.
7. Проверьте на боевых сценариях. Прогоните оформление в разных зонах, заполнение слота до отказа, отмену с возвратом брони и падение API с запасным сценарием.

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

Настройки экспресс-доставки живут в разделе служб доставки магазина и в параметрах обработчика. Схематично экран настройки службы выглядит так:

Обработчик доставки — сердце интеграции. Его метод расчёта получает корзину и адрес, определяет зону, спрашивает у каталога слотов доступные интервалы и возвращает набор вариантов доставки с ценой и сроком. Логику API и слотов лучше держать в отдельных сервис-классах, а обработчик оставить тонким — так его проще тестировать и переиспользовать между службами (своя курьерка и внешний сервис часто делят один расчёт зон).

Своя курьерка: маршруты и приложение курьера

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

Назначение заказов. Диспетчер или алгоритм распределяет заказы слота между курьерами с учётом зоны, загрузки и близости адресов. На старте достаточно ручного назначения из админки, позже — автоматической группировки заказов в маршруты.

Маршрутизация. Заказы одного слота и зоны выгоднее везти одним маршрутом в разумном порядке. Оптимизацию маршрута можно отдать внешнему сервису построения маршрутов или начать с простой сортировки по близости — даже это заметно сокращает пробег.

Приложение курьера. Курьеру нужен минимум: список его заказов на слот, адреса с картой и кнопки смены статуса («забрал», «в пути», «доставлен», «недозвон»). Это может быть адаптивная веб-страница на том же Битрикс с авторизацией курьера — не обязательно нативное приложение. Каждая смена статуса тут же уходит клиенту тем же каналом Pull, что и статусы внешнего сервиса.

• Одна модель статусов. Держите единый справочник статусов доставки для своей курьерки и внешних сервисов, чтобы витрина клиента не зависела от способа доставки.
• Геометки по желанию. Если курьер передаёт координаты, клиент видит движение на карте; если нет — показывайте текстовый статус, этого часто достаточно.
• Подтверждение вручения. Фото, код или подпись при вручении снижают споры «не доставили» и упрощают разбор проблемных заказов.

Трекинг и карта курьера для клиента

Страница трекинга — это лицо экспресса для покупателя. Хорошая страница отвечает на три вопроса без лишних кликов: на каком этапе заказ, когда ждать курьера и как с ним связаться. Технически она собирает статус из заказа и, если доступно, позицию курьера, и обновляется в реальном времени.

Минимально жизнеспособная страница трекинга содержит: визуальную шкалу статусов (назначен → забрал → в пути → доставлен), ожидаемое окно доставки, имя и телефон курьера на этапе «в пути» и, опционально, карту с меткой курьера. Обновление приходит через Pull или коротким опросом JSON-эндпоинта. Не перегружайте страницу: клиенту важнее ясность, чем анимированная карта, которая тормозит на слабом телефоне.

Отдельно продумайте уведомления вне сайта. Не все держат вкладку трекинга открытой, поэтому ключевые смены статуса дублируйте push-уведомлением, SMS или сообщением в мессенджер: «курьер выехал, будет через 30 минут». Это снижает число недозвонов и несостоявшихся вручений — самой дорогой проблемы экспресса.

Отказоустойчивость и таймауты API

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

• Короткие таймауты. Держите таймаут обращения к API в пределах 2–3 секунд. Лучше показать расчёт по кэшу, чем заставлять покупателя ждать зависший запрос.
• Кэш ответов. Кэшируйте расчёт по ключу «зона + вес + интервал» на несколько минут — это и ускоряет, и защищает от кратких сбоев сервиса.
• Circuit breaker. Если сервис массово отдаёт ошибки, временно перестаньте его дёргать и переключитесь на запасной сценарий, а не колотите в мёртвый эндпоинт на каждый расчёт.
• Резервная служба. Держите запасной вариант доставки (другой сервис или стандартная доставка), который подхватит, если основной экспресс недоступен.
• Очередь для заявок. Создание заявки в сервисе делайте через очередь с ретраями: если API не ответил, заявка создастся при следующей попытке, а заказ уже принят.

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

Нагрузка, очереди и метрики

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

Что измерять, чтобы управлять качеством экспресса:

• Время расчёта доставки в корзине. Держите в пределах сотен миллисекунд на тёплом кэше — это прямо влияет на конверсию оформления.
• Доля успешных обращений к API. Падение ниже нормы — сигнал включить запасной сценарий и разобраться с сервисом.
• Заполняемость слотов. Показывает, где не хватает курьеров, а где ёмкость простаивает; основа для планирования смен.
• Доля доставок в срок (SLA). Ключевая метрика экспресса: сколько заказов приехало в обещанное окно.
• Число недозвонов и переносов. Дорогая проблема; растёт — усиливайте проактивные уведомления.

Планирование ёмкости слотов и распределение нагрузки по интервалам — отдельная большая тема. Как выстроить логистику слотов и не «перепродать» вечерние окна, мы подробно разбираем в статье про логистику и слоты доставки в Битрикс.

Частые ошибки при внедрении

• Показывают слоты без ограничения вместимости — вечерний интервал перепродаётся, и курьер физически не успевает к части клиентов.
• Определяют зону по названию города, а не по координатам — адреса на границах районов уходят не в ту зону или отваливаются.
• Дёргают курьерский API синхронно на каждый пересчёт корзины без кэша и таймаута — медленный сервис тормозит всё оформление.
• Не проверяют наличие товара на ближайшем складе до показа слотов — обещают «через 2 часа» то, что физически не привезти.
• Обрабатывают вебхуки статусов не идемпотентно — дубль события создаёт вторую заявку или дважды списывает бронь слота.
• Не освобождают слот при отмене или неоплате заказа — интервалы «протухают» занятыми и закрывают продажи.
• Нет запасного сценария на случай сбоя API — падение внешнего сервиса роняет оформление заказа целиком.
• Не проверяют подпись вебхука — система доверяет любому входящему POST и принимает поддельные статусы.

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

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

1. Служба и обработчик готовы. Создана служба доставки с собственным обработчиком, логика зон и слотов вынесена в отдельные сервис-классы.
2. Зоны описаны и геокодятся. Полигоны заданы, адрес определяется по координатам, результат геокодирования кэшируется, есть запасной геокодер.
3. Слоты с вместимостью. Сетка интервалов раскатывается агентом, бронирование атомарно, отмена возвращает место в слот.
4. Стоимость прозрачна. Формула «зона + срочность + вес + спрос + порог» реализована и настраивается без правки кода.
5. API подключён отказоустойчиво. Короткий таймаут, кэш расчёта, circuit breaker, очередь на создание заявки, резервная служба доставки.
6. Статусы в реальном времени. Вебхук принимает и проверяет подпись, обработка идемпотентна, обновление уходит клиенту через Pull или опрос.
7. Трекинг и уведомления. Есть страница трекинга со шкалой статусов и проактивные уведомления «курьер в пути».
8. Метрики сняты. Замеряются время расчёта, доля успешных вызовов API, заполняемость слотов, доставка в срок и число недозвонов.

Вывод

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