VibeFox iMile for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

PHP: 8.0 або новіша. Модуль не встановлюється на старіші версії PHP.

Тариф iMile: ціни, погоджені з відділом продажів iMile. Ви вводите їх у таблиці цін у валюті магазину за замовчуванням.

Обліковий запис API iMile (лише для онлайн-розрахунку): онлайн-розрахунок використовує метод OpenAPI iMile «Estimated order delivery costs». Потрібні Customer ID та Secret key (ключ API, який iMile видає разом із Customer ID). Для тестового клієнта зареєструйтеся на порталі розробників iMile (developer.imile.com). Бойові ключі видає ваш менеджер iMile. Якщо ви використовуєте лише таблицю цін, ключі API не потрібні.

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

Встановлення

1. У бек-офісі перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox iMile у списку модулів і натисніть Configure.

3. Введіть ліцензійний ключ VibeFox у License key у блоці ліцензії у верхній частині сторінки Configure і натисніть Activate (див. розділ «Ліцензійний ключ»).

4. Введіть ваші ціни iMile у Price table. За бажанням заповніть розділ Live rates (API) і увімкніть Live estimate (див. Налаштування). Натисніть Save.

Під час встановлення модуль створює перевізника iMile з текстом строку доставки Courier delivery. Перевізник призначається всім зонам і всім групам покупців. Зони, групи покупців, строк доставки, логотип і обмеження за розміром можна змінити в Shipping > Carriers. Не встановлюйте там ціни: ціна завжди береться з модуля.

Налаштування

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox iMile > Configure. Вони діють для всіх зон перевізника. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищає кеш розрахунків iMile і токени доступу.

Якщо Live estimate увімкнено, але не може працювати, над налаштуваннями з'являються попередження: Customer ID або Secret key порожні, не вказано місто або країну відправлення (або країна не є ринком iMile), немає курсів обміну, або таблиця цін порожня і немає ціни для інших країн. Попередження також з'являється, якщо модуль не знає одиницю ваги магазину: тоді вага товарів приймається в кілограмах, тож задайте одиницю в International > Localization (Local units). Під час збереження модуль перевіряє, що Method title коректний (не більше 64 символів), що поля суми та ваги є числами не меншими за 0, що Minimum weight не більше за Maximum weight і що податкове правило існує. Інакше він показує помилку й нічого не зберігає.

Загальні

Enable iMile: вмикає або вимикає перевізника. Це той самий перемикач, що й статус перевізника в Shipping > Carriers.

Method title: назва перевізника, яка показується в кошику та під час оформлення замовлення. За замовчуванням: iMile. Обов'язково.

