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

Вимоги

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

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

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

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

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

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Shipping > VibeFox Cargoson > Edit. Розділи перелічено зліва. Одна кнопка Save внизу зберігає всю сторінку без перезавантаження. Після збереження ви побачите Settings saved. Cached Cargoson prices were cleared. Дробові числа можна вводити з крапкою або комою. Нічого не зберігається, і сторінка показує помилки, якщо Method title порожнє або довше 64 символів, числове поле містить текст чи від'ємне число, Currency conversion rate дорівнює 0, Minimum weight (kg) більше за Maximum weight (kg), Price currency не є трилітерним кодом, рядок таблиці цін містить некоректну країну або ціну, або Sort order не є цілим числом. Якщо розширення не знає одиниці ваги магазину, попередження після збереження повідомить, що ваги товарів приймаються в кілограмах; додайте клас ваги з одиницею kg у System > Localisation > Weight Classes. Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

Загальні

Покупець бачить один тариф Cargoson. Ви можете обмежити спосіб доставки геозоною або країнами в Availability.

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

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

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

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

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

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: країна, з якої ви відправляєте. Перший варіант, Store country, використовує країну вашого магазину.

Collection postcode: поштовий індекс, з якого ви відправляєте. Cargoson вимагає його для живих цін. Адреса магазину в OpenCart — вільний текст, тому поштовий індекс із неї ніколи не береться: введіть його тут.

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

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

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

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

Умови

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

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

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

Free shipping: вмикає безкоштовну доставку Cargoson від суми, вказаної нижче.

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

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

Доступність

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

Ignore shipping zones: не перевіряти геозону; вирішує список країн нижче.

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

Додатково

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

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

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

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

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

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

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

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

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

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

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

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

Замовлення

Коли покупець оформлює замовлення з Cargoson, тариф, розрахований під час оформлення, зберігається разом із замовленням. У Sales > Orders сторінка замовлення показує панель Cargoson shipping:

Carrier, Service та Cargoson service ID: перевізник і сервіс Cargoson, що були розраховані, показуються, коли використовувалася жива ціна.

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

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

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

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

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

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

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

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

Cargoson не з'являється під час оформлення замовлення: перевірте, чи ліцензія активна і чи увімкнено Enable Cargoson. Перевірте Geo zone (або Ignore shipping zones і Countries), обмеження ваги та Minimum order amount. У фіксованому режимі перевірте, чи є у країни або * All other countries ціна для розміру кошика. Перевірте, чи у товарів Requires Shipping встановлено Yes.

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

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

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

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

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

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

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

Видалення

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

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

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