VibeFox USPS for OpenCart — Допомога

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіша (перевірено на 4.1.0.3).

PHP: 8.0 або новіша, з розширенням cURL.

Застосунок у USPS Developer Portal (лише для тарифів у реальному часі): увійдіть до USPS Developer Portal (developers.usps.com) з безкоштовним бізнес-акаунтом USPS, створіть застосунок і скопіюйте його Consumer Key та Consumer Secret. Розширення використовує актуальні API USPS з OAuth 2.0. Старий Web Tools User ID з ними не працює. Без ключів використовуються лише фіксовані ціни.

Поштовий індекс відправника: тарифи в реальному часі потребують 5-значного поштового індексу США, з якого відправляються посилки.

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

Встановлення

Завантаження — це один ZIP-файл із пакетами для обох версій OpenCart. Розпакуйте його на своєму комп'ютері. Він містить README.txt, пакет для OpenCart 3 vfd_usps-oc3-(version).ocmod.zip і пакет для OpenCart 4 vfd_usps.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

1. В адмінпанелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл vfd_usps-oc3-(version).ocmod.zip. Розширення не додає модифікацій OCMOD, тому оновлювати Extensions > Modifications не потрібно. Замість Installer можна скопіювати вміст папки upload з цього пакета в кореневу папку вашого магазину.

2. Перейдіть до Extensions > Extensions і виберіть тип розширення Shipping. Знайдіть VibeFox USPS і натисніть Install (зелена кнопка +).

3. Натисніть Edit (кнопка з олівцем), щоб відкрити сторінку налаштувань.

4. Введіть ваш ліцензійний ключ VibeFox у поле License key блока ліцензії у верхній частині сторінки Edit і натисніть Activate (див. License key).

5. Введіть Consumer Key і Consumer Secret, 5-значний Ship from ZIP code та оберіть Services. Якщо основна валюта вашого магазину не USD, введіть USD exchange rate.

6. За бажанням введіть фіксовані ціни як запасний варіант, увімкніть Enable USPS shipping і натисніть Save.

OpenCart 4

1. В адмінпанелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл vfd_usps.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з імені файлу, і перейменований пакет не працює.

2. Пакет з'являється у списку встановлених розширень на тій самій сторінці. Натисніть поруч Install (зелена кнопка +).

3. Перейдіть до Extensions > Extensions і виберіть тип розширення Shipping. Знайдіть VibeFox USPS, натисніть Install (зелена кнопка +), а потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ і налаштування так само, як у кроках 4–6 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях.

Після встановлення спосіб вимкнений, доки ви не увімкнете Enable USPS shipping і не збережете налаштування. Якщо ви встановите розширення повторно після видалення, знову використовуватимуться збережені налаштування USPS.

Налаштування

Усі налаштування розміщені на сторінці розширення: Extensions > Extensions > Shipping > VibeFox USPS > Edit. Розділи перелічено ліворуч. Одна кнопка Save внизу зберігає всю сторінку без перезавантаження. Кожне збереження очищує кешований токен і тарифи USPS. Зберігати налаштування, очищати кеш або журнал можуть лише адміністратори з правом на зміну цього розширення.

Недійсне значення не зберігається: сторінка вказує поле, повертає попереднє значення і показує The other settings were saved. Це стосується порожньої, надто довгої назви або назви із забороненими символами, від'ємного чи нечислового значення, поштового індексу не з 5 цифр, неправильного розміру коробки, Min weight (kg) більшої за Max weight (kg) (обидва обмеження зберігають свої значення), порядку сортування, який не є цілим числом, а також невідомого класу податку чи геозони. Ціни за країнами, які не є числами, очищаються і перелічуються. Попередження над налаштуваннями повідомляють, коли задано лише один із двох ключів, коли немає ні ключів, ні фіксованих цін (тоді спосіб ніколи не показується), коли не вказано поштовий індекс, коли не обрано жодної послуги, коли відсутній курс USD, коли увімкнено тестове середовище або коли розширення не розпізнає одиницю ваги чи довжини магазину.

