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

Вимоги

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

PHP: 8.0 або новіша версія з розширенням cURL. Для DHL XML Services також потрібне розширення PHP SimpleXML.

Обліковий запис DHL Express (лише для тарифів у реальному часі): тарифи в реальному часі використовують MyDHL API. Вам потрібні номер облікового запису DHL Express і облікові дані MyDHL API: API key та API secret. Отримайте їх на порталі розробників DHL (MyDHL API, "Get access") або у свого менеджера облікового запису DHL Express. Облікові записи, які ще мають облікові дані DHL XML Services (Site ID і пароль), можуть використовувати їх замість них. Якщо ви використовуєте лише резервні ціни, облікові дані DHL не потрібні.

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

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

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

OpenCart 3

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

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

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

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

5. Виберіть API DHL, введіть API key, API secret і номер вашого облікового запису DHL. Залиште Test mode увімкненим, поки використовуєте тестові облікові дані. Введіть адресу Ship from. Якщо ваш обліковий запис DHL не виставляється в базовій валюті магазину, задайте DHL quote currency та Exchange rate. За бажанням задайте ціни за країнами та резервну вартість (див. Configuration). Увімкніть Enable DHL Express Africa і натисніть Save.

OpenCart 4

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

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

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

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

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

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

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

Попередження у верхній частині сторінки повідомляють, коли тарифи в реальному часі вимкнено через відсутність API key, API secret або номера облікового запису (або, у разі XML Services, Site ID чи пароля), коли не вказано країну або місто відправлення, коли вибрано XML Services (DHL їх виводить з експлуатації), коли задано валюту котирування без курсу обміну, а також коли розширення не знає одиницю ваги чи довжини магазину (тоді ваги товарів читаються як кг, а розміри — як см; додайте клас ваги з одиницею kg у System > Localisation > Weight Classes або клас довжини з одиницею cm у System > Localisation > Length Classes).

