docs.modx.pro
msRussianPost
msRussianPost
Расчёт доставки Почтой России для MODX 3 и MiniShop3
  • MODX 3
  • PHP 8.2
  • miniShop3
  • Vue 3
  1. Компоненты
  2. msRussianPost
  3. Быстрый старт

Быстрый старт ​

Пошаговое подключение расчёта доставки Почтой России к оформлению заказа MiniShop3.

Установка ​

Требования ​

ТребованиеВерсия
MODX Revolution3.0.3+
PHP8.2+
MiniShop3актуальная версия
VueToolsпо желанию: для раздела Extras → Почта России в панели управления MODX

Провайдер ModStore ​

Транспортный пакет зашифрован. Установщик снимает шифрование ключом, который получает у провайдера modstore.pro. Без провайдера установка прерывается с ошибкой Package provider not found.

  1. Система → Управление пакетами → Провайдеры → добавьте modstore.pro:
    • URL: https://modstore.pro/extras/
    • Email и API-ключ из личного кабинета modstore.pro
  2. Подключите репозиторий ModStore, чтобы пакет появился в каталоге установщика.

Через Менеджер пакетов ​

  1. Откройте Extras → Installer
  2. Найдите пакет msRussianPost в каталоге ModStore (Download Extras), в Show Details укажите провайдер modstore.pro
  3. Нажмите Установить
  4. Настройки → Очистить кэш

Ручная загрузка архива не сработает

Содержимое категории компонента в транспортном пакете лежит в зашифрованном виде, а установщик прерывает установку при ошибке шифрования. Архив, загруженный в установщик вручную или собранный на машине без провайдера modstore.pro, установку не пройдёт: ставить пакет нужно из ModStore с подключённым провайдером. Сборка для разработки делается без шифрования ('encrypt' => false в _build/config.inc.php), но в дистрибуцию такой пакет не идёт.

Анонимная статистика при установке и обновке

Резолвер пакета отправляет на metrics.modx.pro обезличенные сведения о среде: версии MODX, PHP и SAPI, MiniShop3, pdoTools, тип и версия базы данных, семейство ОС, веб-сервер, версия пакета и её предыдущая версия при обновке, тип установки и язык контекста по умолчанию. Домен сайта, IP-адреса и данные заказов не передаются.

Запрос уходит один раз, при установке и при обновке, с таймаутом 2 секунды: недоступность сервера не мешает установке. Системной настройки для отключения в пакете нет, отключить отправку можно только на уровне сервера, например правилом firewall или записью в hosts для metrics.modx.pro.

После установки появятся:

  • 25 системных настроек (фильтр в Настройки → Системные настройки: msrussianpost)
  • пункт меню Extras → Почта России и вложенный пункт Системные настройки (право settings)
  • сниппеты msRussianPost и msrpLexiconScript
  • чанки tplRussianPostStatus и tplRussianPostMethods
  • плагин msRussianPost Autoload на событие OnMODXInit с приоритетом -100: класс доставки он подгружает и без себя (см. ниже), а в контексте mgr добавляет блок «Выбранный тариф Почты России» с автозагрузкой данных по заказу
  • плагин msRussianPost Delivery на событие msOnGetDeliveryCost
  • плагин msRussianPost Order tariff на события msOnSubmitOrder, msOnBeforeCreateOrder, msOnCreateOrder — переносит выбранный код тарифа в свойства заказа для отображения в карточке заказа в менеджере MiniShop3

Класс доставки подгружается без плагина

Файл core/components/msrussianpost/bootstrap.php подключается ядром при инициализации пространства имён, то есть до OnMODXInit, и сам подгружает RussianPostDelivery.php. Плагин msRussianPost Autoload эту задачу дублирует, поэтому выключать его ради класса не нужно: без плагина класс всё равно доступен MiniShop3.

Проверка: откройте Extras → Почта России. Если видны табы «Тестовый расчёт», «Журнал запросов», «Справочник объектов» — админка компонента доступна. Если показано предупреждение про VueTools, установите пакет VueTools через установщик (для витрины и виджета на чекауте VueTools не обязателен).

При обновлении пакета системные настройки сохраняются, сниппеты, чанки и плагины подтягиваются до версии из пакета. Обновление с прежних версий дополнительно мигрирует пространство имён msrussianpost2 → msrussianpost и ключи настроек: msrussianpost2_* → msrussianpost_*, точечные msrussianpost.* → msrussianpost_*. После обновления очистите кэш (Настройки или Управление → Очистить кэш, либо кнопка на странице Extras → Почта России).

