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

Вимоги

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

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

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

Доставка до Південної Африки: актуальні тарифи та локери доступні лише для адрес у Південній Африці. Південна Африка має бути увімкненою країною магазину (System > Localisation > Countries), а для актуального тарифу кур'єра потрібні південноафриканські провінції (зони), які вже є в OpenCart 3.

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

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

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

OpenCart 3

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

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

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

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

5. Увімкніть Courier to the door та/або TCG locker і введіть API key ShipLogic. Для актуальних тарифів заповніть адресу відправника (вулиця, місто, провінція, поштовий індекс) і, якщо валюта вашого магазину не ZAR, ZAR conversion rate.

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

OpenCart 4

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

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

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

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

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

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

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

Якщо назва варіанта, податковий клас, порядок сортування або геозона некоректні, нічого не зберігається, і сторінка показує причину, наприклад Enter a valid option name (1-64 characters, without < > ; = # { }). Некоректне число (наприклад, від'ємне) не зберігається: сторінка називає поле й залишає попереднє значення, решта зберігається. Поки увімкнено хоча б один варіант, попередження у верхній частині сторінки повідомляють, якщо Південна Африка не є увімкненою країною, відсутній ключ API, курс ZAR або адреса відправника, немає ні таблиці цін, ні резервної вартості, у Південної Африки немає зон (провінцій) або останній запит до ShipLogic завершився помилкою (з датою та текстом помилки). Попередження також з'являється, якщо в магазині немає вагової одиниці kg або одиниці довжини cm.

Загальні

Кожен тип доставки — окремий варіант на етапі оформлення замовлення.

Courier to the door: пропонує кур'єрську доставку The Courier Guy на адресу покупця. За замовчуванням: вимкнено.

Courier option name: назва варіанта кур'єра на етапі оформлення замовлення. За замовчуванням: The Courier Guy. Обов'язкове поле, не більше 64 символів, без < > ; = # { }.

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

Locker option name: назва варіанта з локером на етапі оформлення замовлення. За замовчуванням: The Courier Guy locker. Ті самі правила, що й для назви кур'єра.

Tax status: податковий клас обох варіантів. За наявності податкового класу актуальні тарифи беруться без ПДВ, а OpenCart додає податок цього класу. None (live rates including VAT) (за замовчуванням): актуальні тарифи беруться з ПДВ.

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

API ShipLogic

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

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

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

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

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

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

Адреса відправника (звідки The Courier Guy забирає посилки в Південній Африці)

Адреса магазину в OpenCart — це вільний текст, тому адреса відправника вводиться тут. Вулиця, місто, провінція та поштовий індекс потрібні для актуальних тарифів.

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

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

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

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

Sender province: оберіть одну з 9 південноафриканських провінцій зі списку.

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 для тарифу не надсилається.

Доступність

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

Ignore shipping zones: для типу доставки, вказаного нижче, геозона не перевіряється. Натомість варіант пропонується в країнах, перелічених нижче.

Delivery type without zones: Courier to the door (за замовчуванням) або TCG locker (customer chooses a locker). Використовується лише з Ignore shipping zones. Інший тип і далі підпорядковується Geo zone.

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

Додатково

Debug log: записує повідомлення налагодження у storage/logs/vfd_tcgr_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, списку країн). Враховуються лише товари з Requires Shipping, встановленим на Yes: інші товари не додають ваги й не входять до суми замовлення. Далі розширення перевіряє умови: вагу кошика та мінімальну суму замовлення. Сума замовлення — це ціна товарів, що потребують доставки, до податків і після знижки за купоном. Якщо діє безкоштовна доставка, ціна дорівнює 0.

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

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

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

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

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

В OpenCart 4 покупець натискає Choose у блоці способу доставки на сторінці оформлення замовлення і вибирає варіант кур'єра або локера у вікні Shipping method options. Спосіб працює так само, як в OpenCart 3.

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

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

