VibeFox DHL Packstation for OpenCart — Допомога

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіша версія (перевірено на 4.1.0.3). Вибір пункту видачі працює зі стандартним оформленням замовлення OpenCart.

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

DHL API key: список пунктів надходить із безкоштовного API DHL Location Finder. Зареєструйтеся на порталі розробників DHL (developer.dhl.com), створіть застосунок, додайте API «Location Finder - Unified» і скопіюйте API-ключ застосунку. Для цього API не потрібен діловий договір із DHL. Без ключа спосіб доставки приховано під час оформлення замовлення. Враховуйте ліміт запитів вашого застосунку DHL: кожен новий пошук за поштовим індексом або містом — це один запит до API.

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

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

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

OpenCart 3

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

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

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

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

5. Вставте DHL API key, натисніть Save, потім натисніть Test API key. Виберіть типи пунктів видачі та введіть ціни за країнами (див. Configuration). Увімкніть Enable/Disable і натисніть Save.

OpenCart 4

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

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

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

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

Після встановлення спосіб доставки вимкнено, доки ви не увімкнете Enable/Disable і не збережете налаштування. У прайсі за замовчуванням є ціни для Німеччини та Австрії й ціна для інших країн. Якщо ви встановлюєте розширення повторно після видалення, знову використовуються збережені налаштування.

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

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Shipping > VibeFox DHL Packstation > Edit. Розділи перелічено зліва. Одна кнопка Save зберігає всю сторінку без перезавантаження. Кожне збереження очищає кеш пунктів. Якщо поле містить помилку (некоректна назва або назва довша за 64 символи, радіус чи кількість результатів, що не є цілим числом, некоректне або від'ємне число, Min weight (kg) більше за Max weight (kg), порядок сортування, що не є цілим числом, невідомий податковий клас чи географічна зона), нічого не зберігається і показується помилка. Зберігати налаштування можуть лише адміністратори з правом змінювати це розширення.

Попередження у верхній частині сторінки повідомляють, коли API-ключ DHL порожній, коли не увімкнено жодного типу пунктів видачі (в обох випадках спосіб доставки не показується під час оформлення), коли записи цін за країнами не у форматі CC:PRICE (ці записи ігноруються), і коли немає класу ваги з одиницею kg у System > Localisation > Weight Classes (ваги товарів тоді читаються за назвою одиниці їхнього класу: kg, g, lb або oz; невідомі одиниці вважаються кілограмами).

Загальні

Налаштування застосовуються до всіх географічних зон.

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

Name: назва способу доставки, яку бачить покупець. За замовчуванням: DHL Packstation. Обов'язкове поле, не більше 64 символів, без символів < > ; = # { }.

Tax Class: податковий клас вартості доставки або --- None --- (за замовчуванням). OpenCart додає цей податок до цін нижче. За --- None --- ціни остаточні.

Sort Order: позиція DHL Packstation серед способів доставки. Ціле число.

DHL Location Finder API

DHL API key: «API Key» вашого застосунку на developer.dhl.com. Без нього спосіб доставки приховано під час оформлення замовлення. Після збереження поле залишається порожнім і показує Saved - leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

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

Connection test: кнопка Test API key шукає пункти поблизу 53113 Bonn зі збереженим ключем і очищає кеш пунктів. Спочатку збережіть налаштування. Вона показує, скільки пунктів знайдено (Connected: … DHL locations found near 53113 Bonn.), що DHL відхилив ключ (401/403), або що API відповів некоректно (деталі в журналі налагодження).

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

Під час оформлення замовлення покупець бачить пункти поблизу поштового індексу доставки і може шукати інший поштовий індекс або місто.

Location types: які пункти DHL може обрати покупець: Packstation (parcel locker), Post Office (Postfiliale) і DHL Parcel Shop (Paketshop). За замовчуванням увімкнено всі три. Якщо не вибрано жодного, спосіб доставки приховується. Для Packstation покупець має ввести свій DHL Postnummer.

Search radius (meters): радіус навколо шуканого поштового індексу або міста. За замовчуванням: 5000. Ціле число; значення менше 100 або більше 25000 м (максимум DHL) встановлюються на цій межі.

Max results: максимальна кількість пунктів, що показуються за один пошук. За замовчуванням: 20. Ціле число; DHL дозволяє до 50, більші значення зменшуються до 50.

Shipping address: використовувати обраний пункт як адресу доставки замовлення. Увімкнено за замовчуванням. Рядок адреси 1 стає, наприклад, «Packstation 105» (або «Postfiliale 502» для поштового відділення чи DHL Parcel Shop), рядок 2 — «Postnummer» з номером, а також поштовий індекс, місто й країна пункту, щоб етикетки, надруковані із замовлення, потрапляли за правильною адресою. Ім'я, компанія і телефон беруться з адреси покупця. Регіон очищується. Адресна книга покупця не змінюється.

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

Country prices: ціна для кожної країни призначення в базовій валюті магазину, без податку, у форматі CC:PRICE, через кому або з нового рядка. За замовчуванням: DE:4.99, AT:5.99. Десятковий кома також працює (DE:4,99).

Other countries: ціна для країни призначення, якої немає в Country prices. За замовчуванням: 5.99. Залиште порожнім, щоб приховати спосіб доставки для таких країн.

Calculation: Per order (за замовчуванням) стягує ціну один раз. Per item (price x quantity) множить її на кількість товарів у кошику.

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

Доступність

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

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

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

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

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

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

Додатково

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

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

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

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

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

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

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

Коли OpenCart показує способи доставки, він запитує у розширення ціну DHL Packstation. Якщо задано Geo Zone (і Ignore shipping zones вимкнено) та адреса знаходиться поза нею, спосіб доставки не пропонується. Враховуються лише товари з Requires Shipping, встановленим на Yes: інші товари не додають ваги і не входять до суми замовлення. Розширення перевіряє, що задано API-ключ і принаймні один тип пунктів, дозволені країни (з Ignore shipping zones), вагу кошика та мінімальну суму замовлення. Далі воно бере ціну для країни призначення (або ціну для інших країн) і застосовує безкоштовну доставку, якщо сума замовлення достатня. Сума замовлення — це ціна товарів, що потребують доставки, після знижки за купоном і без податку. Ціна не залежить від пункту видачі, і для її розрахунку запит до DHL не надсилається. Вона розраховується в базовій валюті та показується покупцеві у його валюті з податком обраного Tax Class.

Розширення не створює відправлень DHL, не друкує етикетки та не відстежує посилки. Скористайтеся діловим порталом клієнтів DHL або інструментом для етикеток: за увімкненої опції Shipping address замовлення вже містить адресу Packstation і Postnummer. Розширення не розраховує тарифи DHL у реальному часі й не показує карту. Ручного введення номера Packstation немає.

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

Коли покупець обирає DHL Packstation на кроці способу доставки, під способом з'являється вибір пункту. Завантажуються пункти DHL поблизу поштового індексу та міста доставки. Покупець може ввести інший поштовий індекс або місто і натиснути Search. Пункти групуються за типом (Packstation, Post Office, Parcel Shop) і сортуються за відстанню. Якщо нічого не знайдено, покупець бачить No DHL locations found near "…". Try another postcode or city.

Для Packstation покупець має ввести DHL Postnummer — свій номер клієнта DHL з 6–12 цифр, з застосунку DHL або облікового запису DHL. Для інших пунктів він необов'язковий. Вибір зберігається одразу після того, як його зроблено. Після натискання Continue сервер перевіряє його знову: пункт має бути серед результатів пошуку DHL у країні доставки. Без пункту покупець бачить Please choose a DHL Packstation or post office for delivery. і не може продовжити. Якщо Postnummer для Packstation не введено, показується Please enter your DHL Postnummer - it is required for delivery to a Packstation., а якщо він некоректний — The DHL Postnummer must consist of 6 to 12 digits.

Результати пошуку кешуються на 12 годин. Порожній або невдалий пошук кешується на 10 хвилин, щоб оформлення замовлення не чекало DHL під час кожного оновлення. За стандартного файлового кешу OpenCart записи живуть не довше за термін кешу магазину (за замовчуванням 1 година), тож список оновлюється раз на годину. Тайм-аут API — 12 секунд. Якщо API DHL недоступний, покупець бачить DHL locations cannot be loaded right now. Please try again later or choose another shipping method. Пункт, який покупець уже обрав, все одно приймається.

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

Коли замовлення оформлено, пункт (ID, тип, номер, назва, адреса) і Postnummer зберігаються разом із замовленням. Пункт додається до способу доставки замовлення як DHL pickup location: і DHL Postnummer:, тож з'являється всюди, де OpenCart показує спосіб доставки: на сторінці замовлення покупця, у листах про замовлення та в рахунку. Якщо Shipping address увімкнено, адреса доставки замовлення замінюється адресою пункту.

OpenCart 4 зберігає одне замовлення для оформлення і оновлює його щоразу, коли покупець підтверджує вибір знову. Разом із ним оновлюються пункт, текст способу доставки та адреса замовлення.

Замовлення

Відкрийте замовлення в Sales > Orders. Панель DHL pickup location над історією замовлення показує пункт, його тип і ID, а також Postnummer, навіть після вимкнення розширення. Замовлення без пункту показує No DHL location was selected for this order.

Натисніть Change, шукайте за поштовим індексом або містом, оберіть інший пункт зі списку DHL, за потреби змініть Postnummer і натисніть Save location. Можна змінити й лише Postnummer. Текст способу доставки замовлення оновлюється. Якщо Shipping address увімкнено, адреса доставки замовлення також оновлюється, знову виходячи з первинної адреси покупця. Кожна зміна додає до історії замовлення запис DHL pickup location changed to: … з поточним статусом замовлення і без сповіщення покупця. Для зміни пункту потрібне право змінювати замовлення; доступ до налаштувань розширення не потрібен.

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

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

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

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

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

DHL Packstation не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable/Disable увімкнено. Перевірте Geo Zone (або увімкніть Ignore shipping zones і перевірте Countries (ignore zones)). Перевірте, що поле DHL API key заповнене, обрано принаймні один тип пунктів, для країни призначення є ціна (або задано Other countries), і що правила ваги та суми замовлення не приховують спосіб. Перевірте, що товари мають Requires Shipping, встановлений на Yes.

Пункти не відображаються: натисніть Test API key. Якщо DHL відхиляє ключ (401/403), перевірте ключ і те, що ваш застосунок має API «Location Finder - Unified». Увімкніть Debug log, перезавантажте оформлення замовлення і перегляньте поле Log на сторінці розширення. Перевірте, що ліміт запитів вашого застосунку DHL не вичерпано.

Немає пунктів поблизу адреси: збільште Search radius (meters) або Max results, або дозвольте покупцеві шукати інший поштовий індекс чи місто. Packstation без номера в даних DHL не показується.

Покупець бачить "Enter your postcode or city to see DHL locations near you.": в адресі доставки немає ні поштового індексу, ні міста. Покупець може ввести один із них у полі пошуку.

Change на сторінці замовлення в адмінпанелі показує "Please choose a DHL location of the search - nothing was changed.": знайдіть за поштовим індексом або містом і оберіть пункт із результатів. Якщо в замовлення ще немає пункту, його треба обрати до збереження Postnummer.

Панель DHL pickup location відсутня на сторінці замовлення: панель показується лише для замовлень, відправлених через DHL Packstation (вона залишається, навіть якщо розширення вимкнено).

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

Видалення

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

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

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