Якщо значення під час збереження недійсне (порожня назва способу або назва довша за 64 символи, некоректне чи від'ємне число, курс обміну 0, мінімальна вага більша за максимальну, невідома валюта котирування, країна відправлення, клас податку чи географічна зона, порядок сортування, який не є цілим числом), попередження над налаштуваннями вказує поле, наприклад Select a valid origin country. It was not saved. Попереднє значення цього поля зберігається, а інші налаштування зберігаються.

Загальні

Enable DHL Express Africa: показує або приховує DHL Express під час оформлення замовлення. За замовчуванням: off.

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

Tax class: клас податку для вартості доставки або No tax (за замовчуванням). З класом податку (і увімкненими в магазині податками) тариф DHL береться без податку, який вказав DHL, а OpenCart додає власний податок. З No tax тариф DHL стягується так, як його котирували, з податком у складі.

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

Обліковий запис DHL Express (потрібен лише для тарифів у реальному часі)

DHL API: який інтерфейс DHL використовується.

API key: ваше ім'я користувача MyDHL API (API key).

API secret: ваш пароль MyDHL API (API secret). Після збереження поля API key і API secret залишаються порожніми та показують Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Remove the saved API key and API secret: показується лише для MyDHL API, коли збережено ключ або secret. Увімкніть і натисніть Save, щоб видалити обидва.

XML Site ID: ваш Site ID DHL XML Services (лише для застарілого API). Очищення також видаляє збережений XML-пароль.

XML password: ваш пароль DHL XML Services (лише для застарілого API). Як і API secret, після збереження його більше не показують.

DHL account number: ваш номер облікового запису DHL Express (9 цифр). Його вимагає MyDHL API. З XML Services він повертає тарифи вашого облікового запису замість опублікованих тарифів.

Test mode: використовувати тестове середовище DHL. Увімкнено за замовчуванням. Тестові облікові дані працюють лише в тестовому середовищі, а робочі — лише в робочому. Вимкніть, коли переходите до роботи з реальними замовленнями.

Адреса відправлення

Адреса, з якої DHL забирає посилки. Тариф залежить від неї. OpenCart зберігає адресу магазину як вільний текст, тож місце відправлення завжди вказується тут. Примітка в цьому розділі показує країну вашого магазину.

Origin country: країна, з якої ви відправляєте.

Origin city: місто, з якого ви відправляєте, наприклад Johannesburg. Його вимагає MyDHL API.

Origin postcode: залиште порожнім для країн без поштових індексів (наприклад Кенія, Нігерія, Гана).

Тарифи

Усі ціни вказані в базовій валюті магазину, без податку. Тариф у реальному часі — це найдешевший продукт DHL Express для посилки. Якщо DHL не налаштовано, повертає помилку або не має сервісу для маршруту, використовується ціна для країни, а потім резервна вартість. Якщо немає ні того, ні іншого, спосіб доставки приховується.

DHL quote currency: DHL видає котирування у валюті країни вашого облікового запису DHL (наприклад ZAR, NGN або KES). Якщо DHL не повертає суму в базовій валюті вашого магазину, тариф у реальному часі конвертується з цієї валюти за курсом нижче. Інакше він не використовується. За замовчуванням: — None —.

Exchange rate: скільки коштує 1 одиниця валюти котирування DHL у базовій валюті вашого магазину, наприклад 1 ZAR = 0.05. Значення має бути більшим за 0. Залиште порожнім, якщо конвертація не потрібна. Курс задається вручну.

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

Country prices: резервна ціна для кожної країни призначення, по одній на рядок: CC:Price, наприклад ZA:25.00. Використовується, коли немає тарифу в реальному часі. Рядки в іншому форматі ігноруються, а попередження під час збереження їх перелічує.

Fallback price basis: Per order (за замовчуванням) стягує ціну один раз. Per item (multiplied by the cart quantity) множить її на кількість товарів. Застосовується лише до ціни для країни та резервної вартості. Тариф DHL у реальному часі завжди стосується всієї посилки.

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

Умови

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

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

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

Доступність

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

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

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

Додатково

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

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

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

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

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

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

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

Коли OpenCart показує способи доставки, він запитує у розширення ціну DHL Express. Якщо задано Geo zone (і Ignore shipping zones вимкнено) та адреса знаходиться поза нею, DHL Express не пропонується. Враховуються лише товари з Requires Shipping, встановленим на Yes: інші товари не додають ваги і не входять до суми замовлення. Далі розширення перевіряє умови: країни з Ignore shipping zones, вагу кошика та мінімальну суму замовлення. Сума замовлення — це ціна товарів, які потребують доставки, після знижки за купоном і без податку. Подарункові сертифікати, бонусні бали та кредит магазину не враховуються. Якщо діє безкоштовна доставка, ціна дорівнює 0 і запит до DHL не надсилається.

В інших випадках розширення передає DHL відправлення та призначення (країна, місто, поштовий індекс), вагу кошика, переведену в кг з класів ваги товарів (щонайменше 0,5 кг), і одну коробку, складену за розмірами товарів у см: найбільша довжина, найбільша ширина та сума висот у стопці. Товари без розмірів нічого не додають. Якщо жоден товар не має розмірів, використовується коробка 10 x 10 x 10 см. Відправлення в іншу країну декларуються митниці, а задекларованою вартістю є сума кошика. Внутрішні відправлення не декларуються. Дата забору — сьогодні за часовим поясом магазину, а у вихідні — понеділок. Тариф у реальному часі запитується лише після того, як покупець указав місто (для XML Services — місто або поштовий індекс). До того діють резервні ціни.

Найдешевший продукт DHL Express показується однією ціною з назвою вашого способу доставки. Покупець не бачить продукту DHL. Ціна розраховується в базовій валюті, округлюється до її десяткових знаків і показується покупцеві у його валюті з податком обраного Tax class.

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

Розширення лише розраховує тарифи. Воно не створює відправлень DHL, не друкує етикетки та комерційні інвойси, не замовляє кур'єрів, не відстежує посилки, не пропонує пункти обслуговування DHL, не дає покупцеві вибирати між продуктами DHL, не пакує кілька коробок, не додає страхування та не розраховує мита і податки. Котирування стосується лише доставки. Мита та імпортні податки сплачує одержувач.

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

Замовлення

Коли замовлення оформлено, розширення зберігає тариф, розрахований для його кошика. Відкрийте замовлення в Sales > Orders: панель DHL Express Africa над історією замовлення показує, що потрібно забронювати в DHL:

DHL product: продукт DHL Express з тарифу в реальному часі, наприклад "EXPRESS WORLDWIDE (P)". Показується лише для тарифів у реальному часі.

Price source: Live DHL rate, Fallback price (no live rate) або Free shipping threshold.

Calculated price (excl. tax): ціна в базовій валюті вашого магазину.

Продукт DHL не показується покупцеві в листах або на його сторінці замовлення. У замовленні відображаються назва способу доставки та вартість доставки, як для будь-якого іншого способу доставки OpenCart.

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

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

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox DHL Africa є першим блоком на сторінці Extensions > Extensions > Shipping > VibeFox DHL Africa > Edit, над налаштуваннями. Вставте ключ у поле License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) і кнопки: Check now для повторної перевірки статусу, Change key, щоб ввести інший ключ, і Remove key, щоб прибрати ключ із цього магазину. Нижче розташовані рядок Product: opencart-shipping-dhl-africa та посилання 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 Express не показується покупцям під час оформлення замовлення, і тариф не розраховується. Адміністратор, який увійшов в адмінпанель у тому самому браузері, усе ще бачить спосіб доставки в магазині, позначений як (unlicensed — visible to admins only), тож ви можете налаштувати й протестувати розширення до покупки ключа. На OpenCart 4 цей попередній перегляд недоступний: магазин не бачить входу адміністратора, тому без активного ключа спосіб доставки приховано для всіх. Після того як ви один раз відкрили сторінку Edit, на Dashboard адмінпанелі з'являється нагадування. Закрийте його кнопкою ×, щоб приховати на 7 днів. Наявні замовлення не змінюються.

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

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

