msRussianPost
Расчёт доставки Почтой России для MODX 3 и MiniShop3
Системные настройки
Все ключи относятся к пространству имён msrussianpost (префикс в БД: msrussianpost_).
Где изменить: Настройки → Системные настройки — фильтр по namespace msrussianpost.
Быстрый переход из менеджера: Extras → Почта России → Системные настройки — откроется список настроек MODX с фильтром по msrussianpost (если пункт реализован в вашей сборке пакета).
Доставка и параметры расчёта
| Настройка | Описание | По умолчанию |
|---|---|---|
msrussianpost_delivery_id | ID доставок MiniShop3 через запятую. Пусто — авто: все доставки с классом msrussianpost\Delivery\RussianPostDelivery | (пусто) |
msrussianpost_sender_index | Почтовый индекс пункта отправления (6 цифр) | 101000 |
msrussianpost_object_codes | Коды типов отправлений через запятую | 23030,27030 |
msrussianpost_object_labels | Свои подписи в виджете: строки код=текст (допустимы : | или таб между кодом и текстом), по одной на строку. Строки с # в начале — комментарий. Ручные подписи важнее подписи из ответа API | (пусто) |
msrussianpost_tariff_pack | Параметр pack в запросе GET …/v2/calculate/tariff/delivery публичного API. Для EMS RT (27030) без pack API возвращает ошибку 1201. Значение 1 подходит в большинстве случаев. Пустая строка — не передавать pack (редкие сценарии, часть услуг может перестать считаться). Ключ кэша учитывает это поле | 1 |
Популярные коды объектов (ориентир):
| Код | Услуга |
|---|---|
23030 | Посылка онлайн |
27030 | EMS RT |
47030 | Курьер онлайн |
4030 | Бандероль |
2010 | Заказное письмо 1 класса |
Полный перечень удобно смотреть во вкладке Extras → Почта России → Справочник объектов (нужен VueTools).
Для кода 2010 публичный API допускает вес не более 100 г. При большем весе корзины компонент не запрашивает тариф для этого кода (чтобы не получать ошибку 2003 в журнале). Не смешивайте коды писем с посылками без учёта лимитов.
Публичный API часто отдаёт одинаковый caption для разных кодов. Тогда в виджет подставляется название из справочника API по коду. Поле object_labels позволяет задать свои формулировки. После смены подписей очистите кэш на странице компонента (в ключ кэша входит содержимое object_labels).
Справочник кодов объектов расчёта для публичного API — в документации калькулятора Почты России (PDF).
Вес и габариты
| Настройка | Описание | По умолчанию |
|---|---|---|
msrussianpost_default_weight | Вес в граммах, если в корзине нет веса | 1000 |
msrussianpost_weight_coefficient | Множитель веса (например 1000, если вес задан в килограммах) | 1 |
msrussianpost_dimensions_enabled | Передавать в API габариты посылки | 0 |
msrussianpost_default_length | Длина по умолчанию, см | 30 |
msrussianpost_default_width | Ширина по умолчанию, см | 20 |
msrussianpost_default_height | Высота по умолчанию, см | 10 |
msrussianpost_product_length_key | Имя поля длины товара в данных корзины | (пусто → length) |
msrussianpost_product_width_key | Имя поля ширины | (пусто → width) |
msrussianpost_product_height_key | Имя поля высоты | (пусто → height) |
Для каждой позиции корзины читаются три оси (пустые подставляются из дефолтов), в расчёт уходит максимум по каждой оси среди позиций («ящик не меньше самого крупного товара»). Публичный API tariff принимает размеры в сантиметрах. API Отправки POST /1.0/tariff — в миллиметрах (внутри компонента выполняется перевод см × 10). Кэш и журнал учитывают переданные габариты.
API
| Настройка | Описание | По умолчанию |
|---|---|---|
msrussianpost_api_mode | tariff — публичный API. otpravka — персональный API с fallback на tariff при ошибках | tariff |
msrussianpost_api_base_url | Базовый URL публичного API | https://tariff.pochta.ru |
msrussianpost_otpravka_base_url | Базовый URL API Отправки | https://otpravka.pochta.ru |
msrussianpost_otpravka_token | Base64-значение для заголовка X-User-Authorization: Basic <token> | (пусто) |
msrussianpost_otpravka_key | AccessToken для заголовка Authorization: AccessToken <key> | (пусто) |
В режиме otpravka тарифы персональные (в т.ч. по договору), действуют лимиты порядка трети суточного объёма отправлений по данным личного кабинета. Режим tariff — публичные тарифы, отдельной авторизации не требует.
Где взять ключи для API Отправки (otpravka)
Персональный расчёт через otpravka.pochta.ru доступен при договоре с Почтой России и подключённом доступе к API в сервисе Отправка (личный кабинет организации). Без договора и активации API остаётся только публичный режим tariff.
- Зарегистрируйтесь или войдите в личный кабинет Отправки, оформите договорные отношения с Почтой России, если их ещё нет.
- В кабинете откройте раздел API → Настройки (или актуальный аналог в меню личного кабинета). Там выдают пару значений для авторизации запросов.
- Значение для
Authorization: AccessToken …вставьте вmsrussianpost_otpravka_key. Значение дляX-User-Authorization: Basic …(как выдаёт кабинет) — вmsrussianpost_otpravka_token. При расхождении подписей в интерфейсе с заголовками HTTP ориентируйтесь на официальную спецификацию API Отправки (раздел про авторизацию). - В системных настройках MODX выставьте
msrussianpost_api_modeвotpravkaи сохраните настройки. Очистите кэш сайта и при необходимости кэш компонента (см. раздел про кэш ниже).
Если токен или ключ неверные, API вернёт 401 и компонент при включённом fallback доберёт варианты через публичный tariff (см. Интеграция и кастомизация → Режимы API).
В режиме otpravka, если токен и ключ пусты, расчёт выполняется только через публичный API. При ошибках по отдельным кодам недостающие варианты добираются через tariff.
Параметры тарифа
| Настройка | Описание | По умолчанию |
|---|---|---|
msrussianpost_isavia | Авиа: 0 — нет, 1 — авиа, 2 — наземная | 0 |
msrussianpost_sumoc_enabled | Объявленная ценность (стоимость корзины в расчёте) | 1 |
msrussianpost_sumin_enabled | Наложенный платёж / стоимость вложения | 1 |
msrussianpost_services | Дополнительные услуги — коды через запятую | (пусто) |
Кэш и журнал
| Настройка | Описание | По умолчанию |
|---|---|---|
msrussianpost_cache_ttl | TTL кэша ответов API, секунды | 21600 (6 ч.) |
msrussianpost_log_enabled | Писать запросы и ответы в журнал раздела «Почта России» в MODX | 0 |
Кэш хранится в core/cache/msrussianpost/. Очистка — кнопка в разделе Extras → Почта России (панель управления MODX) или смена параметров, влияющих на ключ кэша.
Ориентир по msrussianpost_cache_ttl:
| Сценарий | TTL (сек.) |
|---|---|
| Обычный магазин | 21600 (6 ч.) |
| Частые изменения тарифов | 3600 (1 ч.) |
| Минимум запросов к API | 86400 (24 ч.) |
Рекомендации
- Для рабочего сайта задайте
delivery_id, чтобы виджет не показывался при выборе курьера или самовывоза. - Начните с
api_mode=tariff. Переключайтесь наotpravka, когда есть договор и ключи в личном кабинете Отправки. log_enabledвключайте точечно при диагностике — журнал может разрастаться.
Логотип доставки
В MiniShop3 в списке доставок колонка Логотип берётся из поля logo. При установке или обновлении пакета для всех доставок с классом msrussianpost\Delivery\RussianPostDelivery с пустым логотипом подставляется URL файла assets/components/msrussianpost/img/pochta-ru-logo.png (фирменный знак Почты России).