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

Вимоги

PrestaShop: 8.0–9.x.

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

Доступ до API NZ Post (лише для тарифів у реальному часі): тарифи у реальному часі використовують NZ Post ShippingOptions API. Запитайте доступ до API в Developer Resource Centre на сайті NZ Post. NZ Post видає Client ID та Client Secret: спочатку для тестового середовища (UAT), а потім для продакшн після свого чек-листа запуску. Для тарифів всередині Нової Зеландії вам також потрібен діловий рахунок NZ Post: номер рахунку та його auth code або site code. Якщо ви використовуєте лише фіксовані ціни, доступ до API не потрібен.

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

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

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

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

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

4. Для тарифів у реальному часі заповніть розділ NZ Post API (live rates). За бажанням введіть фіксовані ціни: вони використовуються без тарифів у реальному часі та як запасний варіант (див. Налаштування). Натисніть Save.

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

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

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

Над налаштуваннями з'являються попередження, якщо тарифи у реальному часі не можуть працювати із збереженими значеннями: заповнено лише одне з полів Client ID і Client Secret, не вказано курс NZD або неповні дані для внутрішніх тарифів. Попередження також з'являється, якщо модуль не розпізнає одиницю ваги або розміру магазину (тоді ваги вважаються в кг, а розміри в см). Одиниці задаються в International > Localization (Local units). Числові поля мають містити 0 або додатне число; інакше сторінка покаже помилку, і нічого не буде збережено.

General

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

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

Tax: податкове правило перевізника або No tax (вартість доставки не оподатковується). Якщо магазин додає GST до доставки, встановіть нижче API prices на Excluding GST, щоб GST не нараховувався двічі.

NZ Post API (live rates) (залиште Client ID порожнім, щоб використовувати лише фіксовані ціни)

Environment: Production (api.nzpost.co.nz) (за замовчуванням) або Testing / UAT (api.uat.nzpost.co.nz). Використовуйте середовище, для якого видано ваш Client ID.

Client ID: OAuth2 client ID вашого застосунку NZ Post API. Якщо його очистити, також видаляється збережений Client Secret.

Client Secret: OAuth2 client secret. Він обмінюється на токен доступу, який кешується до закінчення строку дії. Після збереження поле лишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Account number: номер вашого ділового (платіжного) рахунку NZ Post. Обов'язковий для тарифів всередині Нової Зеландії. Для міжнародних тарифів він необов'язковий; із ним NZ Post повертає ваші договірні тарифи. Якщо його очистити, також видаляється збережений auth code.

Auth code: код авторизації рахунку для внутрішніх тарифів. Він не потрібен, якщо ви вводите site code. Як і Client Secret, після збереження він більше не показується.

Site code: альтернатива auth code: ваш код пункту приймання NZ Post.

Ship-from suburb: передмістя (suburb) адреси, з якої відправляються посилки, наприклад Petone. Потрібне для внутрішніх тарифів.

Ship-from city: населений пункт або місто, з якого відправляються посилки, наприклад Lower Hutt. Потрібне для внутрішніх тарифів.

Ship-from postcode: 4-значний новозеландський поштовий індекс, з якого відправляються посилки, наприклад 5012. Потрібен для внутрішніх тарифів.

Services: необов'язкові коди служб NZ Post через кому, наприклад CPOLP, ICOU. Тарифи розраховуються лише для цих служб. Залиште порожнім, щоб використовувати найдешевшу службу, яку NZ Post поверне для посилки.

API prices: Including GST (за замовчуванням) або Excluding GST. Внутрішні ціни NZ Post включають 15% GST; міжнародне поштове відправлення оподатковується за нульовою ставкою. Оберіть Excluding GST, коли у перевізника є податкове правило (Tax вище), щоб GST не нараховувався двічі.

Курс NZD → (валюта магазину): ціни NZ Post вказані в NZD. Якщо основна валюта вашого магазину не NZD, вкажіть, скільки одиниць вашої валюти коштує один NZD, наприклад 0.55. Без цього курсу тарифи у реальному часі не використовуються. Той самий курс перераховує суму замовлення, яка передається в міжнародних запитах. Курс має бути більшим за 0. Якщо валюта вашого магазину NZD, залиште поле порожнім.

Parcel for live rates

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

Default product weight (kg): використовується для кожного товару без ваги. За замовчуванням: 0.5.

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

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

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

Fixed prices (використовуються, коли тарифи у реальному часі не налаштовані або NZ Post не повертає тариф)

Ціни вказані в основній валюті магазину, без податків.

Country prices: один рядок на країну призначення. Натисніть Add country, щоб додати рядок, і значок кошика, щоб його видалити. Оберіть * Default для рядка, який охоплює всі інші країни. Кожен рядок має ціну Any weight і необов'язкові колонки за вагою: ≤ 1 kg, 1–2 kg, 2–3 kg, 3–5 kg і > 5 kg (вага кошика). Заповнена колонка ваги замінює Any weight; порожня або з 0 колонка використовує Any weight. Ціна Any weight, що дорівнює 0, означає безкоштовну доставку в цю країну. Приймаються обидва варіанти: «9.99» і «9,99». Рядки без жодної ціни та від'ємні ціни видаляються під час збереження. Для кожної країни зберігається лише один рядок.

