VibeFox Mondial Relay for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3) со стандартной темой.

PHP: 8.0 или новее.

Учётная запись Mondial Relay: код бренда (Enseigne) и закрытый ключ выдаются вместе с учётной записью для бизнеса в Mondial Relay: см. раздел для профессионалов на mondialrelay.fr, вашу зону клиента «Connect» или ваш контакт по продажам. Для выбора на карте достаточно кода бренда. Для списка ближайших пунктов нужны оба. Для тестов Mondial Relay предоставляет код бренда BDTEST13 с закрытым ключом PrivateK.

Лицензионный ключ VibeFox: покупается на vibefox.net. Один ключ работает на одном домене.

Установка

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

OpenCart 3

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

2. Перейдите в Extensions > Extensions и выберите тип расширения Shipping. Найдите VibeFox Mondial Relay и нажмите Install (зелёная кнопка +).

3. Нажмите Edit (кнопка с карандашом), чтобы открыть страницу настроек.

4. Введите лицензионный ключ VibeFox в License key в блоке лицензии в верхней части страницы Edit и нажмите Activate (см. Лицензионный ключ).

5. Введите код бренда (Enseigne) и, для режима списка, закрытый ключ. Заполните Country prices (например, строку для Франции) или Fallback cost, включите Enable/Disable и нажмите Save.

OpenCart 4

1. В админке перейдите в Extensions > Installer, нажмите Upload и выберите файл vfd_mondialrelay.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на этой же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Перейдите в Extensions > Extensions и выберите тип расширения Shipping. Найдите VibeFox Mondial Relay, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ и настройки, как в шагах 4 и 5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях.

После установки способ доставки выключен, пока вы не включите Enable/Disable и не сохраните настройки. Если вы устанавливаете расширение заново после удаления, сохранённые настройки снова используются.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Mondial Relay > Edit. Разделы перечислены слева. Одна кнопка Save сохраняет всю страницу без перезагрузки. При каждом сохранении также очищаются кэшированные списки пунктов выдачи. Сохранять настройки могут только администраторы с правом изменения для этого расширения.

Предупреждения в верхней части страницы показывают проблемы, из-за которых способ доставки скрыт: нет кода бренда, нет закрытого ключа в режиме списка, нет цены для Франции, Бельгии или Испании, а также неизвестная расширению единица веса магазина (тогда вес товаров считается в кг). Если поле Name пустое, длиннее 64 символов или содержит один из символов < > ; = # { }, если Min weight (kg) больше Max weight (kg), или код бренда недопустим, страница показывает ошибку и ничего не сохраняется. Числовое поле со значением, которое не является числом (или отрицательно), после Save помечается, и остаётся прежнее значение; остальные настройки сохраняются.

Общие

Доставка в Point Relais Mondial Relay для Франции, Бельгии, Люксембурга, Испании, Португалии и Нидерландов. Способ предлагается в своей гео-зоне (см. Availability) или, при Ignore shipping zones, в перечисленных странах.

Enable/Disable: показывает или скрывает Mondial Relay при оформлении заказа. По умолчанию: выключено.

Name: название способа доставки, которое видят покупатели в корзине и при оформлении заказа. По умолчанию: Mondial Relay Point Relais. Обязательное поле, до 64 символов.

Tax status: None (по умолчанию) означает, что цены в таблице окончательные. Вариант Taxable с названием класса налога означает, что OpenCart добавит к ценам налог на доставку этого класса.

Sort order: место Mondial Relay среди способов доставки при оформлении заказа. Целое число.

Учётная запись Mondial Relay

Brand code (Enseigne): обязательно, до 8 букв и цифр, например BDTEST13 для тестов. Используется картой пунктов выдачи и Web Service. Без него покупатели не могут выбрать Point Relais, поэтому способ доставки не показывается при оформлении заказа.

