VibeFox Loggi for OpenCart — Помощь

Требования

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

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

Аккаунт Loggi (только для актуальных цен): актуальная цена использует API Loggi GraphQL с API-ключом, который Loggi выдаёт бизнес-аккаунтам. Запросите его у вашего менеджера Loggi или в службе поддержки интеграций Loggi (integracoes@loggi.com); см. также документацию API Loggi на docs.api.loggi.com. Нужны три значения: адрес электронной почты вашего аккаунта Loggi, API-ключ и числовой ID вашего магазина. Если в вашем аккаунте Loggi есть только учётные данные для новой REST-платформы Loggi (client ID и secret), актуальная цена недоступна, и используются фиксированные цены. Если вы используете только фиксированные цены, аккаунт Loggi не нужен.

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

Установка

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

OpenCart 3

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

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

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

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

5. Введите адрес электронной почты API Loggi, API-ключ, ID магазина и адрес отправления, а также, если основная валюта магазина не BRL, курс BRL. Добавьте фиксированные цены как страховку (см. Configuration), включите Enable Loggi и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

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

Предупреждения над настройками (они показываются снова после каждого сохранения) указывают на неполную настройку: нет учётных данных API (используются только фиксированные цены), нет ни учётных данных API, ни фиксированных цен (способ доставки никогда не показывается), нет адреса отправления или курса BRL. Ещё одно предупреждение появляется, если в магазине нет весовой единицы с кг или единицы длины с см и единица классов по умолчанию не распознана. Тогда веса товаров считаются в кг, а размеры — в см. Добавьте классы в System > Localisation > Weight Classes и Length Classes.

Общие

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

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

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

API Loggi (актуальная цена) (оставьте учётные данные пустыми, чтобы использовать только фиксированные цены)

API e-mail: адрес электронной почты вашего аккаунта Loggi. API-ключ принадлежит ему. Это должен быть корректный адрес электронной почты. Его очистка также удаляет сохранённый API-ключ.

API key: ваш API-ключ Loggi. Он отправляется только в Loggi и никогда не записывается в журнал. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it; clear the API e-mail to remove it. Вводите новое значение, только чтобы его изменить. Если вы меняете API e-mail, введите также API-ключ для нового адреса, иначе страница покажет ошибку и ничего не сохранится.

Shop ID: числовой ID (pk) вашего магазина в панели Loggi, например 12345. Другое значение отклоняется с ошибкой.

Staging: используйте тестовую среду Loggi (staging) с тестовыми учётными данными. Тестовая среда и рабочая среда имеют разные аккаунты и ключи. По умолчанию: выключено.

Pickup address: откуда Loggi забирает посылки, одной строкой: улица и номер дома, район, город, штат и CEP, например Rua Example, 123 - Bairro, São Paulo - SP, 01310-100. Обязателен для актуальных цен: адрес магазина в OpenCart — свободный текст, поэтому он никогда не используется вместо него. Без адреса отправления Loggi не может рассчитать оценку, и используются только фиксированные цены.

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

Фиксированные цены (в валюте магазина по умолчанию, без налога)

Фиксированные цены используются, когда API Loggi не настроен, для направлений за пределами Бразилии или без полного CEP, а также всякий раз, когда Loggi не возвращает цену (API недоступен, ключ отклонён, адрес вне зоны обслуживания).

Price table: одна строка на страну назначения. Нажмите Add country, чтобы добавить строку, и кнопку удаления, чтобы убрать её. Выберите * All other countries для всех стран без собственной строки. Каждая строка содержит Base price и весовые колонки: XS до 1 кг, S до 2 кг, M до 3 кг, L до 5 кг и XL свыше 5 кг. Пустая (или 0) весовая колонка использует базовую цену. Базовая цена 0 означает бесплатную доставку. Принимаются и "9.99", и "9,99". Пустые строки и вторая строка для той же страны удаляются при сохранении.

Price for countries not in the table: используется, когда нет актуальной цены Loggi и в таблице нет строки для страны назначения (и нет строки *). Оставьте поле пустым, чтобы скрыть способ доставки в этом случае.

Fixed price applies: способ подсчёта фиксированных цен. Актуальная цена Loggi уже покрывает всю корзину и никогда не умножается.

Условия

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

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

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

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

Tax class: налоговый класс стоимости доставки или No tax (по умолчанию). Выберите No tax, если ваши цены и цена Loggi уже включают налоги.

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

Для ограничений по весу и весовых колонок товар без веса считается как 0 кг.

Страны

В OpenCart нет зон перевозчика: Geo zone ограничивает способ доставки адресами одной гео-зоны. Вместо этого можно включить Ignore shipping zones и выбрать список стран.

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

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

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

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

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

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

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

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

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

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

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

