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). Экспресс должен быть включён для вашей учётной записи и страны.

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 означает бесплатную доставку в эту страну. Принимаются и «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.