VibeFox The Courier Guy for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

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

Ключ API ShipLogic (для тарифів у режимі реального часу та поштоматів): The Courier Guy працює на платформі ShipLogic. Створіть ключ API в кур'єрському порталі The Courier Guy, у розділі Settings > API Keys (бізнес-акаунт). Без ключа використовується лише таблиця цін, а перевізник-поштомат не пропонується.

Доставка в ПАР: тарифи в режимі реального часу та поштомати — лише для адрес у ПАР. ПАР має бути активною країною магазину (International > Locations > Countries).

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

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

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

2. Коли завантаження завершиться, натисніть Configure або пізніше знайдіть VibeFox The Courier Guy у списку модулів і натисніть Configure.

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

4. Введіть API key ShipLogic. Для тарифів у режимі реального часу заповніть адресу відправника (вулиця, місто, провінція, поштовий індекс) і, якщо валюта вашого магазину не ZAR, — ZAR conversion rate.

5. Заповніть таблицю цін та/або резервну вартість і натисніть Save.

6. Для тарифів кур'єра в режимі реального часу натисніть Add South African provinces у розділі Advanced, якщо сторінка повідомляє, що в адресах ПАР немає провінції.

Під час встановлення модуль створює два перевізники: The Courier Guy (текст строку доставки The Courier Guy courier delivery to your door) та The Courier Guy locker (Delivery to a TCG locker of your choice). Обидва активні, прив'язані до зони ПАР і до всіх груп клієнтів. Зони, групи клієнтів, строк доставки, логотип і обмеження розміру можна змінити в Shipping > Carriers. Ціни там не задавайте: ціна завжди береться з модуля.

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox The Courier Guy > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження очищає кешовані тарифи, поштомати та останню помилку ShipLogic. Попередження вгорі сторінки повідомляють, коли ПАР не є активною країною магазину, відсутній ключ API, курс ZAR або адреса відправника, не задані ні таблиця цін, ні резервна вартість, в адресах ПАР немає провінції, модуль не знає одиницю ваги або розміру магазину, чи останній запит до ShipLogic завершився помилкою (з датою та текстом помилки). Некоректне число (наприклад, від'ємне) не зберігається: сторінка називає поле і залишає попереднє значення.

Загальні

Courier to the door: вмикає або вимикає кур'єрського перевізника. Це той самий перемикач, що й статус перевізника в Shipping > Carriers.

Courier carrier name: назва кур'єрського перевізника на етапі оформлення замовлення. За замовчуванням: The Courier Guy. Обов'язкове поле.

TCG locker: вмикає або вимикає перевізника-поштомат. Покупець обирає поштомат під час оформлення замовлення. Його пропонують лише для адрес у ПАР і лише за наявності ключа API ShipLogic.

Locker carrier name: назва перевізника-поштомата на етапі оформлення замовлення. За замовчуванням: The Courier Guy locker. Обов'язкове поле.

Tax status: податкове правило обох перевізників. Taxable: <tax rule>: тарифи в режимі реального часу беруться без ПДВ, а PrestaShop додає податок на доставку за обраним правилом. None: тарифи в режимі реального часу беруться з ПДВ.

API ShipLogic (тарифи в режимі реального часу та поштомати)

API key: ваш ключ API ShipLogic з порталу The Courier Guy. Його ніколи не показують покупцям і не записують у журнал. Після збереження поле залишається порожнім і показує Saved - leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Позначте Remove the saved API key і збережіть, щоб видалити ключ.

Account ID: необов'язково. Числовий ID акаунта ShipLogic, лише якщо ваш ключ має доступ до кількох акаунтів. Значення, яке не є числом, не зберігається.

Тарифи в режимі реального часу (для адрес у ПАР; якщо тариф у режимі реального часу недоступний, використовується таблиця цін)

Price source: звідки береться ціна.

ZAR conversion rate: ShipLogic розраховує в південноафриканських рандах (ZAR). Якщо основна валюта вашого магазину не ZAR, вкажіть, скільки коштує 1 ZAR у вашій валюті, наприклад 0.05. Без цього тарифи в режимі реального часу не використовуються, і діє таблиця цін. Якщо валюта магазину — ZAR, залиште поле порожнім. Курс не оновлюється автоматично.

Адреса відправника (для тарифів у режимі реального часу) (звідки The Courier Guy забирає посилки в ПАР; для тарифів у режимі реального часу потрібні вулиця, місто, провінція та поштовий індекс)

Sender company: назва вашої компанії.

Sender street address: наприклад, 12 My Road.

Sender suburb: район адреси відправника.

Sender city: місто адреси відправника.

Sender province: оберіть провінцію ПАР зі списку.

Sender postal code: поштовий індекс адреси відправника.

Таблиця цін (ваші ціни в основній валюті магазину, без податків: використовується з Price table only, поза ПАР і щоразу, коли немає тарифу в режимі реального часу; допускаються десятковий кома або крапка)

Calculation type: стосується лише таблиці цін. Тариф у режимі реального часу завжди розраховується на все замовлення.

Prices by weight: таблиця країн з колонкою Price та ваговими категоріями XS (до 1 кг), S (до 2 кг), M (до 3 кг), L (до 5 кг) та XL (понад 5 кг). Натисніть Add row, щоб додати рядок (новий рядок починається з ПАР), і значок кошика, щоб видалити рядок. Порожня або нульова категорія використовує колонку Price. Ціна 0 означає безкоштовну доставку. Рядок * Any country застосовується до країн без власного рядка та до рядка країни без жодної ціни. Ціна, яка не є числом, очищається, і сторінка перелічує такі ціни.

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

Умови (обидва перевізники)

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

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

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

Free shipping from: сума кошика, від якої доставка безкоштовна. Залиште порожнім, щоб ніколи не пропонувати безкоштовну доставку. Коли проміжний підсумок досягає цього значення, перевізники показуються з ціною 0, і запит до ShipLogic за тарифом не надсилається.

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

Зазвичай перевізники пропонуються в зонах доставки, до яких вони прив'язані в Shipping > Carriers.

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

Delivery type without zones: Courier to the door або TCG locker (customer chooses a locker). Використовується лише з Ignore shipping zones.

Countries: країни призначення для цього режиму. Залиште порожнім, щоб дозволити всі країни. Поштомати пропонуються лише в ПАР.

Додатково

South African provinces: у PrestaShop немає провінцій ПАР, але тарифу кур'єра в режимі реального часу потрібна провінція адреси. Add South African provinces додає 9 провінцій (EC, FS, GP, KZN, LP, MP, NC, NW, WC) як регіони ПАР і показує поле регіону в адресах ПАР. Провінції, які вже існують, повторно не додаються. До того часу кур'єр отримує ціну з таблиці.

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

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

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

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

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

Courier to the door: модуль запитує в ShipLogic найдешевшу послугу від адреси вашого відправника до адреси покупця. В адресі мають бути вулиця, місто, провінція та поштовий індекс. До того часу використовується таблиця цін.

TCG locker: тариф у режимі реального часу — найдешевша послуга «від дверей до поштомата» до поштомата, найближчого до міста покупця. Він не перераховується для поштомата, який обрав покупець. Перевізник-поштомат з'являється лише для адрес у ПАР і лише за наявності ключа API.

Усе замовлення розраховується як одна посилка: загальна вага, найбільші довжина й ширина та сумарна висота. Товари без розмірів вважаються кубами 10 см. Вага й розміри переводяться з одиниць вашого магазину. Сума в рандах перераховується в основну валюту магазину, а потім показується у валюті кошика покупця.

Запити до ShipLogic припиняються через 12 секунд. Тарифи кешуються на 1 годину, поштомати на 6 годин, помилки на 10 хвилин, щоб повільний API не сповільнював кожне оновлення оформлення замовлення. Якщо тарифу в режимі реального часу немає, ціна береться з таблиці, потім із Fallback cost. Якщо жодне з цього не застосовується, перевізник приховується. Помилки API ніколи не показуються покупцеві.

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

Модуль не оформлює відправлення, не створює накладних чи етикеток і не оновлює відстеження автоматично. Карти поштоматів немає: поштомати обираються зі списку. Тарифи в режимі реального часу та поштомати — лише для ПАР. Для інших країн використовується таблиця цін. Для кожного перевізника показується лише один тариф (найдешевший рівень послуги), без вибору рівнів послуги, страхування чи додаткових опцій під час оформлення.

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

Коли покупець обирає перевізника-поштомат, під ним з'являється селектор поштоматів. Він показує поштомати, які ShipLogic повертає для міста адреси доставки, спочатку найближчі. Покупець може ввести інше місто, район або поштовий індекс і натиснути Search. Поштомат треба обрати, перш ніж покупець зможе продовжити: інакше на кроці доставки з'явиться повідомлення Please choose a The Courier Guy locker.

Поштомат повторно перевіряється на сервері за списком ShipLogic, зокрема під час оформлення замовлення. Його назва та постачальник беруться з ShipLogic, ніколи з браузера. Вибір зберігається для кошика і скидається, коли змінюється адреса доставки.

Якщо ShipLogic недоступний, селектор повідомляє, що поштомати не вдалося завантажити і що магазин зв'яжеться з покупцем щодо поштомата. Замовлення тоді можна оформити без поштомата. Його позначають на сторінці замовлення в адмін-панелі: Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.

Замовлення

Обраний поштомат (назва, ID та постачальник) зберігається разом із замовленням. Він показується в блоці The Courier Guy на сторінці замовлення в адмін-панелі, на сторінці підтвердження замовлення, у деталях замовлення покупця та в листі з підтвердженням замовлення. Лист магазину про нове замовлення (модуль Mail alerts) також показує ID поштомата або повідомляє, що поштомат не обрано, бо ShipLogic був недоступний.

Номер відстеження The Courier Guy: оформіть посилку в особистому кабінеті The Courier Guy і вкажіть референс як номер відстеження відправлення в блоці Shipping замовлення (Edit). Блок The Courier Guy його показує. Покупець бачить його в деталях замовлення та отримує лист PrestaShop «у дорозі».

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

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

Без активного ключа жоден із перевізників The Courier Guy (courier to the door або TCG locker) не показується покупцям під час оформлення замовлення, і тариф не розраховується. Вітрина PrestaShop не знає, що ви ввійшли в back office, тому перевізники приховані й для вас: модуль можна налаштувати до купівлі ключа, але перевірити його під час оформлення замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються.

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

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

The Courier Guy не з'являється під час оформлення замовлення: перевірте, чи активна ліцензія і чи увімкнено перевізника (Courier to the door або TCG locker). У Shipping > Carriers перевірте, чи перевізник охоплює зону країни покупця та групу покупця (або чи увімкнено Ignore shipping zones і чи дозволена країна). Перевірте обмеження ваги та Minimum order amount. Переконайтеся, що в таблиці або в Fallback cost є ціна. Перевізник-поштомат з'являється лише для адрес у ПАР і за наявності ключа API. Крім того, на сторінці товару товари можуть бути обмежені певними перевізниками.

Покупці не бачать списку поштоматів: для поштоматів потрібні ключ API, увімкнений перевізник TCG locker і адреса доставки в ПАР. На сторінці налаштувань показано останню помилку ShipLogic, якщо вона є, наприклад відхилений ключ.

Ціна завжди з таблиці: перевірте попередження на сторінці налаштувань. Тариф у режимі реального часу потребує ключ API, повну адресу відправника і, для магазинів не в рандах, курс ZAR. Для доставки кур'єром адреса покупця має містити вулицю, місто, провінцію та поштовий індекс: додайте провінції ПАР у розділі Advanced. Для поштоматів ShipLogic має знайти поштомат поблизу міста покупця. Увімкніть Debug log, перезавантажте оформлення замовлення і перегляньте поле Log на сторінці модуля.

ShipLogic недоступний: показується ціна з таблиці або резервна вартість. Замовлення з поштоматом можна оформити без поштомата, і вони позначаються в замовленні.

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

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

Видалення

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

The Courier Guy та ShipLogic є торговельними марками їхніх власників. Цей модуль не пов'язаний із The Courier Guy чи ShipLogic і не схвалений ними.