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

Вимоги

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

PHP: 8.0 або новіша версія, з розширенням cURL. Розширення SOAP для PHP не потрібне.

Purolator E-Ship Web Services (лише для актуальних тарифів): зареєструйтеся в E-Ship Web Services у Purolator E-Ship Resource Centre на сайті Purolator. Purolator видає окремі ключі та паролі для тестового і робочого середовища. Також потрібні номер вашого платіжного облікового запису Purolator і канадський поштовий індекс, з якого ви відправляєте. Якщо ви використовуєте лише фіксовані ціни, API-ключі не потрібні.

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

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

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

OpenCart 3

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

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

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

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

5. Для актуальних тарифів заповніть розділ Purolator API (live rates): API-ключ, пароль, номер платіжного облікового запису, канадський поштовий індекс відправлення та, якщо валюта магазину не CAD, курс CAD. Для тестування увімкніть Development environment з ключем для розробки. Заповніть Country prices або Fallback price, якщо потрібні фіксовані ціни або резерв (див. розділ Налаштування). Увімкніть Enable Purolator і натисніть Save.

OpenCart 4

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

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

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

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

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

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

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

Якщо актуальні тарифи не можуть працювати із збереженими значеннями (немає ключа, пароля або платіжного облікового запису, немає канадського поштового індексу відправлення, немає курсу CAD) або немає ні API-даних, ні фіксованих цін, у розділі General з'являється попередження. Воно також повідомляє, чи використовуються до того часу фіксовані ціни, чи спосіб приховано. Попередження з'являється і тоді, коли одиниця ваги магазину невідома розширенню. У цьому разі ваги товарів зчитуються як кг; додайте вагову категорію з одиницею kg у System > Localisation > Weight Classes.

Числове поле, яке не містить числа 0 або більше, не зберігається. Повідомлення після Save називає поле і значення. Поле лишається порожнім або отримує значення за замовчуванням для полів ваги. Неправильне значення в Country prices зберігається як 0, а повідомлення називає країну та стовпець. Нічого не зберігається і з'являється помилка, якщо назва способу порожня або довша за 64 символи, якщо Min cart weight (kg) більше за Max cart weight (kg), якщо порядок сортування не є цілим числом, або якщо податковий клас чи геозона некоректні.

Загальні

Покупець бачить один тариф Purolator. Налаштування діють для всіх геозон. Спосіб можна обмежити геозоною або країнами в Availability.

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

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

Tax class: податковий клас вартості доставки або No tax (за замовчуванням). Він визначає, чи додає магазин податок зверху. Для канадських адрес підсумкова сума Purolator уже містить GST/HST/PST/QST. Див. нижче Canadian sales taxes.

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

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

Коли API-ключ, пароль і платіжний обліковий запис заповнені, ціна береться з веб-сервісу Purolator E-Ship Estimating (Quick Estimate, за загальною вагою кошика). Якщо Purolator не повертає тариф, використовується фіксована ціна, або спосіб приховується, коли її немає. У розділі є посилання на Purolator E-Ship Resource Centre, де ви реєструєтеся і отримуєте ключі. Деталі помилок потрапляють у журнал, але ніколи не показуються покупцеві.

API key: ваш ключ E-Ship Web Services для вибраного середовища. Після збереження поле лишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

API password: пароль, який належить до ключа. Як і ключ, після збереження він більше не показується.

Billing account number: ваш номер облікового запису Purolator. Оцінки використовують тарифи цього облікового запису. Тестове середовище приймає тестовий обліковий запис із документації Purolator. Очищення цього поля також видаляє збережені API-ключ і пароль.

Development environment: використовує тестове середовище Purolator (devwebservices) з ключем для розробки. Ціни є тестовими даними. Вимкніть це в магазині, який працює.

Ship-from postal code: канадський поштовий індекс, з якого відправляються посилки, наприклад L4W 5M8. В OpenCart немає поштового індексу магазину, тож він не береться з адреси магазину: введіть його тут.

Service in Canada: Cheapest available (за замовчуванням), Purolator Ground, Purolator Ground 9AM, Purolator Ground 10:30AM, Purolator Ground Evening, Purolator Express, Purolator Express 9AM, Purolator Express 10:30AM, Purolator Express 12PM або Purolator Express Evening.

Service to the USA: Cheapest available (за замовчуванням), Purolator Ground U.S., Purolator Express U.S., Purolator Express U.S. 9AM, Purolator Express U.S. 10:30AM або Purolator Express U.S. 12:00.

International service: Cheapest available (за замовчуванням), Purolator Express International, Purolator Express International 9AM, Purolator Express International 10:30AM або Purolator Express International 12:00.

Якщо обрана служба не пропонується для адреси, використовується найдешевша з доступних.

Canadian sales taxes: використовувати ціни Purolator без GST/HST/PST/QST. Для канадських адрес підсумкова сума Purolator містить ці податки. Вмикайте, коли магазин сам додає податок до доставки (податковий клас у General), щоб податок не стягувався двічі. За замовчуванням: вимкнено.

CAD → (store currency) rate: ціни Purolator вказані в CAD. Якщо валюта магазину за замовчуванням не CAD, вкажіть, скільки одиниць вашої валюти коштує один CAD, наприклад 0.68. Без цього значення актуальні тарифи не використовуються. Якщо валюта за замовчуванням — CAD, залиште поле порожнім.

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

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

