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.