Private Key: нужен только для выбора List of nearest points. После сохранения поле остаётся пустым и показывает Saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённый ключ, отметьте Remove the saved Private Key и нажмите Save. Когда заданы код бренда и закрытый ключ, подключение к Web Service Mondial Relay проверяется при каждом сохранении настроек, и сообщение показывает, действительны ли они.

Выбор пункта выдачи

Покупатель должен выбрать Point Relais, прежде чем перейти к шагу оплаты. Пункт сохраняется в заказе.

Выбор: как покупатель выбирает Point Relais.

Тарифы (в валюте магазина по умолчанию, без налога)

У Mondial Relay нет публичного API тарифов: цена берётся из этой таблицы.

Country prices: цена по стране назначения и весу посылки. Нажмите Add country, чтобы добавить строку, и кнопку удаления, чтобы удалить строку. Выберите * Default в качестве страны для всех остальных стран. В каждой строке есть Price и колонки веса: XS до 1 кг, S 1-2 кг, M 2-3 кг, L 3-5 кг и XL свыше 5 кг. Пустая колонка веса или колонка с 0 использует колонку Price. Если и Price пустая, доставка для этого веса бесплатна, поэтому заполните Price, если используете только некоторые колонки веса. Десятичные знаки с точкой или запятой (4.90 или 4,90). Строки без цены и строки с неизвестной страной удаляются при сохранении, а значения, которые не являются числами, сообщаются и остаются пустыми.

Fallback cost: используется для стран без строки в таблице. Оставьте пустым, чтобы скрыть способ доставки для них.

Calculation type: как рассчитывается цена.

Free shipping from: промежуточный итог корзины (после скидок, без налога), начиная с которого доставка бесплатна. Оставьте пустым, если бесплатной доставки не будет.

Доступность

Min weight (kg): скрывает способ доставки, если корзина весит меньше. 0 означает без ограничения (по умолчанию).

Max weight (kg): скрывает способ доставки, если корзина весит больше. Mondial Relay принимает посылки до 30 кг в Points Relais. По умолчанию: 30. 0 означает без ограничения. Пустое поле означает 30 кг.

Minimum subtotal: показывает способ доставки, только если промежуточный итог корзины (товары, требующие доставки, после скидок, без налога) не меньше этой суммы. Оставьте пустым, чтобы показывать всегда.

Geo zone: предлагает способ доставки только для адресов в этой гео-зоне. All zones (по умолчанию) означает везде. Гео-зоны настраиваются в System > Localisation > Geo Zones. Не проверяется, если включён Ignore shipping zones.

Ignore shipping zones: если включено, Geo zone не проверяется: способ доставки предлагается только в странах, указанных ниже, или во всех поддерживаемых странах, если список пуст.

Countries (ignore zones): страны назначения для этого режима. Это поле используется только при включённом Ignore shipping zones. В списке только страны с Points Relais.

Дополнительно

Debug log: записывает расчёты тарифов, обращения к Web Service и выбор пунктов в storage/logs/vfd_mrel_debug.log.php (в OpenCart 4 — system/storage/logs/vfd_mrel_debug.log.php). Файл не может быть прочитан из веба. Ошибки всегда записываются, даже если эта опция выключена. Ключи и данные покупателей никогда не записываются. Когда файл достигает 5 МБ, он переносится в vfd_mrel_debug.old.log.php, и начинается новый журнал.

Log: показывает размер и последние записи журнала отладки. Нажмите Clear log, чтобы очистить его.

Remove data on uninstall: если включено, при удалении расширения удаляются настройки и журнал. Если выключено (по умолчанию), они сохраняются для повторной установки. Кэшированные списки пунктов всегда удаляются. Пункты выдачи, сохранённые в заказах, остаются.

Импорт / Экспорт

Export: нажмите Download JSON, чтобы сохранить настройки в файл JSON, без закрытого ключа.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки, например в другом магазине. Применяются те же проверки, что и при Save. Сохранённый закрытый ключ остаётся.

Как это работает при оформлении заказа

