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

Вимоги

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

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

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

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

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

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

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

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

Нічого не зберігається і показується помилка, якщо поле Method title порожнє, довше 64 символів або містить < > ; = # { }, якщо в числовому полі текст або від'ємне число, якщо курс NZD дорівнює 0, якщо Min cart weight (kg) більше за Max cart weight (kg) або якщо Sort order не є цілим числом. Над налаштуваннями з'являються попередження, якщо актуальні тарифи не можуть працювати із збереженими значеннями: заповнено лише одне з полів Client ID та Client Secret, немає курсу конвертації NZD або неповні дані для внутрішніх тарифів. Попередження також з'являється, якщо в магазині немає вагового класу з одиницею kg або лінійного класу з одиницею cm: ваги та розміри тоді переводяться за назвою одиниці їхнього класу (kg, g, lb, oz; cm, mm, m, in), а інші одиниці читаються як кг і см.

Загальні

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

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

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

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

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

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.

Client Secret: секрет клієнта OAuth2. Він обмінюється на токен доступу, який кешується до закінчення строку дії. Після збереження поле залишається порожнім і показує 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 (pickup site code).

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

Курс NZD → (валюта магазину): ціни NZ Post вказані в NZD. Якщо валюта магазину за замовчуванням не NZD, введіть, скільки одиниць вашої валюти становить один NZD, наприклад 0.55. Без цього значення актуальні тарифи не використовуються. Той самий курс перераховує вартість замовлення, яка передається в міжнародних запитах. Курс має бути більшим за 0. Якщо валюта вашого магазину — 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; порожня або нульова колонка використовує 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 кг); порожнє поле також означає 25. 0 означає відсутність обмеження. Якщо Ignore shipping zones увімкнено, порожнє поле означає відсутність обмеження для адрес поза Geo zone.

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

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

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

Доступність

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

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

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

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

Додатково

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

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

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

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

Export: натисніть Download JSON, щоб зберегти налаштування у файл JSON. Client Secret і auth code не експортуються.

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

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

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

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

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

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

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

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

Замовлення

Коли оформлено замовлення з NZ Post, розширення зберігає, на чому ґрунтувалася ціна доставки. Відкрийте замовлення в Sales > Orders: на сторінці замовлення є панель NZ Post із NZ Post service (тарифікована служба NZ Post для актуального тарифу, з її кодом) і Price source: Live rate (NZ Post ShippingOptions API), Fixed price або Free shipping. Панель показує значення на момент замовлення, навіть якщо тарифи або налаштування змінилися пізніше, а також коли спосіб доставки вимкнено. Покупець не бачить назву служби.

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

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

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

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

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

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

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

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

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

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

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

GST нараховується на доставку двічі: внутрішні тарифи NZ Post включають 15 % GST. Якщо спосіб має Tax class, встановіть API prices на Excluding GST.

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

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

Для розробників: район, що передається для адреси доставки в Новій Зеландії, можна змінити подією OpenCart vfd_nz_post/delivery_suburb (тригер catalog/vfd_nz_post/delivery_suburb). Адресу NZ Post API можна замінити налаштуванням vfd_nzpt_api_url (для тестів); на сторінці налаштувань для неї немає поля.

Видалення

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

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

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