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

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

Доступ к 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 на Филиппинах, в Индонезии и других странах публичного API расчёта нет, поэтому для них используйте таблицу цен. Если вы используете только таблицу цен и резервную стоимость, доступ к API J&T не нужен.

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

Установка

1. В Back Office перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox J&T Express в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в поле License key в блоке лицензии вверху страницы Configure и нажмите Activate (см. Лицензионный ключ).

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

При установке модуль создаёт перевозчика J&T Express с текстом срока доставки Courier delivery. Перевозчик назначается всем зонам и всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Не задавайте там цены: цена всегда берётся из модуля.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox J&T Express > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает кэш расчётов J&T. Если онлайн-расчёт настроен не полностью, предупреждение вверху страницы перечисляет недостающие настройки или сообщает, что не задан курс конвертации валюты. Суммы, которые не являются числом не меньше 0, отклоняются с ошибкой, так же как Currency conversion rate, равный 0, и Min weight, большее Max weight. Если единица веса вашего магазина не распознана, предупреждение просит задать стандартную единицу в International > Localization.

Общие

Настройки этой страницы действуют для всех зон. Зоны, группы клиентов и ограничения по размеру перевозчика задаются в Shipping > Carriers (или используйте Ignore shipping zones ниже).

Enable J&T Express: включает или выключает перевозчика. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

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

Tax: налоговое правило перевозчика или No tax. Налоговое правило добавляет налог на доставку вашего магазина к стоимости. Выберите No tax, если цена J&T уже включает всё, что вы хотите взять с покупателя.

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

VIP customer code: ваш VIP-код клиента J&T Express. Очистка также удаляет сохранённый VIP API-ключ.

VIP API key: API-ключ (пароль), который J&T Express выдал вместе с VIP-кодом. Он никогда не записывается в журнал. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

API account: название вашей API-учётной записи J&T Express. Очистка также удаляет сохранённый приватный ключ.

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

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

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

Таблица цен и резерв (используется для стран, отличных от Малайзии, когда онлайн-расчёт не настроен или когда 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, ни таблица не дают цену. Оставьте поле пустым, чтобы скрыть перевозчика в этом случае. 0 означает бесплатную доставку.

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

Условия

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

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

Min weight: скрывать перевозчика, если корзина весит меньше, в кг. Веса товаров пересчитываются из единицы веса вашего магазина. 0 — без ограничения. Не может быть больше Max weight.

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

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

Ignore shipping zones: предлагать перевозчика для стран, указанных ниже, даже если он не привязан к их зоне. При включении перевозчик привязывается ко всем активным зонам, а также к зонам, которые вы создадите позже. При выключении перевозчик предлагается только в его собственных зонах в Shipping > Carriers. Выключение возвращает перевозчику его прежние зоны.

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

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

Debug log: записывает расчёты цен в logs/vfd_jtex_debug.log.php в папке модуля. Файл нельзя открыть через веб. Ошибки API J&T всегда записываются в журнал, даже при выключенной опции. Ключи, пароли и почтовые индексы покупателей не записываются. Выключите журнал, когда закончите.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Remove data on uninstall: если включено, удаление модуля стирает настройки модуля, перевозчика, кэш расчётов и журнал. Если выключено, всё сохраняется для повторной установки.

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

На этапе доставки PrestaShop запрашивает у модуля цену J&T Express. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в сумму корзины. Модуль сначала проверяет условия: страна доставки (с учётом Ignore shipping zones), вес корзины и минимальная сумма. Если сумма корзины достигает Free shipping from, цена равна 0 и запрос в J&T не отправляется.

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

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

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

3. Резервная стоимость.

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

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

Если вы редактируете перевозчика в Shipping > Carriers после того, как у него появились заказы, PrestaShop сохраняет его как новую версию перевозчика. Модуль автоматически следует за новой версией.

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

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox J&T Express — это первый блок на странице Modules > Module Manager > VibeFox J&T Express > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-shipping-jt-express и ссылка 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.

Без активного ключа перевозчик J&T Express не показывается покупателям при оформлении заказа, и стоимость не рассчитывается. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому перевозчик скрыт и для вас: вы можете настроить модуль до покупки ключа, но не можете проверить его при оформлении заказа. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются.

Когда лицензия истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова во время вашей работы в бэк-офисе: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Задание cron не требуется. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

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

J&T Express не появляется при оформлении заказа: проверьте, что лицензия активна и включён Enable J&T Express. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя (или что включён Ignore shipping zones и страна разрешена). Проверьте ограничения по весу и Minimum subtotal. Убедитесь, что в Country prices есть строка для страны или строка *, либо задана Fallback cost. Товары также могут быть ограничены определёнными перевозчиками на странице товара. Включите Debug log и посмотрите поле Log на странице модуля.

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

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

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

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

На странице написано, что перевозчик J&T Express не найден: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его заново.

Хуки для разработчиков: хук actionVfdJtexQuoteRequest изменяет тело запроса расчёта (например, тип услуги), а actionVfdJtexApiUrl меняет адрес эндпоинта расчёта.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox J&T Express и выберите Uninstall. Лицензионный ключ и статус лицензии всегда удаляются. Кэш расчётов всегда удаляется. Если Remove data on uninstall включено, перевозчик удаляется (заказы сохраняют свою историю), а настройки и журнал стираются. Если выключено, перевозчик только отключается, а все настройки сохраняются. При повторной установке модуля сохранённому перевозчику возвращается его прежний статус.

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