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

Вимоги

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

PHP: 8.0 або новіший.

Ключ PAC API Australia Post (лише для живих тарифів): живі тарифи використовують API Postage Assessment Calculator (PAC) від Australia Post. Ключ безкоштовний: зареєструйтеся для отримання ключа PAC API на Australia Post Developer Centre (developers.auspost.com.au). На сторінці налаштувань є посилання на сторінку реєстрації. Також потрібен австралійський поштовий індекс із 4 цифр, з якого ви відправляєте. Якщо ви використовуєте лише фіксовані ціни за країнами, ключ API не потрібен.

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

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

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

OpenCart 3

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

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

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

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

5. Оберіть Rate source (джерело тарифів). Для фіксованих цін додайте рядки в Country prices. Для живих тарифів введіть ключ PAC API, поштовий індекс відправлення і, якщо валюта за замовчуванням вашого магазину не AUD, курс у AUD (див. Налаштування). Увімкніть Enable Australia Post і натисніть Save.

OpenCart 4

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

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

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

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

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

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

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

Деякі помилки не дають зберегти налаштування, і тоді нічого не зберігається: Method title довший за 64 символи, Sort order, що не є цілим числом, або невідомий податковий клас чи геозона. Інші проблеми показуються як попередження над панеллю, а решта налаштувань зберігається. Числове поле зі значенням, яке не є числом або від'ємне, зберігає попереднє значення, а попередження називає поле. Числові поля приймають крапку або кому як десятковий роздільник.

Якщо обрано джерело живих тарифів, але бракує ключа API, поштового індексу відправлення з 4 цифр або курсу AUD, після збереження показується попередження. Воно також пояснює, що відбувається до виправлення: спосіб доставки приховується під час оформлення замовлення, або в режимі запасного варіанта використовуються фіксовані ціни за країнами. Сторінка також попереджає, якщо у вашому магазині немає класу ваги з одиницею kg або класу довжини з одиницею cm. Тоді ваги та розміри товарів переводяться за одиницею їхнього класу (kg, g, lb, oz; cm, mm, m, in), а інші одиниці читаються як кг і см.

Загальні

Налаштування діють для всіх геозон. Обмежити спосіб доставки геозоною можна в Conditions, або списком країн у Availability without shipping zones.

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

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

Rate source: як розраховується ціна.

Деталі помилок потрапляють у журнал, але не до покупця.

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

API Australia Post (живі тарифи) (не потрібно для фіксованих цін)

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

Remove the saved API key: увімкніть і збережіть, щоб видалити збережений ключ. Живі тарифи тоді перестають працювати.

Ship-from postcode: австралійський поштовий індекс із 4 цифр, з якого відправляються посилки, наприклад 2000.

Domestic service: використовується для доставки всередині Австралії (до 22 кг, 105 см з кожного боку): Parcel Post (за замовчуванням) або Express Post.

International service: використовується для доставки за межі Австралії (до 20 кг): International Standard (за замовчуванням), International Express або International Courier.

Remove GST: ділить внутрішні ціни API на 1,1. Внутрішні ціни Australia Post включають 10 % GST. Увімкніть, коли OpenCart сам додає податок до доставки (обрано Tax class), щоб GST не стягувався двічі. Міжнародна пересилка не обкладається GST і ніколи не змінюється.

AUD → (your currency) rate: мітка показує валюту за замовчуванням вашого магазину. Ціни Australia Post вказані в AUD. Якщо валюта за замовчуванням не AUD, введіть, скільки одиниць вашої валюти коштує один AUD, наприклад 0,61. Курс має бути більшим за 0. Без нього живі тарифи не використовуються. Якщо валюта за замовчуванням — AUD, поле вказує, що конвертація не потрібна: залиште його порожнім.

Посилка для живих тарифів

Кошик надсилається як одна посилка. Ваги та розміри товарів переводяться з класів ваги та довжини OpenCart у кг і см. Значення нижче використовуються для товарів без ваги або розмірів.

Default product weight (kg): використовується для кожного товару без ваги, у запиті до Australia Post і в перевірці Min cart weight (kg) / Max cart weight (kg). За замовчуванням: 1.

Default parcel length (cm): використовується, коли жоден товар у кошику не має розмірів. За замовчуванням: 22.

Default parcel width (cm): використовується, коли жоден товар у кошику не має розмірів. За замовчуванням: 16.

