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 і не схвалене нею.