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

Вимоги

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

PHP: 8.0 або новіша.

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

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

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

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

OpenCart 3

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

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

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

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

5. Заповніть розділ Prices і, для селектора бокса для посилок, ваші API key та API secret Budbee (див. розділ «Налаштування»). Увімкніть Enable/Disable і натисніть Save.

OpenCart 4

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

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

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

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

Після встановлення спосіб доставки вимкнено, доки ви не увімкнете Enable/Disable і не збережете налаштування. Якщо ви перевстановите розширення після видалення, збережені налаштування Instabee буде використано знову.

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

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

Попередження над налаштуваннями повідомляють, коли введено лише один з облікових даних API, коли облікових даних API немає, коли немає цін за країнами і резервної вартості, коли останній запит до API Budbee завершився помилкою (із датою, часом і причиною), а також коли в магазині немає вагової категорії з одиницею kg і одиницю класу ваги за замовчуванням не розпізнано (тоді ваги вважаються в кілограмах; додайте вагову категорію kg у розділі System > Localisation > Weight Classes).

Якщо Method name порожнє або занадто довге, Min weight (kg) більше за Max weight (kg), Sort order не є цілим числом, або клас податку чи геозона не існують, нічого не зберігається і показується помилка.

Загальні

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

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

Tax class: None (the prices are final) (за замовчуванням) означає, що ціни нижче остаточні. Клас податку додає до цін нижче податок на доставку цього класу.

Sort order: позиція Instabee серед способів доставки під час оформлення замовлення. Ціле число.

Селектор бокса для посилок (API Budbee)

За наявності облікових даних 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). За замовчуванням: off.

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

Усі ціни вказуються у валюті магазину за замовчуванням, без податку. Приймаються і десяткова кома, і десяткова крапка (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 для рядка, що застосовується до всіх країн без власного рядка. Порожня або нульова категорія використовує стовпець Price. Ціна Price, що дорівнює 0, означає безкоштовну доставку. Якщо в рядку країни немає ціни для ваги кошика, використовується рядок *, потім Fallback cost. Під час збереження ціна, яка не є числом від 0 і вище, очищається, а рядок з невідомою країною видаляється; попередження їх перелічує. Ваги товарів перераховуються з їхнього вагового класу OpenCart у кг.

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

Умови

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

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

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

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

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

Доступність

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

Ignore shipping zones: коли ввімкнено, Geo zone не перевіряється, і спосіб пропонується для країн нижче. Коли вимкнено (за замовчуванням), діє лише Geo zone.

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

Додатково

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

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

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

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

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

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

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

Коли OpenCart показує способи доставки, він запитує у розширення ціну Instabee. Якщо ввімкнено Ignore shipping zones, Instabee пропонується лише для дозволеної країни (геозона не перевіряється). Інакше, якщо задано Geo zone і адреса знаходиться поза нею, Instabee не пропонується. Враховуються лише товари з Requires Shipping, встановленим у Yes: інші товари не додають ваги і не входять до суми замовлення. Сума замовлення — це ціна товарів, що потребують доставки, після знижки за купоном і до податку. Розширення перевіряє вагу кошика та мінімальну суму замовлення. Якщо проміжна сума досягає Free shipping from, ціна дорівнює 0. Інакше ціна береться з рядка Country prices країни призначення, рядка * або з Fallback cost. Якщо ціни немає, спосіб доставки приховується. Ціна розраховується у валюті магазину за замовчуванням, округлюється до її знаків після коми і показується покупцеві у його валюті з податком обраного Tax class.

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

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

В OpenCart 4 покупець натискає Choose у блоці способу доставки на сторінці оформлення і вибирає Instabee у вікні Shipping method options. Блок Parcel box з'являється в цьому вікні під варіантом Instabee і працює так само. Кнопка Continue у цьому вікні не переходить далі без бокса зі списку, з тими самими повідомленнями.

Розширення передає Budbee лише країну призначення і поштовий індекс, але ніколи імена, адреси, е-пошту чи дані замовлення. Списки боксів кешуються на 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. Тоді замовлення позначається, а бокс ви вибираєте під час бронювання відправлення. Раніше обраний бокс, який у цей момент неможливо перевірити, зберігається і позначається як неперевірений.

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

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

Під час створення замовлення бокс перевіряється ще раз і зберігається в замовленні. Відтоді вітрина не може його змінити. В OpenCart 4 для оформлення зберігається одне замовлення, яке оновлюється щоразу, коли покупець знову підтверджує оформлення, і бокс замовлення оновлюється разом із ним. Якщо покупець переводить це замовлення на інший спосіб доставки, його бокс видаляється. Бокс відображається в таких місцях:

Спосіб доставки замовлення: бокс додається до назви способу, наприклад Instabee parcel box: (назва способу), далі назва і адреса бокса. Цей текст з'являється на сторінках замовлення в адмін-панелі та в кабінеті покупця, у листах про замовлення і в рахунку.

Сторінка замовлення в адмін-панелі (Sales > Orders): панель 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. Панель лише для читання і показується, навіть коли спосіб доставки вимкнено. В OpenCart 4 вона показується над History.

Лист про нове замовлення магазину: назва бокса з його ID або Instabee parcel box: not chosen (Budbee API unavailable at checkout).

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

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

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

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

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

Instabee не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і увімкнено Enable/Disable. Перевірте Geo zone або, якщо ввімкнено Ignore shipping zones, що країна дозволена в Countries. Перевірте, що для країни є ціна, або що є рядок * чи Fallback cost. Перевірте обмеження ваги і Minimum order amount, а також що у товарів Requires Shipping встановлено в Yes. Попередження над налаштуваннями повідомляє, коли ціну не задано. Увімкніть 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 на сторінці розширення. Це очистить кеш списків боксів.

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

Видалення

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

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

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