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: пригород адреса, с которого отправляются посылки, например 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 и не одобрен ею.