Подключение 5Post и постаматов

5Post — логистический сервис X5 Group с сетью постаматов и пунктов выдачи в «Пятёрочке» и «Перекрёстке». В типовом 1С-Битрикс отдельного обработчика для него нет, поэтому службу доставки собирают либо из модуля Маркетплейса, либо на собственной интеграции с REST API. Разберём оба пути, настройку выбора постамата на кассе и передачу заказов в отгрузку.

Что даёт 5Post и как он устроен для магазина

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

Для магазина на Битрикс это значит, что нужно решить три задачи: показать точки на карте в оформлении заказа, рассчитать стоимость доставки до выбранной точки и передать заказ в личный кабинет или API 5Post для формирования отгрузки. Всё это ложится на службу доставки Битрикса и на обмен с внешним сервисом.

Два способа подключения

Готового встроенного обработчика 5Post в дистрибутиве Битрикса нет, поэтому выбирают один из двух путей.

Модуль ставится штатно через Marketplace → Каталог решений или загрузкой архива; после установки он добавляет обработчик в Магазин → Настройки → Службы доставки. Свою интеграцию делают отдельным модулем с классом-наследником Bitrix\Sale\Delivery\Services\Base, который сам ходит в API 5Post за тарифами и точками.

Создание службы доставки в админке

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

• Название и логотип — то, что видит покупатель в корзине;
• Ограничения — по местоположению, весу и сумме заказа; здесь отсекают регионы без точек 5Post и негабаритные посылки;
• Расчёт стоимости — либо фиксированные тарифы Битрикса, либо расчёт через профиль обработчика, который тянет цену из API;
• Профили — можно завести отдельно «Постамат» и «Пункт выдачи», если тарифы и сроки различаются.

Привязка к местоположениям использует штатный модуль sale.location. Если города точек 5Post не совпадают со справочником местоположений, ограничения будут работать неверно — сверьте справочник до запуска.

API 5Post: авторизация и методы

Интеграция строится на REST API. Доступ выдаётся по API-ключу (Bearer-токен) из личного кабинета 5Post; токен передают в заголовке Authorization каждого запроса. Для интеграции обычно нужны четыре группы методов:

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

Запросы удобно отправлять через встроенный Bitrix\Main\Web\HttpClient, а справочник точек — кэшировать, чтобы не дёргать API на каждый хит корзины. Ключ и адрес API выносят в настройки службы или в .settings.php, а не в код.

Выбор постамата на кассе

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

Технически это делают так: в компонент sale.order.ajax (или в кастомный шаг чекаута) добавляют блок с картой (Яндекс.Карты) и списком точек, полученных из API 5Post и отфильтрованных по городу покупателя. Выбранную точку записывают в свойство заказа типа «строка» — как правило, код точки плюс её адрес для читаемости.

1. Покупатель выбирает город — фронт запрашивает точки этого города;
2. Точки рисуются метками на карте и списком;
3. Выбор точки сохраняет её код в свойстве заказа;
4. При передаче в API этот код уходит как пункт выдачи.

Передача заказов, штрихкоды и статусы

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

Автоматизацию вешают на событие смены статуса заказа (OnSaleOrderSaved или обработчик статуса): при статусе «Передан в доставку» модуль формирует отправление, получает штрихкод и трек-номер и записывает их обратно в заказ. Дальше трек показывают покупателю и периодически опрашивают API для обновления статуса доставки.

• Штрихкод отправления печатают на этикетку и клеят на посылку;
• Трек-номер отдают покупателю в письме и в личном кабинете;
• Статусы обновляют агентом или cron-скриптом, а не на каждом хите.

Если магазин ведёт заказы в 1С, отправления и трек-номера логично прокидывать через тот же обмен, чтобы менеджер работал в одном окне.

Типичные проблемы

Что чаще всего ломается при подключении 5Post:

1. Точки не показываются. Обычно причина — истёкший токен, недоступность API с сервера или пустой ответ по городу, которого нет в сети 5Post. Проверьте ответ API напрямую и логи HttpClient.
2. Не совпадают местоположения. Ограничение службы по региону не срабатывает, если города точек не привязаны к справочнику sale.location.
3. Заказ уходит без кода точки. Свойство заказа не заполняется, если фронт не сохранил выбор на карте — проверьте, что идентификатор точки реально попадает в свойство.
4. Отправление отклонено. Чаще всего из-за превышения габаритов или веса ячейки постамата — добавьте эти ограничения в службу доставки заранее.

Итог

Подключение 5Post к 1С-Битрикс — это связка из службы доставки в админке, интеграции с REST API (свой ключ, справочник точек, тарифы и создание отправлений) и удобного выбора постамата на карте в чекауте. Отдельно продумайте ограничения по весу и габаритам под ячейку постамата, привязку точек к справочнику местоположений и логирование обмена, чтобы отслеживать отказы.

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