VibeFox Blue Express for OpenCart — Допомога

Вимоги

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

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

Обліковий запис Blue Express (лише для живих тарифів): живим тарифам потрібен обліковий запис електронної комерції Blue Express та його ключ API (x-api-key). Запросити його можна у Blue Express: developers.bluex.cl або gpo.integraciones@bx.cl. Послуга, яку ви використовуєте (EX, PY або MD), має бути увімкнена у вашому договорі з Blue Express. Якщо ви використовуєте лише фіксовані ціни, ключ API не потрібен.

Регіони Чилі: для живого тарифу адреса доставки має містити регіон Чилі. Якщо в вашому магазині немає регіонів Чилі, розширення може додати їх за вас (див. Налаштування).

Пункти видачі: карта Blue Express завантажується в браузері покупця з widget-pudo.blue.cl.

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

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

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

OpenCart 3

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

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

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

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

5. Введіть ключ API, послугу, код району відправлення (наприклад SCL), курс CLP, якщо валюта вашого магазину не CLP, і фіксовані ціни (наприклад CL=4500). Увімкніть Enable/Disable для доставки додому та Pickup point option, якщо хочете пропонувати отримання в пунктах Blue Express. Натисніть Save. Див. Налаштування.

OpenCart 4

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

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

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

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

Під час встановлення розширення створює таблицю для пунктів видачі замовлень. Спосіб вимкнений, доки ви не увімкнете доставку додому або варіант з пунктом видачі та не збережете налаштування. Якщо ви встановлюєте розширення повторно після видалення, знову використовуються збережені налаштування Blue Express.

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

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

Недійсні значення відхиляються з помилкою, і нічого не зберігається: порожня назва або назва із символами < > ; = # { }, назва довша за 64 символи, від'ємне або некоректне число, Min weight (kg) більше за Max weight (kg), Sort order, яке не є цілим числом, або невідомий податковий клас чи геозона.

Попередження про налаштування, які приховали б варіанти або живий тариф, показуються вгорі сторінки: немає ключа API, валюта магазину не CLP без курсу обміну, порожня таблиця фіксованих цін, немає зон для Чилі, а також магазин без класу ваги з одиницею «кілограм» або класу довжини з одиницею «сантиметр», одиниці за замовчуванням яких розширення не розпізнає (тоді ваги читаються як кг, а розміри як см).

Загальні

Enable/Disable: вмикає або вимикає доставку Blue Express додому.

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

Tax class: податковий клас вартості доставки або None (no tax on shipping) (за замовчуванням). Ціни Blue Express включають ПДВ (IVA). Оберіть None, якщо OpenCart не має додавати податок зверху. Діє для обох варіантів.

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

Отримання в пунктах Blue Express (PUDO)

Pickup point option: пропонує доставку в пункт Blue Express, обраний покупцем, як другий варіант поряд із доставкою додому. За замовчуванням вимкнено.

Pickup point name: назва способу доставки, яку бачить покупець на оформленні для отримання в пункті Blue Express. За замовчуванням: Blue Express pickup point. Обов'язкове поле, не більше 64 символів.

API Blue Express (потрібен для живих тарифів)

API key: ваш ключ API Blue Express (заголовок x-api-key). Без нього використовуються лише фіксовані ціни. Після збереження поле лишається порожнім і показує A key is saved - leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Remove the saved API key: увімкніть і збережіть, щоб видалити збережений ключ.

Service: послуга Blue Express для тарифу: Express (EX) (за замовчуванням), Prioritario (PY) або SameDay (MD). Вона має бути увімкнена у вашому договорі з Blue Express.

Origin district code: код району Blue Express місця, з якого ви відправляєте, наприклад SCL для Сантьяго (за замовчуванням). Якщо не впевнені, уточніть у Blue Express.

CLP per 1 (your currency): напис показує основну валюту вашого магазину, наприклад CLP per 1 EUR. Ціни Blue Express вказані в чилійських песо (CLP). Введіть, скільки CLP коштує одна одиниця основної валюти вашого магазину, наприклад 1050. Без цього живі тарифи не використовуються. Ігнорується, якщо валюта магазину — CLP.

Ціна

Rate source: як розраховується ціна. Живий тариф потребує чилійської адреси з регіоном і комуною (містом). Помилки записуються в журнал і ніколи не показуються покупцеві.

