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 и не одобрено ею.