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.