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

Вимоги

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

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

Застосунок у 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. Один ключ працює на одному домені.

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

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

OpenCart 3

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

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

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

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

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

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

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

OpenCart 4

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

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

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

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

Після встановлення спосіб залишається вимкненим, доки ви не увімкнете Enable UPS shipping і не збережете налаштування. Країна Ship from спочатку збігається з країною магазину. Якщо ви встановлюєте розширення повторно після видалення, збережені налаштування UPS знову використовуються.

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

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

Якщо назва, податковий клас, порядок сортування або геозона некоректні, нічого не зберігається, і сторінка показує причину, наприклад Enter a valid name (64 characters max, without < > ; = # { }). Nothing was saved. Некоректні числа (наприклад, від'ємні), неправильний розмір коробки, Min weight (kg) більше за Max weight (kg) та клітинки цін, що не є числами, позначаються під час збереження: це поле зберігає попереднє значення, а решта зберігається. Попередження над налаштуваннями повідомляють, якщо заповнене лише одне з полів Client ID або Client Secret, немає ні облікових даних, ні фіксованих цін (тоді спосіб ніколи не показується), бракує поштового індексу чи штату відправлення, обрано тарифи облікового запису без номера облікового запису, бракує курсу обміну або розширення не розпізнає одиницю ваги чи довжини магазину.

Загальні

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

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

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

Tax class: податковий клас вартості доставки або None (за замовчуванням). Тарифи UPS вказуються без податків. За наявності податкового класу OpenCart додає свій податок на доставку зверху.

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

API UPS (актуальні тарифи)

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

Client ID: Client ID вашого застосунку в UPS Developer Portal. Якщо його очистити, збережений Client Secret також видаляється.

Client Secret: Client Secret того самого застосунку. Після збереження поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише щоб його змінити.

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

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

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

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

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

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

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

Cache: токени UPS кешуються до закінчення терміну дії (не довше за час життя кешу OpenCart), тарифи — на 1 годину, невдалі запити — на 5–10 хвилин. Натисніть Clear cached UPS token and rates, щоб одразу очистити кеш.

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

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

State / province code: двобуквений код, обов'язковий для США та Канади, наприклад NY, CA або ON. Він передається в UPS лише для цих двох країн.

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

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

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

Country prices: ціни у валюті магазину за замовчуванням, без податків, за країною призначення. Натисніть Add country, щоб додати рядок, і кнопку видалення, щоб видалити рядок. * Default (all other countries) застосовується до будь-якої іншої країни. Колонка ваги (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: проміжна сума кошика (товари, що потребують доставки, після купона, до податків), від якої цей спосіб безкоштовний. У такому разі запит до UPS не надсилається. Залиште порожнім, щоб ніколи не пропонувати безкоштовну доставку.

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

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

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

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

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

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

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

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

Додатково

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Замовлення

Коли замовлення оформлено з актуальним тарифом UPS, послуга UPS зберігається із замовленням. На сторінці замовлення в Sales > Orders є панель UPS з UPS service, наприклад UPS Ground, і Live rate (excl. tax). Ці значення зберігаються під час оформлення замовлення. У замовлень із фіксованою ціною або безкоштовною доставкою такої панелі немає.

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

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

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox UPS — це перший блок на сторінці Extensions > Extensions > Shipping > VibeFox UPS > Edit, над налаштуваннями. Введіть ключ у License key і натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої ліцензія дійсна, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа і Remove key для видалення ключа з цього магазину. Нижче розташовано рядок Product: opencart-shipping-ups та посилання 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. Якщо сервер ліцензій недоступний, розширення продовжує працювати за останнім відомим статусом.

Один ключ працює на одному домені. Ліцензії та домени ви керуєте у своєму обліковому записі vibefox.net.

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

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

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

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

Live rates do not appear: перегляньте попередження у верхній частині сторінки Edit. Увімкніть Debug log, перезавантажте оформлення замовлення і перегляньте поле Log на сторінці розширення. Там видно помилки OAuth (перевірте Client ID, Client Secret і Test mode), повідомлення про помилки UPS і проблеми з валютою.

The rate is in USD but the store is not: UPS повертає тарифи у валюті облікового запису відправника. Встановіть UPS account currency і Exchange rate. Без курсу обміну такі тарифи ігноруються, і використовується фіксована ціна.

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

The page warns about the weight or length unit: без вагового класу з одиницею kg невідомі одиниці ваги читаються як kg. Додайте ваговий клас у kg в System > Localisation > Weight Classes. Невідома одиниця довжини магазину призводить до того, що Box size читається як cm. Використовуйте cm, mm, m або in як лінійний клас магазину (System > Settings, вкладка Option).

Rates look outdated after a change: натисніть Save на сторінці розширення або Clear cached UPS token and rates.

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

For developers: розширення запускає події OpenCart, на які можуть реагувати інші розширення: vfd_ups/allowed_services і vfd_ups/excluded_services обмежують послуги UPS, які можна показувати, vfd_ups/rate_request змінює запит тарифу, vfd_ups/api_base_url — адресу API, а vfd_ups/currency_codes зіставляє коди валют, які повертає UPS.

Видалення

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

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

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