VibeFox Canada Post for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

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

Canada Post Developer Program (лише для актуальних тарифів): актуальні тарифи використовують Rating API Canada Post. Зареєструйтеся в Canada Post Developer Program на сайті Canada Post і скопіюйте ключ API та номер клієнта. Ключ API має вигляд username:password, а Canada Post видає окремі ключі для тестового (sandbox) та робочого середовища. Також потрібен канадський поштовий індекс, з якого ви відправляєте. Якщо ви використовуєте лише фіксовані ціни, ключі API не потрібні.

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

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

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

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

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

4. Для актуальних тарифів введіть ім'я користувача та пароль API, номер клієнта та поштовий індекс відправлення. Якщо валюта вашого магазину за замовчуванням не CAD, введіть курс CAD. Заповніть Country prices, якщо потрібні фіксовані ціни або запасний варіант (див. розділ «Налаштування»). Натисніть Save.

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

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

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

Якщо значення неправильне, сторінка показує помилку і нічого не зберігається: числове поле або ціна в Country prices, яка не є числом 0 або більше (наприклад, -1 або 12abc), курс CAD, що дорівнює 0, Min cart weight (kg), більше за Max cart weight (kg), або Method title довший за 64 символи. Якщо одиниця ваги чи розміру вашого магазину невідома модулю, сторінка попереджає, що ваги читаються як кг (розміри — як см). Встановіть kg, g, lb або oz (cm, mm, m або in) в International > Localization, розділ Local units.

Після збереження сторінка показує попередження, якщо налаштування не можуть працювати як задумано: заповнене лише одне з полів API username та API password, поштовий індекс відправлення не є канадським (формат A1A 1A1), курс CAD відсутній для магазину в іншій валюті, або немає ні облікових даних API, ні фіксованих цен. Попередження також повідомляє, що відбувається тим часом: використовуються фіксовані ціни за країнами або перевізник приховується під час оформлення замовлення, якщо таблиця Country prices порожня.

Загальні

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

Method title: назва перевізника, яку бачить покупець під час оформлення замовлення. За замовчуванням: Canada Post, також якщо поле залишено порожнім. До 64 символів, без символів, які PrestaShop не дозволяє в назвах перевізників.

Tax: податкове правило, яке PrestaShop додає до вартості доставки, або No tax (не оподатковується).

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

Коли ім'я користувача та пароль API заповнені, ціна береться з Rating API Canada Post. Якщо API не повертає тариф (API недоступний, неправильний поштовий індекс, сервіс недоступний), використовується фіксована ціна з Country prices, або перевізник приховується, якщо її немає. Розділ містить посилання на Canada Post Developer Program, де ви знайдете ключі API та номер клієнта. Деталі помилок потрапляють у журнал і ніколи не показуються клієнту.

API username: частина ключа API до двокрапки. Використовуйте ключ для розробки з Sandbox, а ключ для робочого середовища — у діючому магазині.

API password: частина ключа API після двокрапки. Після збереження поле залишається порожнім і показує A password is saved. Leave empty to keep it; clear the username and save to remove both. Вводьте нове значення, лише якщо хочете його змінити. Пароль зберігається саме так, як введено, і ніколи не записується в журнал.

Customer number: з номером клієнта Canada Post повертає комерційні (зі знижкою) тарифи вашого облікового запису. Залиште поле порожнім для роздрібних (касових) тарифів. Пробіли видаляються.

Contract number: необов'язкове поле для клієнтів із договором. Використовується лише разом із номером клієнта.

Sandbox: використовує тестове середовище Canada Post для перевірки з ключем API для розробки. Ціни є тестовими даними. Вимкніть у діючому магазині.

Ship-from postal code: канадський поштовий індекс, з якого відправляються посилки, наприклад K1A 0B1. Без нього актуальні тарифи не працюють.

Service in Canada: сервіс для канадських адрес: Cheapest available, Regular Parcel (DOM.RP, за замовчуванням), Expedited Parcel (DOM.EP), Xpresspost (DOM.XP) або Priority (DOM.PC).

Service to the USA: Cheapest available (за замовчуванням), Expedited Parcel USA (USA.EP), Tracked Packet USA (USA.TP), Small Packet USA Air (USA.SP.AIR), Xpresspost USA (USA.XP) або Priority Worldwide parcel USA (USA.PW.PARCEL).

International service: Cheapest available (за замовчуванням), International Parcel Surface (INT.IP.SURF), International Parcel Air (INT.IP.AIR), Tracked Packet International (INT.TP), Small Packet International Surface (INT.SP.SURF), Small Packet International Air (INT.SP.AIR), Xpresspost International (INT.XP) або Priority Worldwide parcel International (INT.PW.PARCEL).

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