Default parcel height (cm): використовується, коли жоден товар у кошику не має розмірів. За замовчуванням: 8.

Коли товари мають розміри, посилка бере найбільші довжину та ширину серед них, а висота зростає, доки посилка не вміщує об'єм усіх товарів.

Фіксовані ціни (використовуються з фіксованими цінами і як запасний варіант для живих тарифів)

Country prices: список країн і цін у валюті за замовчуванням вашого магазину, без податків. Натисніть Add row, щоб додати рядок, і кнопку ×, щоб видалити рядок. Оберіть * All other countries для ціни, яка діє для кожної країни без власного рядка. Країна без ціни (і без рядка *) не отримує фіксованого тарифу, тому спосіб доставки для неї приховано. Рядки без ціни видаляються під час збереження. Таблиця порожня, доки ви не додасте ціни.

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

Умови

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

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

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

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

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

Tax class: податковий клас вартості доставки або No tax (за замовчуванням). Внутрішні ціни Australia Post включають GST: за наявності податкового класу увімкніть Remove GST.

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

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

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

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

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

Додатково

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

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

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

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

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

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

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

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

У режимі фіксованих цін ціна береться з таблиці. У режимах живих тарифів розширення надсилає в Australia Post вагу посилки та, для доставки всередині Австралії, поштові індекси відправлення й доставки та розміри посилки; для міжнародної доставки — країну призначення. Внутрішній живий тариф запитується, лише якщо в адресі доставки є поштовий індекс з 4 цифр. Запит не надсилається, якщо посилка перевищує межі Australia Post (22 кг або 105 см всередині країни, 20 кг міжнародна). Ціна в AUD перераховується за вашим курсом, а GST вилучається з внутрішніх цін, якщо увімкнено Remove GST. Ціна розраховується у валюті магазину за замовчуванням, округлюється до її знаків після коми і показується покупцеві у його валюті з податком обраного Tax class.

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

Розширення лише розраховує тарифи. Воно не створює етикетки, відправлення та маніфести eParcel або MyPost Business, не відстежує посилки і не дозволяє покупцям обирати постомати чи поштові відділення. Воно нічого не додає до замовлень: у замовленні показуються назва способу доставки та вартість доставки, як для будь-якого іншого способу доставки OpenCart. Кошик завжди розраховується як одна посилка. Листи, конверти та договірні тарифи (eParcel) не враховуються.

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

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

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Australia Post — перший блок сторінки Extensions > Extensions > Shipping > VibeFox Australia Post > Edit, над налаштуваннями. Вставте ключ у поле License key і натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа і Remove key для вилучення ключа з цього магазину. Нижче є рядок Product: opencart-shipping-australia-post і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише адміністратори з правом змінювати розширення. Тексти блоку відповідають мові адмінпанелі (включено англійську та російську).

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

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

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

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

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

Australia Post не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable Australia Post увімкнено. Перевірте Geo zone (або Ignore shipping zones і Countries), обмеження ваги кошика та Minimum order amount. У режимі фіксованих цін перевірте, що для країни або * All other countries є ціна. Перевірте, що у товарів Requires Shipping встановлено Yes.

Живі тарифи не з'являються: увімкніть Debug log, перезавантажте оформлення замовлення і перегляньте поле Log на сторінці розширення. Там вказано причину: немає ключа API або поштового індексу відправлення, ще немає поштового індексу доставки з 4 цифр, посилка поза межами, немає курсу AUD або повідомлення про помилку від Australia Post. З Live rates, fixed price if the API gives no rate покупці все одно отримують фіксовану ціну, поки ви виправляєте проблему.

Мій магазин не в AUD: введіть курс (скільки одиниць валюти за замовчуванням коштує один AUD) у полі AUD → (your currency) rate. Фіксовані ціни завжди вказуються у валюті за замовчуванням.

GST стягується з доставки двічі: внутрішні ціни Australia Post включають 10 % GST. Якщо обрано Tax class, увімкніть Remove GST або встановіть Tax class у No tax.

Ціна занадто висока або занадто низька: перевірте ваги та розміри товарів, їхні класи ваги та довжини, а також значення за замовчуванням у Parcel for live rates. За Item (price × quantity) фіксовані ціни множаться на кількість товарів.

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

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

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

Видалення

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

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

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