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

Вимоги

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

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

Обліковий запис Balikobot (для живих тарифів і пунктів видачі): потрібен обліковий запис Balikobot з доступом до API. Користувач API і ключ API знаходяться в клієнтській зоні Balikobot (client.balikobot.cz). Підтримка Balikobot (podpora@balikobot.cz) активує API для вашого облікового запису та перевізників. Живим тарифам потрібні перевізник і послуга, для яких Balikobot підтримує «transportcosts». Пунктам видачі потрібен перевізник з підтримкою «branchlocator» (наприклад Česká pošta, Zásilkovna, PPL, DPD, GLS). Якщо не впевнені, уточніть у підтримки Balikobot. Фіксовані ціни працюють без облікового запису.

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

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

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

OpenCart 3

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

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

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

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

5. Введіть користувача та ключ API, виберіть перевізника і тип послуги, джерело ціни та ціни за країнами (див. розділ Налаштування). Для послуг із пунктами видачі увімкніть Pickup point selection. Увімкніть Enable/Disable і натисніть Save.

OpenCart 4

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

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

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

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

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

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Shipping > VibeFox Balikobot > Edit. Розділи перелічено ліворуч. Одна кнопка Save зберігає всю сторінку без перезавантаження. Після збереження ви побачите Settings saved. Cached rates and pickup points were cleared. Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

