VibeFox USPS for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

Приложение в USPS Developer Portal (только для тарифов в реальном времени): войдите в USPS Developer Portal (developers.usps.com) с бесплатным бизнес-аккаунтом USPS, создайте приложение и скопируйте его Consumer Key и Consumer Secret. Модуль использует актуальные API USPS с OAuth 2.0. USPS отключила старый Web Tools API (User ID и XML) 25 января 2026 года, поэтому Web Tools User ID больше не работает. Без ключей используются только фиксированные цены.

Ship-from ZIP code: для тарифов в реальном времени нужен 5-значный ZIP-код США, с которого отправляются посылки.

Лицензионный ключ VibeFox: покупается на vibefox.net. Один ключ работает на одном домене.

Установка

1. В панели администратора перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox USPS в списке модулей и нажмите Configure.

3. Вставьте лицензионный ключ VibeFox в поле License key в блоке лицензии вверху страницы Configure и нажмите Activate (см. Лицензионный ключ).

4. Введите Consumer Key и Consumer Secret, 5-значный Ship from ZIP code и выберите услуги. Если валюта магазина по умолчанию не USD, введите USD exchange rate. По желанию введите фиксированные цены как запасной вариант. Нажмите Save.

При установке модуль создаёт перевозчика USPS с текстом срока доставки Delivery by USPS. Перевозчик назначается всем зонам и всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox USPS > Configure. Они действуют для всех зон перевозчика. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает кэш токена USPS и тарифов.

Недопустимое значение не сохраняется: остаётся предыдущее значение, ошибка указывает поле, а остальные поля сохраняются. Предупреждения вверху страницы сообщают, если заполнен только один из ключей, ключей и фиксированных цен нет (тогда перевозчик никогда не показывается), не указан ZIP-код отправки, не выбрана ни одна услуга, не задан курс USD, включена тестовая среда, неизвестна единица веса или размера магазина (задаётся в International > Localization, Local units) или перевозчик USPS был удалён.

Общие

Enable USPS shipping: включает или выключает перевозчика. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

Name: название перевозчика, которое видит покупатель при оформлении заказа. По умолчанию: USPS. Обязательно, до 64 символов.

Tax status: налоговое правило перевозчика. Тарифы USPS не включают налоги. Выберите налоговое правило, чтобы добавить налог на доставку, или None, если доставка не облагается налогом.

API USPS (тарифы в реальном времени)

Consumer Key: Consumer Key (client_id) вашего приложения разработчика USPS.

Consumer Secret: Consumer Secret (client_secret) того же приложения. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Очистка Consumer Key также удаляет сохранённый секрет.

Test environment: использует USPS Testing Environment for Mailers (apis-tem.usps.com). Только для приложений, которым он доступен. Для реальных цен оставьте выключенным (apis.usps.com). По умолчанию: выключено.

Prices: какие тарифы USPS используются.

Services: услуги USPS, которые могут предлагаться. Показывается самая дешёвая выбранная услуга, которую USPS предлагает для посылки. Тарифы Flat Rate, Cubic, Hold for Pickup и Sunday никогда не используются. По умолчанию: USPS Ground Advantage, Priority Mail и First-Class Package International Service. Если не выбрана ни одна услуга, тарифы в реальном времени не используются.

USD exchange rate: тарифы USPS указаны в USD. Если валюта магазина по умолчанию не USD, введите цену 1 USD в этой валюте, например 0.92. Без него тарифы в реальном времени не используются, и действуют фиксированные цены. Не нужен, если валюта по умолчанию USD. Должен быть больше 0.

Cache: кнопка Clear cached USPS token and rates сразу очищает кэш. Тарифы кэшируются на 1 час, неудачный тариф — на 10 минут. После таймаута, ошибки сервера, ограничения частоты запросов или отклонённых ключей USPS не запрашивается в течение 5 минут.

Отправка и посылка (тарифы USPS зависят от ZIP-кода отправки, веса и размера посылки; корзина рассчитывается как одна посылка, а посылки более 70 фунтов используют фиксированные цены)

Ship from ZIP code: 5-значный ZIP-код США, с которого отправляются посылки. ZIP+4 обрезается до 5 знаков. Другие значения отклоняются с сообщением.

Box size: необязательные размеры коробки в единицах измерения размеров вашего магазина, например 30x20x15. Оставьте пустым, чтобы собрать размер из размеров товаров: наибольшая длина, наибольшая ширина и сложенные высоты. Если у товара нет размеров, используется коробка 10 x 8 x 4 дюйма.

