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

Вимоги

PrestaShop: 8.0–9.x.

PHP: 8.0 або новіша версія. Модуль не встановлюється на старіших версіях PHP.

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

Нігерія у вашому магазині: ціни в реальному часі запитуються лише для адрес доставки в Нігерії, тому країна Нігерія має існувати й бути активною в International > Locations > Countries.

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

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

1. У бек-офісі перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Коли завантаження завершиться, натисніть Configure або пізніше знайдіть VibeFox GIG Logistics у списку модулів і натисніть Configure.

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

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

5. Якщо поле Nigerian states показує кнопку Add Nigerian states, натисніть її (див. Налаштування).

Під час встановлення модуль створює перевізника GIG Logistics з текстом терміну доставки Courier delivery. Перевізника прив'язано до зони Нігерії (у магазині за замовчуванням — Африка) і до всіх груп клієнтів. Зони, групи клієнтів, термін доставки, логотип і обмеження розміру можна змінити в Shipping > Carriers. Не встановлюйте там ціни: ціна завжди береться з модуля.

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

Усі параметри знаходяться на сторінці модуля: Modules > Module Manager > VibeFox GIG Logistics > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищує кеш цін GIG Logistics, токенів API та координат адрес.

Над розділами сторінка показує попередження, коли ціни в реальному часі не можна використати: введено лише ім'я користувача або пароль API, не заповнено Sender phone або місто чи штат відправлення, або валюта за замовчуванням не NGN і не задано Currency conversion rate. Також з'являється попередження, якщо перевізника GIG Logistics не знайдено, та коли одиниця ваги магазину (International > Localization > Local units) невідома модулю; тоді ваги товарів читаються як кг. Під час збереження повідомляється про некоректне число (від'ємна сума, Currency conversion rate 0, широта поза межами від -90 до 90, довгота поза межами від -180 до 180), про Min weight (kg), більший за Max weight (kg), про порожній або некоректний Method title чи невідоме податкове правило, і нічого не зберігається.

General

Налаштування цієї сторінки застосовуються до всіх зон перевізника.

Enable/Disable: вмикає або вимикає перевізника. Це той самий перемикач, що й статус перевізника в Shipping > Carriers.

Method title: назва перевізника, яка показується в кошику та під час оформлення замовлення. За замовчуванням: GIG Logistics. Обов'язково.

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

GIG Logistics API (live prices) (необов'язково)

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

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

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

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

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

Pickup (sender) address

Звідки GIG Logistics забирає посилки, у Нігерії. Якщо ваш магазин у Нігерії, порожні поля вулиці, міста та штату беруть адресу магазину з Shop Parameters > Contact > Stores.

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

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

Street address: адреса вулиці для відправлення.

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

State: штат Нігерії для адреси відправлення, обирається з 37 штатів. Варіант за замовчуванням, Shop state (Shop parameters > Contact > Stores), використовує штат з адреси магазину. Обов'язково для цін у реальному часі.

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

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

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

Nigerian states: штат адреси доставки передається в GIG Logistics і в пошук адрес. PrestaShop за замовчуванням не має штатів Нігерії; без них використовуються лише вулиця та місто. Кнопка Add Nigerian states додає 37 штатів (коди LA, FC тощо), вмикає Contains states для Нігерії та додає поле штату до форми адреси в Нігерії. Штати, які вже є (за кодом або за назвою), не додаються вдруге. Коли все налаштовано, поле показує, скільки штатів є для адрес у Нігерії. Нічого не змінюється, доки ви не натиснете кнопку.

Price table and fallback

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

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

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

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

Conditions

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

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

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

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

Availability without shipping zones

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

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

Advanced

Debug log: записує розрахунки цін у logs/vfd_gigl_debug.log.php у папці модуля. Файл неможливо відкрити з веб-браузера. Помилки API завжди записуються, навіть коли журнал вимкнено. Паролі, токени та адреси клієнтів не записуються.

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

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

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

На кроці доставки PrestaShop запитує в модуля ціну GIG Logistics. Враховуються лише товари, що потребують доставки: віртуальні товари не додають ваги і не входять до суми кошика. Модуль спочатку перевіряє умови: країну доставки (з Ignore shipping zones), вагу кошика та мінімальну суму. Якщо сума досягає Free shipping from, ціна дорівнює 0, і запит до GIG Logistics не надсилається.

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

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

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

Якщо ви редагуєте перевізника в Shipping > Carriers після того, як у нього з'явилися замовлення, PrestaShop зберігає його як нову версію перевізника. Модуль автоматично переходить на нову версію.

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

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox GIG Logistics — це перший блок у Modules > Module Manager > VibeFox GIG Logistics > Configure, над налаштуваннями. Вставте ключ у License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої діє ліцензія, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа і Remove key для видалення ключа з цього магазину. Нижче розміщені рядок Product: presta-shipping-gig-logistics і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише працівники з правом Configure для модуля. Тексти блоку відповідають мові back office (включено англійську та російську).

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

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

Без активного ключа перевізник GIG Logistics не показується покупцям під час оформлення замовлення, і ціна не розраховується. Вітрина PrestaShop не знає, що ви увійшли в back office, тож перевізник приховано і для вас: ви можете налаштувати модуль до купівлі ключа, але не можете перевірити його під час оформлення замовлення. Нагадування з’являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються.

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

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

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

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

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

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

Попередження про місто та штат відправлення не зникає: оберіть штат у State і заповніть City / area. Адреса магазину використовується, лише якщо країна магазину — Нігерія, а штат магазину стає відомим лише після додавання штатів Нігерії та вибору штату в Shop Parameters > Contact > Stores.

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

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

Сторінка повідомляє, що перевізника GIG Logistics не знайдено: перевізника видалено в Shipping > Carriers. Скиньте модуль у Modules > Module Manager, щоб створити його знову.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox GIG Logistics і оберіть Uninstall. Ліцензійний ключ і статус ліцензії завжди видаляються. Кешовані ціни, токени та координати адрес завжди видаляються. Якщо Remove data on uninstall увімкнено, перевізника видаляють (замовлення зберігають свою історію), а також налаштування та журнал. Якщо вимкнено, перевізника лише деактивують, а всі налаштування зберігаються. Повторне встановлення модуля повертає збереженому перевізнику його попередній статус. Штати Нігерії, додані через Add Nigerian states, залишаються у вашому магазині в обох випадках.

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