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

Вимоги

PrestaShop: від 8.0 до 9.x.

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

Обліковий запис Blue Express (лише для тарифів у реальному часі): тарифи в реальному часі потребують облікового запису e-commerce 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. Один ключ працює на одному домені.

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

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

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

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

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

Під час встановлення модуль створює двох перевізників: Blue Express (доставка додому, текст строку доставки Home delivery, увімкнено) та Blue Express pickup point (текст строку доставки Pickup at a Blue Express point, вимкнено, доки ви його не увімкнете). Обидва призначені зоні Чилі та всім групам клієнтів. Зони, групи клієнтів, строк доставки, логотип і обмеження розмірів можна змінити в Shipping > Carriers. Ціни там не задавайте: ціна завжди береться з модуля.

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Blue Express > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищує кеш тарифів Blue Express і даних про комуни. У верхній частині сторінки відображаються попередження про налаштування, які б приховали перевізників або тариф у реальному часі: немає API-ключа, валюта магазину не CLP без курсу обміну, порожня таблиця фіксованих цін, немає регіонів для Чилі, одиниця ваги або розмірів магазину, яку модуль не розпізнає (тоді ваги читаються як кг, а розміри як см), або видалений перевізник. Некоректні значення відхиляються з помилкою, і нічого не зберігається: порожня або некоректна назва перевізника, назва довша за 64 символи, від'ємне або некоректне число чи Min weight (kg) більше за Max weight (kg). Умови та ціни нижче застосовуються до обох перевізників.

Загальні

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

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

Tax status: None (no tax on shipping) або Taxable з одним із ваших податкових правил. Ціни Blue Express включають IVA. Оберіть None, якщо PrestaShop не має додавати податок зверху. Застосовується до обох перевізників.

Самовивіз у пунктах Blue Express (PUDO)

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

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 unit of store currency: якщо валюта магазину за замовчуванням не CLP, підпис показує її, наприклад CLP per 1 EUR. Ціни Blue Express вказані в чилійських песо (CLP). Введіть, скільки CLP коштує одиниця валюти магазину за замовчуванням, наприклад 1050. Без цього значення тарифи в реальному часі не використовуються. Ігнорується, якщо валюта магазину — CLP.

Ціна

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

Fixed prices: один рядок на країну у форматі COUNTRY_CODE=PRICE, у валюті магазину за замовчуванням, без податків, наприклад 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 кг. Min weight (kg) не може бути більшим за Max weight (kg).

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

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

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

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

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

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

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

Додатково

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

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

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

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

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

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

На кроці доставки PrestaShop запитує в модуля ціну кожного перевізника Blue Express. Враховуються лише фізичні товари: віртуальні товари не додають ваги і не входять до проміжного підсумку. Модуль перевіряє Countries (з Ignore shipping zones), вагу кошика і Minimum order subtotal. Якщо застосовується безкоштовна доставка, ціна дорівнює 0 і запит до Blue Express не надсилається.

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

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

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

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

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

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

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

Під час оформлення замовлення пункт зберігається в замовленні разом із кодом агенції Blue Express, назвою та адресою. На сторінці замовлення в панелі адміністратора він показується в блоці Blue Express pickup point. Натисніть Edit, щоб обрати інший пункт кнопкою Choose on the Blue Express map або ввести Agency code, Name та Address вручну, а потім натисніть Save pickup point. Зміна записується як приватне повідомлення до замовлення. Для зміни пункту потрібні лише права на редагування замовлень, а не доступ до сторінок Modules. Покупець бачить пункт на сторінці підтвердження замовлення, на сторінці деталей замовлення та в листі з підтвердженням замовлення — поруч із назвою перевізника. Новий лист про замовлення для магазину (з модуля Mail alerts) також показує код агенції. Наявні замовлення зберігають свої дані про пункт видачі.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Blue Express розташований першим на сторінці Modules > Module Manager > VibeFox Blue Express > Configure, над налаштуваннями. Вставте ключ у License key і натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа і Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: presta-shipping-blue-express і посилання 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.

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

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

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

Blue Express не з'являється на оформленні замовлення: перевірте, що ліцензія активна і увімкнено Enable/Disable (або Pickup point carrier). У Shipping > Carriers перевірте, що перевізник охоплює зону країни покупця та групу покупця, або увімкніть Ignore shipping zones і перевірте Countries. Прочитайте попередження у верхній частині сторінки модуля. Перевірте обмеження ваги, Minimum order subtotal і наявність рядка для країни в Fixed prices, якщо ви використовуєте фіксовані ціни або резерв. Товари також можуть бути обмежені певними перевізниками на сторінці товару.

Тарифи в реальному часі не з'являються: з 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 status на None (no tax on shipping).

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

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

Сторінка повідомляє, що бракує перевізника Blue Express: перевізника видалено в Shipping > Carriers. Скиньте модуль у Modules > Module Manager, щоб створити його знову. Скидання зберігає ваші налаштування та статуси перевізників.

Видалення

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

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