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

Требования

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

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

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

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

Установка

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Ninja Van > Edit. Разделы перечислены слева. Одна кнопка Save внизу сохраняет всю страницу без перезагрузки. Ничего не сохраняется, и показывается ошибка, если поле Method title пустое, длиннее 64 символов или содержит < > ; = # { }, если в числовом поле текст или отрицательное число, если IDR conversion rate равен 0, если Minimum weight (kg) больше Maximum weight (kg) или если Sort order не является целым числом. Если в магазине нет весового класса с единицей kg, а единица весового класса по умолчанию расширению неизвестна, появляется предупреждение, что веса товаров считаются в килограммах: добавьте весовой класс kg в System > Localisation > Weight Classes. Сохранять настройки могут только администраторы с правом изменения этого расширения.

Общие

Настройки применяются ко всем географическим зонам. Ограничить способ доставки географической зоной можно в разделе Conditions, либо использовать Ignore shipping zones.

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

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

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

Sort order: положение Ninja Van среди способов доставки при оформлении заказа. Целое число.

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

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

Price table: одна строка на страну назначения. Нажмите Add country, чтобы добавить строку, и кнопку × — чтобы удалить её. Выберите * All other countries для всех стран, для которых нет отдельной строки. В каждой строке есть цена Base и столбцы веса: 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) — Индонезия

Ninja Van Tariff API возвращает стандартную стоимость доставки без надбавок и скидок для посылок, отправляемых внутри Индонезии. Ninja Van предлагает его только для Индонезии. Когда Live rates включён, строки статуса под заголовком раздела показывают зону отправления, отсутствующий курс конвертации и последний ответ Tariff 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), адрес которого показан под полем. Введите оба: адрес магазина в OpenCart не содержит отдельных города и улицы, поэтому зону отправления по нему определить нельзя. Коды переводятся в заглавные буквы. Код в неверном формате очищается с предупреждением. Если введён только один код, предупреждение просит ввести оба, а строка статуса сообщает, что актуальные тарифы не запрашиваются. Строка статуса также предупреждает, если два кода не составляют пару в соответствии кодов зон.

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

Условия

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

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

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

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

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

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

Ignore shipping zones: предлагать Ninja Van для стран, указанных ниже, независимо от Geo zone. Если опция выключена (по умолчанию), решает географическая зона, а список стран не используется.

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

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

Debug log: записывает расчёты тарифов в storage/logs/vfd_njvn_debug.log.php (в OpenCart 4 — system/storage/logs/vfd_njvn_debug.log.php). Этот файл недоступен из веба. Адреса покупателей и коды зон не записываются. Неудачные запросы к Tariff API записываются в журнал, даже если эта опция выключена. Выключите её, когда закончите. Когда файл достигает 5 МБ, он переносится в vfd_njvn_debug.old.log.php, и начинается новый журнал.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для разработчиков: магазин со своим полем района (Kecamatan) может передавать коды зон через событие OpenCart vfd_ninja_van/tariff_zone (триггер catalog/vfd_ninja_van/tariff_zone), в том числе для зоны отправления. Адрес Tariff API можно заменить настройкой vfd_njvn_api_url (для тестов); на странице настроек для неё нет поля.

Удаление

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

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

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