VibeFox USPS for WooCommerce — Помощь

Требования

WordPress: 5.8 или новее.

WooCommerce: 7.0 или новее, установлен и активен. Плагин не активируется без него.

PHP: 8.0 или новее.

Приложение в 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. В WordPress откройте Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку vfd_usps в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Shipping > VibeFox USPS или нажмите Settings под названием плагина на странице Plugins.

4. Введите лицензионный ключ VibeFox в блоке лицензии вверху страницы и нажмите Activate.

5. Введите Consumer Key и Consumer Secret, 5-значный Ship from ZIP code и выберите услуги. Если валюта магазина не USD, введите USD exchange rate.

6. Добавьте VibeFox USPS в зону доставки в WooCommerce > Settings > Shipping > Shipping zones или включите Ignore shipping zones и выберите страны.

7. При необходимости введите фиксированные цены как запасной вариант.

Настройки

Все настройки находятся на одной странице: WooCommerce > Settings > Shipping > VibeFox USPS. Они действуют для всех зон доставки. При добавлении способа в зону окно зоны содержит только одно поле:

Title (zone): название этого варианта на оформлении заказа. Оставьте пустым, чтобы использовать общее Name.

При каждом сохранении настроек очищаются кэшированный токен USPS и тарифы. Также можно нажать Clear cached USPS token and rates в разделе USPS API. Предупреждения над настройками сообщают, когда заполнен только один из ключей, ключей и фиксированных цен нет, не указан ZIP-код отправки, не выбрана ни одна услуга, не указан курс USD или включена тестовая среда.

Общие

Enable/Disable: включает или выключает способ во всех зонах сразу.

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

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

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

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

Consumer Secret: Consumer Secret (client_secret) того же приложения.

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

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.

Отправка и посылка (тарифы USPS зависят от ZIP-кода отправки, веса и размера посылки)

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

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

Default product weight (kg): вес для товаров без веса, используется в тарифах 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 применяется ко всем остальным странам. Значения, которые не являются числами, очищаются с сообщением.

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 (kg): минимальный вес корзины, при котором появляется этот способ. 0 означает без ограничения.

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

Excluded shipping classes: скрыть способ, если в корзине есть товар из любого из этих классов доставки WooCommerce.

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

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

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

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

Debug log: записывает запросы к API и расчёт тарифов в WooCommerce > Status > Logs, источник vfd-usps. Ошибки API записываются всегда, даже если эта опция выключена. Ключи, токены и адреса покупателей никогда не записываются.

Remove data on uninstall: если включено, удаление плагина стирает все его настройки и способы в зонах. Деактивация никогда не удаляет настройки.

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

Когда покупатель вводит адрес доставки, WooCommerce запрашивает у плагина тариф. Плагин сначала проверяет условия: вес корзины, минимальную сумму и исключённые классы доставки. Если действует бесплатная доставка, способ показывается с ценой 0, и запрос в USPS не отправляется.

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

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

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

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

Способ работает на классическом оформлении заказа и в блоках «Корзина» и «Оформление заказа». Совместим с WooCommerce High-Performance Order Storage (HPOS).

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

Заказы

Для тарифа в реальном времени строка доставки заказа сохраняет USPS service, например USPS Ground Advantage. Менеджер магазина видит её на экране заказа в админке.

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

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Shipping > VibeFox USPS. Вставьте ключ в поле License key и нажмите Activate. В блоке отображается статус, например дата, до которой лицензия активна, и ваш домен. Нажмите Check now, чтобы проверить статус ещё раз, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить его с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

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

Без активного ключа USPS не показывается покупателям на оформлении заказа. Менеджеры магазина, вошедшие в систему, по-прежнему его видят, с пометкой (unlicensed — visible to admins only), чтобы можно было настроить и проверить плагин до покупки ключа. Напоминание появляется на странице Plugins и на страницах WooCommerce. Существующие заказы не затрагиваются.

Когда срок лицензии истекает, плагин продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется в фоновом режиме.

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

USPS не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и способ добавлен в зону страны покупателя (или включено Ignore shipping zones и страна разрешена). Проверьте ограничения по весу, Minimum subtotal и Excluded shipping classes. Без рабочих ключей USPS способу нужна фиксированная цена (Country prices или Fallback cost).

Тарифы в реальном времени не появляются: проверьте предупреждения вверху страницы настроек. Включите Debug log и откройте WooCommerce > Status > Logs, источник vfd-usps. Там записываются неверные ключи, неправильная среда и сообщения об ошибках 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.

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите место в аккаунте vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать по последнему известному статусу.

Удаление

Деактивация плагина сохраняет настройки и только очищает кэшированный токен и тарифы. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина, а также кэшированные токен и тарифы всегда удаляются. Настройки и способы в зонах удаляются, только если была включена опция Remove data on uninstall. Иначе они сохраняются для повторной установки. Существующие заказы сохраняют свои строки доставки.

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