VibeFox J&T Express for WooCommerce — Помощь

Требования

WordPress: 5.8 или новее.

WooCommerce: 5.0 или новее, установлен и активен. Плагин не активируется без него.

PHP: 8.0 или новее.

Доступ к API J&T Express Malaysia (только для онлайн-расчёта): онлайн-расчёт доступен только для J&T Express Malaysia и только для адресов доставки в Малайзии. Нужны четыре значения. Подайте заявку на VIP-аккаунт J&T на сайте J&T Express Malaysia (на странице настроек есть ссылка): J&T выдаст вам VIP-код клиента и VIP API-ключ. API-учётную запись и приватный ключ для подписи запросов J&T выпускает для интеграции через API. Запросите их у своего менеджера J&T. У J&T Philippines, Indonesia и других стран нет публичного API расчёта, поэтому для них используйте таблицу цен. Если вы используете только таблицу цен и резервную стоимость, доступ к API J&T не нужен.

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

Установка

1. В WordPress откройте Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку vfd_jt_express в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Shipping > VibeFox J&T Express или нажмите Settings под названием плагина на странице Plugins.

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

5. Заполните таблицу цен и/или резервную стоимость. Для онлайн-расчёта по Малайзии также введите учётные данные API J&T, почтовый индекс отправителя и, если валюта магазина не MYR, курс конвертации (см. раздел «Настройка»).

6. Добавьте VibeFox J&T Express в зону доставки: WooCommerce > Settings > Shipping > Shipping zones, или включите Ignore shipping zones и выберите страны.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Shipping > VibeFox J&T Express. Они действуют для всех зон доставки. Когда вы добавляете способ в зону, в окне зоны есть только одно поле:

Title (zone): название, которое покупатель видит для этой зоны. Оставьте поле пустым, чтобы использовать общее Method title.

При каждом сохранении настроек кэш расчётов J&T очищается. Если онлайн-расчёт настроен не полностью, предупреждение вверху страницы перечисляет недостающие настройки или сообщает, что не задан курс конвертации валюты.

Общие

Enable/Disable: включает или выключает способ во всех зонах сразу. По умолчанию: on.

Method title: название способа доставки, которое показывается в корзине и при оформлении заказа. Зона может его переопределить. По умолчанию: J&T Express.

Tax status: Taxable добавляет налог на доставку вашего магазина к стоимости, None — не добавляет. Выберите None, если тариф J&T уже включает всё, что вы хотите взимать.

API J&T Express Malaysia (онлайн-расчёт) (необязательно, для адресов доставки в Малайзии; нужны все четыре значения)

VIP customer code: ваш VIP-код клиента J&T Express.

VIP API key: API-ключ (пароль), который J&T Express выдал вместе с VIP-кодом. Он никогда не записывается в журнал.

API account: название вашей API-учётной записи J&T Express.

API private key: приватный ключ API-учётной записи. Он используется только для подписи запросов (SHA-256). Он никогда не отправляется в J&T и не записывается в журнал.

Sender postcode: малайзийский почтовый индекс, с которого отправляются посылки. Оставьте поле пустым, чтобы использовать почтовый индекс магазина из WooCommerce > Settings > General, если магазин находится в Малайзии. Пробелы удаляются при сохранении.

Currency conversion rate: тарифы J&T Express Malaysia указаны в MYR. Если валюта вашего магазина не MYR, укажите, сколько единиц вашей валюты стоит один MYR (1 MYR = X). Без этого значения онлайн-расчёт не используется, вместо него применяются таблица цен или резервная стоимость. Если валюта магазина MYR, оставьте поле пустым: тарифы используются без изменений. В качестве десятичного разделителя принимаются и точка, и запятая.

Таблица цен и резерв (используется для стран, кроме Малайзии, когда онлайн-расчёт не настроен или когда J&T не возвращает расчёт; цены в валюте вашего магазина)

Country prices: таблица с одной строкой на страну. Нажмите Add country, чтобы добавить строку, и крестик, чтобы удалить её. Выберите * Any other country для всех стран без собственной строки. В каждой строке есть Base price и пять весовых категорий: XS — до 1 кг, S — до 2 кг, M — до 3 кг, L — до 5 кг и XL — свыше 5 кг. Цена категории больше 0 заменяет базовую цену для корзин этой категории. Категория с 0 использует базовую цену. Базовая цена 0 означает бесплатную доставку, а пустая базовая цена сохраняется как 0. Страны без строки (если нет строки *) не получают цену из таблицы.

Fallback cost: цена, которая используется, когда ни J&T, ни таблица не дают цену. Оставьте поле пустым, чтобы в этом случае скрыть способ доставки.

Table / fallback price is: Per order — цена берётся один раз. Per item (multiplied by the number of items) — цена умножается на количество товаров в корзине. Онлайн-расчёты J&T всегда относятся ко всему заказу.

Условия

Free shipping from: сумма корзины (после скидок, до налогов), начиная с которой доставка бесплатна. Оставьте поле пустым, если бесплатной доставки не будет.

Minimum subtotal: показывать способ только тогда, когда сумма корзины достигает этого значения. Оставьте поле пустым, чтобы показывать его всегда.

Min weight (kg): скрывать способ, когда корзина весит меньше. Вес товаров пересчитывается из единицы веса вашего магазина. 0 означает без ограничения.

Max weight (kg): скрывать способ, когда корзина весит больше. По умолчанию: 50. 0 означает без ограничения.

Excluded shipping classes: скрывать способ, если в корзине есть товар из любого из этих классов доставки WooCommerce.

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

Ignore shipping zones: предлагать способ для стран, указанных ниже, даже если он не добавлен ни в одну зону доставки. Когда опция выключена, способ отображается только в тех зонах, куда он добавлен.

