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

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 та новіші (перевірено на 4.1.0.3).

PHP: 8.0 або новіша.

Тариф 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. Один ключ працює на одному домені.

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

Завантаження — це один zip-архів з пакетами для обох версій OpenCart. Розпакуйте його на своєму комп'ютері. Він містить README.txt, пакет для OpenCart 3 vfd_imile-oc3-(version).ocmod.zip і пакет для OpenCart 4 vfd_imile.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

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

2. Перейдіть до Extensions > Extensions і виберіть тип розширення Shipping. Знайдіть VibeFox iMile і натисніть Install (зелена кнопка +).

3. Натисніть Edit (кнопка з олівцем), щоб відкрити сторінку налаштувань.

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

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

OpenCart 4

1. В адмінпанелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл vfd_imile.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з назви файлу, і перейменований пакет не працює.

2. Пакет з'являється у списку встановлених розширень на тій самій сторінці. Натисніть Install (зелена кнопка +) поруч із ним.

3. Перейдіть до Extensions > Extensions і виберіть тип розширення Shipping. Знайдіть VibeFox iMile, натисніть Install (зелена кнопка +), потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ і налаштування так само, як у кроках 4 і 5 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях.

Після встановлення спосіб доставки вимкнений, доки ви не увімкнете Enable iMile і не збережете налаштування. Якщо ви встановлюєте розширення повторно після видалення, знову використовуються збережені налаштування iMile.

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

Усі налаштування містяться на сторінці розширення: Extensions > Extensions > Shipping > VibeFox iMile > Edit. Розділи перелічені ліворуч. Одна кнопка Save зберігає всю сторінку без перезавантаження. Кожне збереження також очищає кешовані оцінки iMile та токени доступу. Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

Під час збереження розширення перевіряє, що Method title коректний (не більше 64 символів, без символів < > ; = # { }), що поля ціни, суми та ваги містять числа від 0 і більше, що Minimum weight (kg) не більше за Maximum weight (kg), що Sort order є цілим числом, а клас податку та географічна зона існують. Інакше воно показує помилку і нічого не зберігає.

Попередження з'являються над налаштуваннями (і знову після збереження), коли Live estimate увімкнено, але не може працювати: Customer ID або Secret key порожні, не вказано місто або країну відправлення (або країна не є ринком iMile), немає курсів валют, або таблиця цін порожня і немає ціни для інших країн. Попередження також з'являється, коли в магазині немає класу ваги в кілограмах, а одиниця класу ваги за замовчуванням розширенню невідома: тоді ваги товарів вважаються в кілограмах, тож додайте клас ваги kg у System > Localisation > Weight Classes.

Загальні

Налаштування застосовуються до всіх географічних зон. Ви можете обмежити спосіб доставки географічною зоною в Conditions або увімкнути Ignore shipping zones у Countries, щоб обмежити його списком країн.

Enable iMile: показує або приховує iMile під час оформлення замовлення. За замовчуванням: вимкнено.

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

Sort order: позиція 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: країна, з якої ви відправляєте. Перший варіант, Store country, використовує країну вашого магазину. Список містить лише країни, для яких розширення знає коди країн iMile.

Ship-from city: місто, з якого відправляються ваші посилки, написане так само, як у списку міст iMile (наприклад Dubai, Riyadh). Обов'язкове для оцінок у реальному часі: в OpenCart немає міста магазину, тож без цього поля використовується лише таблиця цін.

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 кг, S ≤2 кг, M ≤3 кг, L ≤5 кг і XL >5 кг. Порожня (або 0) колонка ваги використовує базову ціну. Базова ціна 0 означає безкоштовну доставку до цієї країни. Приймаються і «9.99», і «9,99».

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

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

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

Ваги товарів переводяться з класу ваги OpenCart у кілограми, а розміри — з класу довжини у сантиметри.

Умови

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

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

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

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

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

Geo zone: пропонує iMile лише для адрес у цій географічній зоні. All zones (за замовчуванням) означає відсутність обмежень. Географічна зона не перевіряється, коли увімкнено Ignore shipping zones. Географічні зони керуються в System > Localisation > Geo Zones.

Країни

Ignore shipping zones: якщо увімкнено, Geo zone не перевіряється, і iMile пропонується для країн, зазначених нижче. Якщо вимкнено (за замовчуванням), діє лише Geo zone.

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

Додатково

Debug log: записує розрахунки тарифів у storage/logs/vfd_imile_debug.log.php (на OpenCart 4 system/storage/logs/vfd_imile_debug.log.php). Файл неможливо прочитати через веб. Ключі та адреси покупців не записуються. Невдалі запити до iMile завжди записуються, навіть коли журнал налагодження вимкнено. Вимкніть журнал, коли закінчите. Коли файл досягає 5 МБ, його переносять до vfd_imile_debug.old.log.php і починають новий журнал.

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

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

Імпорт / експорт

Export: натисніть Download JSON, щоб зберегти налаштування у файл JSON. Secret key не експортується.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування, наприклад в іншому магазині. Значення перевіряються так само, як під час звичайного збереження. Збережений Secret key залишається.

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

Коли OpenCart показує способи доставки, він запитує в розширення ціну iMile. Якщо задано Geo zone, Ignore shipping zones вимкнено і адреса поза географічною зоною, iMile не пропонується. Враховуються лише товари з Requires Shipping, встановленим у Yes: інші товари не додають ваги і не входять до суми замовлення. Далі розширення перевіряє умови: дозволені країни (коли Ignore shipping zones увімкнено), вага кошика та мінімальна сума замовлення. Сума замовлення — це ціна товарів, що потребують доставки, після знижки за купоном і без податку. Подарункові сертифікати, бонусні бали та кредит магазину не враховуються. Якщо діє безкоштовна доставка, ціна дорівнює 0 і запит до iMile не надсилається.

Коли оцінка в реальному часі увімкнена, розширення надсилає в iMile країну, область і місто відправлення, країну призначення, регіон, місто та поштовий індекс призначення, вагу кошика в кг, розмір у см³ (з розмірів товарів), вартість кошика, сервіс iMile та категорію товарів. Оцінка завжди запитується як передплачена, тож комісії накладеного платежу не включаються. Оцінка в реальному часі запитується лише після того, як покупець ввів адресу доставки з містом, і лише коли кожен товар у кошику має вагу.

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

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

На OpenCart 4 покупець натискає Choose у блоці способу доставки на сторінці оформлення замовлення і вибирає iMile у вікні Shipping method options. Спосіб доставки працює так само, як в OpenCart 3.

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

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

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox iMile є першим блоком на сторінці Extensions > Extensions > Shipping > VibeFox iMile > Edit, над налаштуваннями. Введіть ключ у License key і натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) та кнопки Check now — перевірити статус ще раз, Change key — ввести інший ключ і Remove key — видалити ключ із цього магазину. Нижче розміщені рядок Product: opencart-shipping-imile і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише адміністратори з правом змінювати це розширення. Тексти блоку відповідають мові адмінпанелі (включено англійську та російську).

