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

Требования

OpenCart: 3.0.x (протестировано на 3.0.5.0) или 4.0.2 и новее (протестировано на 4.1.0.3).

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

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

Установка

Скачиваемый файл — это один zip-архив с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 vfd_jt_express-oc3-(version).ocmod.zip и пакет для OpenCart 4 vfd_jt_express.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ одинаков для обеих версий.

OpenCart 3

1. В админке перейдите в Extensions > Installer, нажмите Upload и выберите файл vfd_jt_express-oc3-(version).ocmod.zip. Расширение не добавляет модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо Installer можно скопировать содержимое папки upload этого пакета в корневую папку магазина.

2. Перейдите в Extensions > Extensions и выберите тип расширения Shipping. Найдите VibeFox J&T Express и нажмите Install (зелёная кнопка +).

3. Нажмите Edit (кнопка с карандашом), чтобы открыть страницу настроек.

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

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

OpenCart 4

1. В админке перейдите в Extensions > Installer, нажмите Upload и выберите файл vfd_jt_express.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на той же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Перейдите в Extensions > Extensions и выберите тип расширения Shipping. Найдите VibeFox J&T Express, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ и настройки так же, как в шагах 4 и 5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях.

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox J&T Express > Edit. Разделы перечислены слева. Одна кнопка Save внизу сохраняет всю страницу без перезагрузки. Каждое сохранение также очищает кэш тарифов J&T. Если значение неверно, ничего не сохраняется, и страница показывает причину: неверное название способа, сумму, которая не является числом 0 или больше, Currency conversion rate, равный 0, Min weight (kg) больше, чем Max weight (kg), или порядок сортировки, который не является целым числом. Сохранять настройки могут только администраторы с правом изменения этого расширения.

Предупреждения над настройками (они показываются снова после каждого сохранения) сообщают, если актуальные тарифы настроены не полностью: они перечисляют недостающие настройки API или говорят, что валюта магазина не MYR и не задан курс конвертации. Ещё одно предупреждение появляется, если в магазине нет весовой единицы с кг в разделе System > Localisation > Weight Classes. Тогда веса товаров переводятся по названию их единицы (kg, g, lb, oz), а остальные единицы считаются килограммами.

Общие

Способ доставки предлагается для выбранной гео-зоны или для стран из Ignore shipping zones. Настройки этой страницы применяются ко всем зонам.

Enable J&T Express: показывает или скрывает способ доставки при оформлении заказа (статус этого расширения). По умолчанию: выключено.

Method title: название способа доставки, которое видит покупатель в корзине и при оформлении заказа. По умолчанию: J&T Express. Обязательно, до 64 символов, без символов < > ; = # { }.

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

Sort order: позиция способа доставки среди других способов при оформлении заказа. Целое число.

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

Тариф запрашивается у 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. Вводите новое значение, только чтобы его изменить. Чтобы удалить ключ, очистите VIP customer code и сохраните.

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

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

Sender postcode: малайзийский почтовый индекс, из которого отправляются посылки, например 50000. Обязателен для актуальных тарифов: адрес магазина в OpenCart — свободный текст, поэтому индекс из него никогда не берётся.

Currency conversion rate: тарифы J&T Express Malaysia указаны в MYR. Если основная валюта вашего магазина не MYR, укажите, сколько единиц вашей валюты стоит один MYR (1 MYR = X), например 0.20. Без этого значения актуальные тарифы не используются, вместо них применяются таблица цен или резервная стоимость. Если основная валюта — 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 (kg): скрыть способ доставки, если корзина весит меньше. Веса товаров переводятся по их весовой категории. 0 означает без ограничения (по умолчанию). Не может быть больше Max weight (kg).

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

Geo zone: предлагать способ доставки только для адресов в этой гео-зоне. All zones (по умолчанию) означает без ограничения. Гео-зоны настраиваются в System > Localisation > Geo Zones. Не используется, если включено Ignore shipping zones.

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

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

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

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

