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.