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

Вимоги

PrestaShop: 8.0–9.x.

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

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

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

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

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

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

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

4. Оберіть Rate source. Для тарифів у реальному часі введіть ключ PAC API, свій поштовий індекс відправлення і, якщо основна валюта вашого магазину не AUD, курс перерахунку в AUD (див. розділ «Конфігурація»). Натисніть Save.

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

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

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

Якщо вибрано джерело тарифів у реальному часі, але не заповнено ключ API, 4-значний поштовий індекс відправлення або курс перерахунку в AUD, після збереження з'являється попередження. Воно також повідомляє, що відбувається до виправлення: перевізника приховано під час оформлення замовлення або в режимі резервного варіанту використовуються фіксовані ціни для країн.

Числові поля приймають крапку або кому як десятковий роздільник. Значення, яке не є числом або від'ємне, не зберігається: попередження називає поле, а попереднє значення залишається. Сторінка також попереджає, якщо одиниця ваги або розміру магазину (International > Localization) невідома модулю. Тоді вага товарів читається як кг, а розміри — як см.

Загальні

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

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

Tax status: як податок застосовується до вартості доставки.

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

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

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

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. Увімкніть, коли PrestaShop сам додає податок до доставки (Tax status = Taxable з податковим правилом у перевізника), щоб GST не стягувався двічі. Міжнародна доставка звільнена від GST і ніколи не змінюється.

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

Посилка для тарифів у реальному часі

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

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: таблиця двобуквених кодів країн (AU, NZ, US тощо) і цін в основній валюті магазину без податків. Натисніть Add row, щоб додати країну, і посилання ×, щоб видалити рядок. Використовуйте * для всіх інших країн. Країна без ціни (і без рядка *) не має фіксованого тарифу, тому перевізника для неї приховано. Рядки з неправильним кодом країни або без ціни видаляються під час збереження. Таблиця порожня, доки ви не додасте ціни.

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.

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

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

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

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

Додатково

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Тарифи в реальному часі не з'являються: увімкніть 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 status = Taxable і у перевізника є податкове правило, увімкніть Remove GST або встановіть Tax status у значення None.

Податок не додається до доставки: за Tax status = Taxable податок береться з податкового правила перевізника. Оберіть його в Shipping > Carriers. Сторінка модуля показує попередження, поки у перевізника немає податкового правила.

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

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

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

Видалення

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

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