Что вы получите после настройки:

• Автоматический расчет стоимости доставки в карточке товара и корзине.
• Создание заказов в Почте России в один клик из админки.
• Печать накладных (форма f7p) сразу в PDF.
• Отслеживание посылок в личном кабинете заказа.
• Актуальный список почтовых отделений на карте для покупателя.

Что нужно перед началом

Проверьте, что сервер соответствует требованиям: 

1. PHP версии 8.2 или выше, установленное расширение curl, менеджер зависимостей Composer. Если вы используете хостинг с поддержкой PHP 8.2 — всё готово. Если нет — обратитесь к провайдеру с просьбой обновить версию PHP.
2. Также понадобится доступ к личному кабинету Почты России. Если кабинета еще нет — зарегистрируйтесь на сайте otpravka.pochta.ru. Регистрация бесплатная, занимает пару минут. Договор заключается онлайн, визит в отделение не нужен.

Шаг 1. Получение API-ключей в личном кабинете Почты России

Зайдите в личный кабинет Почты России. Перейдите в раздел «Настройки», затем в подраздел «API доступ». Здесь вам нужно создать ключи, без которых модуль не сможет обращаться к серверам Почты.

Access Token. Нажмите «Создать токен», выберите права на чтение и запись. Скопируйте полученный токен и сохраните в текстовый файл — он показывается только один раз, при обновлении страницы исчезнет.

Authorization Key. Это ваш ключ авторизации, он привязан к логину и паролю от личного кабинета. Находится там же, в разделе API доступа. Выглядит как строка в формате base64. Копируем и сохраняем.

Логин и пароль от личного кабинета Почты России. Обычный логин, который вы используете для входа, и пароль. Важно: не токен, не ключ, а именно логин и пароль от учётной записи.

Важно: Access Token и Authorization Key — разные ключи, не путайте их местами.

Шаг 2. Установка официального SDK Почты России

Модуль использует официальный пакет lapaygroup/russianpost-sdk. Это форк официального SDK, обновлённый для современных версий PHP. Он поддерживает PHP 8.2, 8.3 и 8.4.

Откройте терминал, перейдите в корневую директорию вашего сайта на UniSite CMS. Выполните команду:

composer require lapaygroup/russianpost-sdk

Если Composer не установлен глобально, используйте:

php composer.phar require lapaygroup/russianpost-sdk

Установка занимает несколько секунд. После завершения проверьте, что в папке vendor появилась директория lapaygroup/russianpost. Если директория есть — SDK установлен успешно.

Шаг 3. Установка модуля в UniSite CMS

Сам модуль — это PHP-класс, который нужно разместить в папке с доставками. Перейдите в директорию app/Addons/Delivery вашего сайта, после чего произвести импорт базы данных .sql.

Модуль готов к активации, никаких дополнительных действий не требуется — система сама подхватит новый класс благодаря автозагрузке UniSite CMS.

Шаг 4. Настройка

Заполните поля:

1. Название службы доставки. Можете указать «Почта России», «Доставка Почтой» или любое другое название, которое будет отображаться покупателям на сайте.
2. Access Token. Вставьте токен, полученный в первом шаге. Это длинная строка, копируйте целиком, без пробелов.
3. Authorization Key. Вставьте ключ авторизации из личного кабинета.
4. Логин и пароль. Укажите ваш логин и пароль от личного кабинета Почты России. Эти данные используются для получения временного токена авторизации, который живёт один час. Модуль сам обновляет его автоматически.
5. Индекс отправителя. Укажите почтовый индекс вашего склада или офиса, откуда вы отправляете заказы. Этот индекс будет использоваться при расчёте стоимости доставки, если в карточке товара не указан другой.
6. Тестовый режим. Включите, если хотите протестировать работу модуля без создания реальных заказов. В тестовом режиме запросы уходят на тестовый сервер Почты России, деньги не списываются. Рекомендую сначала проверить всё в тестовом режиме, а потом переключить на боевой.
7. Минимальная и максимальная стоимость доставки. Ограничения по цене, при которых этот способ доставки будет доступен покупателю. Например, если заказ дешевле 500 рублей, доставка Почтой России может не отображаться.
8. Минимальный и максимальный вес. Лимиты по весу в граммах. Почта России принимает посылки весом до 20 000 граммов, но вы можете установить свои ограничения, например, до 10 000 граммов.
9. Минимальные и максимальные габариты. Размеры посылки в сантиметрах: ширина, высота, глубина. Если товар выходит за эти пределы, доставка Почтой России не будет предлагаться покупателю.
10. Нажмите «Сохранить». Служба доставки активирована.

