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

Вимоги

PrestaShop: 8.0–9.x.

PHP: 8.0 або новіша версія. Модуль не встановлюється на старіших версіях PHP. Розширення PHP SOAP не потрібне.

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

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

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

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

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

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

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

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

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

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox Purolator > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищає кеш ставок Purolator.

Якщо ставки в реальному часі не можуть працювати із збереженими значеннями (немає ключа, пароля або розрахункового облікового запису, немає канадського поштового індексу відправлення, немає курсу CAD) або немає ані облікових даних API, ані фіксованих цін, над параметрами з'являється попередження. Попередження також з'являється, якщо одиниця ваги магазину не належить до відомих модулю (kg, g, lb, oz та подібні). Тоді ваги товарів вважаються в кілограмах. Встановіть одиницю ваги в International > Localization (Local units).

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

Загальні

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

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

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

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

Коли заповнені ключ API, пароль і розрахунковий обліковий запис, ціна береться з веб-сервісу Purolator E-Ship Estimating. Якщо 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.purolator.com) з ключем розробки. Ціни — тестові дані. Вимкніть його на робочому магазині.

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

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 включає ці податки. Увімкніть, коли в перевізника є податкове правило в Tax, щоб податок не стягувався двічі.

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

Default product weight: у кг, використовується для кожного товару без ваги. За замовчуванням: 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 × quantity) множить її на кількість товарів у кошику. Це стосується лише фіксованих цін. Ставки в реальному часі завжди розраховуються на все відправлення.

Умови

Min cart weight: у кг; приховує перевізника, якщо кошик важить менше. 0 означає без обмеження.

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

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

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

Для цих умов товари без ваги враховуються як 0.

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

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

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

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

Додатково

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

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

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

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

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

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

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

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

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

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

Замовлення

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

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

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

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

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

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

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

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

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

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

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

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

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

Видалення

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

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