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

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более ранних версиях PHP.

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

Нигерия в вашем магазине: цены в реальном времени запрашиваются только для адресов доставки в Нигерии, поэтому страна Нигерия должна существовать и быть активной в International > Locations > Countries.

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

Установка

1. В бэк-офисе перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. По окончании загрузки нажмите Configure или позже найдите VibeFox GIG Logistics в списке модулей и нажмите Configure.

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

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

5. Если в поле Nigerian states отображается кнопка Add Nigerian states, нажмите её (см. Настройки).

При установке модуль создаёт перевозчика GIG Logistics с текстом срока доставки Courier delivery. Перевозчик привязывается к зоне Нигерии (в магазине по умолчанию — Африка) и ко всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Не задавайте там цены: цена всегда берётся из модуля.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox GIG Logistics > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает кэш цен GIG Logistics, токенов API и координат адресов.

Над разделами страница показывает предупреждения, если цены в реальном времени не могут использоваться: введено только имя пользователя или пароль API, не заполнены Sender phone или город и штат отправления, либо валюта по умолчанию не NGN и не задан Currency conversion rate. Также выводится предупреждение, если перевозчик GIG Logistics не найден, и если единица веса магазина (International > Localization > Local units) не известна модулю; в этом случае веса товаров читаются как килограммы. При сохранении сообщается о некорректном числе (отрицательная сумма, Currency conversion rate равный 0, широта вне диапазона от -90 до 90, долгота вне диапазона от -180 до 180), о Min weight (kg) больше Max weight (kg), о пустом или некорректном Method title или о неизвестном налоговом правиле, и ничего не сохраняется.

General

Настройки этой страницы применяются ко всем зонам перевозчика.

Enable/Disable: включает или выключает перевозчика. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

Method title: название перевозчика, которое показывается в корзине и при оформлении заказа. По умолчанию: GIG Logistics. Обязательно.

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

GIG Logistics API (live prices) (необязательно)

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

API username: имя пользователя стороннего API GIG Logistics, обычно ваш адрес e-mail.

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

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

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

Pickup (sender) address

Место, откуда GIG Logistics забирает посылки, в Нигерии. Если ваш магазин находится в Нигерии, пустые поля улицы, города и штата берут адрес магазина из Shop Parameters > Contact > Stores.

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

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

Street address: адрес улицы для отправления.

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

State: штат Нигерии для адреса отправления, выбирается из 37 штатов. Вариант по умолчанию, Shop state (Shop parameters > Contact > Stores), использует штат из адреса магазина. Обязательно для цен в реальном времени.

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

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

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

Nigerian states: штат адреса доставки передаётся в GIG Logistics и в поиск адресов. В PrestaShop по умолчанию нет штатов Нигерии; без них используются только улица и город. Кнопка Add Nigerian states добавляет 37 штатов (коды LA, FC и т. д.), включает Contains states для Нигерии и добавляет поле штата в форму адреса в Нигерии. Штаты, которые уже есть (по коду или по названию), не добавляются повторно. Когда всё настроено, поле показывает, сколько штатов есть для адресов в Нигерии. Ничего не меняется, пока вы не нажмёте кнопку.

Price table and fallback

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

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

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

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

Conditions

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

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

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

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

Availability without shipping zones

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

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

Advanced

Debug log: записывает расчёты цен в logs/vfd_gigl_debug.log.php в папке модуля. Файл нельзя открыть из браузера. Ошибки API всегда записываются в журнал, даже когда журнал выключен. Пароли, токены и адреса покупателей не записываются.

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

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

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

На шаге доставки PrestaShop запрашивает у модуля цену GIG Logistics. Учитываются только товары, требующие доставки: виртуальные товары не добавляют вес и не входят в сумму корзины. Модуль сначала проверяет условия: страну доставки (с Ignore shipping zones), вес корзины и минимальную сумму. Если сумма достигает Free shipping from, цена равна 0 и запрос в GIG Logistics не отправляется.

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

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

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

Если вы редактируете перевозчика в Shipping > Carriers после того, как по нему есть заказы, PrestaShop сохраняет его как новую версию перевозчика. Модуль автоматически переходит на новую версию.

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

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox GIG Logistics — это первый блок в Modules > Module Manager > VibeFox GIG Logistics > Configure, над настройками. Вставьте ключ в License key и нажмите Activate. После этого блок показывает ключ в маскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-shipping-gig-logistics и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку back office (включены английский и русский).

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

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

Без действующего ключа перевозчик GIG Logistics не показывается покупателям при оформлении заказа, и цены не рассчитываются. Витрина PrestaShop не знает, что вы вошли в back office, поэтому перевозчик скрыт и для вас: вы можете настроить модуль до покупки ключа, но не можете проверить его при оформлении заказа. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются.

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

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

GIG Logistics не появляется при оформлении заказа: проверьте, что лицензия активна и Enable/Disable включено. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя, или включите Ignore shipping zones и проверьте Countries. Проверьте ограничения по весу и Minimum subtotal. Убедитесь, что таблица (страна или *) или Fallback cost даёт цену для страны. Товары также могут быть ограничены определёнными перевозчиками на странице товара.

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

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

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

Предупреждение о городе и штате отправления не исчезает: выберите штат в State и заполните City / area. Адрес магазина используется, только если страна магазина — Нигерия, а штат магазина становится известен только после добавления штатов Нигерии и выбора штата в Shop Parameters > Contact > Stores.

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

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

Страница сообщает, что перевозчик GIG Logistics не найден: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его заново.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox GIG Logistics и выберите Uninstall. Лицензионный ключ и статус лицензии всегда удаляются. Кэш цен, токенов и координат адресов всегда удаляется. Если Remove data on uninstall включено, перевозчик удаляется (заказы сохраняют свою историю), а настройки и журнал удаляются. Если выключено, перевозчик только отключается, и все настройки сохраняются. При повторной установке модуля сохранённый перевозчик получает прежний статус. Штаты Нигерии, добавленные через Add Nigerian states, остаются в вашем магазине в обоих случаях.

GIG Logistics — товарный знак его владельца. Модуль не связан с GIG Logistics и не одобрен GIG Logistics.