Fixed prices: один рядок на країну у форматі КОД_КРАЇНИ=ЦІНА, в основній валюті магазину, без податку, наприклад CL=4500 у магазині в CLP або CL=4.50 у магазині в EUR. Як десятковий роздільник приймаються кома або крапка. Некоректні рядки ігноруються та перелічуються в попередженні під час збереження. Країна без рядка не має фіксованої ціни, тож варіанти для неї приховуються, коли потрібна фіксована ціна. Фіксовані ціни можна використовувати для будь-якої країни.

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

Умови

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

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

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

Безкоштовна доставка

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

Free from subtotal: сума кошика (валюта магазину, товари, що потребують доставки, після купона, без податку), від якої доставка безкоштовна. Тоді запит до Blue Express не надсилається. Використовується лише тоді, коли ввімкнено Free shipping.

Доступність

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

Ignore shipping zones: пропонувати обидва варіанти в кожній геозоні. Тоді країни обмежуються списком нижче.

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

Регіони Чилі (показується, лише якщо в вашому магазині немає регіонів Чилі)

Blue Express потребує регіон чилійської адреси (RM, VS тощо) для живого тарифу. Регіон береться з зони адреси за її кодом або назвою. Розділ показує, скільки зон Чилі є у вашому магазині і яких регіонів бракує (стандартний магазин OpenCart 3.0.5 має 15 з 16, без Ñuble). Натисніть Add Chilean regions, щоб додати відсутні регіони як зони Чилі з кодами, які використовує Blue Express. Регіони, які у вас вже є (за кодом або назвою), не додаються повторно. Нічого не змінюється, доки ви не натиснете кнопку. Ви також можете додати їх вручну в System > Localisation > Zones.

Додатково

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

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

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

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

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

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

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

Коли OpenCart показує способи доставки, він запитує в розширення ціну кожного увімкненого варіанта. Якщо задано Geo zone (і Ignore shipping zones вимкнено) та адреса поза нею, Blue Express не пропонується. За Ignore shipping zones вирішує список Countries. Враховуються лише товари з Requires Shipping = Yes: інші товари не додають ваги й не входять до підсумку. Розширення перевіряє вагу кошика та Minimum order subtotal. Підсумок — це ціна товарів, що потребують доставки, після знижки за купоном і до податку. Подарункові сертифікати, бонусні бали та кредит магазину не враховуються. Якщо діє безкоштовна доставка, ціна дорівнює 0 і запит до Blue Express не надсилається.

Для живого тарифу адреса має бути в Чилі, з регіоном і містом (комуною). Розширення спочатку просить Blue Express розпізнати комуну, потім запитує ціну за послугу, район відправлення, призначення та посилки. Кожен товар надсилається з вагою та габаритами, переведеними в кг і см з його класів ваги та довжини. Товари без ваги чи розміру надсилаються як 0,01 кг, 10 x 10 x 10 см. Оголошена вартість надсилається в CLP. Ціна в CLP перераховується в основну валюту магазину, округлюється до його десяткових знаків і показується покупцеві в його валюті з податком обраного Tax class.

Тарифи кешуються на 1 годину, дані про комуни — до 12 годин, але не довше, ніж термін життя кешу OpenCart (1 година за замовчуванням). Невдалий виклик API запам'ятовується на 5 хвилин, а тайм-аут становить 10 секунд, тож повільний або недоступний API не сповільнює кожне оновлення оформлення. Помилки API ніколи не показуються покупцеві: варіант приховується, або в режимі резерву використовується фіксована ціна. Причина записується в журнал.

Розширення не створює відправлень і етикеток у Blue Express, не присвоює номери відстеження та не показує оновлення відстеження. Створіть відправлення у своєму обліковому записі Blue Express. Регіональних тарифних таблиць за комунами немає: використовуйте тариф API Blue Express або фіксовану ціну для кожної країни. Живі тарифи працюють лише для Чилі.

На OpenCart 4 покупець натискає Choose у блоці способів доставки на сторінці оформлення і вибирає Blue Express або Blue Express pickup point у вікні Shipping method options. Варіанти працюють так само, як на OpenCart 3; блок пункту видачі описано в розділі Пункти видачі.

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

Коли опцію пункту видачі увімкнено, під способом Blue Express pickup point на кроці Delivery Method оформлення замовлення в OpenCart з'являється блок із кнопкою Choose pickup point. Кнопка відкриває офіційну карту Blue Express, де покупець обирає пункт. Обраний пункт показується з назвою та адресою, а кнопка змінюється на Change pickup point. Пункт зберігається для сеансу оформлення, і тариф перераховується за ціною отримання (PUDO) Blue Express. Якщо ціна змінюється, варіант показує нову ціну. Якщо варіант більше не пропонується для цього пункту, крок доставки перезавантажується. Доки пункт не обрано, варіант показує ціну доставки додому.

