VibeFox Frenet for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

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

Учётная запись Frenet (только для актуальных расчётов): создайте бесплатную учётную запись в панели Frenet (painel.frenet.com.br), включите нужных перевозчиков и скопируйте API-токен. Если вы используете только фиксированные цены, учётная запись Frenet не нужна.

Товары: заполните вес и габариты для точных цен. Для товаров без них расчёт ведётся как для 0,3 кг и 16 × 11 × 2 см (минимальная коробка Correios).

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

Установка

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

OpenCart 3

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

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

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

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

5. Вставьте API-токен и укажите CEP отправления. Если валюта по умолчанию не BRL, введите курс BRL. При необходимости добавьте фиксированные цены и запасную стоимость. Включите Enable Frenet и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Frenet > Edit. Разделы перечислены слева. Одна кнопка Save внизу сохраняет всю страницу без перезагрузки. Каждое сохранение также очищает кешированные расчёты Frenet. Поля цен принимают как точку, так и запятую в качестве десятичного разделителя. Если значение неверное, ничего не сохраняется, а страница показывает причину, например Enter a valid method title (64 characters max, without < > ; = # { })., "…" must be a number. или "…" must not be negative. Также отклоняются BRL exchange rate ноль или меньше и Minimum weight (kg) больше Maximum weight (kg). Сохранять настройки могут только администраторы с правом изменения этого расширения.

Вверху страницы, а также после каждого сохранения расширение показывает предупреждения: нет API-токена (тогда используются только фиксированные цены, или способ доставки не показывается, если фиксированных цен тоже нет), нет CEP отправления, CEP отправления не из 8 цифр или валюта по умолчанию не BRL и нет курса обмена. Оно также предупреждает, если в магазине нет класса веса с единицей kg или класса длины с единицей cm. Тогда вес и габариты товаров пересчитываются по названию единицы их класса, а неизвестные единицы считаются килограммами или сантиметрами. Проверьте System > Localisation > Weight Classes и Length Classes.

Общие

Настройки применяются ко всем гео-зонам. Способ можно ограничить гео-зоной в разделе Conditions или использовать Ignore shipping zones. Цена всегда поступает из этого расширения.

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

Method title: название способа доставки, которое видит покупатель в корзине и при оформлении. По умолчанию: Frenet. Обязательное поле, не более 64 символов, без символов < > ; = # { }.

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

Актуальные расчёты Frenet

Frenet сравнивает перевозчиков, включённых в вашей учётной записи Frenet (Correios, Jadlog, Loggi и другие), и возвращает их цены для корзины. Актуальные расчёты запрашиваются только для адресов в Бразилии с полным 8-значным CEP. В разделе есть ссылка на панель Frenet.

API token: ваш API-токен Frenet из панели Frenet. Оставьте поле пустым, чтобы использовать только фиксированные цены. После сохранения поле остаётся пустым и показывает A token is saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённый токен, отметьте Remove the saved token и сохраните.

Origin CEP: почтовый индекс (CEP), с которого отправляются посылки, например 01001-000. В OpenCart нет почтового индекса магазина, поэтому для актуальных расчётов нужно это поле. CEP не из 8 цифр сохраняется как введён, а страница показывает Frenet: the origin CEP must have 8 digits.

Service to offer: Cheapest service (по умолчанию) или Fastest service. Frenet возвращает несколько сервисов, а способ доставки показывает одну цену. Выбранные перевозчик, сервис и срок доставки сохраняются с заказом.

BRL exchange rate: Frenet считает в бразильских реалах. Если валюта по умолчанию не BRL, введите, сколько единиц вашей валюты по умолчанию составляет 1 BRL, например 0.16. По этому курсу пересчитываются расчёт и объявленная стоимость заказа. Без него актуальные расчёты не используются. Если валюта по умолчанию — BRL, поле сообщает, что цены Frenet используются без изменений.

Фиксированные цены

Используются, когда нет API-токена, для стран, которые Frenet не обслуживает, и всякий раз, когда Frenet не возвращает цену (API недоступен, CEP не обслуживается).

Price per country: таблица с колонками Country, Price, XS, S, M, L и XL, цены в валюте по умолчанию без налога. Нажмите Add country, чтобы добавить строку. Колонки размеров зависят от веса корзины: XS до 1 кг, S до 2 кг, M до 3 кг, L до 5 кг, XL свыше 5 кг. Если колонка размера пуста, используется Price. Значение Price 0 означает бесплатную доставку в эту страну. Используйте * Default (all other countries) для всех стран без собственной строки. Строки без цен удаляются при сохранении.

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

Fixed price applies: Per order (по умолчанию) берёт цену один раз. Per item (price × quantity) умножает её на количество позиций. Это относится только к фиксированным ценам и запасной стоимости. Расчёты Frenet уже покрывают всю корзину.

Условия

Minimum weight (kg): скрывает способ доставки при весе корзины ниже этого значения. 0 означает без ограничений.

Maximum weight (kg): скрывает способ доставки при весе корзины выше этого значения. По умолчанию: 30 (используется и тогда, когда поле пусто). 0 означает без ограничений. Не может быть меньше Minimum weight (kg).

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

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

Tax class: налоговый класс, добавляемый к стоимости доставки, или No tax. Цены Frenet — это окончательные цены перевозчика. Выберите No tax, если OpenCart не должен добавлять на них налог.

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

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

Обычно способ доставки предлагается в гео-зоне, выбранной в Conditions (во всех зонах, если ни одна не выбрана).

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

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

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

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

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

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

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

Export: нажмите Download JSON, чтобы сохранить настройки в файл JSON. API-токен не экспортируется.

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

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену Frenet. Если задана Geo zone (и Ignore shipping zones выключено) и адрес находится вне её, Frenet не предлагается. Учитываются только товары с Requires Shipping, установленным в Yes: остальные не добавляют веса и не входят в сумму заказа. Затем расширение проверяет список стран (если включено Ignore shipping zones), вес корзины и минимальную сумму заказа. Сумма заказа — это цена товаров, требующих доставки, после скидки по купону и без налога. Если применяется бесплатная доставка, цена равна 0 и запрос в Frenet не отправляется.

Для адреса в Бразилии с полным 8-значным CEP, при заданных API-токене и CEP отправления расширение отправляет в Frenet CEP отправления и назначения, каждую позицию корзины (вес в кг, габариты в см, количество, Model товара и его категории), сумму заказа в BRL и код купона корзины. Пока CEP не полный, запрос не делается. Frenet возвращает сервисы включённых перевозчиков. Сервисы с ошибкой или без цены пропускаются. Расширение выбирает самый дешёвый или самый быстрый сервис и пересчитывает цену в валюту по умолчанию. Цена округляется по десятичным знакам валюты по умолчанию и показывается покупателю в его валюте с налогом выбранного Tax class.

Каждый ответ кешируется на 1 час для той же корзины и того же адреса. Неудачный запрос или CEP, который не обслуживает ни один включённый перевозчик, запоминается на 10 минут. Таймаут API — 10 секунд. В этих случаях покупатель не видит ошибки: используется фиксированная цена или запасная стоимость, либо способ доставки скрывается, если их нет. Причина записывается в журнал. Для адресов за пределами Бразилии используются только фиксированные цены.

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

Расширение только рассчитывает тарифы. Оно не создаёт отправления, не печатает этикетки и не отслеживает посылки. На одну корзину показывается один сервис Frenet, а не несколько, и нет пунктов выдачи или постаматов. Frenet рассчитывает доставку только по Бразилии; для других стран используйте фиксированные цены.

Заказы

Когда заказ оформлен с Frenet, расширение сохраняет, как была рассчитана его цена доставки: именно тот вариант, который покупатель видел на шаге доставки, без нового запроса в Frenet. Страница заказа в Sales > Orders тогда показывает блок Frenet с такими строками:

Carrier: перевозчик и сервис Frenet, например сервис Correios или Jadlog. Показывается для актуальных расчётов.

Delivery time: срок доставки в рабочих днях, который вернул Frenet. Показывается для актуальных расчётов.

Price source: Live Frenet quote, Fixed price (price per country), Fallback cost или Free shipping.

В OpenCart 4 блок показывается над History. OpenCart 4 обновляет тот же заказ, когда покупатель подтверждает его снова: сохранённые данные Frenet тоже обновляются, а если покупатель выбрал другой способ доставки, данные Frenet для заказа удаляются.

Блок показывается и тогда, когда расширение выключено. Эти данные сохраняются при удалении расширения, в том числе при Remove data on uninstall.

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

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

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

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

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

Frenet не появляется при оформлении заказа: проверьте, что лицензия активна и Enable Frenet включено. Проверьте Geo zone или Ignore shipping zones и Countries, ограничения по весу и Minimum order amount. Проверьте предупреждения вверху страницы расширения. Типичные причины: покупатель ещё не ввёл полный 8-значный CEP, а фиксированных цен нет; либо Frenet не вернул сервис для маршрута, и фиксированной цены нет. Проверьте, что у товаров Requires Shipping установлено в Yes.

Актуальные расчёты не появляются: включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице расширения. Оно покажет причину: нет CEP отправления, нет курса BRL, неполный CEP покупателя, превышено ограничение по весу или сумме, либо сообщения пропущенных сервисов.

В журнале сказано, что API-токен отклонён (HTTP 401 или 403): скопируйте токен заново из панели Frenet и вставьте его в поле API token.

В журнале сказано, что Frenet не вернул сервисов: включите хотя бы одного перевозчика в панели Frenet.

Мой магазин продаёт в евро или долларах: Frenet отвечает в BRL. Введите BRL exchange rate (сколько единиц вашей валюты по умолчанию составляет 1 BRL).

К цене Frenet добавляется налог: цены Frenet — это окончательные цены перевозчика. Установите Tax class в No tax.

Тарифы выглядят устаревшими после изменения: нажмите Save на странице расширения. Это очистит кешированные расчёты Frenet.

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

Для разработчиков: адрес запроса расчётов Frenet можно заменить настройкой vfd_frn_api_url (для тестов); для неё нет поля на странице настроек.

Удаление

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

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

Frenet — товарный знак его правообладателя. Это расширение не связано с Frenet и не одобрено Frenet.