Default product weight: вес в кг для товаров без веса, в тарифах USPS, ограничениях по весу и весовых категориях. По умолчанию: 0.5.

Фиксированные цены (цены в валюте магазина по умолчанию, без налогов; используются, когда не введены ключи API, и как запасной вариант, если USPS не возвращает тариф: API недоступен, неверные ключи, нет услуги или назначение без ZIP-кода США; оставьте оба поля пустыми, чтобы скрыть перевозчика в этом случае)

Country prices: цены по стране назначения и весу корзины. Нажмите Add country, чтобы добавить строку, и значок корзины, чтобы удалить её. Столбцы: Price и весовые категории XS (до 1 кг), S (1–2 кг), M (2–3 кг), L (3–5 кг) и XL (более 5 кг). Пустая категория или 0 использует Price. Строка * Default (any other country) действует для любой другой страны. Строка страны без цены отправляет эту страну в Fallback cost. Значения, которые не являются числами, очищаются с сообщением.

Fallback cost: фиксированная цена, когда ни одна цена по стране не подходит. Оставьте пустым, чтобы скрыть перевозчика в этом случае.

Fixed price is: Per order берёт цену один раз по весу всей корзины. Per item (each item priced by its own weight x quantity) рассчитывает каждый товар по весу одной единицы (вес по умолчанию, если его нет) и умножает на количество. Тарифы USPS в реальном времени всегда рассчитываются на всю посылку.

Условия

Free shipping from: сумма корзины (после скидок, до налогов), начиная с которой этот перевозчик бесплатный. Запрос в USPS в этом случае не отправляется. Оставьте пустым, чтобы никогда не предлагать бесплатную доставку.

Minimum subtotal: показывать перевозчика, только если сумма корзины не меньше этой суммы. Оставьте пустым, чтобы показывать всегда.

Min weight: минимальный вес корзины в кг, при котором перевозчик появляется. 0 означает без ограничения.

Max weight: перевозчик скрывается при весе корзины больше этого значения в кг. По умолчанию: 30. USPS принимает до 70 фунтов (31,7 кг). 0 означает без ограничения. Если Min weight больше Max weight, показывается ошибка и сохраняются предыдущие ограничения.

Доступность без зон доставки

Ignore shipping zones: предлагать перевозчика во всех зонах для стран, указанных ниже. При сохранении перевозчик привязывается ко всем зонам магазина, в том числе созданным позже. При выключении перевозчик получает обратно свои прежние зоны.

Countries: страны назначения для этого режима. Оставьте пустым, чтобы разрешить все страны, в которые магазин доставляет. Это поле используется только при включённой опции Ignore shipping zones.

Дополнительно

Debug log: записывает запросы к API и расчёт тарифов в logs/vfd_usps_debug.log.php в папке модуля. Файл нельзя открыть из браузера. Ошибки API записываются всегда, даже когда эта опция выключена. Ключи, токены и адреса клиентов никогда не записываются.

Log: показывает размер журнала и последние записи. Нажмите Clear log, чтобы очистить его.

Remove data on uninstall: если включено, при удалении модуля удаляются настройки USPS, перевозчик, сохранённые услуги заказов, кэш тарифов и журналы. Если выключено, всё сохраняется для повторной установки.

Как это работает при оформлении заказа

На этапе доставки PrestaShop запрашивает у модуля цену USPS. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в сумму корзины. Модуль сначала проверяет условия: разрешённые страны (с Ignore shipping zones), вес корзины и минимальную сумму. Если применяется бесплатная доставка, цена равна 0 и запрос в USPS не отправляется.

Модуль получает токен OAuth от USPS и хранит его до незадолго до истечения срока. Токен, который USPS отклонил, обновляется, и расчёт повторяется. Для назначений в США и их территориях (Пуэрто-Рико, Виргинские острова США, Гуам, Американское Самоа, Северные Марианские острова, Федеративные Штаты Микронезии, Маршалловы Острова и Палау) модуль обращается к API Domestic Prices и требует 5-значный ZIP-код покупателя. Для других стран он обращается к API International Prices с указанием страны и почтового индекса.

Запрос содержит ZIP-код отправки, вес корзины в фунтах, размер посылки в дюймах и тип цены. Посылки более 70 фунтов получают фиксированные цены. Покупатель видит один вариант с самой дешёвой выбранной услугой, пересчитанной из USD в валюту магазина по умолчанию и затем показанной в валюте корзины покупателя.

