VibeFox GIG Logistics for OpenCart — Помощь

Требования

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

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

Учётные данные API GIG Logistics (только для актуальных цен): актуальные цены используют сторонний API GIG Logistics. GIG Logistics выдаёт бизнес-клиентам имя пользователя API (обычно адрес электронной почты) и пароль. Запросите их на странице разработчиков GIG Logistics (giglogistics.com/developer). Тестовые учётные данные работают только с тестовым API. Если вы используете только таблицу цен и запасную стоимость, учётные данные API не нужны.

Нигерия в вашем магазине: актуальные цены запрашиваются только для адресов доставки в Нигерии. В OpenCart уже есть страна Nigeria с 37 штатами; её нужно включить в System > Localisation > Countries.

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

Установка

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

OpenCart 3

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

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

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

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

5. Заполните таблицу цен и/или запасную стоимость. Для актуальных цен также введите имя пользователя и пароль API, телефон отправителя, улицу, город и штат, а также курс пересчёта валюты, если валюта по умолчанию не NGN (см. Настройка). Включите Enable/Disable и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

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

Вверху страницы, а также после каждого сохранения расширение показывает предупреждения, когда актуальные цены не могут использоваться: введены только имя пользователя или пароль API, не заполнены Sender phone или город и штат забора, либо валюта по умолчанию не NGN и не задан Currency conversion rate. Оно также предупреждает, если в магазине нет класса веса с единицей kg (System > Localisation > Weight Classes); тогда веса товаров пересчитываются по названию их единицы (kg, g, lb, oz), а прочие единицы считаются килограммами. При сохранении сообщается о неверном числе (отрицательная сумма, Currency conversion rate равный 0, широта вне диапазона от -90 до 90, долгота вне диапазона от -180 до 180), о Min weight (kg) больше Max weight (kg), о пустом или некорректном Method title, о порядке сортировки, который не является целым числом, либо о неизвестном налоговом классе или гео-зоне, и ничего не сохраняется.

Общие

Способ предлагается для гео-зоны, выбранной в Conditions, или для стран из Ignore shipping zones. Настройки этой страницы применяются ко всем зонам.

Enable/Disable: показывает или скрывает GIG Logistics при оформлении заказа (состояние этого расширения). По умолчанию: выключено.

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

Tax class: налоговый класс стоимости доставки или No tax. Налоговый класс добавляет ваш налог на доставку к стоимости. Выберите No tax, если цена GIG уже включает всё, что вы хотите взимать.

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

API GIG Logistics (актуальные цены) (необязательно)

При наличии учётных данных API цена запрашивается у GIG Logistics для каждого адреса в Нигерии и кешируется на час. Без учётных данных либо если API не возвращает цену, используются таблица цен и запасная стоимость. В разделе есть ссылка на страницу разработчиков GIG Logistics.

API username: ваше имя пользователя API сторонних сервисов GIG Logistics, обычно адрес электронной почты.

API password: ваш пароль API сторонних сервисов GIG Logistics. Он используется только для входа в API и никогда не записывается в журнал. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. To remove it, clear the API username and save. Вводите новое значение, только если хотите его изменить.

Test mode: использовать тестовый API (dev) GIG Logistics. Тестовые учётные данные работают только с тестовым API. Выключите, чтобы получать реальные цены. По умолчанию: выключено.

Currency conversion rate: GIG Logistics возвращает цены в NGN. Если валюта по умолчанию вашего магазина не NGN, введите, сколько стоит 1 NGN в вашей валюте по умолчанию (1 NGN = ? вашей валюты, например 0.0006). Курс должен быть больше 0. Без него актуальные цены GIG не используются. Если валюта по умолчанию — NGN, поле это сообщает, и оно не нужно.

Адрес забора (отправитель)

Где GIG Logistics забирает посылки, в Нигерии. В OpenCart нет структурированного адреса магазина, поэтому введите здесь улицу и город. Если страна вашего магазина — Нигерия, пустое поле State использует регион магазина из System > Settings > Store > Local.

Sender name: имя отправителя, передаваемое в GIG Logistics. Если пусто, используется название магазина.

Sender phone: ваш номер телефона, например 08030000000. GIG Logistics требует его для актуальных цен.

Street address: улица забора, например 1 Adeola Odeku Street.

City / area: город или район забора, например Victoria Island. Обязательно для актуальных цен.

State: штат Нигерии для адреса забора, выбирается из 37 штатов. Вариант по умолчанию, Store region (System > Settings > Store > Local), использует регион вашего магазина, если магазин находится в Нигерии. Обязательно для актуальных цен.

Pickup latitude: необязательная широта точки забора на карте, например 6.4281. GIG Logistics считает цену по расстоянию. Если поле пусто, координаты ищутся по адресу.

Pickup longitude: необязательная долгота точки забора на карте, например 3.4219.

Address lookup: поиск координат адресов на карте через OpenStreetMap (Nominatim). GIG Logistics рассчитывает цену по координатам забора и доставки. Улица, город и штат покупателя отправляются на nominatim.openstreetmap.org, а результаты кешируются на 30 дней. Без этой опции отправляется только текст адреса, и GIG Logistics может не вернуть цену. По умолчанию: включено.

