VibeFox Cargoson for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

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

Обліковий запис Cargoson (лише для тарифів у реальному часі): тарифи в реальному часі використовують API розрахунку вартості фрахту Cargoson. Запити цін на фрахт потребують передплати Cargoson з доступом до API (план Advanced або вищий на момент написання). Ключ API видає ваш обліковий запис Cargoson; якщо ваш план не показує налаштування API, зверніться до служби підтримки Cargoson. Ціни надходять від перевізників і прайс-листів, підключених до цього облікового запису. Якщо ви використовуєте лише фіксовані ціни, обліковий запис Cargoson не потрібен.

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

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

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

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

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

4. Оберіть, як розраховуватиметься вартість доставки, і заповніть відповідні розділи: фіксовані ціни та, для тарифів у реальному часі, ключ API і поштовий індекс відправлення (див. Налаштування). Натисніть Save.

Під час встановлення модуль створює перевізника Cargoson з текстом терміну доставки Delivery by the cheapest Cargoson carrier. Перевізник призначається всім зонам і всім групам покупців. Зони, групи покупців, термін доставки, логотип і обмеження розміру можна змінити в Shipping > Carriers. Ціни там не задавайте: ціна завжди береться з модуля.

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Cargoson > Configure. Вони застосовуються до всіх зон перевізника. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Після збереження ви побачите Settings saved. Cached Cargoson prices were cleared. Десяткові числа можна вводити з крапкою або комою. Нічого не зберігається, і сторінка показує помилку, якщо в числовому полі є текст або від'ємне число, Currency conversion rate дорівнює 0, Minimum weight більша за Maximum weight, Method title довша за 64 символи, Price currency не є трилітерним кодом валюти, або в рядку таблиці цін вказано неправильний код країни чи ціну. Якщо модуль не розпізнає одиницю ваги магазину, після збереження з'явиться попередження, що ваги товарів беруться в кілограмах; задайте одиницю в International > Localization (Local units).

General

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

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

Shipping cost: як розраховується ціна.

Причина відсутності тарифу в реальному часі записується в журнал модуля. Покупцеві вона ніколи не показується.

API Cargoson (потрібно лише для тарифів у реальному часі)

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

Remove the saved API key: з'являється, коли ключ збережено. Увімкніть опцію та збережіть, щоб видалити ключ.

Carrier: які ціни використовуються. Покупець бачить один тариф.

Package type code: код типу упаковки Cargoson, який надсилається із запитом ціни. За замовчуванням: CLL. Приклади API Cargoson використовують EUR (піддон EUR) і FIN (піддон FIN). Для посилок використовуйте код упаковки вашого облікового запису Cargoson. Замовлення надсилається як одна посилка із загальною вагою кошика.

Price currency: валюта цін у вашому обліковому записі Cargoson у вигляді трилітерного коду. За замовчуванням: EUR. API повертає суми без коду валюти.

Currency conversion rate: потрібен, лише якщо валюта цін відрізняється від основної валюти магазину: 1 одиниця валюти Cargoson = X одиниць основної валюти магазину. Залиште поле порожнім, щоб відхиляти такі ціни, — тоді покупець ніколи не сплатить у неправильній валюті.

Відправлення з (адреса забору) (використовується для тарифів у реальному часі)

Collection country: країна, з якої ви відправляєте. За замовчуванням це країна вашого магазину.

Collection postcode: поштовий індекс, з якого ви відправляєте. Cargoson його вимагає. Якщо поле порожнє і країна забору є країною магазину, використовується поштовий індекс магазину з Shop Parameters > Contact > Stores.

Дата забору, яка надсилається в Cargoson, — сьогодні за часовим поясом магазину або наступний понеділок, якщо це вихідні.

Фіксовані ціни (використовуються, коли Shipping cost має значення Fixed prices, а також як резервний варіант для тарифів у реальному часі)

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