Шаг 1: Способ доставки в MiniShop3 ​

  1. Extras → MiniShop3 → Настройки → Доставки → создайте доставку (например «Почта России»).
  2. Поля:
    • price: 0 (стоимость считает обработчик)
    • class: msrussianpost\Delivery\RussianPostDelivery
    • validation_rules (пример): {"index": "required|digits:6", "city": "required", "first_name": "required", "last_name": "required", "phone": "required"}
  3. Сохраните и запомните числовой ID доставки.

MiniShop3 — настройка способа доставки Почта России

MiniShop3 — настройка способа доставки Почта России

Шаг 2: Системные настройки ​

Настройки → Системные настройки, фильтр: msrussianpost.

Минимум:

КлючДействие
msrussianpost_delivery_idУкажите ID из шага 1 (несколько ID — через запятую). Пусто: в JS подставляются все доставки с классом msrussianpost\Delivery\RussianPostDelivery (auto). Если таких нет — виджет может показываться при любой доставке (any). Для рабочего сайта задайте ID явно
msrussianpost_sender_indexИндекс отправителя, 6 цифр (например индекс вашего склада)

Остальные параметры — Системные настройки.

Быстрый переход из панели управления MODX: Extras → Почта России → Системные настройки — откроется список настроек с фильтром по msrussianpost. Пункт вложен в меню компонента при установке пакета и требует права settings.

Шаг 3: Виджет в чанке заказа ​

Вставьте блок внутрь формы оформления заказа (обычно чанк tpl.msOrder), после выбора доставки. Нужна одна обёртка с классом msrp__wrapper или атрибутом data-msrp-widget — по ней скрипт показывает и скрывает блок при смене доставки.

Порядок: сначала лексикон для JS, затем сниппет (он подключает CSS и russianpost.js и выставляет window.msRussianPostConfig), затем чанки статуса и методов.

Подсказки адреса и индекс (mxDadata)

Чтобы покупатель выбирал адрес из подсказок DaData и в заказ попадал индекс, установите mxDadata и выведите [[!mxDadataAddressSuggest]] (или Fenom-эквивалент) выше блока с msrpLexiconScript / msRussianPost. Порядок вывода и событие mxdadata:order-address-updated — в разделе Подключение на сайте → mxDadata.

Блок виджета Почты России

fenom
<div class="msrp__wrapper" data-msrp-widget>
    {'msrpLexiconScript' | snippet}
    {'msRussianPost' | snippet}
    {'tplRussianPostStatus' | chunk}
    {'tplRussianPostMethods' | chunk}
</div>
modx
<div class="msrp__wrapper" data-msrp-widget>
    [[!msrpLexiconScript]]
    [[!msRussianPost]]
    [[$tplRussianPostStatus]]
    [[$tplRussianPostMethods]]
</div>

Fenom и auto_escape

При включённом auto_escape выводите сниппеты как сырой HTML ({raw ...} или эквивалент в вашей версии Fenom), иначе скрипты могут экранироваться.

Не оборачивайте чанки в лишние блоки с классами .msrp__status или .msrp__methods: эти классы уже заданы внутри tplRussianPostStatus и tplRussianPostMethods.

Параметры сниппета msRussianPost: connectorUrl, indexSelector, debug — см. msRussianPost. Первые два объявлены в свойствах сниппета и видны в админке, debug в свойствах не объявлен: задавайте его прямо в вызове сниппета или через ?msrp_debug=1 в адресе.

Шаг 4: Проверка ​

  1. Откройте страницу оформления заказа, выберите доставку «Почта России» — должен появиться блок виджета.
  2. Введите корректный 6-значный индекс — должны загрузиться методы и цены.
  3. В панели управления MODX откройте Extras → Почта России. При установленном VueTools должны открываться табы «Тестовый расчёт», «Журнал запросов», «Справочник объектов». Если VueTools нет, интерфейс раздела может быть недоступен. На витрину магазина это не влияет. Подробное описание вкладок — Админка в MODX.

Блок виджета Почты России

При проблемах включите отладку: параметр сниппета &debug=1 или параметр ?msrp_debug=1 в адресе страницы — см. раздел Интеграция и кастомизация → Отладка.

Что дальше ​