VibeFox Loggi for OpenCart — Допомога

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіші (перевірено на 4.1.0.3).

PHP: 8.0 або новіша версія.

Обліковий запис Loggi (лише для актуальних цін): актуальна ціна використовує API Loggi GraphQL з API-ключем, який Loggi видає бізнес-обліковим записам. Запитайте його у свого менеджера Loggi або в службі підтримки інтеграцій Loggi (integracoes@loggi.com); див. також документацію API Loggi на docs.api.loggi.com. Потрібні три значення: адреса електронної пошти вашого облікового запису Loggi, API-ключ і числовий ID вашого магазину. Якщо у вашому обліковому записі Loggi є лише облікові дані для нової REST-платформи API Loggi (client ID і secret), актуальна ціна недоступна, і використовуються фіксовані ціни. Якщо ви використовуєте лише фіксовані ціни, обліковий запис Loggi вам не потрібен.

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

Встановлення

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

OpenCart 3

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

2. Перейдіть до Extensions > Extensions і виберіть тип розширення Shipping. Знайдіть VibeFox Loggi і натисніть Install (зелена кнопка +).

3. Натисніть Edit (кнопка з олівцем), щоб відкрити сторінку налаштувань.

4. Введіть свій ліцензійний ключ VibeFox у поле License key у блоці ліцензії вгорі сторінки Edit і натисніть Activate (див. Ліцензійний ключ).

5. Введіть адресу електронної пошти API Loggi, API-ключ, Shop ID і адресу забору, а також, якщо основна валюта вашого магазину не BRL, курс BRL. Додайте фіксовані ціни як страхову сітку (див. Configuration), увімкніть Enable Loggi і натисніть Save.

OpenCart 4

1. В адмінпанелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл vfd_loggi.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з назви файлу, і перейменований пакет не працює.

2. Пакет з'являється у списку встановлених розширень на тій самій сторінці. Натисніть поруч із ним Install (зелена кнопка +).

3. Перейдіть до Extensions > Extensions і виберіть тип розширення Shipping. Знайдіть VibeFox Loggi, натисніть Install (зелена кнопка +), а потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ і налаштування так само, як у кроках 4 і 5 для OpenCart 3. Сторінка налаштувань та її поля однакові в обох версіях.

Під час встановлення розширення створює невелику таблицю для кешованих цін Loggi. Спосіб доставки вимкнено, доки ви не увімкнете Enable Loggi і не збережете налаштування. Якщо ви встановлюєте розширення повторно після видалення, знову використовуються збережені налаштування Loggi.

Налаштування

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Shipping > VibeFox Loggi > Edit. Розділи перелічені ліворуч. Вони застосовуються до всіх геозон. Одна кнопка Save внизу зберігає всю сторінку без перезавантаження. Кожне збереження також очищує кешовані ціни Loggi. Якщо значення некоректне, наприклад від'ємне число, неправильна адреса електронної пошти або Shop ID, що не є числом, сторінка показує помилку і нічого не зберігається. Зберігати налаштування можуть лише адміністратори з правом зміни цього розширення.

Попередження над налаштуваннями (показуються знову після кожного збереження) вказують на неповне налаштування: немає облікових даних API (використовуються лише фіксовані ціни), немає ні облікових даних API, ні фіксованих цін (спосіб доставки ніколи не показується), немає адреси забору або курсу BRL. Ще одне попередження з'являється, якщо в магазині немає вагової одиниці з кг або одиниці довжини з см, а одиниця класу за замовчуванням не розпізнана. Тоді ваги товарів рахуються в кг, а розміри — в см. Додайте класи в System > Localisation > Weight Classes і Length Classes.

Загальні

Enable Loggi: показує або приховує Loggi під час оформлення замовлення. За замовчуванням: вимкнено.

Method title: назва способу доставки, яку бачить покупець у кошику та під час оформлення. За замовчуванням: Loggi. Обов'язково, до 64 символів, без символів < > ; = # { }.

Sort order: позиція Loggi серед способів доставки під час оформлення. Ціле число.

API Loggi (актуальна ціна) (залиште облікові дані порожніми, щоб використовувати лише фіксовані ціни)

