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

Вимоги

PrestaShop: 8.0–9.x.

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

Обліковий запис 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. Один ключ працює на одному домені.

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

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

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

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

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

Під час встановлення модуль створює перевізника Balikobot з текстом терміну доставки Delivery by Balikobot. Перевізник призначається зонам Чехії, Словаччини та Угорщини і всім групам клієнтів. Зони, групи клієнтів, термін доставки, логотип і обмеження розміру можна змінити в Shipping > Carriers. Не встановлюйте там ціни: ціна завжди береться з модуля.

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

Усі налаштування знаходяться на сторінці модуля: Modules > Module Manager > VibeFox Balikobot > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Після збереження ви побачите Settings saved. Cached rates and pickup points were cleared. У верхній частині сторінки з'являються попередження про налаштування, які приховали б перевізника, живі тарифи або пункти видачі: живі тарифи або пункти видачі без користувача чи ключа API, валюта магазину, відмінна від CZK, без Exchange rate, порожні Country prices з фіксованими цінами або з резервним режимом, одиниця ваги магазину, яку модуль не знає (тоді ваги читаються як кг; використовуйте kg, g, lb або oz), і видалений перевізник. Значення, яке не є числом, не зберігається, і ви побачите попередження з назвою поля.

General

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

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

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

Обліковий запис 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: таблиця двобуквенних кодів країн (наприклад, CZ, SK) і цін. Натисніть Add row, щоб додати країну, та значок кошика, щоб видалити її. Використовуйте * як код країни для всіх інших країн. Десяткові числа з крапкою або комою. Використовується у фіксованому режимі та як резерв у разі збою API. Країна без ціни (і без рядка з *) не отримує фіксованого тарифу. Некоректні рядки видаляються під час збереження, а попередження їх перелічує.

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

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

Умови

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

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

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

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

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

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

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

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

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

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

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

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

Додатково

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

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

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

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

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

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

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

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

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

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

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

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

Обраний пункт видачі зберігається в замовленні. На сторінці замовлення в панелі адміністратора він показується в блоці Balikobot pickup point разом з ID відділення Balikobot і перевізником, які потрібні під час створення відправлення в Balikobot. Натисніть Change, щоб обрати інший пункт поблизу адреси замовлення, і натисніть Save. Для зміни пункту потрібне лише право редагувати замовлення, доступ до сторінок модулів не потрібен. Якщо в замовленні немає пункту, блок показує No pickup point was selected for this order.

Покупець бачить пункт як Pickup point: на сторінці підтвердження замовлення та в деталях замовлення. У листі з підтвердженням замовлення та в листі про нове замовлення для магазину (модуль Mail alerts) він додається після назви перевізника. Наявні замовлення зберігають дані про пункт видачі.

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

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

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

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

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

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

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

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

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

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

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

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

Для розробників: модуль має власні хуки для зміни адреси API (actionVfdBlkbApiUrl), пакета «transportcosts» (actionVfdBlkbTransportcostsPackage) і кількості пунктів видачі (actionVfdBlkbPickupMaxResults, за замовчуванням 30).

Видалення

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

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