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 і не схвалений компанією.