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

Вимоги

WordPress: 5.8 або новіша версія.

WooCommerce: 5.0 або новіша, встановлений і активний. Плагін не активується без нього.

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

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

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-архів плагіна та натисніть Install Now. Також можна завантажити папку vfd_imile до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Shipping > VibeFox iMile або натисніть Settings під назвою плагіна на сторінці Plugins.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії вгорі сторінки та натисніть Activate.

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

6. Додайте VibeFox iMile до зони доставки в WooCommerce > Settings > Shipping > Shipping zones (наприклад, «United Arab Emirates») або увімкніть Ignore shipping zones і виберіть країни.

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

Усі налаштування розташовані на одній сторінці: WooCommerce > Settings > Shipping > VibeFox iMile. Вони діють для всіх зон доставки. Коли ви додаєте метод до зони, у вікні зони є лише одне поле:

Title (zone): назва, яку покупці бачать для цієї зони. Залиште порожнім, щоб використовувати загальний Method title.

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

Загальні

Enable/Disable: вмикає або вимикає метод у всіх зонах одночасно.

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: секретний ключ (API-ключ), який iMile видає разом із Customer ID. Він підписує запити.

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

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

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

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 (kg): приховує метод, якщо кошик важить менше. 0 означає без обмеження.

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

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

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

Excluded shipping classes: приховує метод, якщо в кошику є товар із будь-якого з цих класів доставки WooCommerce.

Tax status: Taxable додає податок WooCommerce до вартості доставки, None — не додає. Виберіть None, якщо ціни в таблиці та розрахунки iMile уже включають ПДВ.

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

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

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

Додатково

Debug log: записує розрахунки тарифів у WooCommerce > Status > Logs (джерело «vfd_imile»). Ключі та адреси покупців не записуються. Неуспішні запити до iMile записуються завжди, навіть коли журнал налагодження вимкнено. Вимкніть журнал, коли закінчите.

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

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

Коли покупець вводить адресу доставки, WooCommerce запитує в плагіна тариф. Спершу плагін перевіряє умови: країну доставки, вагу кошика, мінімальну суму замовлення та виключені класи доставки. Якщо діє безкоштовна доставка, покупець бачить метод без оплати, і запит до iMile не надсилається.

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

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

Метод працює в класичному оформленні замовлення та в блоках «Кошик» і «Оформлення замовлення». Сумісний із WooCommerce High-Performance Order Storage (HPOS).

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

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розташований вгорі сторінки WooCommerce > Settings > Shipping > VibeFox iMile. Вставте ключ у поле License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, і ваш домен. Кнопка Check now повторно перевіряє статус, Change key дозволяє ввести інший ключ, а Remove key видаляє ключ із цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис vibefox.net.

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

Без активного ключа iMile не показується покупцям під час оформлення замовлення. Авторизовані адміністратори магазину все ще бачать його, позначеним як (unlicensed — visible to admins only), щоб ви могли налаштувати та протестувати плагін до купівлі ключа. Нагадування з'являється на сторінці Plugins і на сторінках WooCommerce. Наявні замовлення не змінюються.

Коли ліцензія закінчується, плагін продовжує працювати, але оновлення та підтримка потребують продовження. Статус автоматично перевіряється знову у фоновому режимі.

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

iMile не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і метод додано до зони країни покупця (або увімкнено Ignore shipping zones і країна дозволена). Перевірте обмеження ваги, Minimum order amount та Excluded shipping classes. Переконайтеся, що для країни або * є рядок у Price table, або заповнено Price for countries not in the table.

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

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

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

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

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

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

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

Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть слот в обліковому записі vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати з останнім відомим статусом.

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте та видаліть на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються. Налаштування, методи зон і кешовані розрахунки видаляються, лише якщо була увімкнена опція Remove data on uninstall. Інакше вони зберігаються для повторного встановлення. Наявні замовлення зберігають свої рядки доставки.

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