Способ доставки предлагается только для стран с Points Relais: Франция, Бельгия, Люксембург, Испания, Португалия и Нидерланды. Он скрывается, когда покупатели не могли бы выбрать пункт: без кода бренда или в режиме списка без закрытого ключа. Если задана Geo zone и адрес находится вне её, способ доставки не предлагается. При включённом Ignore shipping zones гео-зона не проверяется, и обслуживаются только страны из этого списка (все поддерживаемые страны, если список пуст).

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену. Учитываются только товары с Requires Shipping, установленным в Yes: остальные товары не добавляют вес и не входят в промежуточный итог. Вес товаров переводится из класса веса OpenCart в кг. Промежуточный итог — это цена товаров, требующих доставки, после скидки по купону и до налога. Расширение проверяет вес корзины и минимальный промежуточный итог. Цена берётся из строки страны (или строки *): колонка веса, иначе Price. Без строки используется резервная стоимость. Если цены нет, способ доставки скрывается. Если промежуточный итог достигает Free shipping from, цена становится 0. Цена рассчитывается в валюте магазина по умолчанию, округляется до нужных знаков и показывается в валюте покупателя с налогом выбранного Tax status. Для расчёта цены запрос в Mondial Relay не отправляется.

В OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа и выбирает Mondial Relay в окне Shipping method options. Цены такие же, как в OpenCart 3.

Расширение не запрашивает тарифы в реальном времени: у Mondial Relay нет публичного API тарифов. Оно не создаёт отправления, не печатает этикетки и не отслеживает посылки. Создавайте отправления в своём пространстве Mondial Relay «Connect», используя номер Point Relais, указанный в заказе. Доставка на дом (Domicile) не предлагается.

Пункты выдачи

Когда покупатель выбирает вариант Mondial Relay на шаге способа доставки, под ним появляется блок Mondial Relay pickup point.

Режим карты: кнопка Choose a Point Relais открывает в окне официальную карту Mondial Relay для страны доставки, почтового индекса и веса посылки. После выбора покупателем пункта он показывается как Selected:, а кнопка меняется на Change Point Relais. Виджет карты загружается с widget.mondialrelay.com, а библиотека карты — с unpkg.com, только когда покупатель открывает карту. Упомяните это в вашей политике конфиденциальности.

Режим списка: выпадающий список - Choose a Point Relais - показывает 10 ближайших пунктов для почтового индекса доставки с расстоянием до них. Выбранный пункт показывается с часами работы. Список загружает ваш сервер, поэтому для него в браузере не выполняется никакой сторонний скрипт. Списки кэшируются на 12 часов, пустой ответ — на 1 час, а неудачный запрос запоминается на 5 минут. Тайм-аут Web Service — 10 секунд. Без почтового индекса покупатель видит Enter your postcode to see the nearest pickup points. Если пункт не найден или список недоступен, покупатель видит сообщение вида «Список пунктов выдачи сейчас недоступен. Пожалуйста, воспользуйтесь картой.», и ему предлагается карта.

Выбранный пункт сразу сохраняется для сеанса покупателя. Пункт обязателен. Когда покупатель нажимает Continue, магазин повторно проверяет пункт. Без пункта покупатель видит Please choose a Mondial Relay pickup point. и не может перейти к оплате. Пункт в другой стране, чем адрес доставки, отклоняется с сообщением, что пункт не находится в стране доставки. В режиме списка пункт дополнительно сверяется со списком для адреса. После оформления заказа выбор очищается, поэтому следующая корзина выбирает заново.

В OpenCart 4 блок Mondial Relay pickup point появляется в окне Shipping method options, под вариантом Mondial Relay, а карта открывается внутри этого окна. Клавиша Escape закрывает только карту. Кнопка Continue в окне не пропускает дальше без действительного пункта, с теми же сообщениями.