Для адреса в Бразилии с полным 8-значным CEP расширение формирует посылки Loggi: каждый товар поворачивается так, чтобы его наименьшая сторона была высотой, и товары укладываются в одну посылку, пока она остаётся в пределах 55 × 55 × 55 см и 20 кг. Товары без веса или размеров считаются как 1 см по каждой стороне, а каждая посылка весит не менее 100 г. Loggi принимает 2 посылки на оценку, поэтому более крупные корзины отправляются несколькими запросами, а итоги суммируются. Расширение отправляет в Loggi ID вашего магазина, адрес отправления, адрес доставки (улица, город, штат и CEP) и посылки, а итог Loggi из BRL переводит в основную валюту вашего магазина. Цена округляется до знаков этой валюты и показывается покупателю в его валюте с налогом выбранного Tax class.

Каждая цена Loggi кэшируется на 1 час для корзины, адреса, аккаунта и среды, чтобы одна и та же корзина не вызывала новый запрос. Неудачная оценка кэшируется на 10 минут. Если Loggi вообще недоступен, запросы приостанавливаются на 2 минуты, чтобы оформление заказа не ждало Loggi при каждом обновлении. Таймаут API составляет 10 секунд.

Вместо них используются фиксированные цены, когда API не настроен, адрес находится за пределами Бразилии или ещё не имеет полного CEP, отсутствует курс BRL, нет адреса отправления, товар больше посылки Loggi, корзине нужно более 10 посылок, или Loggi возвращает ошибку, отклонённую посылку, адрес вне зоны обслуживания или нулевой итог. Если нет и фиксированной цены, способ доставки скрывается. Покупатель никогда не видит ошибку API. Причина записывается в журнал отладки.

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

Расширение только рассчитывает цены. Оно не создаёт заказы и отправления Loggi, не печатает этикетки, не отслеживает посылки, не показывает срок доставки при оформлении заказа и не предлагает пункты выдачи или постаматы. Оно ничего не добавляет к заказам: в заказе отображаются название способа и стоимость доставки, как для любого другого способа доставки OpenCart. Отправления создаются в панели Loggi. Loggi доставляет только по Бразилии. Для других стран используйте фиксированные цены.

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Loggi — первый блок на странице Extensions > Extensions > Shipping > VibeFox Loggi > Edit, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now, чтобы проверить статус ещё раз, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже них находятся строка Product: opencart-shipping-loggi и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Изменять ключ могут только администраторы с правом Modify для расширения. Тексты блока соответствуют языку админки (включены английский и русский).

Если ключ не принят, блок показывает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on и дату. После смены адреса магазина или после освобождения места для домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, расширение продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: адрес магазина из конфигурации OpenCart. Удаление ключа из магазина не освобождает место для домена. Освободите место в своём аккаунте vibefox.net.

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

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

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

Loggi не появляется при оформлении заказа: проверьте, что лицензия активна и Enable Loggi включено. Проверьте Geo zone, Ignore shipping zones и Countries, предупреждения вверху страницы расширения, ограничения по весу и Minimum order amount. Если покупатель ещё не ввёл полный CEP или Loggi не возвращает цену, способу доставки нужна фиксированная цена: строка для страны, строка * или Price for countries not in the table. Проверьте, что у товаров Requires Shipping в значении Yes.

Показываются только фиксированные цены: посмотрите поле Log на странице расширения. Ошибки всегда записываются в журнал. Включите Debug log для каждого шага и перезагрузите оформление заказа. Типичные причины: не заданы адрес электронной почты, ключ или ID магазина API, нет адреса отправления, нет BRL exchange rate для валюты магазина, отличной от BRL, ещё нет полного 8-значного CEP, товар больше 55 см или тяжелее 20 кг, либо адрес вне зоны обслуживания Loggi.

HTTP 401 или 403 в журнале: Loggi отклонил адрес электронной почты или ключ API. Проверьте их в Loggi и убедитесь, что Staging соответствует учётным данным: ключи тестовой и рабочей среды различаются.

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

Цены неточные: заполните вес и размеры ваших товаров. Без них товары считаются как 1 см по каждой стороне, а каждая посылка — как минимум 100 г.

Per item не умножает цену Loggi: так и задумано. Актуальная цена Loggi покрывает всю корзину. Per item применяется только к фиксированным ценам.

Цены выглядят устаревшими после изменения: нажмите Save на странице расширения. Это очистит кэшированные цены Loggi.

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

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

Удаление

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

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

Loggi — торговая марка её владельца. Это расширение не связано с Loggi и не одобрено ею.