Системные настройки

Все ключи относятся к пространству имён msrussianpost (префикс в БД: msrussianpost_).

Где изменить: Настройки → Системные настройки — фильтр по namespace msrussianpost.

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

Служебный ключ msrussianpost_core_path в списке основных настроек нет: пакет создаёт его только миграцией со старого точечного ключа msrussianpost.core_path при обновлении. Его читает контроллер страницы админки, чтобы найти файл шаблона. По умолчанию используется core/components/msrussianpost/templates/default/index.tpl. Создавать ключ вручную нужно, только если вы переносили шаблон в другое место.

Доставка и параметры расчёта

Настройка	Описание	По умолчанию
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. Одно значение на все коды из object_codes; для 23030 обычно подходит 1. Пустая строка — не передавать pack: часть услуг без него не считается. Ключ кэша учитывает это поле	1

Пакет не разбирает коды ошибок API по полю pack: он передаёт значение как есть и показывает текст ошибки из ответа Почты. Проверяйте реакцию API на конкретный код на вкладке «Тестовый расчёт» и в журнале запросов.

Популярные коды объектов (ориентир):

Код	Услуга
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 — публичные тарифы, отдельной авторизации не требует.

Таймаут HTTP-запросов к обоим API жёстко задан в коде: 10 секунд на запрос. Настройки для него в пакете нет. При недоступности Почты виджет показывает ошибку расчёта, а при включённом msrussianpost_log_enabled запрос попадает в журнал.

Где взять ключи для API Отправки (otpravka)

Персональный расчёт через otpravka.pochta.ru доступен при договоре с Почтой России и подключённом доступе к API в сервисе Отправка (личный кабинет организации). Без договора и активации API остаётся только публичный режим tariff.

1. Зарегистрируйтесь или войдите в личный кабинет Отправки, оформите договорные отношения с Почтой России, если их ещё нет.
2. В кабинете откройте раздел API → Настройки (или актуальный аналог в меню личного кабинета). Там выдают пару значений для авторизации запросов.
3. Значение для Authorization: AccessToken … вставьте в msrussianpost_otpravka_key. Значение для X-User-Authorization: Basic … (как выдаёт кабинет) — в msrussianpost_otpravka_token. При расхождении подписей в интерфейсе с заголовками HTTP ориентируйтесь на официальную спецификацию API Отправки (раздел про авторизацию).
4. В системных настройках MODX выставьте msrussianpost_api_mode в otpravka и сохраните настройки. Очистите кэш сайта и при необходимости кэш компонента (см. раздел про кэш ниже).

Если токен или ключ неверные, API вернёт 401 и компонент при включённом fallback доберёт варианты через публичный tariff (см. Интеграция и кастомизация → Режимы API).

В режиме otpravka, если токен и ключ пусты, расчёт выполняется только через публичный API. При ошибках по отдельным кодам недостающие варианты добираются через tariff.

Параметры тарифа

Настройка	Описание	По умолчанию
msrussianpost_isavia	Приоритетная доставка, уходит в публичный API как isavia. Значение приводится к целому и передаётся без проверки, допустимые значения задаёт Почта России	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) или смена параметров, влияющих на ключ кэша.

Журнал запросов — обычный текстовый файл core/cache/msrussianpost_requests.log по строке на запрос. Панель показывает последние 100 строк, кнопка Очистить журнал удаляет файл. Путь и лимит выборки в коде заданы жёстко, настроек для них в пакете нет.

Ориентир по 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 (фирменный знак Почты России).