VibeFox UPS for WooCommerce — Допомога

Вимоги

WordPress: 5.8 або новіша версія.

WooCommerce: 7.0 або новіша версія, встановлений і активний. Без нього плагін не активується.

PHP: 8.0 або новіша версія.

Застосунок у UPS Developer Portal (лише для тарифів у реальному часі): увійдіть до UPS Developer Portal (developer.ups.com), створіть застосунок із продуктом «Rating», прив'яжіть свій обліковий запис UPS і скопіюйте Client ID та Client Secret. Плагін використовує OAuth 2.0. Access Key, ім'я користувача і пароль не потрібні. Для узгоджених тарифів також потрібен 6-символьний номер облікового запису UPS. Без облікових даних використовуються лише фіксовані ціни.

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

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

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна і натисніть Install Now. Також можна завантажити папку vfd_ups до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Shipping > VibeFox UPS або натисніть Settings під назвою плагіна на сторінці Plugins.

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

5. Введіть Client ID і Client Secret, номер облікового запису UPS (для узгоджених тарифів) та адресу Ship from: поштовий індекс і для США та Канади — дволітерний код штату.

6. Якщо валюта вашого облікового запису UPS відрізняється від валюти магазину, введіть UPS account currency і Exchange rate.

7. Додайте VibeFox UPS до зони доставки в WooCommerce > Settings > Shipping > Shipping zones або увімкніть Ignore shipping zones і виберіть країни.

8. За бажанням введіть фіксовані ціни як запасний варіант.

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

Усі параметри розміщено на одній сторінці: WooCommerce > Settings > Shipping > VibeFox UPS. Вони діють для всіх зон доставки. Коли ви додаєте спосіб до зони, у вікні зони є лише одне поле:

Title (zone): назва цього варіанта під час оформлення замовлення. Залиште порожнім, щоб використовувати загальне Name.

Щоразу, коли ви зберігаєте налаштування, кешовані токен UPS і тарифи очищуються. Ви також можете натиснути Clear cached UPS token and rates у розділі UPS API. Попередження над налаштуваннями повідомляють, коли заповнено лише одне з полів Client ID та Client Secret, коли немає ні облікових даних, ні фіксованих цін, коли не вказано поштовий індекс або штат відправлення, коли обрано тарифи облікового запису без його номера або коли не вказано курс обміну.

General

Enable/Disable: вмикає або вимикає спосіб у всіх зонах одночасно.

Name: назва способу доставки, яку бачить покупець під час оформлення замовлення. За замовчуванням: UPS.

Tax status: Taxable дозволяє WooCommerce додати податок на доставку, None — не додає. Тарифи UPS подаються без податків, тож податок не стягується двічі.

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

Test mode: використовувати тестове середовище UPS. Тестові тарифи не є справжніми цінами. Вимкніть для тарифів у реальному часі. За замовчуванням: вимкнено.

Client ID: Client ID вашого застосунку в UPS Developer Portal.

Client Secret: Client Secret того самого застосунку.

UPS account number: ваш 6-символьний номер відправника UPS, наприклад A1B2C3. Потрібен для тарифів облікового запису (узгоджених), необов'язковий для публічних тарифів.

Rates: які ціни UPS використовуються.

Measurement units: одиниці, які передаються в UPS. Ваги та розміри магазину перераховуються.

Residential delivery: розраховувати адреси покупців як житлові з житловою надбавкою UPS. Вимкніть, якщо ви відправляєте переважно компаніям. За замовчуванням: увімкнено.

Box size: необов'язкові розміри коробки в одиницях вимірювання розмірів вашого магазину, наприклад 30x20x15. Тоді UPS застосовує об'ємну вагу. Залиште порожнім, щоб рахувати лише за вагою.

UPS account currency: UPS рахує в валюті країни облікового запису відправника, наприклад USD для США, CAD для Канади або EUR для єврозони. За замовчуванням: USD.

Exchange rate: потрібен лише тоді, коли валюта облікового запису UPS відрізняється від валюти магазину. Введіть ціну 1 одиниці валюти облікового запису у валюті вашого магазину, наприклад 0.92. Без нього такі тарифи не використовуються, і діють фіксовані ціни. Курси обміну не оновлюються автоматично.

Адреса відправлення (адреса, звідки UPS забирає посилки або куди ви їх здаєте; використовується для тарифів у реальному часі)

Country: країна, з якої ви відправляєте. За замовчуванням це країна вашого магазину.

State / province code: дволітерний код, обов'язковий для США та Канади, наприклад NY, CA або ON.

City: місто, з якого ви відправляєте.

ZIP / postal code: поштовий індекс, з якого ви відправляєте. UPS потребує його для розрахунку тарифів.

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

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