DHL Express не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і Enable DHL Express Africa увімкнено. Перевірте Geo zone (або увімкніть Ignore shipping zones і перевірте Countries), обмеження ваги та Minimum subtotal. Без тарифу в реальному часі спосіб доставки з'являється, лише якщо задано ціну для країни або резервну вартість. Перевірте, що товари мають Requires Shipping, встановлений на Yes.

Тарифи в реальному часі не з'являються: перевірте попередження у верхній частині сторінки розширення (відсутні облікові дані або місце відправлення). Увімкніть Debug log, перезавантажте оформлення замовлення і перегляньте поле Log на сторінці розширення. Помилки DHL, як-от HTTP-помилка MyDHL API, відсутність продуктів для маршруту або проблема з валютою, завжди записуються в журнал. Перевірте, що Test mode відповідає вашим обліковим даним, і що в адресі покупця є місто.

DHL повертає тариф у ZAR, NGN або KES, але мій магазин використовує іншу валюту: у журналі вказано DHL quote not usable. Встановіть DHL quote currency у цю валюту та введіть Exchange rate. Без цього тариф у реальному часі не використовується, і діють резервні ціни.

У мене старі облікові дані DHL XML Services: оберіть XML Services (legacy) у DHL API. Перейдіть на MyDHL API, коли отримаєте облікові дані MyDHL.

Податок на доставку стягується двічі: задайте Tax class, щоб тариф DHL брався без податку DHL, або оберіть No tax, щоб стягувати суму DHL так, як її котирували.

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

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

Для розробників: розширення викликає події OpenCart catalog/vfd_dhl_africa/api_url, is_dutiable, package_box, rest_request та xml_request (з тим самим префіксом), які можуть змінювати адресу API, митну декларацію, коробку та запити до DHL.

Видалення

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

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

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