VibeFox Ninja Van for PrestaShop — Помощь

Требования

PrestaShop: от 8.0 до 9.x.

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

Тарифная сетка Ninja Van: цены вашего аккаунта отправителя Ninja Van или от отдела продаж Ninja Van, введённые в таблицу цен. Ключи API не нужны. Необязательные актуальные цены внутри Индонезии используют API тарифов Ninja Van, который является публичным и не требует аутентификации.

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

Установка

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

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Ninja Van в списке модулей и нажмите Configure.

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

4. Введите ваши цены Ninja Van в таблицу цен. Для Индонезии при желании включите Live rates (см. Настройка). Нажмите Save.

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Ninja Van > Configure. Они применяются ко всем зонам перевозчика. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Ничего не сохраняется, и выводится ошибка, если в числовое поле введён текст или отрицательное число, IDR conversion rate равен 0, Minimum weight (kg) больше Maximum weight (kg) или Method title длиннее 64 символов. Если единица веса вашего магазина не входит в число известных модулю, после сохранения появляется предупреждение о том, что веса товаров принимаются в килограммах.

Общие

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

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

Tax: налоговое правило перевозчика или No tax (по умолчанию). Выберите No tax, если цены в таблице уже включают налоги (GST, SST, VAT).

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

Введите цены вашей тарифной сетки Ninja Van в валюте по умолчанию вашего магазина. Если ваша сетка в SGD, MYR, IDR или другой валюте, сначала пересчитайте её. Эта таблица используется для каждого назначения за пределами Индонезии и всегда, когда актуальная цена недоступна.

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

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

Price applies: способ расчёта цен. Это относится и к актуальным ценам.

Актуальные цены (API) — Индонезия

API тарифов Ninja Van возвращает стандартную стоимость доставки без надбавок и скидок для посылок, отправляемых внутри Индонезии. Ninja Van предлагает его только для Индонезии. Когда Live rates включён, строки статуса под заголовком раздела показывают зону отправления, отсутствие курса конвертации и последний ответ API тарифов (окружение, время и результат).

Live rates: получать актуальные цены Ninja Van для доставки внутри Индонезии. По умолчанию: выключено. Без этой опции при оформлении заказа в Ninja Van ничего не отправляется.

Environment: Production (api.ninjavan.co) (по умолчанию) или Sandbox — testing only (api-sandbox.ninjavan.co).

Service level: сервис, для которого запрашивается цена: Standard (по умолчанию), Express, Same day или Next day. Если у Ninja Van нет цены для маршрута и сервиса, используется таблица цен.

Ship-from zone code L1 и Ship-from zone code L2: коды уровней L1 и L2 района, из которого вы отправляете, например ID_A00007_01 и ID_B00069_01, из таблицы соответствия кодов зон Ninja Van (CSV), адрес которой показан под полем. Введите оба или оставьте оба пустыми, чтобы определить их по адресу магазина в Shop Parameters > Contact > Stores: Индонезия, провинция (state), город и, если в городе несколько зон, район (Kecamatan) в строке адреса. Код в неверном формате очищается с предупреждением. Если введён только один код, предупреждение просит ввести оба, а строка статуса показывает, что актуальные цены не запрашиваются.

IDR conversion rate: API тарифов возвращает стоимость в индонезийских рупиях (IDR). Если валюта по умолчанию вашего магазина — IDR, оставьте поле пустым. Иначе укажите, сколько 1 IDR составляет в валюте вашего магазина, например 0.000058. Значение должно быть больше 0. Без него актуальные цены не используются, а используется таблица.

Условия

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

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

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

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

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

Ignore shipping zones: предлагать Ninja Van для стран ниже, даже если перевозчик не привязан к их зоне. Когда опция включена, перевозчик привязывается ко всем активным зонам, включая зоны, которые вы создадите позже. Когда вы её выключаете, перевозчик возвращает зоны, которые у него были раньше.

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

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

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

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

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

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

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

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

При включённой опции Live rates доставка внутри Индонезии сначала тарифицируется Ninja Van. Модуль переводит адреса отправления и доставки в коды зон Ninja Van: провинция (state), город или регентство и, для городов с несколькими зонами, район (Kecamatan), указанный в строке адреса. Он отправляет коды, вес и уровень сервиса и переводит стоимость из IDR в валюту вашего магазина. При Per item отправляется один запрос на каждый отличающийся вес товара, не более 5 на корзину. При большем числе разных весов используется таблица цен.

API тарифов разрешает 20 запросов в минуту, поэтому ответы кэшируются на 6 часов, ошибки — на 5 минут, а «нет цены для этого маршрута» — на 1 час. Модуль никогда не отправляет больше 18 запросов в минуту, а после ответа HTTP 429 приостанавливается на час. Тайм-аут API составляет 12 секунд. Если Ninja Van не отвечает, возвращает ошибку, не имеет цены для маршрута или адрес не удаётся сопоставить, используется цена из таблицы. Ошибки попадают в журнал, но никогда не показываются покупателю.

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

Модуль только рассчитывает цены. Он не создаёт заказы в Ninja Van, не печатает авианакладные (AWB), не заказывает забор посылок, не отслеживает посылки и не работает с наложенным платежом (COD). Для этого используйте Ninja Van Dashboard. Выбора пункта выдачи (Ninja Points) нет: перевозчик предусматривает доставку до двери. Актуальные цены вне Индонезии недоступны.

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

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

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

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

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

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

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

Ninja Van не появляется при оформлении заказа: проверьте, что лицензия активна и включён Enable Ninja Van. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя (или включите Ignore shipping zones и проверьте Countries). Проверьте ограничения по весу и Minimum order amount, а также что для страны, строки * или Price for countries not in the table задана цена. Товары также могут быть ограничены определёнными перевозчиками на странице товара.

Актуальная цена не используется для некоторых адресов: адрес назначения должен соответствовать зоне Ninja Van: Индонезия, провинция (state), город или регентство и, для городов с несколькими зонами, район (Kecamatan) в строке адреса. Иначе используется цена из таблицы. Включите Debug log, обновите оформление заказа и посмотрите поле Log на странице модуля.

Актуальные цены вообще не запрашиваются: строки статуса под Актуальные цены (API) — Индонезия показывают причину: адрес магазина не в Индонезии или зону отправления не удалось определить (введите оба кода зон), введён только один из двух кодов, введённые коды не образуют пару в таблице соответствия зон или отсутствует IDR conversion rate.

Достигнут лимит запросов (HTTP 429): актуальные запросы приостанавливаются на один час, а в это время используется таблица цен.

В какой валюте цены: таблица и условия указаны в валюте по умолчанию вашего магазина. Актуальные цены указаны в рупиях (IDR) и пересчитываются по IDR conversion rate, если валюта магазина не IDR.

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

Разработчикам: магазин с собственным полем района (Kecamatan) может передавать коды зон через хук actionVfdNjvnTariffZone.

Удаление

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

Ninja Van — товарный знак его правообладателя. Этот модуль не связан с Ninja Van и не одобрен ею.