Countries: страны назначения для этого режима. Оставьте пустым, чтобы использовать все страны, в которые вы доставляете. Это поле используется только при включённой опции Ignore shipping zones.

Дополнительно

Debug log: записывает расчёты цен в WooCommerce > Status > Logs, источник vfd-jt-express. Ошибки API J&T записываются всегда, даже если эта опция выключена. Ключи, пароли и почтовые индексы покупателей не записываются. Выключите журнал, когда закончите.

Remove data on uninstall: если включено, удаление плагина удаляет его настройки, способы для зон и кэш расчётов. Деактивация плагина ничего не удаляет.

Как это работает при оформлении заказа

Когда покупатель вводит адрес доставки, WooCommerce запрашивает у плагина тариф. Сначала плагин проверяет условия: страну доставки, вес корзины, минимальную сумму и исключённые классы доставки. Если сумма корзины достигает Free shipping from, способ показывается с ценой 0, но только если для страны есть цена: строка в Country prices, Fallback cost или онлайн-расчёт J&T. Запрос к J&T делается, только если таблица и резервная стоимость не дают цену.

Иначе стоимость берётся из первого источника, который даёт цену:

1. Онлайн-расчёт J&T: только если заданы все четыре значения API и почтовый индекс отправителя, страна доставки — Малайзия, покупатель ввёл 5-значный почтовый индекс и, для магазинов не в MYR, задан курс конвертации. Плагин отправляет в J&T почтовые индексы отправителя и получателя и вес корзины (не менее 0,1 кг) для стандартной услуги EZ, одна посылка, и пересчитывает полученную в MYR цену в валюту вашего магазина.

2. Country prices: строка страны доставки или строка *, с ценой весовой категории корзины.

3. Fallback cost.

Если ни один из источников не даёт цену, способ скрывается. Per item применяется только к ценам таблицы и резервной стоимости.

Каждый ответ J&T кэшируется на 1 час, поэтому одна и та же корзина не вызывает новый запрос. Неудачный запрос кэшируется на 10 минут, чтобы оформление заказа не ждало J&T при каждом обновлении. Таймаут запроса — 10 секунд. Если J&T возвращает ошибку, нулевую цену или не отвечает, покупатель не видит ошибки. Используется цена из таблицы или резервная стоимость, а причина записывается в журнал.

Способ работает при классическом оформлении заказа и в блоках «Корзина» и «Оформление заказа». Он совместим с высокопроизводительным хранилищем заказов WooCommerce (HPOS).

Плагин только рассчитывает стоимость доставки. Он не создаёт накладные, транспортные накладные или этикетки, не вызывает курьера, не отменяет и не отслеживает отправления и не позволяет покупателю выбрать пункт выдачи. Создавайте и отслеживайте отправления в личном кабинете J&T, как обычно. Плагин создан на основе формата запросов официального плагина J&T Express Malaysia. Перед запуском магазина уточните тарифы в своём аккаунте J&T.

Лицензионный ключ

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Shipping > VibeFox J&T Express. Вставьте ключ в поле License key и нажмите Activate. В блоке показан статус, например дата, до которой лицензия активна, и ваш домен. Кнопка Check now повторно проверяет статус, Change key позволяет ввести другой ключ, а Remove key удаляет ключ с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

Один ключ работает на одном домене. Удаление ключа с сайта не освобождает место под домен. Освободите его в своём аккаунте на vibefox.net.

Без активного ключа J&T Express не показывается покупателям при оформлении заказа. Администраторы магазина, вошедшие в систему, видят его с пометкой (unlicensed — visible to admins only), чтобы вы могли настроить и проверить плагин до покупки ключа. Напоминание появляется на странице Plugins и на страницах WooCommerce. Существующие заказы не затрагиваются.

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

Устранение неполадок

J&T Express не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и способ добавлен в зону страны покупателя (или включено Ignore shipping zones и страна разрешена). Проверьте ограничения по весу, Minimum subtotal и Excluded shipping classes. Проверьте, что в Country prices есть строка для страны или строка *, либо что задано Fallback cost. Включите Debug log и посмотрите WooCommerce > Status > Logs.

Цена берётся из таблицы, а не от J&T: для онлайн-расчёта нужны все четыре значения API, почтовый индекс отправителя, малайзийский адрес доставки с 5-значным почтовым индексом и, для магазинов не в MYR, Currency conversion rate. Проверьте предупреждения вверху страницы настроек. Если J&T отклоняет запрос или не отвечает, ошибка записывается в журнал и используется цена из таблицы или резервная стоимость. Неудачный запрос повторяется через 10 минут.

Нет онлайн-расчёта для Филиппин и Индонезии: J&T не предлагает публичного API расчёта для этих стран. Используйте для них таблицу цен и резервную стоимость.

Стране по ошибке назначена бесплатная доставка: в её строке базовая цена 0 (пустая базовая цена сохраняется как 0). Введите базовую цену или удалите строку.

Тарифы выглядят устаревшими после изменений: сохраните страницу настроек. Это очистит кэш расчётов J&T.

Хуки для разработчиков: фильтр vfd_jtex_quote_request изменяет тело запроса расчёта (например, тип услуги), vfd_jtex_api_url меняет адрес API расчёта, а стандартный фильтр woocommerce_shipping_vfd_jt_express_is_available управляет доступностью.

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

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить его полностью, деактивируйте и удалите плагин на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки, способы для зон и кэш расчётов удаляются, только если была включена опция Remove data on uninstall. В противном случае они сохраняются для повторной установки. Существующие заказы сохраняют свои строки доставки.

J&T Express — товарный знак его владельца. Этот плагин не связан с J&T Express и не одобрен компанией.