Шаг 5. Загрузка списка почтовых отделений

Модуль умеет автоматически загружать список всех почтовых отделений России в базу вашего сайта. Это нужно, чтобы покупатель мог выбрать удобное отделение на карте при оформлении заказа.

Модуль начнёт загружать отделения. Их много, поэтому процесс может занять до пяти минут. После окончания загрузки у вас в базе появятся все актуальные почтовые отделения с адресами, координатами, расписанием работы и отметкой о приёме банковских карт.

Данные обновляются автомотически, вам не нужно в ручном режиме обновлять пункты выдачи.

Шаг 6. Проверка работы модуля

После настройки проверьте, что всё работает правильно.

1. Создайте тестовый заказ. Перейдите на сайт как обычный покупатель, добавьте товар в корзину, перейдите к оформлению. Среди способов доставки должна появиться Почта России. Выберите её, укажите индекс получателя или выберите отделение на карте. Система рассчитает стоимость доставки и покажет её покупателю. Если сумма отображается корректно — расчёт работает.
2. Завершите тестовый заказ. В админ-панели перейдите в раздел «Заказы», найдите созданный заказ. В карточке заказа должна быть кнопка управления доставкой. Нажмите «Создать отправление». Модуль обратится к API Почты России и создаст заказ. Вы получите трек-номер.
3. Проверьте печать накладной. Нажмите «Скачать накладную» — должен скачаться PDF-файл с формой f7p. Откройте его, убедитесь, что все данные заполнены корректно: адреса, ФИО, вес, сумма.
4. Проверьте отслеживание. Через некоторое время после создания реального заказа статус должен обновиться. В тестовом режиме отслеживание может не работать, поэтому лучше проверять на боевом сервере с реальным заказом.
5. Если на каком-то этапе возникла ошибка, проверьте логи. UniSite CMS записывает ошибки модуля в лог-файл. Откройте папку storage/logs и найдите записи с префиксом pochta_russia. Скорее всего, проблема в неправильно указанных ключах или индексе отправителя.

Частые ошибки и их решение

1. Ошибка авторизации?

• Модуль не может получить временный токен. Проверьте правильность Access Token и Authorization Key. Важно: в личном кабинете Почты России токен и ключ — это разные вещи, не путайте их местами.

2. Ошибка создания заказа?

• Проверьте, что индекс отправителя и получателя указаны корректно. Почта России проверяет существование индекса, и если индекс неверный, заказ не создастся.

3. Стоим0ость не рассчитывается?

• Убедитесь, что указаны корректные индексы отправителя и получателя, вес и габариты не превышают максимально допустимые. Также проверьте, что в личном кабинете Почты России у вас подключён тариф на отправку посылок.

4. Пустой список отделений?

• Возможно, модуль не смог загрузить данные из-за превышения лимита запросов. Подождите пять минут и попробуйте снова. Если не помогает, проверьте логи.

5. Логи ошибок?

• Файлы логов находятся в storage/logs с префиксом pochta_russia. Откройте их и найдите записи с ошибками — это поможет быстро определить причину.
•  

Модуль доставки Почты России для UniSite CMS установлен и настроен. Теперь ваши покупатели могут выбирать доставку почтой, видеть точную стоимость, отслеживать статус заказа, а вы — экономить время на ручном заполнении форм и печати накладных.

Если у вас остались вопросы по настройке, напишите в нашу службу поддержки. Мы поможем с установкой SDK, проверкой ключей и отладкой модуля. Как правило, все вопросы решаются за один сеанс связи. Подключайте доставку Почты России и начинайте отправлять заказы уже сегодня.