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; пустая или нулевая колонка использует 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.