Use Canada Post prices without GST/HST/PST: для канадських адрес ціна Canada Post включає ці податки. Увімкніть, коли PrestaShop сам додає податок до доставки (Tax вище), щоб податок не стягувався двічі.

CAD to … rate: назва поля показує валюту магазину за замовчуванням, наприклад CAD to USD rate. Ціни Canada Post вказані в CAD. Якщо валюта за замовчуванням не CAD, введіть, скільки одиниць вашої валюти коштує один CAD, наприклад 0.68. Без цього значення актуальні тарифи не використовуються. Якщо валюта за замовчуванням — CAD, залиште поле порожнім. Курс має бути більшим за 0. Як десятковий роздільник приймаються і крапка, і кома.

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

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

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

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

Умови

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

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

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

Free shipping: вмикає безкоштовну доставку від суми, вказаної нижче.

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

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

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

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

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

Додатково

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

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

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

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

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

З обліковими даними API модуль надсилає в Canada Post поштовий індекс відправлення, призначення, вагу посилки та, коли кожен товар має розміри, орієнтовний розмір посилки. Для Канади призначенням є поштовий індекс, для США — ZIP-код, для всіх інших країн — лише країна. Актуальний тариф запитується, лише якщо канадська або американська адреса має дійсний поштовий індекс або ZIP-код. Canada Post повертає всі сервіси для посилки. Модуль обирає обраний сервіс для групи призначення або найдешевший, видаляє канадські податки з продажів (GST/HST/PST), якщо увімкнено Use Canada Post prices without GST/HST/PST, і конвертує ціну в CAD за вашим курсом. Ціна розраховується у валюті магазину за замовчуванням, а потім показується у валюті кошика покупця.

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

Якщо API не повертає тариф, використовується фіксована ціна або перевізник приховується, коли фіксованої ціни немає. Покупець ніколи не бачить деталей помилок API; вони потрапляють у журнал.

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

Модуль лише розраховує тарифи. Він не створює відправлень, не друкує етикеток, не створює маніфестів чи повернень і не відстежує посилки. Покупці не можуть обрати поштове відділення або пункт видачі. Модуль показує один тариф Canada Post без дат доставки, опцій страхування чи підпису. Кошик завжди розраховується як одна посилка, а курси валют автоматично не оновлюються.

Замовлення

Коли замовлення оформлено з перевізником Canada Post, модуль зберігає, як була розрахована його ціна. На сторінці замовлення в панелі адміністратора (Orders > Orders, відкрийте замовлення) блок Canada Post показує:

Canada Post service: назву та код сервісу актуального тарифу, наприклад Regular Parcel (DOM.RP).

Price source: Live rate (Canada Post Rating API), Fixed price або Free shipping.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Canada Post — перший блок на сторінці Modules > Module Manager > VibeFox Canada Post > Configure, над налаштуваннями. Вставте ключ у License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої ліцензія активна, і ваш домен), а також кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: presta-shipping-canada-post і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з правом на налаштування модуля. Тексти блоку відповідають мові back office (включено англійську та російську).

Якщо ключ не прийнято, блок пояснює причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on з датою. Після зміни адреси магазину або після звільнення місця для домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, модуль продовжує працювати з останнім відомим статусом.

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

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

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

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

Canada Post не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable Canada Post увімкнено. У Shipping > Carriers перевірте, що перевізник охоплює зону країни покупця та групу покупця (або що Ignore shipping zones увімкнено і країна дозволена). Перевірте обмеження ваги та Minimum order amount. Має бути тариф: з обліковими даними API адреса повинна мати дійсний поштовий індекс (Канада) або ZIP-код (США); інакше має існувати фіксована ціна для країни або для *. Крім того, товари можуть бути обмежені певними перевізниками на сторінці товару.

Актуальні тарифи не з'являються: увімкніть Debug log, оновіть оформлення замовлення і перегляньте панель Log на сторінці модуля. Там показано причину: відсутні ім'я користувача або пароль API, некоректний поштовий індекс відправлення чи призначення, відсутній курс CAD, посилка понад 30 кг або повідомлення про помилку від Canada Post. Тим часом покупці отримують фіксовану ціну, якщо вона є.

Тариф відрізняється від сайту Canada Post: з номером клієнта ви отримуєте комерційні (зі знижкою) тарифи вашого облікового запису; без нього — роздрібні (касові) тарифи. Для канадських адрес ціна Canada Post включає GST/HST/PST. Ціни конвертуються за вашим курсом CAD.

Податок на доставку стягується двічі: увімкніть Use Canada Post prices without GST/HST/PST або встановіть Tax на No tax.

Перевірка цін у діючому магазині: вимкніть Sandbox і використовуйте ключ API для робочого середовища.

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

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

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

Видалення

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

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