API e-mail: адреса електронної пошти вашого облікового запису Loggi. API-ключ належить до нього. Це має бути дійсна адреса електронної пошти. Її очищення також видаляє збережений API-ключ.

API key: ваш API-ключ Loggi. Він надсилається лише до Loggi і ніколи не записується до журналу. Після збереження поле залишається порожнім і показує Saved — leave empty to keep it; clear the API e-mail to remove it. Вводьте нове значення, лише якщо хочете його змінити. Якщо ви змінюєте API e-mail, введіть також API-ключ для нової адреси, інакше сторінка покаже помилку і нічого не збережеться.

Shop ID: числовий ID (pk) вашого магазину в панелі Loggi, наприклад 12345. Інше значення відхиляється з помилкою.

Staging: використовуйте тестове середовище Loggi (staging) з тестовими обліковими даними. Тестове та робоче середовища мають різні облікові записи і ключі. За замовчуванням: вимкнено.

Pickup address: звідки Loggi забирає посилки, в один рядок: вулиця й номер будинку, район, місто, штат і CEP, наприклад Rua Example, 123 - Bairro, São Paulo - SP, 01310-100. Обов'язкова для актуальних цін: адреса магазину в OpenCart — вільний текст, тому її ніколи не використовують замість неї. Без адреси забору Loggi не може розрахувати оцінку, і використовуються лише фіксовані ціни.

BRL exchange rate: ціни Loggi вказані в бразильських реалах. Якщо валюта магазину за замовчуванням — BRL, це поле не потрібне, і сторінка про це повідомляє. Інакше введіть, скільки коштує 1 BRL у валюті вашого магазину, наприклад 0.16. Без нього актуальні ціни не використовуються. Приймається лише додатне число. Як десятковий роздільник приймаються і крапка, і кома.

Фіксовані ціни (у валюті магазину за замовчуванням, без податків)

Фіксовані ціни використовуються, коли API Loggi не налаштовано, для напрямків поза Бразилією або без повного CEP, а також щоразу, коли Loggi не повертає ціну (API недоступний, ключ відхилено, адреса поза зоною обслуговування).

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

Price for countries not in the table: використовується, коли немає актуальної ціни Loggi і в таблиці немає рядка для країни призначення (і немає рядка *). Залиште поле порожнім, щоб приховати спосіб доставки в такому разі.

Fixed price applies: спосіб підрахунку фіксованих цін. Актуальна ціна Loggi вже охоплює весь кошик і ніколи не множиться.

Умови

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

Maximum weight (kg): приховує спосіб доставки, коли вага кошика вища за це значення. За замовчуванням: 30. 0 означає без обмежень. Minimum weight не може бути більшою за Maximum weight.

Minimum order amount: показувати спосіб доставки, лише коли проміжна сума товарів, що потребують доставки (після купона, до податків), досягає цієї суми. Залиште поле порожнім, щоб показувати його завжди.

Free shipping from: проміжна сума товарів, що потребують доставки (після купона, до податків), починаючи з якої доставка Loggi безкоштовна. Залиште поле порожнім, якщо безкоштовної доставки немає.

Tax class: податковий клас вартості доставки або No tax (за замовчуванням). Оберіть No tax, якщо ваші ціни та ціна Loggi вже включають податки.

Geo zone: пропонуйте Loggi лише для адрес у цій геозоні. All zones (за замовчуванням) означає без обмежень. Геозони налаштовуються в System > Localisation > Geo Zones. Геозона не перевіряється, якщо увімкнено Ignore shipping zones.

Для вагових обмежень і вагових колонок товар без ваги вважається 0 кг.

Країни

В OpenCart немає зон перевізника: Geo zone обмежує спосіб доставки адресами однієї геозони. Натомість можна увімкнути Ignore shipping zones і обрати список країн.

Ignore shipping zones: пропонувати Loggi для країн нижче, незалежно від Geo zone. У цьому режимі геозона не перевіряється. За замовчуванням: вимкнено.

Countries: країни призначення для цього режиму. Залиште поле порожнім, щоб дозволити всі країни, увімкнені в магазині. Це поле використовується лише коли увімкнено Ignore shipping zones.

