VibeFox bpost Cubee for PrestaShop — Допомога
Вимоги
PrestaShop: 8.0 — 9.x.
PHP: 8.0 або новіша. Модуль не встановлюється на старіших версіях PHP.
Обліковий запис bpost Shipping Platform (лише для вибору пункту видачі): модуль шукає пункти видачі через API bpost Shipping Platform. Увійдіть в обліковий запис bpost Shipping Platform на plugins.bpost.be і створіть ключі в Settings > Key management. Потрібні три значення: Account ID (публічний ключ), Passphrase (приватний ключ) та App ID (X-APPID). App ID видає bpost для вашої інтеграції; запитайте його в службі підтримки e-commerce bpost (eol@bpost.be). Також потрібен ID перевізника за вашим договором (68 = bpost). Без повних ключів перевізник однаково працює з фіксованими цінами, але покупців не просять обрати пункт видачі.
Ліцензійний ключ VibeFox: купується на vibefox.net. Один ключ працює на одному домені.
Встановлення
1. У back office перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.
2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox bpost Cubee у списку модулів і натисніть Configure.
3. Введіть ліцензійний ключ VibeFox у поле License key у блоці ліцензії вгорі сторінки Configure і натисніть Activate (див. Ліцензійний ключ).
4. Введіть свої ціни та, для вибору пункту видачі, API-ключі bpost (див. Налаштування). Натисніть Save.
Під час встановлення модуль створює перевізника bpost parcel locker з текстом строку доставки Pickup point or parcel locker. Перевізник прив'язаний до зони Бельгії та до всіх груп клієнтів, без податкового правила. Зони, групи клієнтів, текст строку доставки та логотип можна змінити в Shipping > Carriers. Не встановлюйте там ціни: ціна завжди береться з модуля.
Налаштування
Усі налаштування розміщені на сторінці модуля: Modules > Module Manager > VibeFox bpost Cubee > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищує збережений API-токен і кеш списків пунктів видачі.
Сторінка показує попередження, коли щось непомітно приховує перевізника або вибір: вибір пункту видачі увімкнено, але API-ключі заповнені не повністю; немає ціни для Бельгії (BE) і ціни за замовчуванням; останнє підключення до API bpost не вдалося; модулю невідома одиниця ваги магазину (встановіть її в International > Localization, Local units); або перевізника bpost не знайдено. Під час збереження рядки Country prices, які не вдалося прочитати, перелічуються в попередженні, так само як і значення Size prices, у якому не розпізнано жодного розміру. Вага або сума, які не є числом чи від'ємні, не зберігаються: попередження називає поле, а попереднє значення залишається. Якщо Min weight (kg) більше за Max weight (kg), ваги також не зберігаються.
Загальні
Enable/Disable: вмикає або вимикає доставку через bpost parcel locker. Це той самий перемикач, що й статус перевізника в Shipping > Carriers.
Name: назва способу доставки, яку бачить покупець під час оформлення замовлення (назва перевізника). За замовчуванням: bpost parcel locker. Якщо залишити поле порожнім, використовується значення за замовчуванням. Не більше 64 символів; довша назва відхиляється, і нічого не зберігається.
Tax status: None означає, що ціни остаточні. Taxable з податковим правилом додає податок цього правила до ваших цін. Вибір зберігається в перевізнику.
API bpost (пошук пунктів видачі) (потрібно лише для вибору пункту видачі)
Account ID (public key): публічний ключ вашого облікового запису bpost Shipping Platform з Key management на plugins.bpost.be. Очищення цього поля також видаляє збережену Passphrase.
Passphrase (private key): приватний ключ, яким підписується кожен запит (HMAC-SHA256). Він ніколи не надсилається до bpost і не записується в журнал. Після збереження поле залишається порожнім і показує Saved - leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.
App ID (X-APPID): ідентифікатор застосунку, який bpost видав для вашої інтеграції. Він передається в заголовку X-APPID.
Carrier ID: перевізник вашого договору bpost Shipping Platform, пункти видачі та поштомати якого виводяться в списку. За замовчуванням: 68 (bpost). Інші перевізники, увімкнені у вашому договорі, мають власні ID.
Вибір пункту видачі
Pickup points: показує вибір пункту видачі та поштомату під час оформлення замовлення. Увімкнено за замовчуванням. Вибір з'являється, і пункт видачі є обов'язковим, лише коли заповнені всі три API-ключі.
Search field width: ширина поля поштового індексу / міста в CSS, наприклад 100% або 300px. За замовчуванням: 100%.
Pickup point list width: ширина списку пунктів видачі в CSS, наприклад 100% або 400px. За замовчуванням: 100%.
Ціни (у валюті за замовчуванням вашого магазину, без податку; bpost не повертає вартість доставки через цей API)
Price by: як обирається ціна.
Country prices: один рядок на країну у формі CC=ЦІНА, наприклад BE=4.95. Рядок *=ЦІНА встановлює ціну для всіх інших країн, наприклад *=9.95. Як десятковий роздільник приймаються і крапка, і кома. Недійсні рядки ігноруються. Країни без ціни (коли немає рядка *) не отримують пропозицію перевізника.
Size prices: використовується, коли Price by — розмір посилки, у формі S=3.50, M=4.50, L=6.00, XL=8.00. Розмір визначається за вагою кошика: S до 2 кг, M до 5 кг, L до 10 кг, XL понад 10 кг.
Calculation: Per order стягує ціну один раз. Per item (price x number of items) множить її на кількість товарів у кошику.
Ціни округлюються до десяткових знаків валюти за замовчуванням, а потім показуються у валюті кошика покупця.
Умови
Min weight (kg): мінімальна вага кошика, за якої з'являється перевізник. Ваги товарів перераховуються з одиниці ваги вашого магазину. 0 означає без обмежень.
Max weight (kg): перевізник приховується, якщо вага кошика перевищує це значення. За замовчуванням: 30, оскільки поштомати bpost приймають посилки до 30 кг. 0 означає без обмежень.
Minimum order amount: показувати перевізника лише тоді, коли підсумок кошика досягає цієї суми. До підсумку входять товари, що потребують доставки, після знижок, без податку. Залиште поле порожнім, щоб завжди показувати перевізника.
Безкоштовна доставка
Free shipping: вмикає безкоштовну доставку від суми, вказаної нижче.
Free shipping from: підсумок кошика (товари, що потребують доставки, після знижок, без податку), від якого доставка безкоштовна. Використовується лише коли увімкнено Free shipping. Для країни все одно потрібна ціна, інакше перевізник не пропонується.
Доступність без зон доставки
Зазвичай перевізник пропонується у своїх зонах доставки в Shipping > Carriers. Під час встановлення це зона Бельгії.
Ignore shipping zones: пропонувати перевізника в країнах, зазначених нижче, без додавання його до зони. Тоді перевізник прив'язується до всіх активних зон, зокрема до зон, які ви створите пізніше. Коли ви знову вимкнете опцію, перевізник отримає назад свої попередні зони.
Countries: країни призначення для цього режиму. За замовчуванням: Бельгія. Залиште поле порожнім, щоб використовувати всі країни, до яких ви доставляєте. Це поле використовується лише коли увімкнено Ignore shipping zones.
Додатково
Debug log: записує в журнал API-запити та розрахунки цін у logs/vfd_bpst_debug.log.php у папці модуля. Файл не можна відкрити через веб. Помилки API завжди записуються, навіть коли ця опція вимкнена. Ключі та токени ніколи не записуються в журнал.
Log: показує розмір і останні записи журналу налагодження. Натисніть Clear log, щоб його очистити.
Remove data on uninstall: якщо увімкнено, видалення модуля стирає його налаштування та перевізника. Пункти видачі, збережені в замовленнях, завжди зберігаються.
Як це працює під час оформлення замовлення
На кроці доставки PrestaShop запитує в модуля ціну bpost. Враховуються лише товари, що потребують доставки: віртуальні товари не додають ваги та не входять до суми замовлення. Модуль перевіряє умови: країни з Ignore shipping zones (якщо увімкнено), вагу кошика та мінімальну суму замовлення. Потім він бере ціну зі списку країн або за розміром посилки, множить її на кількість товарів у режимі за товар і обнуляє, якщо застосовується безкоштовна доставка. Запит до bpost для ціни не надсилається.
Під перевізником bpost покупець бачить поле Postal code or city, кнопку Search і список пунктів видачі. Коли покупець обирає перевізника і ще не шукав, поштовий індекс адреси доставки шукається автоматично. Покупець може ввести інший поштовий індекс або назву міста. Кожен пункт показано з назвою та адресою. Виводиться до 50 пунктів. Список запитується голландською, якщо мова магазину голландська, інакше — французькою.
Покупець має обрати пункт видачі. Без нього Continue на кроці доставки показує Please select a bpost pickup point., а кнопка Place order блокується на сторінці з тим самим повідомленням. Приймається лише пункт зі списку bpost для пошуку. Інакше покупець бачить The selected bpost pickup point is not in the list of your search. Please choose another one. Пошук і вибір зберігаються разом з кошиком, тож оновлення сторінки їх не втрачає. Новий пошук скидає попередній вибір.
Щоб отримати список пунктів видачі, модуль надсилає до bpost лише шуканий поштовий індекс або місто, країну та ID перевізника, підписані вашими ключами. API-токен запитується та оновлюється автоматично. Якщо bpost відхиляє токен, новий запитується один раз і пошук повторюється. Результати пошуку кешуються на 6 годин. Якщо bpost не відповідає, покупець бачить Pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method., а модуль повторює спробу через 5 хвилин. Тайм-аут API — 15 секунд.
Якщо ви редагуєте перевізника в Shipping > Carriers після того, як у нього з'явилися замовлення, PrestaShop зберігає його як нову версію перевізника. Модуль автоматично слідує за новою версією.
Модуль використовує лише фіксовані ціни. Він не отримує актуальні тарифи від bpost, не створює відправлень, не друкує етикетки та не відстежує посилки. Пункти видачі показуються списком, а не на карті. Створюйте відправлення у своєму обліковому записі bpost Shipping Platform або Shipping Manager; ID пункту видачі вказано в замовленні.
Пункти видачі
Під час оформлення замовлення обраний пункт видачі (назва та адреса) і його ID зберігаються разом із замовленням. На сторінці замовлення в back office блок bpost pickup point показує пункт і його ID, або No pickup point was selected for this order. Натисніть Change, знайдіть поштовий індекс або місто, оберіть інший пункт зі списку та натисніть Save. Замовлення оновлюється одразу, і сторінка показує Pickup point updated. Зміна записується в журнал налагодження, якщо увімкнено Debug log. Посилання Change доступне лише за заповненими API-ключами. Для збереження нового пункту потрібне право на редагування замовлень; інакше сторінка показує Permission denied. Доступ до сторінок Modules не потрібен.
Якщо PrestaShop поділяє один кошик на кілька замовлень, пункт видачі залишається в першому замовленні. В інших замовленнях пункту видачі немає, а журнал налагодження показує помилку з назвою першого замовлення; задайте пункт для цих посилок вручну в bpost.
Покупці бачать пункт видачі як bpost pickup point: на сторінці підтвердження замовлення та в деталях замовлення свого облікового запису. Він також додається до назви перевізника в листі з підтвердженням замовлення. Лист про нове замовлення для магазину (якщо ви використовуєте модуль сповіщень електронною поштою) також містить ID пункту.
Щоб пропонувати поштомат і доставку додому разом, використовуйте для доставки додому іншого перевізника в тій самій зоні. Вибір пункту видачі з'являється лише для перевізника bpost.
Ліцензійний ключ
Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox bpost Cubee є першим блоком у Modules > Module Manager > VibeFox bpost Cubee > Configure, над налаштуваннями. Введіть ключ у License key і натисніть Activate. Після цього блок показує ключ прихованим, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) і кнопки Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче розташовані рядок Product: presta-shipping-bpost-cubee і посилання 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.
Без активного ключа перевізник bpost не показується покупцям під час оформлення замовлення, і тарифи не розраховуються. Публічна частина PrestaShop не знає, що ви ввійшли в back office, тому перевізник приховано і для вас: налаштувати модуль можна до купівлі ключа, але перевірити його під час оформлення замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються.
Коли строк дії ліцензії минає, модуль продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус перевіряється автоматично, поки ви працюєте в back office: раз на добу протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення або скидання модуля завжди видаляє ліцензійний ключ і статус ліцензії.
Усунення несправностей
bpost не з'являється під час оформлення замовлення: перевірте, чи активна ліцензія і чи увімкнено Enable/Disable. У Shipping > Carriers перевірте, чи перевізник охоплює зону країни покупця та групу покупця, або чи увімкнено Ignore shipping zones і чи країна є в Countries. Перевірте, чи має країна ціну або чи є рядок *=ЦІНА, а також обмеження ваги та Minimum order amount. Товари також можуть бути обмежені певними перевізниками на сторінці товару. Сторінка налаштувань показує попередження, якщо для Бельгії немає ціни.
Немає вибору пункту видачі під час оформлення замовлення: перевірте, чи увімкнено Pickup points і чи заповнені Account ID (public key), Passphrase (private key) та App ID (X-APPID). Сторінка налаштувань показує попередження, якщо ключі заповнені не повністю.
Покупці бачать "Pickup points cannot be loaded right now": bpost не відповів або відхилив ключі. Причину показано на сторінці налаштувань і в журналі налагодження (поле Log на сторінці модуля). Модуль повторює спробу автоматично через 5 хвилин. Збереження налаштувань повторює спробу одразу.
Для цього поштового індексу або міста пункти видачі не знайдено: bpost не повернув пунктів за цим запитом. Попросіть покупця вказати сусідній поштовий індекс або назву міста та перевірте Carrier ID.
Ціни з комою не використовуються: приймаються і 5,50, і 5.50. Рядки в Country prices, що не відповідають формату CC=ЦІНА, ігноруються; попередження після збереження їх перелічує.
Ціни включають податок? Якщо Tax status встановлено в None, ціни остаточні. З податковим правилом Taxable PrestaShop додає цей податок до ваших цін.
На сторінці написано, що перевізника bpost не знайдено: перевізника видалено в Shipping > Carriers. Скиньте модуль у Modules > Module Manager, щоб створити його знову.
Для розробників: хуки actionVfdBpstApiUrl та actionVfdBpstApiLanguage змінюють адресу API bpost і мову списку пунктів видачі.
Видалення
Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox bpost Cubee і оберіть Uninstall. Ліцензійний ключ і статус ліцензії завжди видаляються. Збережений API-токен і кеш списків пунктів видачі завжди видаляються. Якщо Remove data on uninstall увімкнено, перевізника видаляють (замовлення зберігають свою історію), а також налаштування, журнал і пункти видачі незавершених кошиків. Якщо вимкнено, перевізника лише деактивують і всі налаштування зберігаються. Повторне встановлення модуля повертає перевізникові статус, який був до видалення. Reset у Modules > Module Manager працює так само, тож деактивований перевізник залишається деактивованим. Пункти видачі, збережені в замовленнях, є частиною історії замовлень і ніколи не видаляються.
bpost — торговельна марка відповідного правовласника. Модуль не афільований з bpost і не схвалений ним.