Fixed price applies: Per order стягує ціну один раз. Per item (price × quantity) множить її на кількість товарів у кошику. Тарифи Cargoson у реальному часі завжди вказуються за відправлення.

Умови

Minimum weight: приховує перевізника, якщо вага кошика нижча за це значення, в кг. 0 означає без обмеження.

Maximum weight: приховує перевізника, якщо вага кошика вища за це значення, в кг. За замовчуванням: 25. 0 означає без обмеження.

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

Free shipping: вмикає безкоштовну доставку, коли досягнуто вказану нижче суму замовлення.

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

Tax: податкове правило перевізника або No tax. Тарифи перевізників у Cargoson зазвичай вказуються без ПДВ. Виберіть No tax, якщо ваші ціни вже включають податок.

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

Зазвичай перевізник пропонується в зонах, призначених йому в Shipping > Carriers.

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

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

Додатково

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

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

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

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

На кроці доставки PrestaShop запитує в модуля ціну Cargoson. Враховуються лише фізичні товари: віртуальні товари не додають ваги і не входять до суми замовлення. Ваги товарів переводяться з одиниці магазину в кілограми. Модуль спочатку перевіряє умови: країна доставки, вага кошика та мінімальна сума замовлення. Якщо діє безкоштовна доставка, ціна дорівнює 0 і запит до Cargoson не надсилається.

У режимі фіксованих цін ціна береться з таблиці. У режимах тарифів у реальному часі модуль надсилає в Cargoson дату забору, країну та поштовий індекс забору, країну та поштовий індекс доставки, а також одну посилку з кодом типу упаковки та загальною вагою кошика (щонайменше 0,1 кг). Тариф у реальному часі запитується, лише якщо в адресі доставки є поштовий індекс. Cargoson повертає ціни ваших перевізників; модуль обирає найдешевшу (серед обраного перевізника, якщо він заданий) і за потреби конвертує її в основну валюту магазину. Ціна розраховується в основній валюті магазину, а потім показується у валюті кошика покупця.

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

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

Модуль лише розраховує тарифи. Він не створює відправлень чи бронювань у Cargoson, не друкує етикетки та не відстежує посилки, а покупці не можуть вибрати поштомат або пункт видачі. Кошик котирується як одна посилка із загальною вагою; габарити посилки не передаються. Показується лише найнижча ціна, а не список перевізників.

Замовлення

На сторінці замовлення Cargoson відображається блок Cargoson shipping з тарифом, розрахованим під час оформлення:

Carrier, Service і Cargoson service ID: котирувані перевізник і послуга Cargoson, показуються, коли використовувався тариф у реальному часі.

Price source: Cargoson live price, Fixed price або Free shipping threshold.

Calculated price (excl. tax): ціна в основній валюті магазину.

Котирування зберігається під час оформлення замовлення і згодом не змінюється. Бронюйте відправлення в Cargoson або через його власні інтеграції.

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

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

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

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

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

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

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

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

Тарифи в реальному часі не з'являються: подивіться поле Log на сторінці модуля. Помилки API завжди записуються в журнал; увімкніть Debug log, щоб бачити кожен розрахунок. Типові причини: ще не введено поштовий індекс доставки, немає поштового індексу забору, ключ API відхилено (неправильний або прострочений ключ чи немає доступу до API у вашому плані Cargoson), немає перевізника для маршруту чи ваги або ціна в іншій валюті. За Cargoson live prices, fixed prices if the API fails покупці все одно отримують фіксовану ціну, поки ви виправляєте проблему.

Cargoson відхиляє тип упаковки: використовуйте код упаковки, який ваш обліковий запис Cargoson застосовує в Package type code. Причина з'являється в журналі.

Ціну в іншій валюті відхилено: встановіть Price currency на валюту ваших цін Cargoson і введіть Currency conversion rate.

Податок на доставку стягується двічі: ваші ціни Cargoson уже включають ПДВ. Встановіть Tax на No tax.

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

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

Видалення

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

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