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

Вимоги

PrestaShop: 8.0 до 9.x.

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

Облікові дані Budbee API (лише для вибору посилкової скриньки): API-ключ і API-секрет. Instabee видає їх мерчантам з договором на доставку. Запитайте свого контакту в Instabee або скористайтеся мерчант-порталом Instabee. Документація API розміщена на developer.budbee.com. Без облікових даних перевізник працює з фіксованими цінами, але покупці не можуть вибрати посилкову скриньку.

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

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

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

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

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

4. Заповніть розділ Prices і, для селектора посилкових скриньок, ваші API key та API secret Budbee (див. Налаштування). Натисніть Save.

Під час встановлення модуль створює перевізника Instabee parcel box з текстом строку доставки Delivery to an Instabee parcel box. Перевізник призначається всім групам клієнтів і зонам Швеції, Фінляндії, Данії, Нідерландів і Бельгії. Зони, групи клієнтів, строк доставки та логотип можна змінити в Shipping > Carriers. Не встановлюйте там ціни: ціна завжди береться з модуля.

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

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox Instabee > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку.

Попередження над налаштуваннями повідомляють, коли введено лише один з двох облікових даних API, коли облікових даних немає, коли не задано ціни за країнами та запасної вартості, коли останній запит до API Budbee завершився помилкою (з датою, часом і причиною), коли перевізника Instabee не знайдено та коли одиницю ваги магазину не розпізнано (задайте kg, g, lb або oz у International > Localization, Local units). Під час кожного збереження налаштувань очищаються кешовані списки посилкових скриньок і остання помилка API. Якщо назва методу або податковий статус недійсні, або Min weight (kg) більше за Max weight (kg), нічого не зберігається і з'являється помилка.

General

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

Method name: назва перевізника, яку покупець бачить під час оформлення замовлення. Типово: Instabee parcel box. Обов'язкове поле, не більше 64 символів.

Tax status: None означає, що наведені нижче ціни остаточні. Taxable з податковим правилом означає, що PrestaShop додає до цін нижче податок на доставку за цим правилом.

Селектор посилкових скриньок (Budbee API)

За наявності облікових даних API покупець обирає посилкову скриньку поблизу свого поштового індексу під час оформлення замовлення, і скринька зберігається в замовленні. Потрібні обидва поля. Селектор залишається вимкненим, доки не заповнено обидва.

