VibeFox GIG Logistics for OpenCart — Допомога

Вимоги

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

PHP: 8.0 або новіша.

Облікові дані API GIG Logistics (лише для актуальних цін): актуальні ціни використовують сторонній API GIG Logistics. GIG Logistics видає бізнес-клієнтам ім'я користувача API (зазвичай адресу електронної пошти) і пароль. Запросіть їх на сторінці розробників GIG Logistics (giglogistics.com/developer). Тестові облікові дані працюють лише з тестовим API. Якщо ви використовуєте лише таблицю цін і запасну вартість, облікові дані API не потрібні.

Нігерія у вашому магазині: актуальні ціни запитуються лише для адрес доставки в Нігерії. В OpenCart уже є країна Nigeria з 37 штатами; її потрібно увімкнути в System > Localisation > Countries.

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

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

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

OpenCart 3

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

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

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

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

5. Заповніть таблицю цін та/або запасну вартість. Для актуальних цін також введіть ім'я користувача та пароль API, телефон відправника, вулицю, місто та штат, а також курс конвертації валюти, якщо валюта за замовчуванням не NGN (див. Налаштування). Увімкніть Enable/Disable і натисніть Save.

OpenCart 4

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

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

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

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

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

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Shipping > VibeFox GIG Logistics > Edit. Розділи перелічено ліворуч. Одна кнопка Save внизу зберігає всю сторінку без перезавантаження. Кожне збереження також очищає кешовані ціни GIG Logistics, токени API та координати адрес. Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

Угорі сторінки, а також після кожного збереження розширення показує попередження, коли актуальні ціни не можна використовувати: введено лише ім'я користувача або пароль API, не заповнено Sender phone або місто та штат забору, або валюта за замовчуванням не NGN і не задано Currency conversion rate. Воно також попереджає, якщо в магазині немає класу ваги з одиницею kg (System > Localisation > Weight Classes); тоді ваги товарів перераховуються за назвою їхньої одиниці (kg, g, lb, oz), а інші одиниці вважаються кілограмами. Під час збереження повідомляється про неправильне число (від'ємна сума, Currency conversion rate 0, широта поза межами від -90 до 90, довгота поза межами від -180 до 180), про Min weight (kg) більше за Max weight (kg), про порожній або некоректний Method title, про порядок сортування, що не є цілим числом, або про невідомий податковий клас чи геозону, і нічого не зберігається.

Загальні

Спосіб пропонується для геозони, обраної в Conditions, або для країн з Ignore shipping zones. Налаштування цієї сторінки застосовуються до всіх зон.

Enable/Disable: показує або приховує GIG Logistics під час оформлення замовлення (стан цього розширення). За замовчуванням: вимкнено.

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

Tax class: податковий клас вартості доставки або No tax. Податковий клас додає ваш податок на доставку до вартості. Оберіть No tax, якщо ціна GIG уже включає все, що ви хочете стягувати.

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