Debug log: записывает расчёты цен в storage/logs/vfd_jtex_debug.log.php (в OpenCart 4 — system/storage/logs/vfd_jtex_debug.log.php). Файл нельзя прочитать из веба. Ошибки API J&T всегда записываются в журнал, даже если эта опция выключена. Ключи, пароли, код клиента и почтовые индексы покупателей не записываются. Выключите журнал, когда закончите. Когда файл достигает 5 МБ, он переносится в vfd_jtex_debug.old.log.php, и начинается новый журнал.

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

Remove data on uninstall: если включено, при удалении расширения удаляются настройки J&T Express и журнал. Если выключено (по умолчанию), они сохраняются для повторной установки. Кэшированные тарифы удаляются всегда.

Импорт / Экспорт

Export: нажмите Download JSON, чтобы сохранить настройки в файл JSON. VIP API-ключ и приватный ключ не экспортируются.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки, например в другом магазине. Значения проверяются так же, как при обычном сохранении. Сохранённые ключи остаются.

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену J&T Express. Если задана Geo zone (и Ignore shipping zones выключено) и адрес вне неё, способ доставки не предлагается. Учитываются только товары с Requires Shipping в значении Yes: остальные товары не добавляют вес и не входят в сумму. Затем расширение проверяет условия: разрешённые страны (с 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 применяется только к ценам таблицы и резервным ценам. Цена рассчитывается в основной валюте вашего магазина, округляется до её знаков после запятой и показывается покупателю в его валюте с налогом выбранного Tax class.

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

В OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа и выбирает J&T Express в окне Shipping method options. Способ работает так же, как в OpenCart 3.

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

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

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

Без активного ключа способ доставки J&T Express не показывается покупателям при оформлении заказа, и тариф не рассчитывается. Администратор, вошедший в админку в том же браузере, всё равно видит способ доставки в магазине с пометкой (unlicensed — visible to admins only), поэтому вы можете настроить и проверить расширение до покупки ключа. В OpenCart 4 этот предпросмотр недоступен: магазин не видит вход в админку, поэтому без активного ключа способ доставки скрыт для всех. После того как вы один раз откроете страницу Edit, на Dashboard в админке появится напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются.

Когда срок лицензии истекает, расширение продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова при открытии Dashboard в админке или страницы Edit: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задание не нужно. При удалении расширения всегда удаляются лицензионный ключ и статус лицензии.

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

J&T Express не появляется при оформлении заказа: проверьте, что лицензия активна и Enable J&T Express включено. Проверьте Geo zone (или что Ignore shipping zones включено и страна есть в Countries), ограничения по весу и Minimum subtotal. Проверьте, что в Country prices есть строка для страны или строка *, или что задана Fallback cost. Проверьте, что у товаров Requires Shipping в значении Yes. Включите 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.

На странице написано «Warning: You do not have permission to modify VibeFox J&T Express!»: ваша группа администраторов, возможно, может только просматривать настройки. Дайте группе право изменения для extension/shipping/vfd_jt_express (OpenCart 3) или extension/vfd_jt_express/shipping/vfd_jt_express (OpenCart 4) в System > Users > User Groups.

Для разработчиков: другие расширения могут изменить тело запроса тарифа (например, тип услуги) через событие OpenCart vfd_jt_express/quote_request, а адрес конечной точки тарифов — через vfd_jt_express/api_url.

Удаление

Перейдите в Extensions > Extensions, выберите тип Shipping и нажмите Uninstall (красная кнопка −) рядом с VibeFox J&T Express. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда сбрасывает Enable J&T Express, Sort order, Tax class и Geo zone. Кэшированные тарифы удаляются всегда. Если Remove data on uninstall включено, настройки J&T Express и журнал отладки тоже удаляются. Если выключено, остальные настройки сохраняются и снова используются при повторной установке расширения. Существующие заказы сохраняют свой способ доставки и стоимость.

В OpenCart 4, чтобы удалить также файлы расширения, перейдите после удаления в Extensions > Installer, нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox J&T Express в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

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