VibeFox bpost Cubee for OpenCart — Допомога

Вимоги

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

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

Обліковий запис 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). Також потрібен ідентифікатор перевізника за вашим договором (68 = bpost). Без повних ключів спосіб працює з фіксованими цінами, але покупця не просять обрати пункт видачі.

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

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

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

OpenCart 3

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

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

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

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

5. Введіть свої ціни, наприклад BE=4.95 і *=9.95, а для селектора пунктів видачі — API-ключі bpost (див. Конфігурація). Увімкніть Enable/Disable і натисніть Save.

OpenCart 4

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

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

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

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

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

Конфігурація

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Shipping > VibeFox bpost Cubee > Edit. Розділи перелічені ліворуч. Одна кнопка Save зберігає всю сторінку без перезавантаження. Кожне збереження також очищає збережений API-токен і кешовані списки пунктів видачі. Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

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

Угорі сторінки виводиться попередження, коли щось тихо приховує спосіб або селектор: селектор пунктів видачі увімкнено, але API-ключі заповнені не повністю; для Бельгії (BE) немає ціни і немає ціни за замовчуванням (*=ЦІНА); останнє підключення до API bpost не вдалося; або в магазині немає класу ваги з одиницею «kg» (System > Localisation > Weight Classes). В останньому випадку ваги товарів читаються за назвою їхньої одиниці (kg, g, lb або oz).

Загальні

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

Name: назва способу доставки, яку бачить покупець під час оформлення замовлення. За замовчуванням: bpost parcel locker. Якщо залишити поле порожнім, використовується значення за замовчуванням. Не більше 64 символів.

Tax Class: податок цього класу додається до ваших цін. --- None --- (за замовчуванням) означає, що ціни остаточні.

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

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: показує селектор пунктів видачі та поштоматів під час оформлення замовлення. Увімкнено за замовчуванням. Селектор з'являється, а пункт обов'язковий, лише коли заповнені Account ID, Passphrase і App ID.

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 понад це.

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 увімкнено. Для країни все одно потрібна ціна, інакше спосіб не пропонується.

Доступність

Зазвичай спосіб пропонується в географічній зоні, вибраній нижче. За Ignore geo zone він пропонується в країнах зі списку.

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

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

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

Додатково

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

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

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

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

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

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

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

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

Під опцією bpost покупець бачить поле Postal code or city, кнопку Search і список пунктів видачі. Коли покупець обирає bpost, а список ще не завантажено, автоматично шукається поштовий індекс адреси доставки (або останній пошук покупця). Покупець може ввести інший поштовий індекс або назву міста. Кожен пункт показується з назвою та адресою. Виводиться до 50 пунктів. Список запитується голландською, якщо мова магазину голландська, а в інших випадках — французькою.

Покупець має обрати пункт видачі. Без пункту кнопка Continue на кроці способу доставки показує Please select a bpost pickup point. Приймається лише пункт зі списку bpost для цього пошуку. Інакше покупець бачить The selected bpost pickup point is not in the list of your search. Please choose another one. Пошук і вибір зберігаються для оформлення замовлення, тож оновлення сторінки їх не втрачає. Новий пошук очищає попередній вибір.

В OpenCart 4 покупець натискає Choose у блоці способу доставки на сторінці оформлення замовлення і обирає bpost у вікні Shipping method options. Пошук пунктів видачі та список з'являються у цьому вікні під опцією bpost. Continue у вікні без пункту видачі показує Please select a bpost pickup point. Решта працює так само, як в OpenCart 3.

Щоб вивести пункти видачі, розширення надсилає до bpost лише шуканий поштовий індекс або місто, країну та ідентифікатор перевізника, підписані вашими ключами. API-токен запитується та оновлюється автоматично. Якщо bpost відхиляє токен, новий запитується один раз і пошук повторюється. Результати пошуку кешуються до 6 годин, але не довше строку життя кешу OpenCart (за замовчуванням 1 година). Якщо bpost не відповідає, покупець бачить Pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method., а розширення повторює спробу через 5 хвилин. Тайм-аут API — 15 секунд.

Розширення використовує лише фіксовані ціни. Воно не отримує тарифів у реальному часі від bpost, не створює відправлень, не друкує етикеток і не відстежує посилки. Пункти видачі показуються списком, а не на карті. Створюйте відправлення у вашому обліковому записі bpost Shipping Platform або Shipping Manager; ID пункту видачі вказаний на сторінці замовлення в адмінпанелі.

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

Під час оформлення замовлення обраний пункт видачі додається до способу доставки замовлення як bpost pickup point: з назвою та адресою пункту, наприклад «bpost parcel locker - bpost pickup point: …». Тому покупець бачить його в підтвердженні замовлення, в історії замовлень свого облікового запису, в листах із замовленням і в рахунку. Повні дані пункту, включно з ID, також зберігаються в окремій таблиці розширення. В OpenCart 4 оформлення замовлення зберігає одне замовлення: якщо покупець знову підтверджує замовлення, наприклад після вибору іншого пункту видачі, пункт замовлення оновлюється.

В адмінпанелі на сторінці замовлення в розділі Sales > Orders показана панель bpost pickup point з пунктом і його ID або напис No pickup point was selected for this order. Натисніть Change, знайдіть поштовий індекс або місто, оберіть інший пункт зі списку та натисніть Save. Замовлення та текст його способу доставки оновлюються одразу, а сторінка показує Pickup point updated. Якщо пункту немає в списку bpost для цього пошуку, сторінка показує Pickup point not found in the bpost list of this search. Зміна записується в журнал налагодження, коли Debug log увімкнено. Change доступна лише тоді, коли API-ключі заповнені та адміністратор може змінювати замовлення; доступ до налаштувань розширення не потрібен.

Щоб пропонувати доставку в поштомат і доставку додому разом, для доставки додому використовуйте інший спосіб доставки. Селектор пунктів видачі з'являється лише під опцією bpost.

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

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

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

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

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

bpost не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable/Disable увімкнено. Перевірте Geo Zone або те, що Ignore geo zone увімкнено і країна є в Countries. Перевірте, що для країни є ціна або рядок *=ЦІНА, а також обмеження ваги та Minimum order amount. Перевірте, що в товарів Requires Shipping встановлено Yes. На сторінці налаштувань з'являється попередження, якщо для Бельгії немає ціни.

Селектор пунктів видачі не з'являється під час оформлення замовлення: перевірте, що 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 Class встановлено на --- None ---, ціни остаточні. З податковим класом OpenCart додає цей податок до ваших цін.

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

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

Видалення

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

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

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