Додатково

Debug log: записує розрахунки тарифів і запити до Loggi у storage/logs/vfd_lggi_debug.log.php (в OpenCart 4 — system/storage/logs/vfd_lggi_debug.log.php). Файл не можна прочитати з веб-браузера. Помилки API завжди записуються до журналу, навіть коли цю опцію вимкнено. API-ключ і адреси покупців ніколи не записуються до журналу. Коли файл досягає 5 МБ, його переносять до vfd_lggi_debug.old.log.php, і починається новий журнал.

Log: показує розмір і останні записи журналу налагодження. Натисніть Clear log, щоб його очистити.

Remove data on uninstall: якщо увімкнено, видалення розширення стирає налаштування Loggi і журнал. Якщо вимкнено (за замовчуванням), налаштування зберігаються для повторного встановлення. Кешовані ціни завжди видаляються.

Імпорт / Експорт

Export: натисніть Download JSON, щоб зберегти налаштування у файл JSON. API-ключ не експортується.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування, наприклад в іншому магазині. Значення перевіряються так само, як під час звичайного збереження. Збережений API-ключ залишається.

Як це працює під час оформлення замовлення

Коли OpenCart показує способи доставки, він запитує в розширення ціну Loggi. Якщо задано Geo zone, Ignore shipping zones вимкнено і адреса поза геозоною, Loggi не пропонується. Враховуються лише товари з Requires Shipping у значенні Yes: інші товари не додають ваги і не входять до суми замовлення. Далі розширення перевіряє умови: дозволені країни (з Ignore shipping zones), вагу кошика та мінімальну суму замовлення. Сума замовлення — це ціна товарів, що потребують доставки, після знижки за купоном і до податків. Подарункові сертифікати, бонусні бали та кредит магазину не враховуються. Якщо діє безкоштовна доставка, ціна дорівнює 0, і запит до Loggi не надсилається.

Для адреси в Бразилії з повним 8-значним CEP розширення формує посилки Loggi: кожен товар повертається так, щоб його найменша сторона була висотою, і товари складаються в одну посилку, поки вона залишається в межах 55 × 55 × 55 см і 20 кг. Товари без ваги або розмірів рахуються як 1 см з кожного боку, а кожна посилка важить щонайменше 100 г. Loggi приймає 2 посилки на оцінку, тому більші кошики надсилаються кількома запитами, а підсумки додаються. Розширення надсилає до Loggi ID вашого магазину, адресу забору, адресу доставки (вулиця, місто, штат і CEP) та посилки, а підсумок Loggi з BRL конвертує в основну валюту вашого магазину. Ціна округлюється до знаків цієї валюти і показується покупцеві в його валюті з податком вибраного Tax class.

Кожна ціна Loggi кешується на 1 годину для кошика, адреси, облікового запису та середовища, тож той самий кошик не спричиняє новий запит. Невдала оцінка кешується на 10 хвилин. Якщо Loggi взагалі недоступний, запити призупиняються на 2 хвилини, щоб оформлення не чекало Loggi під час кожного оновлення. Тайм-аут API становить 10 секунд.

Фіксовані ціни використовуються натомість, коли API не налаштовано, адреса поза Бразилією або ще не має повного CEP, відсутній курс BRL, немає адреси забору, товар більший за посилку Loggi, кошику потрібно понад 10 посилок, або Loggi повертає помилку, відхилену посилку, адресу поза зоною обслуговування чи нульовий підсумок. Якщо немає і фіксованої ціни, спосіб доставки приховується. Покупець ніколи не бачить помилки API. Причина записується в журнал налагодження.

В OpenCart 4 покупець натискає Choose у блоці способу доставки на сторінці оформлення і вибирає Loggi у вікні Shipping method options. Спосіб доставки працює так само, як в OpenCart 3.

Розширення лише розраховує ціни. Воно не створює замовлень і відправлень Loggi, не друкує етикетки, не відстежує посилки, не показує строк доставки під час оформлення та не пропонує пункти видачі чи поштомати. Воно нічого не додає до замовлень: у замовленні показано назву способу та вартість доставки, як і для будь-якого іншого способу OpenCart. Відправлення створюйте в панелі Loggi. Loggi доставляє лише по Бразилії. Для інших країн використовуйте фіксовані ціни.