Покупець не може продовжити без пункту: Continue на кроці доставки відхиляється з повідомленням Please choose a Blue Express pickup point. Це перевіряється в браузері та повторно магазином. Некоректний код пункту відхиляється з повідомленням The selected Blue Express pickup point is not valid. Please choose it again on the map., і попередній вибір зберігається. Якщо збереження не вдалося, покупець бачить The pickup point could not be saved. Please try again.

На OpenCart 4 покупець натискає Choose у блоці способів доставки на сторінці оформлення. У вікні Shipping method options показано той самий блок із Choose pickup point під Blue Express pickup point, поки цей варіант вибрано. Коли ціна змінюється разом з обраним пунктом, варіант у вікні показує нову ціну, а якщо варіант отримання вже збережено для оформлення, оновлюються також поле способу доставки та блок підтвердження замовлення. Якщо варіант більше не пропонується для цього пункту, вікно закривається і список способів доставки завантажується знову. Continue у вікні без пункту блокується з повідомленням Please choose a Blue Express pickup point. у блоці, і магазин перевіряє це повторно. OpenCart 4 зберігає одне замовлення для оформлення і оновлює його під час кожного підтвердження; пункт видачі замовлення оновлюється разом із ним і видаляється, коли замовлення переводять на інший спосіб доставки.

Під час оформлення замовлення пункт зберігається в замовленні з кодом агентства Blue Express, назвою, адресою та регіоном. Він також додається до способу доставки замовлення після назви варіанта отримання, наприклад Blue Express pickup point: Blue Point Providencia, Av. Providencia 1234, щоб покупець бачив його в листах про замовлення та на сторінках замовлень свого облікового запису.

На сторінці замовлення в адмінці (Sales > Orders, View) пункт показано в панелі Blue Express pickup point з кодом і регіоном. Якщо в замовленні немає пункту, панель показує Not chosen. Натисніть Edit, щоб обрати інший пункт кнопкою Choose on the Blue Express map або ввести вручну Agency code, Name та Address, потім натисніть Save pickup point. Текст способу доставки замовлення також оновлюється, а зміна додається до історії замовлення без повідомлення покупцеві (Blue Express pickup point changed: старий код -> новий код). Зміна пункту потребує лише права змінювати замовлення, а не доступу до налаштувань розширення. Наявні замовлення зберігають дані про пункт видачі.

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

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Blue Express — це перший блок на сторінці Extensions > Extensions > Shipping > VibeFox Blue Express > Edit, над налаштуваннями. Вставте ключ у License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа і Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: opencart-shipping-blue-express і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише адміністратори з правом змінювати це розширення. Тексти блоку відповідають мові адмінки (включено англійську та російську).

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

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

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

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

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

Blue Express не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable/Disable (або Pickup point option) увімкнено. Прочитайте попередження вгорі сторінки розширення. Перевірте Geo zone (або Ignore shipping zones і Countries), обмеження ваги, Minimum order subtotal, а також чи є в Fixed prices рядок для країни, якщо ви використовуєте фіксовані ціни або резерв. Перевірте, що у товарів Requires Shipping = Yes.

Живі тарифи не з'являються: з Blue Express API only варіанти приховуються, коли тарифу немає. Увімкніть Debug log, перезавантажте оформлення та подивіться поле Log на сторінці розширення. Типові причини: немає ключа API, валюта магазину не CLP без курсу обміну, немає регіону або комуни в адресі, комуну не розпізнав Blue Express, або помилка API (наприклад HTTP 401 або 403, коли ключ API відхилено). З Blue Express API, fixed price if the API gives no rate покупці все одно отримують фіксовану ціну, поки ви виправляєте проблему.

В адресах Чилі немає регіону: сторінка показує попередження про відсутні регіони. Натисніть Add Chilean regions на сторінці розширення. Покупцям, чиї адреси збережено без регіону, потрібно змінити адресу й обрати регіон.

Податок додається поверх ціни Blue Express: ціни Blue Express включають ПДВ (IVA). Встановіть Tax class у None (no tax on shipping).

Карта не відкривається: карта завантажується в браузері покупця з widget-pudo.blue.cl, тому ця адреса має бути доступною і не блокуватися на вашому сайті.

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

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

Для розробників: адреси API та карти Blue Express можна замінити налаштуваннями vfd_blex_api_url і vfd_blex_widget_url (для тестів); на сторінці налаштувань для них немає полів.

Видалення

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

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

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