Fallback cost: фіксована ціна у валюті вашого магазину, коли жодна ціна за країною не підходить. Залиште порожнім, щоб приховати спосіб у цьому випадку.

Fixed price is: Per order стягує ціну один раз. Per item (each item priced by its own weight x quantity) розраховує кожен товар за його власною вагою (вага за замовчуванням, якщо її немає) і множить на кількість. Тарифи UPS у реальному часі завжди розраховуються на загальну вагу кошика.

Умови

Free shipping from: сума проміжного підсумку кошика, починаючи з якої цей спосіб безкоштовний. Покупець бачить назву способу з позначкою «(Free)», і запит до UPS не надсилається. Залиште порожнім, щоб ніколи не пропонувати безкоштовну доставку.

Minimum subtotal: показувати спосіб, лише коли проміжний підсумок кошика не менший за цю суму. Залиште порожнім, щоб показувати завжди.

Min weight (kg): мінімальна вага кошика, за якої з'являється цей спосіб. 0 означає без обмежень.

Max weight (kg): спосіб приховується, коли вага кошика перевищує це значення. За замовчуванням: 70, ліміт UPS на одне місце (70 кг / 150 lbs). 0 означає без обмежень.

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

Excluded shipping classes: приховати спосіб, якщо в кошику є товар з будь-якого з цих класів доставки WooCommerce.

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

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

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

Додатково

Debug log: записує запити до API та розрахунок тарифів у WooCommerce > Status > Logs, джерело vfd-ups. Помилки API завжди записуються, навіть коли цей параметр вимкнено. Облікові дані, токени та адреси покупців ніколи не записуються в журнал.

Remove data on uninstall: якщо увімкнено, видалення плагіна стирає всі його налаштування та способи зон. Деактивація ніколи не видаляє налаштування.

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

Коли покупець вводить адресу доставки, WooCommerce запитує в плагіна тариф. Спочатку плагін перевіряє умови: вагу кошика, мінімальну проміжну суму та виключені класи доставки. Якщо діє безкоштовна доставка, спосіб показується як безкоштовний і запит до UPS не надсилається.

Плагін отримує токен OAuth від UPS і зберігає його до завершення строку дії. Токен, який UPS відхилив, автоматично оновлюється. Далі плагін запитує в API Rating від UPS усі послуги від вашої адреси відправлення до адреси покупця для кошика як одного місця. Для країн з поштовими індексами запит очікує, доки покупець введе індекс. Для відправлень зі США до Канади або Пуерто-Ріко передається вартість товарів, як того вимагає UPS.

Покупець бачить один варіант з найдешевшою послугою UPS, перерахованою у валюту вашого магазину. UPS Access Point Economy не розраховується, оскільки плагін не збирає адресу Access Point.

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

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

Спосіб працює в класичному оформленні замовлення та в блоках Cart і Checkout. Він сумісний з WooCommerce High-Performance Order Storage (HPOS).

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

Замовлення

Для тарифу в реальному часі рядок доставки в замовленні зберігає UPS service, наприклад UPS Ground. Менеджер магазину бачить його на екрані замовлення в адмін-панелі.

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

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

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

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

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

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

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

Тарифи в реальному часі не з'являються: перегляньте попередження у верхній частині сторінки налаштувань. Увімкніть Debug log і відкрийте WooCommerce > Status > Logs, джерело vfd-ups. Там видно помилки OAuth (перевірте Client ID, Client Secret і Test mode), повідомлення про помилки UPS і проблеми з валютою.

Тариф у USD, а магазин — ні: UPS повертає тарифи у валюті облікового запису відправника. Укажіть UPS account currency і Exchange rate. Без курсу обміну такі тарифи ігноруються і використовується фіксована ціна.

«This measurement system is not valid for the selected country»: залиште Measurement units на Automatic або виберіть одиниці, які UPS очікує для вашої країни відправлення.

Тарифи виглядають застарілими після зміни: збережіть сторінку налаштувань або натисніть Clear cached UPS token and rates.

Для розробників: фільтри vfd_upsx_allowed_services і vfd_upsx_excluded_services обмежують послуги UPS, які можуть відображатися. vfd_upsx_rate_request змінює запит тарифу, vfd_upsx_api_base_url — адресу API, а vfd_upsx_currency_codes зіставляє коди валют, які повертає UPS.

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

Видалення

Деактивація плагіна зберігає налаштування і очищує лише кешовані токен та тарифи. Щоб видалити плагін, деактивуйте його і видаліть на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна, а також кешовані токен і тарифи завжди видаляються. Налаштування та способи зон видаляються лише тоді, коли була увімкнена опція Remove data on uninstall. Інакше вони зберігаються для повторного встановлення. Наявні замовлення зберігають свої рядки доставки.

UPS — торгова марка її власника. Цей плагін не афілійований з UPS і не схвалений UPS.