При оформлении заказа пункт остаётся связанным с заказом. Способ доставки в заказе показывает название способа, за которым следуют название, адрес и номер пункта, например Mondial Relay Point Relais: TABAC DU LOUVRE, 12 RUE DE RIVOLI, 75001 PARIS (FR-066974), поэтому покупатель видит его в письме о заказе и в истории заказов своей учётной записи. В письме магазину о новом заказе пункт с номером показан в блоке комментария. В Sales > Orders на странице заказа есть блок Mondial Relay pickup point с названием пункта, адресом и номером Point Relais, либо сообщение No Point Relais was saved for this order. В OpenCart 4 эта панель показывается над блоком History. OpenCart 4 ведёт один заказ на оформление и обновляет его каждый раз, когда покупатель подтверждает заказ снова; пункт заказа обновляется вместе с ним. Если покупатель переводит этот заказ на другой способ доставки, его пункт удаляется.

Лицензионный ключ

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Mondial Relay — это первый блок на странице Extensions > Extensions > Shipping > VibeFox Mondial Relay > Edit, над настройками. Введите ключ в License key и нажмите Activate. После этого блок показывает ключ в маскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now, чтобы проверить статус снова, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: opencart-shipping-mondialrelay и ссылка 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.

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

Когда срок лицензии истекает, расширение продолжает работать, но для обновлений и поддержки нужно продление. Статус проверяется снова автоматически, когда вы открываете админ-панель Dashboard или страницу Edit: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Задание cron не нужно. Удаление расширения всегда удаляет лицензионный ключ и статус лицензии.

Устранение неполадок

Mondial Relay не появляется при оформлении заказа: проверьте, что лицензия активна и включён Enable/Disable. Проверьте Geo zone или Ignore shipping zones и список стран. Проверьте предупреждения в верхней части страницы расширения: способ скрыт без кода бренда, в режиме списка без закрытого ключа, для страны без цены, вне ограничений по весу и промежуточному итогу, а также для стран без Points Relais. Проверьте, что у товаров Requires Shipping установлено в Yes.

Проверка Web Service после сохранения не прошла: сообщение показывает ошибку Mondial Relay, например недопустимый код бренда или недопустимый ключ безопасности. Проверьте код бренда и закрытый ключ у Mondial Relay.

Список пунктов пуст или недоступен: покупателю сначала нужен почтовый индекс доставки. Если Web Service не работает, вместо этого предлагается карта. Включите Debug log, обновите страницу оформления заказа и посмотрите причину в поле Log на странице расширения.

Карта не открывается: карта загружается с widget.mondialrelay.com и unpkg.com. Проверьте, что их не блокирует блокировщик конфиденциальности или скриптов либо политика безопасности контента (Content Security Policy) вашего магазина. Если карту не удаётся загрузить, покупатель видит «Не удалось загрузить карту Mondial Relay. Попробуйте позже или выберите другой способ доставки.»

Страница заказа сообщает No Point Relais was saved for this order: заказ оформлен без пункта из страны доставки. Причина записана в журнал. Попросите покупателя указать Point Relais, прежде чем создавать отправление.

Страница пишет "Warning: You do not have permission to modify VibeFox Mondial Relay!": ваша группа администраторов может только просматривать настройки. Дайте группе право изменения для extension/shipping/vfd_mondialrelay (OpenCart 3) или extension/vfd_mondialrelay/shipping/vfd_mondialrelay (OpenCart 4) в System > Users > User Groups.

Удаление

Перейдите в Extensions > Extensions, выберите тип Shipping и нажмите Uninstall (красная кнопка −) рядом с VibeFox Mondial Relay. Ключ лицензии и статус лицензии этого расширения всегда удаляются. OpenCart всегда сбрасывает Enable/Disable, Sort order, Tax status и Geo zone. Кэшированные списки пунктов выдачи всегда удаляются. Если включено Remove data on uninstall, удаляются также остальные настройки и журнал отладки. Если выключено, они сохраняются и снова используются при повторной установке расширения. Пункты выдачи, сохранённые в заказах, всегда остаются, а существующие заказы сохраняют свой способ доставки и стоимость.

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

Mondial Relay является товарным знаком его владельца. Это расширение не связано с Mondial Relay и не поддерживается им.