Fallback cost: використовується, коли ні API, ні таблиця країн не дають ціну. Залиште порожнім, щоб у цьому випадку приховати перевізника.

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

Conditions

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

Max cart weight (kg): приховує перевізника, коли кошик важить більше. За замовчуванням: 25 (кур'єрські посилки NZ Post важать до 25 кг); порожнє поле також означає 25. 0 означає без обмеження. Коли Ignore shipping zones увімкнено, порожнє поле означає відсутність обмеження за межами власних зон перевізника. Якщо Min cart weight більше за Max cart weight, сторінка покаже помилку, і нічого не буде збережено, бо перевізник ніколи не відображався б.

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

Free shipping from: проміжна сума кошика (після знижок, до податків), від якої доставка NZ Post безкоштовна. Тоді запит до NZ Post не надсилається. Залиште порожнім, щоб ніколи не пропонувати безкоштовну доставку.

Для цих умов вага кошика враховує товари без ваги як 0.

Availability without shipping zones

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

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

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

Advanced

Debug log: записує розрахунки тарифів у файл logs/vfd_nzpt_debug.log.php у папці модуля. Відкрити цей файл через веб неможливо. Помилки API завжди записуються, навіть коли журнал налагодження вимкнено. Облікові дані, токени та адреси клієнтів не записуються. Вимкніть журнал, коли закінчите.

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

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

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

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

Коли тарифи у реальному часі налаштовано, модуль отримує токен доступу за вашими Client ID і Client Secret і запитує у NZ Post ціну. Для адреси в Новій Зеландії він надсилає дані вашого рахунку, адресу відправлення, передмістя, місто та поштовий індекс клієнта, а також вагу та розмір посилки. У PrestaShop немає поля для передмістя: модуль використовує Address line 2, якщо там є назва передмістя (без цифр), інакше — місто. Внутрішній тариф запитується лише після того, як клієнт вказав місто і 4-значний поштовий індекс. Для інших країн надсилаються країна призначення, вага й розмір посилки та сума замовлення в NZD.

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

Якщо NZ Post не повертає тариф (API не налаштовано, помилка, неповна адреса, служба недоступна, немає курсу NZD), клієнт не бачить жодної помилки. Використовується ціна з таблиці країн, потім резервна вартість. Якщо фіксованої ціни немає, перевізника приховують. Причина записується в журнал.

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

Модуль лише розраховує тарифи. Він не створює етикетки для відправлення, не замовляє кур'єра, не формує маніфести, не відстежує посилки, не перевіряє адреси і не дозволяє покупцям вибрати пункт видачі, абонентську скриньку (PO Box) або поштомат (parcel locker). Кошик оцінюється як одна посилка, і клієнт бачить один тариф NZ Post, а не список служб.

Замовлення

Коли оформлюється замовлення з перевізником NZ Post, модуль зберігає, на чому базувалася ціна доставки. На сторінці замовлення в адмін-панелі з'являється блок NZ Post із NZ Post service (розрахованою службою NZ Post для тарифу у реальному часі) та Price source: Live rate (NZ Post ShippingOptions API), Fixed price або Free shipping. Блок показує значення на момент замовлення, навіть якщо тарифи чи налаштування змінюються пізніше.

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

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

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

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

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

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

Тарифи у реальному часі не з'являються: перегляньте попередження у верхній частині сторінки модуля. Потім увімкніть Debug log, перезавантажте оформлення замовлення і перегляньте поле Log. Помилки API там завжди є. Журнал показує причину: відсутній Client ID або Client Secret, токен відхилено, немає даних рахунку чи відправлення, ще немає міста або поштового індексу клієнта, немає курсу NZD або немає служби з ціною. Поки ви виправляєте проблему, використовуються фіксовані ціни.

Запит токена не проходить: перевірте Client ID, Client Secret і Environment. Облікові дані UAT не працюють у продакшн і навпаки.

Внутрішні тарифи відсутні, міжнародні працюють: тарифи всередині Нової Зеландії потребують Account number, Auth code або Site code, а також повної адреси відправлення з 4-значним поштовим індексом. Клієнт має вказати місто і 4-значний поштовий індекс. Розробники можуть змінити передмістя, що передається для адреси доставки, за допомогою хука actionVfdNzptDeliverySuburb.

Мій магазин не в NZD: введіть NZD → (shop currency) rate. Фіксовані ціни завжди вказані в основній валюті магазину.

GST стягується з доставки двічі: внутрішні ціни NZ Post включають 15% GST. Якщо у перевізника є податкове правило в Tax, встановіть API prices на Excluding GST.

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

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

Видалення

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

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