API GIG Logistics (актуальні ціни) (необов'язково)

За наявності облікових даних API ціна запитується в GIG Logistics для кожної адреси в Нігерії й кешується на годину. Без облікових даних або коли API не повертає ціну, використовуються таблиця цін і запасна вартість. Розділ містить посилання на сторінку розробників GIG Logistics.

API username: ваше ім'я користувача API сторонніх сервісів GIG Logistics, зазвичай адреса електронної пошти.

API password: ваш пароль API сторонніх сервісів GIG Logistics. Він використовується лише для входу в API і ніколи не записується в журнал. Після збереження поле лишається порожнім і показує Saved — leave empty to keep it. To remove it, clear the API username and save. Вводьте нове значення, лише якщо хочете його змінити.

Test mode: використовувати тестовий API (dev) GIG Logistics. Тестові облікові дані працюють лише з тестовим API. Вимкніть, щоб отримувати реальні ціни. За замовчуванням: вимкнено.

Currency conversion rate: GIG Logistics повертає ціни в NGN. Якщо валюта за замовчуванням вашого магазину не NGN, введіть, скільки коштує 1 NGN у вашій валюті за замовчуванням (1 NGN = ? вашої валюти, наприклад 0.0006). Курс має бути більшим за 0. Без нього актуальні ціни GIG не використовуються. Якщо валюта за замовчуванням — NGN, поле це повідомляє, і воно не потрібне.

Адреса забору (відправник)

Звідки GIG Logistics забирає посилки, у Нігерії. В OpenCart немає структурованої адреси магазину, тож введіть тут вулицю та місто. Коли країна вашого магазину — Нігерія, порожнє поле State використовує регіон магазину з System > Settings > Store > Local.

Sender name: ім'я відправника, що передається в GIG Logistics. Якщо порожнє, використовується назва магазину.

Sender phone: ваш номер телефону, наприклад 08030000000. GIG Logistics вимагає його для актуальних цін.

Street address: вулиця забору, наприклад 1 Adeola Odeku Street.

City / area: місто або район забору, наприклад Victoria Island. Обов'язково для актуальних цін.

State: штат Нігерії для адреси забору, обирається з 37 штатів. Варіант за замовчуванням, Store region (System > Settings > Store > Local), використовує регіон вашого магазину, якщо магазин у Нігерії. Обов'язково для актуальних цін.

Pickup latitude: необов'язкова широта точки забору на карті, наприклад 6.4281. GIG Logistics розраховує ціну за відстанню. Якщо порожньо, координати шукаються за адресою.

Pickup longitude: необов'язкова довгота точки забору на карті, наприклад 3.4219.

Address lookup: пошук координат адрес на карті через OpenStreetMap (Nominatim). GIG Logistics розраховує ціну за координатами забору та доставки. Вулиця, місто та штат покупця надсилаються на nominatim.openstreetmap.org, а результати кешуються на 30 днів. Без цієї опції надсилається лише текст адреси, і GIG Logistics може не повернути ціну. За замовчуванням: увімкнено.

Таблиця цін і запасний варіант

Використовується для інших країн, коли актуальні ціни не налаштовано або коли GIG Logistics не повертає ціну. Ціни вказані у валюті за замовчуванням вашого магазину, без податку.

Country prices: таблиця з базовою ціною для кожної країни. Натисніть Add country, щоб додати рядок. Оберіть * Any other country для всіх країн без власного рядка. Колонки XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg і XL >5 kg — необов'язкові ціни за ваговими категоріями: ціна категорії вище 0 замінює базову ціну для кошиків цієї категорії. Ціна 0 означає безкоштовну доставку. Порожні або некоректні комірки цін зберігаються як 0, тож заповнюйте базову ціну в кожному доданому рядку. Виправлені значення перелічуються після збереження в попередженні, що починається з Country prices:. Країни без рядка (коли немає рядка *) не отримують ціну з таблиці.

Fallback cost: використовується, коли ні GIG Logistics, ні таблиця не дають ціну. Порожнє означає, що спосіб у такому разі приховується.

Table / fallback price is: Per order стягує ціну один раз. Per item (multiplied by the number of items) множить її на кількість позицій у кошику. Актуальні ціни GIG завжди стосуються всього замовлення.

Умови

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

Minimum subtotal: показує спосіб, лише коли проміжна сума кошика досягає цього значення. Порожнє означає завжди.

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

Max weight (kg): максимальна вага кошика в кг. За замовчуванням: 30. 0 означає без обмежень.

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

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

Ignore shipping zones: пропонувати спосіб для країн, наведених нижче, незалежно від геозони. Geo zone в Conditions тоді не перевіряється.

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

Додатково

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

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

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

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

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

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

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

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

Далі ціна береться з першого джерела, яке її надасть. Спочатку актуальна ціна GIG Logistics, якщо введено облікові дані API, адреса в Нігерії, в адресі є місто або штат, заповнено телефон, місто та штат забору і для магазинів із валютою за замовчуванням, відмінною від NGN, задано курс конвертації. Розширення входить до API GIG Logistics і надсилає адреси та координати забору й доставки, а також позиції кошика з назвами, кількістю, вагою та вартістю. Товари без ваги надсилаються як 1 кг. Ціна запитується для доставки велосипедом. Друге — таблиця Country prices. Третє — Fallback cost. Якщо жодне джерело не дає ціну, спосіб приховується для цього кошика. Ціна розраховується у валюті за замовчуванням, округлюється за її десятковими знаками і показується покупцю у його валюті з податком обраного Tax class.

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

Якщо GIG Logistics повертає помилку або нульову ціну, покупець не бачить помилки. Використовується ціна з таблиці або запасна вартість, а помилка записується в журнал налагодження.

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

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

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

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

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

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

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

GIG Logistics не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable/Disable увімкнено. Перевірте Geo zone або Ignore shipping zones і Countries, обмеження ваги та Minimum subtotal. Перевірте, що таблиця (країна або *) чи Fallback cost дає ціну для країни. Перевірте, що в товарів Requires Shipping встановлено Yes.

Ціна береться з таблиці, а не від GIG Logistics: для актуальних цін потрібні ім'я користувача та пароль API, Sender phone, місто та штат забору, адреса доставки в Нігерії з містом або штатом і, для магазинів із валютою за замовчуванням, відмінною від NGN, Currency conversion rate. Перегляньте попередження у верхній частині сторінки Edit. Увімкніть Debug log, перезавантажте оформлення замовлення і перегляньте поле Log на сторінці розширення, щоб дізнатися причину. Невдалий запит повторюється через 10 хвилин.

Помилка входу в журналі: GIG Logistics відхилив ім'я користувача або пароль API. Перевірте їх і перевірте Test mode: тестові облікові дані працюють лише з тестовим API. Збережіть налаштування, щоб повторити одразу.

GIG Logistics не повертає ціну: GIG розраховує ціни за відстанню. Залиште Address lookup увімкненим або введіть Pickup latitude і Pickup longitude. Підтвердьте ціни у своєму обліковому записі GIG Logistics, перш ніж запускати магазин.

Попередження про місто та штат забору не зникає: оберіть штат у State і заповніть City / area. Регіон магазину використовується, лише коли країна магазину в System > Settings > Store > Local — Нігерія.

До ціни GIG додається податок: встановіть Tax class у No tax, якщо ціна GIG уже включає все, що ви хочете стягувати.

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

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

Для розробників: адресу API GIG Logistics та адресу пошуку адрес можна замінити налаштуваннями vfd_gigl_api_base_url і vfd_gigl_geocode_url (для тестів); для них немає полів на сторінці налаштувань.

Видалення

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

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

GIG Logistics — торговельна марка її власника. Це розширення не пов'язане з GIG Logistics і не схвалене GIG Logistics.