Загальні

Налаштування застосовуються до всіх геозон. USPS пропонується як один варіант доставки під час оформлення замовлення.

Enable USPS shipping: пропонує доставку USPS під час оформлення замовлення. За замовчуванням: вимкнено.

Name: назва способу доставки, яку бачить покупець під час оформлення замовлення. За замовчуванням: USPS. Обов'язково, не більше 64 символів, без < > ; = # { }.

Tax class: клас податку на вартість доставки. Ціни USPS не включають податки. No tax (за замовчуванням) означає, що доставка не оподатковується.

Sort order: місце USPS серед способів доставки під час оформлення замовлення. Ціле число.

API USPS (тарифи в реальному часі)

Consumer Key: Consumer Key (client_id) вашого застосунку розробника USPS. Його очищення також видаляє збережений Consumer Secret.

Consumer Secret: Consumer Secret (client_secret) того самого застосунку. Після збереження поле лишається порожнім і показує Saved — leave empty to keep it. Clearing the Consumer Key removes it too. Вводьте нове значення, лише якщо хочете його змінити.

Test environment: використовуйте USPS Testing Environment для відправників. Лише для застосунків, яким це середовище доступне. Для реальних цін залиште вимкненим. За замовчуванням: вимкнено.

Prices: який прайс-лист USPS використовується.

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

USD exchange rate: ціни USPS вказано в USD. Якщо основна валюта вашого магазину не USD, введіть ціну 1 USD у вашій валюті, наприклад 0.92. Значення має бути більшим за 0. Без нього тарифи в реальному часі не використовуються і діють фіксовані ціни. Якщо валюта вашого магазину USD, він не потрібен. Курс не оновлюється автоматично.

Cache: розрахунки кешуються на 1 годину, невдалий розрахунок на 10 хвилин. Після тайм-ауту, помилки сервера, обмеження кількості запитів або відхилених ключів USPS протягом 5 хвилин не викликається. Натисніть Clear cached USPS token and rates, щоб одразу очистити кеш.

Відправлення та посилка (ціни USPS залежать від поштового індексу відправника, ваги та розміру посилки; кошик розраховується як одна посилка)

Ship from ZIP code: 5-значний поштовий індекс США, з якого відправляються посилки. ZIP+4 скорочується до 5 цифр. В OpenCart немає поштового індексу магазину, тому введіть його тут.

Box size (L x W x H): необов'язкові розміри коробки в одиницях довжини вашого магазину (вказані в назві поля), наприклад 30x20x15. Залиште порожнім, щоб використовувати розміри товару: найдовша сторона, найширша сторона і складені висоти. Товари без розмірів розраховуються як коробка 10 x 8 x 4 дюйми.

Default product weight (kg): вага, що використовується для товарів без ваги, у тарифах USPS, обмеженнях ваги та вагових категоріях. За замовчуванням: 0.5. Порожнє значення також означає 0,5 кг.

Фіксовані ціни (ціни в основній валюті магазину, без податків; використовуються, коли не введено ключі API, і як запасний варіант, коли USPS не повертає тариф; залиште обидва порожніми, щоб приховати спосіб у цьому разі)

Country prices: ціни за країною призначення та вагою кошика. Натисніть Add country, щоб додати рядок, і кнопку видалення, щоб прибрати його. Вагові категорії: XS до 1 кг, S 1–2 кг, M 2–3 кг, L 3–5 кг і XL понад 5 кг. Порожня або нульова категорія використовує Price. * Default (any other country) застосовується до всіх інших країн.

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. Порожнє значення означає 30 кг, 0 означає без обмежень. USPS приймає до 70 фунтів (31,7 кг): важчі посилки отримують фіксовані ціни.

Geo zone: пропонувати USPS лише для адрес у цій геозоні. All zones (за замовчуванням) означає без обмежень. Геозонами керують у System > Localisation > Geo Zones. Не використовується разом з Ignore shipping zones.

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

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