API key: ваш API-ключ Budbee (ім'я користувача HTTP Basic).

API secret: ваш API-секрет Budbee (пароль HTTP Basic). Він ніколи не записується в журнал.

Після збереження обидва поля лишаються порожніми і показують Saved - leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Щоб видалити збережені облікові дані, позначте Remove the saved API key and secret і збережіть. Якщо нічого не збережено, сторінка показує No credentials saved.

Test environment: використовує тестовий API Budbee (api.staging.budbee.com). Вмикайте його лише з тестовими обліковими даними від Instabee. Робочі магазини залишають його вимкненим (api.budbee.com). Типово: вимкнено.

Ціни (у заголовку розділу показано типову валюту вашого магазину)

Усі ціни вказуються в типовій валюті магазину, без податків. Приймаються як десятковий кома, так і десятковий крапка (49,90 = 49.90). Покупцю ціна показується у валюті кошика.

Calculation type: спосіб застосування ціни.

Country prices: таблиця з колонками Country, Price, XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg та XL >5 kg. Натисніть Add country, щоб додати рядок, і значок кошика, щоб видалити рядок. Оберіть * Any other country для рядка, що застосовується до всіх країн без власного рядка. Порожній діапазон або 0 використовує колонку Price. Price, що дорівнює 0, означає безкоштовну доставку. Якщо в рядку країни немає ціни для ваги кошика, використовується рядок *, потім Fallback cost. Значення, що не є числом, очищається, і попередження його перелічує. Ваги перераховуються з одиниці ваги магазину в кг.

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

Умови

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

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

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

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

Якщо значення в цих полях або в полі Fallback cost не є числом, його не зберігають, лишається попереднє значення, і попередження називає поле.

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

Зазвичай перевізника пропонують у зонах доставки, з якими його пов'язано в Shipping > Carriers. Крім того, ви можете увімкнути його тут для списку країн.

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

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

Додатково

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

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

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

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

На кроці доставки PrestaShop запитує у модуля ціну Instabee. Враховуються лише фізичні товари: віртуальні товари не додають ваги та не входять до суми замовлення. Модуль перевіряє умови: вагу кошика та мінімальну суму замовлення, а з Ignore shipping zones — дозволені країни. Якщо проміжна сума кошика досягає Free shipping from, ціна дорівнює 0. Інакше ціна береться з рядка Country prices країни призначення, рядка * або з Fallback cost. Якщо ціни немає, перевізника приховують.

Коли покупець обирає перевізника Instabee і облікові дані API задано, під перевізником для Швеції, Фінляндії, Данії, Нідерландів і Бельгії з'являється блок Parcel box. У ньому перелічено скриньки поблизу поштового індексу адреси доставки, відсортовані за відстанню, з назвою, адресою та відстанню. Покупець може ввести інший поштовий індекс і натиснути Search (або Enter). Доки поштовий індекс не введено, блок його запитує. Якщо скриньок не знайдено, покупцеві пропонують спробувати інший поштовий індекс або обрати інший спосіб доставки. Для інших країн перевізник пропонується без скриньки.

Посилкова скринька обов'язкова. Обрана скринька зберігається в кошику, лише якщо вона є у списку Budbee для цього поштового індексу. Коли покупець натискає Continue на кроці доставки, модуль повторно перевіряє скриньку на сервері. Інакше покупець бачить Please choose an Instabee parcel box. Назва скриньки береться зі списку Budbee, а не з браузера. Якщо покупець змінює країну доставки або поштовий індекс адреси, попередній вибір скидається.

Модуль надсилає Budbee лише країну призначення та поштовий індекс, ніколи імена, адреси, e-mail або дані замовлення. Списки скриньок кешуються на 12 годин для кожного поштового індексу, поштовий індекс без скриньок — на 1 годину, а невдалий запит — на 5 хвилин, щоб повільний або недоступний API не сповільнював кожне оновлення оформлення замовлення. Сторінка оформлення ніколи не чекає на Budbee: список завантажується у фоновому режимі, щойно вибрано перевізника. Тайм-аут API — 10 секунд.

Якщо API Budbee недоступний, покупець бачить Parcel boxes cannot be loaded right now. You can place the order without choosing a box - the shop will assign one. Замовлення тоді позначається, а скриньку ви обираєте під час бронювання відправлення. Раніше обрана скринька, яку в цей момент неможливо перевірити, зберігається та позначається як неперевірена.

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

Модуль не розраховує ставки в реальному часі, не оформлює відправлення, не друкує етикетки, не надає номери та листи для відстеження, не пропонує слоти доставки Budbee Home і не показує карту. Оформіть посилку на обрану скриньку у своїх мерчант-інструментах Instabee / Budbee.

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

Під час створення замовлення скринька перевіряється ще раз і зберігається в замовленні. Відтоді вітрина не може її змінити. Скринька відображається в таких місцях:

Сторінка замовлення в адмін-панелі: блок Instabee parcel box з назвою скриньки, адресою та Box ID. Якщо скриньку не вдалося перевірити під час оформлення, її позначено як not verified (Budbee API was unavailable at checkout). Якщо скриньку не було обрано, бо API був недоступний, блок містить Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment.

Сторінка підтвердження замовлення та деталі замовлення в обліковому записі клієнта: Instabee parcel box: з назвою та адресою скриньки.

Листи про замовлення: скринька додається до назви перевізника в листі з підтвердженням замовлення, надісланому покупцю. Лист про нове замовлення для магазину (з модуля PrestaShop Mail alerts) також показує ID скриньки. Якщо скриньку не було обрано, бо API був недоступний, про це згадує лише лист магазину.

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

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

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

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

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

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

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

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

Покупці не бачать список посилкових скриньок: список з'являється лише тоді, коли заповнені API key і API secret, для Швеції, Фінляндії, Данії, Нідерландів і Бельгії, і після введення поштового індексу. Остання помилка API показується над налаштуваннями. Подробиці — у полі Log на сторінці модуля. Увімкніть Debug log для більш детальної інформації.

HTTP 401 або 403 у журналі: Budbee відхилив API-ключ або секрет. Перевірте їх і переконайтеся, що Test environment відповідає вашим обліковим даним (тестові облікові дані — лише з увімкненим тестовим середовищем).

Немає скриньок для поштового індексу: Budbee не обслуговує цей поштовий індекс. Покупець може ввести інший поштовий індекс або обрати інший спосіб доставки.

Покупець не може продовжити з кроку доставки: посилкову скриньку потрібно обрати зі списку, якщо тільки API Budbee не недоступний. Скринька, якої немає у списку для введеного поштового індексу, не зберігається, і покупець бачить This parcel box is not in the Budbee list for the postal code. Please choose the parcel box again.

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

Сторінка повідомляє, що перевізника Instabee не знайдено: перевізника видалено в Shipping > Carriers. Скиньте модуль у Modules > Module Manager, щоб створити його знову. Те саме стосується повідомлення The settings were saved, but the carrier could not be updated. Скидання зберігає статус перевізника: вимкнений перевізник залишається вимкненим.

Видалення

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

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