Локер перевіряється на сервері за списком ShipLogic, коли покупець продовжує оформлення, і знову при розміщенні замовлення. Його назва та провайдер беруться з ShipLogic, а не з браузера. Вибір прив'язаний до країни та міста або поштового індексу адреси: якщо адреса доставки змінюється, покупець обирає локер заново.

Якщо ShipLogic недоступний, вибір локера показує повідомлення Lockers cannot be loaded right now. You can place the order without choosing one - the store will contact you about the locker. Тоді замовлення можна оформити без локера. На сторінці замовлення в адмінпанелі воно позначається: Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.

В OpenCart 4 вибір локера з'являється у вікні Shipping method options, під варіантом з локером, і завантажується заново щоразу, коли вікно відкривається, оскільки адреса на одноетапному оформленні може змінитися. Кнопка Continue вікна не продовжує без локера зі списку, з тим самим повідомленням, і недоступний ShipLogic також не блокує замовлення. OpenCart 4 зберігає одне замовлення для оформлення і оновлює його щоразу, коли покупець підтверджує знову, а локер замовлення оновлюється разом із ним.

Замовлення

Обраний локер додається до способу доставки замовлення, наприклад: «The Courier Guy locker: назва — адреса». Цей текст з'являється в Sales > Orders, на сторінці замовлення покупця, у рахунку та в листах про замовлення.

На сторінці замовлення в Sales > Orders над історією є панель The Courier Guy для кожного замовлення, відправленого через The Courier Guy. Для замовлення з локером вона показує назву, ID і провайдера локера, з not verified (ShipLogic was unavailable at checkout), якщо локер не вдалося перевірити, або повідомлення Not chosen, якщо ShipLogic був недоступний. Панель відображається, навіть коли розширення вимкнене.

The Courier Guy tracking reference: оформіть посилку в порталі The Courier Guy, внесіть її номер у це поле панелі та натисніть Save. Щоб видалити номер, очистіть поле і збережіть. Адміністратори без права змінювати замовлення бачать номер лише для читання. Покупець бачить номер на сторінці замовлення у своєму обліковому записі (зареєстровані покупці) та в листах про статус замовлення, коли ви повідомляєте покупця. У листі про нове замовлення номера немає, бо його вносять пізніше.

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

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

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

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

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

The Courier Guy does not appear at checkout: перевірте, що ліцензія активна і варіант увімкнено (Courier to the door або TCG locker). Перевірте Geo zone (або Ignore shipping zones та Countries), обмеження ваги та Minimum order amount. Переконайтеся, що в таблиці або в Fallback cost є ціна. Переконайтеся, що у товарів Requires Shipping встановлено Yes. Варіант із локером з'являється лише для адрес у Південній Африці і за наявності ключа API.

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

The price is always the table price: перегляньте попередження на сторінці налаштувань. Актуальний тариф потребує ключа API, повної адреси відправника і, для магазинів не в рандах, курсу ZAR. Для кур'єрської доставки адреса покупця має містити вулицю, місто, провінцію (зону) і поштовий індекс. Для локерів ShipLogic має знайти локер поблизу міста покупця. Увімкніть Debug log, перезавантажте оформлення замовлення і перегляньте поле Log на сторінці розширення.

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

Rates look outdated after a change: натисніть Save на сторінці розширення. Це очистить кешовані тарифи та локери.

The page says "Warning: You do not have permission to modify VibeFox The Courier Guy!": ваша група адміністраторів може лише переглядати налаштування. Надайте групі дозвіл на зміну для extension/shipping/vfd_the_courier_guy (OpenCart 3) або extension/vfd_the_courier_guy/shipping/vfd_the_courier_guy (OpenCart 4) у System > Users > User Groups.

For developers: адресу API ShipLogic можна замінити налаштуванням vfd_tcgr_api_url (для тестів); для нього немає поля на сторінці налаштувань.

Видалення

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

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

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