Каждый расчёт кэшируется на 1 час. Неудачный расчёт запоминается на 10 минут. После таймаута, ошибки сервера, ограничения частоты запросов или отклонённых ключей USPS не запрашивается в течение 5 минут. Таймаут HTTP — 10 секунд.

Если USPS не возвращает тариф, цена берётся из Country prices, затем из Fallback cost. Если ни один вариант не подходит, перевозчик скрывается. Покупатель никогда не видит текстов ошибок USPS. Причина записывается в журнал.

Если вы редактируете перевозчика в Shipping > Carriers после того, как у него появились заказы, PrestaShop сохраняет его как новую версию перевозчика. Модуль автоматически переходит на новую версию.

Модуль только рассчитывает тарифы. Он не покупает почтовые марки и этикетки, не заказывает курьеров, не отслеживает посылки и не позволяет покупателю выбрать отделение почты или пункт выдачи. Он показывает один вариант, а не несколько услуг USPS. Упаковки в коробки нет: корзина рассчитывается как одна посылка. Страховка и другие дополнительные услуги не включены.

Заказы

Когда заказ оформляется с перевозчиком USPS, модуль сохраняет, как была определена цена доставки. На странице заказа в панели администратора показывается блок USPS с USPS service (для тарифа в реальном времени, например USPS Ground Advantage) и Price source: USPS live rate, Fixed price или Free shipping.

Лицензионный ключ

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox USPS находится первым на странице Modules > Module Manager > VibeFox USPS > Configure, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now, чтобы проверить статус снова, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Под ними находятся строка Product: presta-shipping-usps и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока соответствуют языку панели администратора (есть английский и русский).

Если ключ не принят, блок сообщает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с указанием даты. После смены адреса магазина или после освобождения слота домена в аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: домене основного магазина, в том числе при мультимагазинной конфигурации. Удаление ключа из магазина не освобождает слот домена. Освободите слот в своём аккаунте vibefox.net.

Без активного ключа перевозчик USPS не показывается покупателям при оформлении заказа, и тариф не рассчитывается. Витрина PrestaShop не знает, что вы вошли в панель администратора, поэтому перевозчик скрыт и для вас: модуль можно настроить до покупки ключа, но проверить его при оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются.

Когда срок лицензии истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус проверяется снова автоматически, пока вы работаете в панели администратора: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Задание cron не нужно. При удалении или сбросе модуля лицензионный ключ и статус лицензии всегда удаляются.

Устранение неполадок

USPS не появляется при оформлении заказа: проверьте, что лицензия активна и включена опция Enable USPS shipping. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя, или включите Ignore shipping zones и проверьте Countries. Проверьте ограничения по весу и Minimum subtotal. Без работающих ключей USPS перевозчику нужна фиксированная цена (Country prices или Fallback cost). Товары также можно ограничить определёнными перевозчиками на странице товара.

Тарифы в реальном времени не появляются: проверьте предупреждения вверху страницы модуля. Включите Debug log, перезагрузите оформление заказа и посмотрите поле Log. Там записываются неверные ключи, неправильная среда и сообщения об ошибках USPS. Внутренним тарифам нужен 5-значный ZIP-код покупателя.

Мой магазин не в USD: USPS рассчитывает тарифы только в USD. Введите USD exchange rate. Без него тариф в реальном времени не используется, и вместо него показывается фиксированная цена.

Web Tools User ID не работает: старый Web Tools API отключён. Создайте приложение в USPS Developer Portal и используйте его Consumer Key и Consumer Secret.

Тарифы выглядят устаревшими после изменения: кэш очищается при сохранении настроек. Также можно нажать Clear cached USPS token and rates.

На странице написано, что перевозчик USPS не найден: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его снова.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox USPS и выберите Uninstall. Лицензионный ключ и статус лицензии удаляются всегда. Кэш токена и тарифов также удаляется всегда. Если Remove data on uninstall включено, перевозчик удаляется (заказы сохраняют свою историю), а также удаляются настройки, сохранённые услуги заказов и журнал. Если выключено, перевозчик только отключается, а все настройки сохраняются. При повторной установке модуля или при Reset сохранённый перевозчик возвращает свой прежний статус: включённый снова включается, а отключённый остаётся отключённым.

USPS — товарный знак соответствующего правообладателя. Этот модуль не связан с USPS и не одобрен USPS.