Country prices: ціна за країною та вагою кошика у валюті магазину за замовчуванням, без податку. Натисніть Add country, щоб додати рядок, і кнопку ×, щоб його видалити. Оберіть * Default (all other countries) для рядка, який охоплює всі країни без власного рядка. Кожен рядок має ціну Base і колонки розмірів: XS до 1 кг, S від 1 до 2 кг, M від 2 до 3 кг, L від 3 до 5 кг і XL понад 5 кг. Порожня або нульова ціна розміру використовує Base. Base зі значенням 0 або порожній Base означає безкоштовну доставку для ваг без власної ціни розміру. Приймаються як 9.99, так і 9,99. Рядки без жодної ціни не зберігаються, і для кожної країни лишається лише один рядок.

Fallback price: ціна для країни, яка не має рядка в Country prices і рядка *. Залиште порожнім, щоб приховати спосіб для таких країн.

Fixed price per: Order (за замовчуванням) стягує ціну один раз. Item (price x quantity) множить її на кількість товарів у кошику. Це стосується лише фіксованих цін. Актуальні тарифи завжди розраховуються на все відправлення.

Умови

Min cart weight (kg): приховує спосіб, коли кошик важить менше. 0 означає без обмеження (за замовчуванням).

Max cart weight (kg): приховує спосіб, коли кошик важить більше. За замовчуванням: 30. Якщо поле порожнє, використовується 30 кг. 0 означає без обмеження.

Minimum order amount: показує спосіб, лише якщо проміжна сума товарів, які потребують доставки (після купона, до податку), досягає цієї суми. Залиште порожнім, щоб показувати завжди.

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

Доступність

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

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

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

Додатково

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

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

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

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

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

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

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

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

За наявності API-даних розширення надсилає до Purolator запит Quick Estimate: ваш платіжний обліковий запис, поштовий індекс відправлення, місто, провінцію або штат покупця, його країну та поштовий індекс, а також загальну вагу кошика в цілих фунтах. Для Канади потрібен коректний поштовий індекс, для США — коректний ZIP-код; інші країни надсилаються з поштовим індексом у тому вигляді, в якому його введено. Розміри (об'ємна вага) не надсилаються. Purolator відповідає французькою, якщо покупець переглядає магазин французькою, інакше англійською. Purolator повертає ціни всіх служб; розширення бере обрану службу або найдешевшу, вилучає канадські податки з продажів, якщо це налаштовано, і перераховує ціну з CAD. Ціна розраховується у валюті магазину за замовчуванням, округлюється до її десяткових знаків і показується покупцеві у його валюті з податком обраного Tax class.

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

Якщо Purolator не повертає тариф (API недоступний, неправильні облікові дані або поштовий індекс, служба недоступна, немає курсу CAD), покупець не бачить помилки. Використовується фіксована ціна, а якщо її немає — спосіб приховується. Причина записується в журнал.

Розширення лише розраховує тарифи. Воно не створює відправлень Purolator, не друкує етикетки, не бронює забір, не обробляє повернення і не відстежує посилки. Воно не використовує Full Estimate (розміри, кілька місць, опції на кшталт підпису або небезпечних вантажів), не показує дати доставки, не пропонує кілька служб як окремі варіанти та не отримує курси валют автоматично. Покупець не бачить назву служби Purolator, лише назву вашого способу доставки.

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

Замовлення

Коли замовлення оформлено з актуальним тарифом Purolator, служба зберігається разом із замовленням. У Sales > Orders на сторінці замовлення над історією показано панель Purolator з Purolator service (назва та код) і Live rate (excl. tax). Панель лишається видимою, навіть якщо спосіб згодом вимкнули. Замовлення, оцінені за фіксованими цінами або з безкоштовною доставкою, такої панелі не мають. Саме замовлення показує назву способу доставки та вартість доставки, як будь-який інший спосіб доставки OpenCart.

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

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

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

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

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

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

Purolator не з'являється під час оформлення замовлення: перевірте, чи ліцензія активна і чи ввімкнено Enable Purolator. Перевірте Geo zone (або що ввімкнено Ignore shipping zones і країна дозволена), обмеження ваги та Minimum order amount. Якщо Purolator не повертає тариф, спосіб показується лише з ціною за країною, рядком * або Fallback price. Перевірте, чи в товарів Requires Shipping встановлено на Yes.

Актуальні тарифи не з'являються: подивіться поле Log на сторінці розширення. Помилки API завжди є там. Увімкніть Debug log і перезавантажте оформлення замовлення, щоб побачити подробиці. З API-ключами адреса має містити коректний поштовий індекс (Канада) або ZIP-код (США). Перевірте також попередження в розділі General.

HTTP 401 у журналі: API-ключ або пароль не відповідають вибраному середовищу. Ключі для розробки працюють лише з увімкненим Development environment, робочі — лише з вимкненим.

Тариф відрізняється від сайту Purolator: Quick Estimate використовує тарифи вашого платіжного облікового запису та загальну вагу, округлену вгору до цілих фунтів, без об'ємної ваги. Для канадських адрес підсумкова сума містить податки з продажів; використовуйте Canadian sales taxes, якщо ви задали Tax class. Ціни перераховуються за вашим курсом CAD → (store currency) rate.

Значення зникло після збереження: прочитайте повідомлення, яке з'явилося після Save. Значення не було числом 0 або більше, тому його не збережено. Введіть його знову як просте число.

Тарифи виглядають застарілими після зміни: натисніть Save на сторінці розширення. Це очистить кешовані тарифи Purolator.

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

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

Видалення

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

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

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