Countries: країни призначення для цього режиму. Залиште порожнім, щоб дозволити всі країни. Це поле використовується лише тоді, коли увімкнено Ignore shipping zones.

Додатково

Debug log: записує запити до API та розрахунок тарифів у storage/logs/vfd_usps_debug.log.php (в OpenCart 4 system/storage/logs/vfd_usps_debug.log.php). Файл не можна прочитати з веб-сторінки. Помилки API записуються завжди, навіть коли цю опцію вимкнено. Ключі, токени, поштові індекси та адреси покупців ніколи не записуються. Коли файл досягає 5 МБ, його переміщують до vfd_usps_debug.old.log.php і починають новий журнал.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб його очистити.

Remove data on uninstall: якщо увімкнено, видалення розширення стирає налаштування USPS і журнал. Кешовані тарифи завжди видаляються. Послуги USPS з оформлених замовлень завжди зберігаються. Якщо вимкнено, налаштування зберігаються для повторного встановлення.

Імпорт / експорт

Export: натисніть Download JSON, щоб зберегти налаштування у файл JSON. Consumer Secret не експортується.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування, наприклад в іншому магазині. Значення перевіряються так само, як під час звичайного збереження. Збережений Consumer Secret зберігається.

Як це працює під час оформлення замовлення

Коли OpenCart показує способи доставки, він запитує у розширення ціну USPS. Якщо задано Geo zone і адреса знаходиться поза нею, USPS не пропонується (з Ignore shipping zones натомість вирішує список країн). Враховуються лише товари з Requires Shipping у значенні Yes: інші товари не додають ваги і не входять до підсумку. Подарункові сертифікати, бонусні бали та кредит магазину не враховуються. Потім розширення перевіряє умови: вагу кошика та мінімальний підсумок. Якщо діє безкоштовна доставка, ціна дорівнює 0 і запит до USPS не надсилається.

Розширення отримує токен OAuth від USPS і зберігає його до незадовго до закінчення терміну дії. Для напрямків у США та їхніх територіях (Пуерто-Рико, Віргінські острови США, Гуам, Американське Самоа, Північні Маріанські острови, Федеративні Штати Мікронезії, Маршаллові Острови та Палау) воно запитує внутрішні тарифи і потребує 5-значного поштового індексу покупця: без нього запит не надсилається. Для інших країн запитуються міжнародні тарифи.

Запит містить поштовий індекс відправника, вагу кошика, розмір посилки і тип ціни. Посилки важчі за 70 фунтів отримують фіксовані ціни. Покупець бачить один варіант з найдешевшою вибраною послугою. Ціна в USD перераховується в основну валюту магазину, округлюється до її десяткових знаків і показується у валюті покупця з податком вибраного Tax class.

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

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

Розширення лише розраховує тарифи. Воно не купує марки чи етикетки доставки, не замовляє кур'єра, не відстежує посилки і не дозволяє покупцеві вибрати поштове відділення або пункт видачі. Воно показує один варіант, а не кілька послуг USPS. Пакування в коробки немає: кошик розраховується як одна посилка. Страхування та інші додаткові послуги не включено.

В OpenCart 4 покупець натискає Choose у блоці способу доставки на сторінці оформлення замовлення і вибирає USPS у вікні Shipping method options. Спосіб працює так само, як в OpenCart 3.

Замовлення

Коли замовлення оформлюється з USPS, розширення зберігає, як було визначено ціну доставки. Сторінка замовлення в Sales > Orders показує панель USPS з USPS service (для тарифу в реальному часі, наприклад USPS Ground Advantage), Price source (USPS live rate, Fixed price або Free shipping) та Calculated price (excl. tax). Ці значення зберігаються під час оформлення замовлення.

OpenCart 4 зберігає одне замовлення для оформлення і оновлює його щоразу, коли покупець знову підтверджує. Збережені значення оновлюються разом із ним. Якщо покупець обирає інший спосіб доставки, їх прибирають із замовлення. В OpenCart 4 панель USPS відображається над розділом History.