Ліцензійний ключ

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Loggi є першим блоком на сторінці Extensions > Extensions > Shipping > VibeFox Loggi > Edit, над налаштуваннями. Введіть ключ у License key і натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен) та кнопки Check now, щоб перевірити статус ще раз, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче розташовані рядок Product: opencart-shipping-loggi і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише адміністратори з правом Modify для розширення. Тексти блоку відповідають мові адмінпанелі (включено англійську та російську).

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

Один ключ працює на одному домені: адреса магазину з конфігурації OpenCart. Видалення ключа з магазину не звільняє його місце для домену. Звільніть місце у своєму обліковому записі vibefox.net.

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

Коли термін дії ліцензії минає, розширення продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється знову, коли ви відкриваєте Dashboard адмінпанелі або сторінку Edit: раз на день протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення розширення завжди видаляє ліцензійний ключ і статус ліцензії.

Усунення несправностей

Loggi не з'являється під час оформлення: переконайтеся, що ліцензія активна і Enable Loggi увімкнено. Перевірте Geo zone, Ignore shipping zones і Countries, попередження вгорі сторінки розширення, обмеження ваги та Minimum order amount. Якщо покупець ще не ввів повний CEP або Loggi не повертає ціну, способу доставки потрібна фіксована ціна: рядок для країни, рядок * або Price for countries not in the table. Перевірте, що товари мають Requires Shipping у значенні Yes.

Показуються лише фіксовані ціни: перегляньте поле Log на сторінці розширення. Помилки завжди записуються до журналу. Увімкніть Debug log для кожного кроку і перезавантажте оформлення. Типові причини: немає адреси електронної пошти, ключа або Shop ID API, немає адреси забору, немає BRL exchange rate для валюти магазину, відмінної від BRL, ще немає повного 8-значного CEP, товар більший за 55 см або важчий за 20 кг, чи адреса поза зоною покриття Loggi.

HTTP 401 або 403 у журналі: Loggi відхилив адресу електронної пошти або ключ API. Перевірте їх у Loggi і переконайтеся, що Staging відповідає обліковим даним: тестові та робочі ключі різні.

Мій магазин продає в євро або доларах: Loggi відповідає в BRL. Введіть BRL exchange rate (скільки коштує 1 BRL у валюті магазину за замовчуванням). Фіксовані ціни завжди вказані у валюті магазину за замовчуванням.

Ціни неточні: заповніть вагу та розміри ваших товарів. Без них товари рахуються як 1 см з кожного боку, а кожна посилка — як щонайменше 100 г.

Per item не множить ціну Loggi: це задумано. Актуальна ціна Loggi охоплює весь кошик. Per item застосовується лише до фіксованих цін.

Ціни здаються застарілими після зміни: натисніть Save на сторінці розширення. Це очистить кешовані ціни Loggi.

Сторінка показує "Warning: You do not have permission to modify VibeFox Loggi!": ваша група адміністраторів, ймовірно, може лише переглядати налаштування. Надайте групі право зміни для extension/shipping/vfd_loggi (OpenCart 3) або extension/vfd_loggi/shipping/vfd_loggi (OpenCart 4) у System > Users > User Groups.

Для розробників: адресу API Loggi можна замінити налаштуванням vfd_lggi_api_url (для тестів); на сторінці налаштувань для нього немає поля.

Видалення

Перейдіть до Extensions > Extensions, оберіть тип Shipping і натисніть Uninstall (червона кнопка −) поруч із VibeFox Loggi. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди скидає Enable Loggi, Sort order, Tax class і Geo zone. Кешовані ціни Loggi (разом із таблицею) завжди видаляються. Якщо Remove data on uninstall увімкнено, налаштування Loggi і журнал налагодження також видаляються. Якщо вимкнено, інші налаштування зберігаються і знову використовуються під час повторного встановлення розширення. Чинні замовлення зберігають свій спосіб доставки та вартість.

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

Loggi — торговельна марка її власника. Це розширення не афілійоване з Loggi і не схвалене нею.