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

Вимоги

PrestaShop: 8.0–9.x.

PHP: 8.0 або новіша, з розширенням cURL. Модуль не встановлюється на старіших версіях PHP і без 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. Один ключ працює на одному домені.

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

1. В адмін-панелі перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Коли завантаження завершиться, натисніть Configure або пізніше знайдіть VibeFox UPS у списку модулів і натисніть Configure.

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

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

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

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

Під час встановлення модуль створює перевізника UPS з текстом терміну доставки UPS delivery. Перевізник призначається всім зонам і всім групам клієнтів. Зони, групи клієнтів, термін доставки, логотип і обмеження розміру можна змінити в Shipping > Carriers. Не встановлюйте там ціни: ціна завжди береться з модуля.

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

Усі налаштування знаходяться на сторінці модуля: Modules > Module Manager > VibeFox UPS > Configure. Вони діють для всіх зон перевізника. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження очищає кеш токена та тарифів UPS. Також можна натиснути Clear cached UPS token and rates у розділі UPS API.

Попередження над налаштуваннями повідомляють, що заповнено лише одне з полів Client ID та Client Secret, що немає ні облікових даних, ні фіксованих цін (тоді перевізник ніколи не відображається), що не вказано поштовий індекс або код штату відправлення, що обрано тарифи облікового запису без його номера, що немає курсу обміну або що модуль не розпізнає одиницю ваги чи розмірів магазину. Некоректні числа, неправильний розмір коробки і Min weight, більше за Max weight, виводяться під час збереження, а старе значення зберігається.

Загальні

Enable UPS shipping: вмикає або вимикає перевізника. Це той самий перемикач, що й статус перевізника в Shipping > Carriers.

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

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

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

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

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

Account (negotiated) rates: за замовчуванням. Ваші узгоджені ціни UPS. Вони потребують номер облікового запису UPS. Без нього або якщо UPS не повертає узгоджений тариф, використовуються публічні тарифи.

Published (list) rates: публічні ціни UPS.

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

Automatic (by ship-from country): за замовчуванням. LBS / IN для США та Пуерто-Ріко, KG / CM в інших випадках.

LBS / IN або KG / CM: змінюйте, лише якщо UPS відповідає «This measurement system is not valid for the selected country».

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

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, щоб додати рядок, і кнопку видалення, щоб видалити рядок. Країна * застосовується до всіх інших країн. Стовпець ваги (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: мінімальна вага кошика в кг, за якої з'являється цей перевізник. 0 означає без обмеження.

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

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

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

Зазвичай перевізник пропонується в зонах, призначених йому в Shipping > Carriers.

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

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

Додатково

Debug log: записує запити до API та розрахунок тарифів у logs/vfd_upsx_debug.log.php у папці модуля. Файл не можна відкрити з веб-переглядача. Помилки API записуються завжди, навіть коли цю опцію вимкнено. Облікові дані, токени та адреси покупців ніколи не записуються.

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

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

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

На кроці доставки PrestaShop запитує в модуля ціну UPS. Враховуються лише фізичні товари: віртуальні товари не додають ваги і не входять до проміжної суми. Модуль спочатку перевіряє умови: країни з Ignore shipping zones, вагу кошика та мінімальну проміжну суму. Якщо діє безкоштовна доставка, ціна дорівнює 0 і запит до UPS не надсилається.

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

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

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

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

Якщо ви редагуєте перевізника в Shipping > Carriers після того, як у нього з'явилися замовлення, PrestaShop зберігає його як нову версію перевізника. Модуль автоматично переходить на нову версію.

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

Замовлення

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

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

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

Без активного ключа перевізник UPS не показується покупцям під час оформлення замовлення, і тарифи не розраховуються. Вітрина PrestaShop не знає, що ви увійшли в адмін-панель, тому перевізник приховано і для вас: модуль можна налаштувати до купівлі ключа, але перевірити його під час оформлення замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються.

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

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

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

Тарифи в реальному часі не з'являються: перевірте попередження у верхній частині сторінки Configure. Увімкніть Debug log, перезавантажте оформлення замовлення і подивіться поле Log на сторінці модуля. Там видно помилки 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 очікує для вашої країни відправлення.

Сторінка попереджає, що одиниця ваги або розмірів магазину невідома: тоді ваги читаються як кг, а розмір коробки — як см. Встановіть стандартну одиницю (kg, g, lb або oz; cm, mm, m або in) в International > Localization, розділ Local units.

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

Сторінка повідомляє, що перевізника UPS не знайдено: перевізника видалено в Shipping > Carriers. Скиньте модуль у Modules > Module Manager, щоб створити його знову.

Для розробників: хуки actionVfdUpsxAllowedServices і actionVfdUpsxExcludedServices обмежують послуги UPS, які можуть відображатися. actionVfdUpsxRateRequest змінює запит тарифу, actionVfdUpsxApiBaseUrl — адресу API, а actionVfdUpsxCurrencyCodes зіставляє коди валют, які повертає UPS.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox UPS і виберіть Uninstall. Ліцензійний ключ і статус ліцензії видаляються завжди. Кешовані токен і тарифи UPS видаляються завжди. Якщо Remove data on uninstall увімкнено, перевізник видаляється (замовлення зберігають історію), а налаштування, журнал і служби UPS, збережені із замовленнями, видаляються. Якщо вимкнено, перевізник лише деактивується, а налаштування зберігаються. Повторне встановлення модуля або скидання повертає перевізнику статус, який він мав раніше.

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