Якщо ключ не прийнято, блок повідомляє причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on з датою. Після зміни адреси магазину або після звільнення слота домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, розширення продовжує працювати за останнім відомим статусом.

Один ключ працює на одному домені: адреса магазину з конфігурації OpenCart. Видалення ключа з магазину не звільняє слот домену. Звільніть слот у своєму обліковому записі vibefox.net.

Без активного ключа спосіб доставки iMile не показується покупцям під час оформлення замовлення, і тариф не розраховується. Адміністратор, який увійшов в адмінпанель у тому самому браузері, усе ще бачить спосіб доставки в магазині, позначений як (unlicensed — visible to admins only), тож ви можете налаштувати й протестувати розширення до купівлі ключа. На OpenCart 4 цей попередній перегляд недоступний: магазин не бачить вхід адміністратора, тому без активного ключа спосіб доставки приховано для всіх. Після того як ви один раз відкрили сторінку Edit, на Dashboard адмінпанелі з'являється нагадування. Закрийте його кнопкою ×, щоб приховати на 7 днів. Наявні замовлення не змінюються.

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

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

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

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

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

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

Назви міст не збігаються: назви міст мають збігатися зі списком міст iMile. Розробники можуть змінити запит за допомогою події OpenCart vfd_imile/live_request, а коди країн — за допомогою події vfd_imile/live_country_code.

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

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

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

На сторінці написано «Warning: You do not have permission to modify VibeFox iMile!»: ваша група адміністраторів може лише переглядати налаштування. Надайте групі право змінювати extension/shipping/vfd_imile (OpenCart 3) або extension/vfd_imile/shipping/vfd_imile (OpenCart 4) у System > Users > User Groups.

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Shipping і натисніть Uninstall (червона кнопка −) поруч із VibeFox iMile. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди скидає Enable iMile, Sort order, Tax class і Geo zone. Кешовані оцінки та токени доступу завжди видаляються. Якщо Remove data on uninstall увімкнено, налаштування iMile та журнал налагодження також видаляються. Якщо вимкнено, інші налаштування зберігаються і знову використовуються під час повторного встановлення розширення. Наявні замовлення зберігають свій спосіб доставки та вартість.

На OpenCart 4, щоб також видалити файли розширення, після видалення перейдіть до Extensions > Installer, натисніть Uninstall (помаранчева кнопка −) поруч із VibeFox iMile у списку встановлених розширень, а потім Delete (червона кнопка з кошиком), щоб видалити завантажений пакет.

iMile є торговельною маркою її власника. Це розширення не пов'язане з iMile і не схвалене iMile.