Онлайн-тарифи (API) (необов'язково)

Якщо iMile не повертає розрахунок (немає ключів, місто ще не введено, помилка, тайм-аут, немає курсу обміну), використовується таблиця цін.

Live estimate: увімкніть, щоб отримувати вартість доставки від iMile. За замовчуванням: вимкнено. Поки онлайн-розрахунок вимкнений, під час оформлення замовлення нічого не надсилається в iMile.

Environment: Production (openapi.imile.com) (за замовчуванням) або Test (test-openapi.52imile.cn). Тестові ключі працюють лише з тестовим сервером і дають тестові ціни.

Customer ID: код клієнта (customerId), виданий iMile, наприклад C2102192601. Очищення також очищає збережений Secret key.

Secret key: секретний ключ (ключ API), виданий iMile разом із Customer ID. Він підписує запити. Після збереження поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Signature: спосіб підпису запитів.

Ship-from country: країна, з якої ви відправляєте. За замовчуванням це країна вашого магазину (Shop country). У списку лише ті країни, для яких модуль знає коди iMile.

Ship-from city: місто, з якого відправляються ваші посилки, написане так само, як у списку міст iMile (наприклад, Dubai, Riyadh). Залиште порожнім, щоб використовувати місто магазину з Shop Parameters > Contact > Stores.

Ship-from province: необов'язково, наприклад Dubai або Riyadh Province.

iMile service: тип замовлення, який надсилається в iMile: Delivery order (100) (за замовчуванням) або Express order (1100). Express має бути увімкнено для вашого облікового запису й країни.

Goods category: вид товару, який надсилається в iMile: Normal goods (за замовчуванням), Sensitive (cosmetics, liquids...), With battery, Batteries / power banks, Documents або Parcel.

Exchange rates: iMile розраховує вартість у валюті країни призначення. Введіть по одному рядку на валюту з ціною 1 одиниці у валюті магазину за замовчуванням, наприклад «AED = 0.25» або «SAR = 0.24». Десятковим роздільником приймаються крапка або кома. Курс для самої валюти магазину не потрібен. Без курсу розрахунки в цій валюті не використовуються, натомість береться таблиця цін. Той самий курс переводить вартість кошика, оголошену в iMile. Некоректні рядки видаляються під час збереження.

Ціни (використовуються, коли онлайн-розрахунок вимкнено, і як запасний варіант, якщо iMile не повертає розрахунок)

Введіть ваш тариф iMile у валюті магазину за замовчуванням, без податку. Якщо він у AED, SAR або іншій валюті, спочатку переведіть його.

Price table: один рядок на країну призначення. Натисніть Add country, щоб додати рядок, і значок кошика, щоб видалити його. Оберіть * All other countries для рядка, який охоплює всі країни без власного рядка. Кожен рядок має Base price і необов'язкові вагові колонки: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg та XL >5 kg. Порожня (або 0) вагова колонка використовує базову ціну. Базова ціна 0 означає безкоштовну доставку до цієї країни. Приймаються як «9.99», так і «9,99». Рядки без жодної ціни та від'ємні ціни видаляються під час збереження. Для кожної країни залишається лише один рядок.

Price for countries not in the table: ціна у валюті магазину за замовчуванням. Вона використовується, коли в таблиці немає рядка для країни призначення (і немає рядка *), або коли в рядку немає ціни для цієї ваги. Залиште порожнім, щоб у такому разі приховати перевізника.

Price applies: як стягується ціна з таблиці.

Той самий вибір застосовується до онлайн-розрахунку: за замовлення надсилається одне відправлення з усім кошиком, за товар запитується розрахунок для кожного різного відправлення й множиться на кількість одиниць. Якщо в кошику більше 5 різних відправлень, використовується таблиця цін.

Вага й розміри товарів переводяться з одиниць вашого магазину в кілограми й сантиметри.

Умови

Minimum weight: приховує перевізника, якщо кошик важить менше, у кг. 0 означає без обмеження.

Maximum weight: приховує перевізника, якщо кошик важить більше, у кг. За замовчуванням: 30. 0 означає без обмеження.

Minimum order amount: показує перевізника лише тоді, коли проміжна сума кошика (після знижок, до податку) досягає цієї суми. Залиште порожнім, щоб показувати завжди.

Free shipping from: проміжна сума кошика (після знижок, до податку), починаючи з якої доставка iMile безкоштовна. Залиште порожнім, щоб ніколи не пропонувати безкоштовну доставку.

Tax: податкове правило перевізника або No tax. Оберіть No tax, якщо ціни в таблиці та розрахунки iMile вже включають ПДВ.

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

Ignore shipping zones: пропонувати iMile для країн нижче незалежно від того, яка зона підходить. Під час збереження перевізник додається до всіх зон, і зони, створені пізніше, теж його отримають. Під час вимкнення опції додані зони видаляються, і перевізник повертається до зон, які мав раніше.

Countries: країни призначення для цього режиму. Залиште порожнім, щоб використовувати всі активні країни. Це поле використовується лише тоді, коли увімкнено Ignore shipping zones.

Додатково

Debug log: записує розрахунки тарифів у logs/vfd_imle_debug.log.php у папці модуля. Файл не можна відкрити з веб. Ключі та адреси покупців не записуються. Неуспішні запити до iMile завжди записуються, навіть коли журнал налагодження вимкнено. Вимкніть журнал, коли закінчите.

Log: показує розмір і останні записи журналу налагодження. Натисніть Clear log, щоб очистити його.

Remove data on uninstall: якщо увімкнено, видалення модуля видаляє налаштування iMile, перевізника, кеш розрахунків і журнали. Якщо вимкнено, усе зберігається для повторного встановлення.

Як це працює під час оформлення замовлення

На кроці доставки PrestaShop запитує в модуля ціну iMile. Враховуються лише фізичні товари: віртуальні товари не додають ваги й не входять до суми замовлення. Модуль спершу перевіряє умови: дозволені країни (якщо увімкнено Ignore shipping zones), вагу кошика та мінімальну суму замовлення. Якщо застосовується безкоштовна доставка, ціна дорівнює 0 і запит до iMile не надсилається.

Коли онлайн-розрахунок увімкнено, модуль надсилає в iMile країну, область і місто відправлення, країну призначення, регіон, місто та поштовий індекс, вагу кошика в кг, об'єм у см³ (за розмірами товарів), вартість кошика, сервіс iMile і категорію товару. Розрахунок завжди запитується як передоплачений, тож накладений платіж не враховується. Онлайн-розрахунок запитується лише після того, як покупець ввів адресу доставки з містом, і лише якщо кожен товар у кошику має вагу. Кожна відповідь кешується на 1 годину. Неуспішний запит кешується на 5 хвилин. Після тайм-ауту або помилки сервера iMile не опитується 2 хвилини, після відхилених ключів — 5 хвилин, щоб оформлення замовлення не чекало iMile під час кожного оновлення. Тайм-аут API становить 12 секунд. Прострочений токен доступу оновлюється автоматично.

Розрахунок переводиться у валюту магазину за замовчуванням за вашими курсами обміну. Якщо iMile не дає придатного розрахунку (ключі не задано, місто ще не введено, невідоме місто, помилка, тайм-аут, немає курсу обміну), покупець не бачить помилки і використовується ціна з таблиці. Якщо в таблиці теж немає ціни, перевізник приховується. Причина записується в журнал. Ціна розраховується у валюті магазину за замовчуванням, а потім показується у валюті кошика покупця.

Якщо ви редагуєте перевізника в Shipping > Carriers після того, як у нього з'явилися замовлення, PrestaShop зберігає його як нову версію перевізника. Модуль автоматично переходить на нову версію.

Модуль лише розраховує тарифи. Він не створює відправлень iMile, не друкує накладні AWB, не замовляє кур'єра на забір, не відстежує посилки, не звіряє накладені платежі та не пропонує пункти видачі й поштомати. Для відправлень користуйтеся порталом iMile.

Ліцензійний ключ

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

Без активного ключа перевізник iMile не показується покупцям під час оформлення замовлення, і тариф не розраховується. Вітрина PrestaShop не знає, що ви ввійшли в адмін-панель, тож перевізник приховано і для вас: ви можете налаштувати модуль до купівлі ключа, але не можете перевірити його під час оформлення замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються.

Коли ліцензія закінчується, модуль продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється знову, поки ви працюєте в адмін-панелі: раз на день протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення або скидання модуля завжди видаляє ліцензійний ключ і статус ліцензії.

Усунення несправностей

iMile не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і ввімкнено Enable iMile. У Shipping > Carriers перевірте, що перевізник охоплює зону країни покупця та групу покупця, або увімкніть Ignore shipping zones і перевірте Countries. Перевірте обмеження ваги та Minimum order amount. Переконайтеся, що для країни або * є рядок у Price table, або що задано Price for countries not in the table. Товари також можуть бути обмежені певними перевізниками на сторінці товару.

Замість розрахунку iMile показується ціна з таблиці: увімкніть Debug log, оновіть оформлення замовлення і подивіться поле Log на сторінці модуля. Поширені причини: Live estimate вимкнено, немає ключів, покупець ще не ввів місто, iMile не розпізнає написання міста, у товарів немає ваги, немає курсу обміну для валюти призначення, або помилка API. Також перевірте попередження над налаштуваннями.

«sign is invalid» у журналі: перевірте Secret key, потім спробуйте Signature = SimpleKey.

Ключі відхиляються: перевірте Customer ID, Secret key та Environment. Тестові ключі працюють лише з тестовим сервером.

Назви міст не збігаються: назви міст мають збігатися зі списком міст iMile. Розробники можуть зіставити їх за допомогою хука actionVfdImileLiveRequest, а коди країн — за допомогою хука actionVfdImileLiveCountryCode.

Ціни в неправильній валюті: таблиця цін задається у валюті магазину за замовчуванням. Переведіть тариф в AED, SAR або MXN під час введення. Онлайн-розрахунки переводяться за Exchange rates.

Податок на доставку стягується двічі: якщо ваші ціни вже включають ПДВ, встановіть Tax у No tax.

Розрахунки виглядають застарілими після зміни: натисніть Save на сторінці модуля. Це очистить кеш розрахунків iMile.

На сторінці написано, що перевізника iMile не знайдено: перевізника було видалено в Shipping > Carriers. Скиньте модуль у Modules > Module Manager, щоб створити його знову.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox iMile і оберіть Uninstall. Ліцензійний ключ і статус ліцензії завжди видаляються.Кеш розрахунків і токени доступу завжди видаляються. Якщо Remove data on uninstall увімкнено, перевізник видаляється (замовлення зберігають свою історію), а налаштування та журнал видаляються. Якщо вимкнено, перевізник лише деактивується, а всі налаштування зберігаються. Повторне встановлення модуля відновлює статус перевізника, який був раніше.

iMile — торгова марка її власника. Цей модуль не пов'язаний з iMile і не схвалений iMile.