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

Вимоги

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

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

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

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

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

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

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

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

Якщо значення неправильне, сторінка показує помилку і нічого не зберігається: числове поле або ціна в Country prices, яка не є числом 0 або більше (наприклад, -1 чи 12abc), курс CAD, що дорівнює 0, Min cart weight (kg) більше за Max cart weight (kg), Method title довше 64 символів або із символами < > ; = # { }, Sort order, що не є цілим числом, або невідомий податковий клас чи геозона. Якщо в магазині немає класу ваги з одиницею "kg" або класу довжини з одиницею "cm", сторінка попереджає, що ваги та розміри перераховуються за назвою одиниці їхнього класу (kg, g, lb, oz; cm, mm, m, in), а інші одиниці читаються як кг або см.

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

Загальні

Налаштування застосовуються до всіх геозон. Ціна завжди береться з цього розширення: живий тариф Canada Post або фіксовані ціни за країнами.

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

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

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

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

API Canada Post (живі тарифи)

Якщо заповнено ім'я користувача та пароль API, ціна береться з Canada Post Rating API. Якщо 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 API 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: сервіс для канадських адрес: найдешевший доступний, Regular Parcel (DOM.RP, за замовчуванням), Expedited Parcel (DOM.EP), Xpresspost (DOM.XP) або Priority (DOM.PC).

Service to the USA: найдешевший доступний (за замовчуванням), 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: найдешевший доступний (за замовчуванням), 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 включає ці податки. Увімкніть, коли OpenCart сам додає податок на доставку (Tax class вище), щоб податок не стягувався двічі.

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

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

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

Country prices: таблиця країн з ціною Base та цінами залежно від ваги кошика у валюті за замовчуванням вашого магазину, без податків: XS до 1 кг, S 1–2 кг, M 2–3 кг, L 3–5 кг, XL понад 5 кг. Порожня або нульова ціна розміру використовує ціну Base. Натисніть Add country, щоб додати рядок. Рядок * 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: показує спосіб доставки лише тоді, коли проміжна сума товарів, що потребують доставки (після купона, без податків), досягає цієї суми. Залиште поле порожнім, щоб показувати його завжди.

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

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

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

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

Зазвичай спосіб доставки пропонується в геозоні, обраній у Conditions.

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

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

Додатково

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

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

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

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

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

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

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

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

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

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

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

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

В OpenCart 4 покупець натискає Choose у блоці способу доставки на сторінці оформлення замовлення і вибирає Canada Post у вікні Shipping method options, наприклад Canada Post - $12.50. Спосіб працює так само, як в OpenCart 3.

Замовлення

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

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

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

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

Сервіс не додається до листів про замовлення та до сторінки замовлень покупця; там показуються назва способу доставки та вартість доставки, як для будь-якого іншого способу доставки OpenCart.

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

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

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

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

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

Canada Post не з'являється під час оформлення замовлення: перевірте, чи ліцензія активна і чи увімкнено Enable Canada Post. Перевірте Geo zone або чи увімкнено Ignore shipping zones і чи дозволена країна. Перевірте обмеження ваги та Minimum order amount, а також чи у товарів Requires Shipping встановлено Yes. Має існувати тариф: з обліковими даними 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 class у No tax.

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

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

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

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

Видалення

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

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

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