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

Вимоги

WordPress: 5.8 або новіша версія.

WooCommerce: 5.0 або новіша, встановлений і активний. Плагін не активується без нього.

PHP: 8.0 або новіша версія.

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. У WordPress перейдіть до Plugins > Add New > Upload Plugin, оберіть ZIP-файл плагіна та натисніть Install Now. Також можна завантажити папку vfd_canada_post до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Shipping > VibeFox Canada Post або натисніть Settings під назвою плагіна на сторінці Plugins.

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

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

6. Додайте VibeFox Canada Post до своїх зон доставки: WooCommerce > Settings > Shipping > Shipping zones, або увімкніть Ignore shipping zones і оберіть країни.

Конфігурація

Усі налаштування розміщено на одній сторінці: WooCommerce > Settings > Shipping > VibeFox Canada Post. Вони застосовуються до всіх зон доставки. Коли ви додаєте спосіб до зони, у вікні зони є лише одне поле:

Title (zone): назва, яку бачить покупець для цієї зони. Залиште порожнім, щоб використовувати загальний Method title.

Щоразу, коли ви зберігаєте налаштування, кеш тарифів Canada Post очищується. Сторінка також показує помилку, коли налаштування не можуть працювати: заповнено лише одне з полів ім'я користувача або пароль API, поштовий індекс відправлення не є канадським, відсутній курс CAD для магазину з іншою валютою, або немає ні ключів API, ні фіксованих цін.

Загальні

Enable/Disable: вмикає або вимикає спосіб у всіх зонах одразу.

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

Tax status: Taxable додає податок WooCommerce до вартості доставки, None — не додає.

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

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

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

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

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

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

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

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

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

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

International service: Cheapest available (за замовчуванням), International Parcel Surface, International Parcel Air, Tracked Packet International, Small Packet International Surface, Small Packet International Air, Xpresspost International або Priority Worldwide parcel International.

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

Canadian sales taxes: використовує ціни Canada Post без GST/HST/PST. Для канадських адрес ціна Canada Post включає ці податки. Вмикайте, коли WooCommerce сам нараховує податок на доставку (Tax status = Taxable), щоб податок не стягувався двічі.

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

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 × quantity) множить її на кількість товарів у кошику. Це стосується лише фіксованих цін. Актуальні тарифи завжди розраховуються для всієї посилки.

Умови

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

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

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

Excluded shipping classes: приховує спосіб, якщо в кошику є товар з одним із цих класів доставки WooCommerce.

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

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

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

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

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

Додатково

Debug log: записує розрахунки тарифів у WooCommerce > Status > Logs, джерело vfd-canada-post. Помилки API записуються завжди, навіть якщо цю опцію вимкнено. Ключі API, номери клієнтів і поштові індекси покупців не записуються.

Remove data on uninstall: якщо увімкнено, видалення плагіна стирає його налаштування, методи зон і кешовані тарифи. Деактивація плагіна нічого не видаляє.

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

Коли покупець вводить адресу доставки, WooCommerce запитує тариф у плагіна. Плагін спочатку перевіряє умови: вагу кошика, мінімальну суму замовлення та виключені класи доставки. Якщо діє безкоштовна доставка, покупець отримує безкоштовний тариф і запит до Canada Post не надсилається.

З ключами API плагін передає до Canada Post поштовий індекс відправлення, призначення, вагу посилки і, якщо всі товари мають розміри, орієнтовний розмір посилки. Для Канади призначенням є поштовий індекс, для США — ZIP-код, для інших країн — лише країна. Актуальний тариф запитується лише тоді, коли в канадській або американській адресі є коректний поштовий індекс чи ZIP-код. Canada Post повертає всі сервіси для посилки; плагін обирає обраний сервіс для групи призначення або найдешевший, прибирає канадські податки з продажу, якщо увімкнено Canadian sales taxes, і конвертує ціну в CAD за вашим курсом. Назва сервісу зберігається із замовленням і відображається на екрані замовлення в адмінці як Canada Post service.

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

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

Спосіб працює в класичному оформленні замовлення та в блоках Кошик і Оформлення замовлення. Він сумісний із WooCommerce High-Performance Order Storage (HPOS).

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

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розташований угорі WooCommerce > Settings > Shipping > VibeFox Canada Post. Вставте ключ у License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, і ваш домен. Check now — перевірити статус знову, Change key — ввести інший ключ, Remove key — видалити його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис vibefox.net.

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

Без активного ключа Canada Post не показується покупцям під час оформлення замовлення. Адміністратори магазину, які ввійшли в систему, як і раніше бачать його, позначеним (unlicensed — visible to admins only), щоб ви могли налаштувати й протестувати плагін до покупки ключа. Нагадування з'являється на сторінці Plugins і на сторінках WooCommerce. Існуючі замовлення не зачіпаються.

Коли ліцензія закінчується, плагін продовжує працювати, але оновлення та підтримка потребують продовження. Статус автоматично перевіряється у фоновому режимі.

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

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

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

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

Податок на доставку стягується двічі: увімкніть Canadian sales taxes або встановіть Tax status на None.

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

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

Блок ліцензії показує помилку: дотримуйтесь повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть слот у своєму обліковому записі vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати за останнім відомим статусом.

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте та видаліть плагін на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються. Налаштування, методи зон і кешовані тарифи видаляються лише якщо було увімкнено Remove data on uninstall. Інакше вони зберігаються для повторного встановлення. Замовлення ніколи не змінюються.

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