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

Вимоги

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

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

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

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

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

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

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

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

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

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

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

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

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

General

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

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

Tax status: Taxable додає податок WooCommerce до вартості доставки, None не додає. Див. також API prices нижче.

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

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

Client ID: ідентифікатор клієнта OAuth2 вашого застосунку NZ Post API.

Client Secret: секрет клієнта OAuth2. Він обмінюється на токен доступу, який кешується до закінчення строку дії.

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

Auth code: auth code рахунку для внутрішніх тарифів. Не потрібен, якщо ви вводите site code.

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

Ship-from 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 включають GST 15%; міжнародна пересилка оподатковується за нульовою ставкою. Оберіть Excluding GST, коли Tax status має значення Taxable, щоб GST не нараховувався двічі.

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

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

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

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

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

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

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

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

Умови

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

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

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

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

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

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

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

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

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

Додатково

Debug log: записує розрахунки тарифів у WooCommerce > Status > Logs (джерело «vfd-nz-post»). Помилки API записуються завжди, навіть з вимкненим журналом налагодження. Облікові дані, токени та адреси покупців не записуються. Вимкніть журнал, коли закінчите.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Тарифи в реальному часі не з'являються: відкрийте WooCommerce > Status > Logs, джерело «vfd-nz-post». Помилки API там є завжди. Увімкніть Debug log для деталей. Журнал показує причину: немає Client ID або Client Secret, токен відхилено, немає даних рахунку чи адреси відправлення, ще не вказано місто або поштовий індекс покупця, немає курсу NZD або немає служби з ціною. Поки ви виправляєте проблему, використовуються фіксовані ціни.

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

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

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

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

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

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

Видалення

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

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