Деякі помилки зупиняють збереження, і тоді нічого не зберігається: порожнє або надто довге Name, Sort Order, яке не є цілим числом, або невідомий податковий клас чи геозона. Інші проблеми показуються як попередження, а решта налаштувань зберігається: значення, яке не є числом (або від'ємне), не зберігається, і попередження називає поле. Некоректні рядки Country prices видаляються й перелічуються.

Попередження про налаштування, які приховали б спосіб, живі тарифи або пункти видачі, показуються вгорі сторінки: живі тарифи або пункти видачі без користувача чи ключа API, валюта магазину, відмінна від CZK, без Exchange rate, порожні Country prices за фіксованих цін або в режимі резерву, а також магазин без класу ваги з одиницею kg (тоді ваги товарів зчитуються за назвою одиниці: kg, g, lb або oz).

Загальні

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

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

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

Обліковий запис API Balikobot (потрібен для живих тарифів і пунктів видачі)

API user: ваш користувач API Balikobot із клієнтської зони.

API key: ваш ключ API Balikobot із клієнтської зони. Після збереження поле лишається порожнім і показує Saved - leave empty to keep it. Clear the API user to remove the saved key. Вводьте нове значення, лише якщо хочете його змінити.

Carrier: перевізник Balikobot для тарифів і пунктів видачі: Česká pošta (за замовчуванням), Zásilkovna (Packeta), PPL, DPD, GLS, DHL Express, UPS, TNT, FedEx, Geis, InTime, Uloženka, Toptrans, Pošta bez hranic, Slovenská pošta, SPS (Slovak Parcel Service) або Magyar Posta. Його має бути активовано у вашому обліковому записі Balikobot.

Service type: код послуги Balikobot у перевізника. За замовчуванням: NP. Для Česká pošta: NP = посилка у відділення пошти, NB = посилка до Balíkovna, DR = доставка додому. Коди інших перевізників наведено в клієнтській зоні Balikobot та в документації API.

Ціна (усі ціни вказані в основній валюті вашого магазину)

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

Country prices: список країн і цін. Натисніть Add row, щоб додати рядок, і кнопку видалення, щоб видалити рядок. Оберіть * All other countries для всіх країн без власного рядка. Десяткові значення з крапкою або комою. Використовується у фіксованому режимі та як резерв у разі збою API. Для країни без ціни (і без рядка *) фіксованого тарифу немає, тому спосіб для неї прихований.

Fixed price per: Order (за замовчуванням) стягує ціну один раз. Item (price x quantity) множить її на кількість товарів у кошику. Це стосується лише фіксованих цін. Живий тариф Balikobot завжди розраховується на весь пакет.

Exchange rate: вартість 1 одиниці валюти ціни Balikobot (зазвичай CZK) в основній валюті вашого магазину, наприклад 0.04. Використовується, лише якщо Balikobot повертає ціну в іншій валюті. Залиште поле порожнім, щоб відхиляти такі ціни, і покупець ніколи не заплатить неправильну суму.

Умови

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

Max weight (kg): приховувати спосіб, коли кошик важчий. За замовчуванням: 100. 0 означає без обмеження. Порожнє поле означає 100 кг. Якщо Min weight (kg) більше за максимум, ви побачите попередження, і попередні ваги збережуться.

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

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

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

Tax Class: податок цього класу додається до вартості доставки. Ціни Balikobot зазвичай без ПДВ. За замовчуванням: --- None ---.

Доступність

Зазвичай спосіб пропонується в геозоні, обраній тут (All Zones означає всюди). Ignore geo zone натомість пропонує його в країнах зі списку.

Geo Zone: пропонувати спосіб лише для адрес у цій геозоні. Геозони керуються в розділі System > Localisation > Geo Zones.

Ignore geo zone: пропонувати спосіб у країнах, зазначених нижче, незалежно від геозони.

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

Пункти видачі

Pickup point selection: покупець має обрати пункт видачі. Використовуйте для послуг із пунктами видачі, наприклад Česká pošta NP або NB, чи Zásilkovna. Потрібні користувач і ключ API.

Selector width: ширина списку пунктів видачі в CSS, наприклад 100% або 400px. За замовчуванням: 100%.

Додатково

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

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

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

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

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

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

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

Коли OpenCart показує способи доставки, він запитує в розширення ціну Balikobot. Якщо задано Geo Zone (і Ignore geo zone вимкнено) та адреса поза нею, Balikobot не пропонується. За Ignore geo zone вирішує список Countries. Враховуються лише товари з Requires Shipping = Yes: інші товари не додають ваги й не входять до суми замовлення. Далі розширення перевіряє вагу кошика та Minimum order amount. Сума замовлення — це ціна товарів, що потребують доставки, після знижки за купоном і до податку. Якщо діє безкоштовна доставка, ціна дорівнює 0 і запит до Balikobot не надсилається.

У фіксованому режимі ціна береться з Country prices. У живих режимах розширення надсилає Balikobot перевізника, тип послуги, країну та поштовий індекс призначення, а також вагу кошика в кг. Живий тариф запитується, лише якщо в адресі доставки є поштовий індекс. Ціна в іншій валюті перераховується за Exchange rate або відхиляється, якщо курс не задано. Ціна розраховується в основній валюті магазину, округлюється до його десяткових знаків і показується покупцеві в його валюті з податком обраного Tax Class.

Живі ціни кешуються на 1 годину, тож той самий кошик не викликає новий запит. Невдалий запит кешується на 5 хвилин, а тайм-аут API становить 12 секунд, щоб оформлення не чекало Balikobot під час кожного оновлення. Помилки API ніколи не показуються покупцеві: спосіб приховується, або в режимі резерву використовується фіксована ціна. Деталі йдуть у журнал налагодження.

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

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

Пункти видачі

Якщо ввімкнено Pickup point selection, під способом Balikobot на кроці Delivery Method оформлення замовлення в OpenCart з'являється список пунктів видачі. Список завантажується з «branchlocator» Balikobot для країни, міста та поштового індексу адреси доставки. Доки в адресі немає міста, покупець бачить Enter your city to see the pickup points. Поки список завантажується, він бачить Loading pickup points.... Список кешується до 12 годин.

Вибір зберігається, щойно покупець обирає пункт. Він обов'язковий: Continue на кроці доставки відхиляється з повідомленням Please select a pickup point. Сервер також перевіряє, що обраний пункт належить до адреси доставки. Інакше покупець бачить The selected pickup point is not available for your shipping address. Please choose a pickup point again. Якщо Balikobot у цей момент недоступний, уже обраний пункт приймається. Якщо пункти не знайдено, покупцеві пропонують перевірити місто та поштовий індекс або обрати інший спосіб доставки. Якщо пункти не вдалося завантажити, покупцеві пропонують спробувати пізніше або обрати інший спосіб доставки.

В OpenCart 4 покупець натискає Choose у блоці способу доставки на сторінці оформлення замовлення. Вікно Shipping method options показує список пунктів видачі під способом Balikobot, з тими самими текстами та перевірками. Список завантажується щоразу, коли відкривається вікно, бо адреса може змінитися на тій самій сторінці оформлення, і береться з кешу, коли це можливо. Якщо покупець натискає Continue у вікні без дійсного пункту, повідомлення з'являється вгорі сторінки оформлення, а вікно залишається відкритим. OpenCart 4 зберігає одне замовлення для оформлення і оновлює його при кожному підтвердженні; пункт видачі замовлення оновлюється разом із ним.

Обраний пункт додається до способу доставки замовлення у вигляді - Pickup point:, за яким іде його назва та адреса. Покупець бачить його на сторінках замовлень у своєму обліковому записі та в листах про замовлення, а також він друкується на рахунку-фактурі.

На сторінці замовлення в адмінці (Sales > Orders, View) панель Balikobot pickup point показує пункт, його ID Balikobot і перевізника, які потрібні під час створення відправлення в Balikobot. Натисніть Change, оберіть інший пункт поблизу адреси замовлення і натисніть Save. Текст способу доставки замовлення також оновлюється, і ви бачите Pickup point updated. Зміна пункту потребує лише права змінювати замовлення, а не доступу до налаштувань розширення. Якщо в замовлення не вибрано пункт, панель показує No pickup point was selected for this order. Панель працює й тоді, коли Balikobot вимкнено: наявні замовлення зберігають дані пункту видачі, і пункт можна змінити.

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

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

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

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

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

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

Живі тарифи не з'являються: увімкніть Debug log, перезавантажте оформлення замовлення і подивіться поле Log на сторінці розширення. Там вказано причину: відсутні облікові дані API, ще немає поштового індексу, помилка Balikobot для перевізника та послуги (наприклад «authorization failed: check the API user and API key») або ціна в іншій валюті без Exchange rate. З Live Balikobot rate, fixed price if the API fails покупці все одно отримують фіксовану ціну, поки ви виправляєте проблему.

Ціни в неправильній валюті: фіксовані ціни вказані в основній валюті магазину. Balikobot повертає живі ціни у валюті вашого договору з Balikobot (зазвичай CZK). Якщо вона відрізняється від основної валюти, задайте Exchange rate.

Чи включено ПДВ: ціни Balikobot зазвичай без ПДВ. Якщо вибрано Tax Class, OpenCart додає податок на доставку.

У списку немає пунктів видачі: перевірте, що вказано користувача і ключ API, що перевізник підтримує «branchlocator» і що в адресі доставки є місто та поштовий індекс. Перевірте журнал на помилку Balikobot.

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

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

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

Видалення

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

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

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