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

Вимоги

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

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

Обліковий запис Frenet (лише для актуальних розрахунків): створіть безкоштовний обліковий запис у панелі Frenet (painel.frenet.com.br), увімкніть перевізників, яких використовуєте, і скопіюйте свій API-токен. Якщо ви використовуєте лише фіксовані ціни, обліковий запис Frenet не потрібен.

Товари: заповніть вагу та розміри для точних цін. Товари без них розраховуються як 0,3 кг і 16 × 11 × 2 см (найменша коробка Correios).

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

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

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

OpenCart 3

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

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

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

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

5. Вставте API-токен і введіть CEP відправлення. Якщо валюта за замовчуванням не BRL, введіть курс BRL. За бажанням додайте фіксовані ціни та запасну вартість. Увімкніть Enable Frenet і натисніть Save.

OpenCart 4

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

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

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

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

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

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Shipping > VibeFox Frenet > Edit. Розділи перелічено ліворуч. Одна кнопка Save внизу зберігає всю сторінку без перезавантаження. Кожне збереження також очищає кешовані розрахунки Frenet. Поля цін приймають як крапку, так і кому як десятковий роздільник. Якщо значення неправильне, нічого не зберігається, а сторінка показує причину, наприклад Enter a valid method title (64 characters max, without < > ; = # { })., "…" must be a number. або "…" must not be negative. Також відхиляються BRL exchange rate нуль або менше та Minimum weight (kg) більше за Maximum weight (kg). Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

Угорі сторінки, а також після кожного збереження розширення показує попередження: немає API-токена (тоді використовуються лише фіксовані ціни, або спосіб доставки не показується, якщо фіксованих цін також немає), немає CEP відправлення, CEP відправлення не з 8 цифр або валюта за замовчуванням не BRL і немає курсу. Воно також попереджає, якщо в магазині немає класу ваги з одиницею kg або класу довжини з одиницею cm. Тоді вага та розміри товарів перераховуються за назвою одиниці їхнього класу, а невідомі одиниці вважаються кілограмами або сантиметрами. Перевірте System > Localisation > Weight Classes і Length Classes.

Загальні

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

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

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

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

Актуальні розрахунки Frenet

Frenet порівнює перевізників, увімкнених у вашому обліковому записі Frenet (Correios, Jadlog, Loggi та інші), і повертає їхні ціни для кошика. Актуальні розрахунки запитуються лише для адрес у Бразилії з повним 8-значним CEP. Розділ містить посилання на панель Frenet.

API token: ваш API-токен Frenet із панелі Frenet. Залиште поле порожнім, щоб використовувати лише фіксовані ціни. Після збереження поле лишається порожнім і показує A token is saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Щоб видалити збережений токен, позначте Remove the saved token і збережіть.

Origin CEP: поштовий індекс (CEP), з якого відправляються посилки, наприклад 01001-000. В OpenCart немає поштового індексу магазину, тому для актуальних розрахунків потрібне це поле. CEP не з 8 цифр зберігається так, як введено, а сторінка показує Frenet: the origin CEP must have 8 digits.

Service to offer: Cheapest service (за замовчуванням) або Fastest service. Frenet повертає кілька сервісів, а спосіб доставки показує одну ціну. Обраний перевізник, сервіс і строк доставки зберігаються із замовленням.

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

Фіксовані ціни

Використовуються, коли немає API-токена, для країн, які Frenet не обслуговує, і щоразу, коли Frenet не повертає ціну (API недоступний, CEP не обслуговується).

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

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

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

Умови

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

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

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

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

Tax class: податковий клас, що додається до вартості доставки, або No tax. Ціни Frenet — це остаточні ціни перевізника. Виберіть No tax, якщо OpenCart не повинен нараховувати на них податок.

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

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

Зазвичай спосіб пропонується в геозоні, обраній у Conditions (у всіх зонах, якщо жодну не обрано).

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

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

Додатково

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

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

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

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

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

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

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

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

Для адреси в Бразилії з повним 8-значним CEP, коли задано API-токен і CEP відправлення, розширення надсилає до Frenet CEP відправлення та призначення, кожну позицію кошика (вага в кг, розміри в см, кількість, Model товару та його категорії), суму замовлення в BRL та код купона кошика. Поки CEP неповний, запит не робиться. Frenet повертає сервіси ваших увімкнених перевізників. Сервіси з помилкою або без ціни пропускаються. Розширення обирає найдешевший або найшвидший сервіс і переводить ціну у валюту за замовчуванням. Ціна округлюється за десятковими знаками валюти за замовчуванням і показується покупцю у його валюті з податком обраного Tax class.

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

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

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

Замовлення

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

Carrier: перевізник і сервіс Frenet, наприклад сервіс Correios або Jadlog. Показується для актуальних розрахунків.

Delivery time: строк доставки в робочих днях, який повернув Frenet. Показується для актуальних розрахунків.

Price source: Live Frenet quote, Fixed price (price per country), Fallback cost або Free shipping.

На OpenCart 4 блок показується над History. OpenCart 4 оновлює те саме замовлення, коли покупець підтверджує його знову: збережені дані Frenet також оновлюються, а якщо покупець обрав інший спосіб доставки, дані Frenet цього замовлення видаляються.

Блок показується й тоді, коли розширення вимкнено. Ці дані зберігаються під час видалення розширення, зокрема з увімкненим Remove data on uninstall.

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

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

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

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

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

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

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

Frenet не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable Frenet увімкнено. Перевірте Geo zone або Ignore shipping zones і Countries, обмеження ваги та Minimum order amount. Перегляньте попередження у верхній частині сторінки розширення. Типові причини: покупець ще не ввів повний 8-значний CEP, а фіксованих цін немає; або Frenet не повернув жодного сервісу для маршруту, і фіксованої ціни немає. Перевірте, що в товарів Requires Shipping встановлено Yes.

Актуальні розрахунки не з'являються: увімкніть Debug log, перезавантажте оформлення замовлення й перегляньте поле Log на сторінці розширення. Воно покаже причину: немає CEP відправлення, немає курсу BRL, неповний CEP покупця, перевищено обмеження ваги або суми, або повідомлення пропущених сервісів.

У журналі сказано, що API-токен відхилено (HTTP 401 або 403): скопіюйте токен заново з панелі Frenet і вставте його в API token.

У журналі сказано, що Frenet не повернув сервісів: увімкніть принаймні одного перевізника в панелі Frenet.

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

До ціни Frenet додається податок: ціни Frenet — це остаточні ціни перевізника. Встановіть Tax class у No tax.

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

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

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

Видалення

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

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

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