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 використовуються.

Retail (Post Office counter prices): за замовчуванням.

Commercial (online postage / Click-N-Ship prices): нижчі тарифи для онлайн-оплати поштових відправлень.

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

USPS Ground Advantage: лише внутрішні.

Priority Mail / Priority Mail International: внутрішні та міжнародні.

Priority Mail Express / Priority Mail Express International: внутрішні та міжнародні.

First-Class Package International Service: лише міжнародні.

Media Mail (books and media only): лише внутрішні.

Library Mail (libraries and schools only): лише внутрішні.

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 не надсилається.

Модуль отримує від USPS токен OAuth і зберігає його до незадовго до закінчення терміну дії. Токен, який 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.