Ліцензійний ключ

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox USPS є першим блоком на сторінці Extensions > Extensions > Shipping > VibeFox USPS > Edit, над налаштуваннями. Введіть ключ у License key і натисніть Activate. Після цього блок показує ключ прихованим, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) і кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього магазину. Нижче є рядок Product: opencart-shipping-usps і посилання Manage licenses and domains in your account, яке відкриває ваш акаунт vibefox.net. Змінювати ключ можуть лише адміністратори з правом Modify для цього розширення. Тексти блока відповідають мові адмінпанелі (включено англійську та російську).

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

Один ключ працює на одному домені: адреса магазину з конфігурації OpenCart. Видалення ключа з магазину не звільняє його місце для домену. Звільніть місце у своєму акаунті vibefox.net.

Без активного ключа спосіб доставки USPS не показується покупцям під час оформлення замовлення, і тариф не розраховується. Адміністратор, який увійшов в адмінпанель у тому самому браузері, все ще бачить спосіб у магазині з позначкою (unlicensed — visible to admins only), тож ви можете налаштувати й протестувати розширення до купівлі ключа. В OpenCart 4 цей попередній перегляд недоступний: магазин не бачить вхід адміністратора, тому без активного ключа спосіб приховано для всіх. Після того як ви один раз відкриєте сторінку Edit, на Dashboard в адмінпанелі з'явиться нагадування. Закрийте його кнопкою ×, щоб приховати на 7 днів. Наявні замовлення не змінюються.

Коли термін дії ліцензії минає, розширення продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус перевіряється знову автоматично, коли ви відкриваєте Dashboard або сторінку Edit в адмінпанелі: раз на день протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення розширення завжди стирає ліцензійний ключ і статус ліцензії.

Усунення несправностей

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

Тарифи в реальному часі не з'являються: перевірте попередження у верхній частині сторінки Edit: обидва ключі, поштовий індекс, принаймні одну послугу і, для магазинів не в USD, курс. Покупці з США мають вказати поштовий індекс. Увімкніть Debug log, перезавантажте оформлення замовлення і перегляньте поле Log на сторінці розширення.

Тарифи не є реальними цінами: вимкніть Test environment.

Сторінка попереджає про одиницю ваги або довжини: без вагової категорії з одиницею kg невідомі одиниці ваги зчитуються як кілограми. Додайте вагову категорію в kg у System > Localisation > Weight Classes. Невідома одиниця довжини магазину вважається сантиметрами. Використовуйте cm, mm, m або in як клас довжини магазину (System > Settings, вкладка Option).

Тарифи застаріли після змін: натисніть Save на сторінці розширення або Clear cached USPS token and rates.

Сторінка показує "Warning: You do not have permission to modify VibeFox USPS!": ваша група адміністраторів може лише переглядати налаштування. Надайте групі право на зміну для extension/shipping/vfd_usps (OpenCart 3) або extension/vfd_usps/shipping/vfd_usps (OpenCart 4) у System > Users > User Groups.

Для розробників: адресу API USPS можна замінити налаштуванням vfd_usps_api_url (для тестів); на сторінці налаштувань для нього немає поля.

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Shipping і натисніть Uninstall (червона кнопка −) поруч із VibeFox USPS. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди скидає Enable USPS shipping, Sort order, Tax class і Geo zone. Кешований токен USPS і тарифи завжди видаляються. Якщо Remove data on uninstall увімкнено, також видаляються налаштування USPS і журнал налагодження. Якщо вимкнено, інші налаштування зберігаються і знову використовуються під час повторного встановлення розширення. Дані USPS з оформлених замовлень ніколи не видаляються, а наявні замовлення зберігають свій спосіб доставки та вартість.

В OpenCart 4, щоб також видалити файли розширення, після видалення перейдіть до Extensions > Installer, натисніть Uninstall (помаранчева кнопка −) поруч із VibeFox USPS у списку встановлених розширень, а потім Delete (червона кнопка з кошиком), щоб видалити завантажений пакет.

USPS є торговельною маркою її власника. Це розширення не пов'язане з USPS і не схвалено USPS.