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