Таблица цен и запасной вариант

Используется для других стран, когда актуальные цены не настроены или когда GIG Logistics не возвращает цену. Цены указаны в валюте по умолчанию вашего магазина, без налога.

Country prices: таблица с базовой ценой для каждой страны. Нажмите Add country, чтобы добавить строку. Выберите * Any other country для всех стран без собственной строки. Колонки XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg и XL >5 kg — необязательные цены по весовым категориям: цена категории больше 0 заменяет базовую цену для корзин этой категории. Цена 0 означает бесплатную доставку. Пустые или некорректные ячейки цен сохраняются как 0, поэтому заполняйте базовую цену в каждой добавленной строке. Исправленные значения перечисляются после сохранения в предупреждении, которое начинается с Country prices:. Страны без строки (когда нет строки *) не получают цену из таблицы.

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

Table / fallback price is: Per order берёт цену один раз. Per item (multiplied by the number of items) умножает её на количество позиций в корзине. Актуальные цены GIG всегда относятся ко всему заказу.

Условия

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

Minimum subtotal: показывает способ, только когда промежуточная сумма корзины достигает этой суммы. Пусто означает всегда.

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

Max weight (kg): максимальный вес корзины в кг. По умолчанию: 30. 0 означает без ограничений.

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

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

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

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

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

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

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

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

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

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

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

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

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

Затем цена берётся из первого источника, который её даёт. Сначала актуальная цена GIG Logistics, если введены учётные данные API, адрес находится в Нигерии, в адресе есть город или штат, заполнены телефон, город и штат забора и для магазинов с валютой по умолчанию, отличной от NGN, задан курс пересчёта. Расширение входит в API GIG Logistics и отправляет адреса и координаты забора и доставки, а также позиции корзины с названиями, количеством, весом и стоимостью. Товары без веса отправляются как 1 кг. Цена запрашивается для доставки на велосипеде. Второй источник — таблица Country prices. Третий — Fallback cost. Если ни один не даёт цену, способ скрывается для этой корзины. Цена рассчитывается в валюте по умолчанию, округляется по её десятичным знакам и показывается покупателю в его валюте с налогом выбранного Tax class.

Каждый ответ GIG кешируется на 1 час, поэтому та же корзина не вызывает новый запрос. Неудачный запрос или неудачный вход кешируются на 10 минут, чтобы оформление заказа не ждало GIG Logistics при каждом обновлении. Токен входа хранится 30 минут и автоматически обновляется, когда GIG его отклоняет. Координаты адресов хранятся 30 дней, а адрес, который не найден, — 1 день. Таймаут API — 10 секунд, таймаут поиска адреса — 5 секунд.

Если GIG Logistics возвращает ошибку или нулевую цену, покупатель не видит ошибку. Используется цена из таблицы или запасная стоимость, а ошибка записывается в журнал отладки.

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

На OpenCart 4 покупатель нажимает Choose в блоке способов доставки на странице оформления заказа и выбирает GIG Logistics в окне Shipping method options, где у способа указаны название и цена, например GIG Logistics - $4.50. Способ работает так же, как в OpenCart 3.

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

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

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

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

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

GIG Logistics не появляется при оформлении заказа: проверьте, что лицензия активна и Enable/Disable включено. Проверьте Geo zone или Ignore shipping zones и Countries, ограничения по весу и Minimum subtotal. Проверьте, что таблица (страна или *) или Fallback cost дают цену для страны. Проверьте, что у товаров Requires Shipping установлено в Yes.

Цена берётся из таблицы, а не от GIG Logistics: для актуальных цен нужны имя пользователя и пароль API, Sender phone, город и штат забора, адрес доставки в Нигерии с городом или штатом и, для магазинов с валютой по умолчанию, отличной от NGN, Currency conversion rate. Посмотрите предупреждения вверху страницы Edit. Включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице расширения, чтобы узнать причину. Неудачный запрос повторяется через 10 минут.

Ошибка входа в журнале: GIG Logistics отклонил имя пользователя или пароль API. Проверьте их и проверьте Test mode: тестовые учётные данные работают только с тестовым API. Сохраните настройки, чтобы повторить сразу.

GIG Logistics не возвращает цену: GIG считает цену по расстоянию. Оставьте Address lookup включённым или введите Pickup latitude и Pickup longitude. Подтвердите цены в своей учётной записи GIG Logistics, прежде чем запускать магазин в работу.

Предупреждение о городе и штате забора не исчезает: выберите штат в State и заполните City / area. Регион магазина используется, только если страна магазина в System > Settings > Store > Local — Нигерия.

К цене GIG добавляется налог: установите Tax class в No tax, если цена GIG уже включает всё, что вы хотите взимать.

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

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

Для разработчиков: адрес API GIG Logistics и адрес поиска адресов можно заменить настройками vfd_gigl_api_base_url и vfd_gigl_geocode_url (для тестов); для них нет полей на странице настроек.

Удаление

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

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

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