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, курс конвертації валюти (див. Configuration). Увімкніть 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 і не схвалене нею.