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

Вимоги

PrestaShop: 8.0–9.x.

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

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

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

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

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

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

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

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

Під час встановлення модуль створює перевізника DHL Express з текстом строку доставки DHL Express courier. Перевізник призначається всім зонам і всім групам клієнтів. Зони, групи клієнтів, строк доставки, логотип і обмеження розміру можна змінити в Shipping > Carriers. Ціни там не задавайте: ціна завжди береться з модуля.

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

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox DHL Africa > Configure. Вони застосовуються до всіх зон перевізника. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищає кеш котирувань DHL. Ціни та ваги приймають десятковий кому або крапку.

Попередження вгорі сторінки повідомляють, коли актуальні тарифи вимкнено через відсутність API key, API secret або номера облікового запису (або, для XML Services, Site ID чи пароля), коли не вказано країну або місто відправлення, коли вибрано XML Services (DHL їх припиняє), коли вказано валюту котирування без обмінного курсу, і коли одиниця ваги або розміру магазину в International > Localization (Local units) невідома модулю (тоді використовуються кг або см). Якщо значення під час збереження недійсне (порожня назва або довша за 64 символи, некоректне чи від'ємне число, обмінний курс 0, мінімальна вага більша за максимальну, валюта котирування, країна відправлення або податкове правило), помилка вказує на поле, попереднє значення цього поля зберігається, а інші параметри зберігаються.

Загальні

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

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

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

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

DHL API: який інтерфейс DHL використовується. Показуються лише поля обраного API.

MyDHL API (REST) — recommended: актуальний API DHL Express. DHL видає новим клієнтам лише облікові дані MyDHL API.

XML Services (legacy): лише якщо у вас ще є чинний XML Site ID. DHL припиняє XML Services.

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: показується, лише коли збережено ключ або секрет. Увімкніть і натисніть 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. Увімкнено за замовчуванням. Тестові дані працюють лише в тестовому середовищі, робочі — лише в робочому. Вимкніть його, коли переходите на робочий режим.

Ship from

Адреса, з якої DHL забирає посилки. Від неї залежить тариф.

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

Origin city: місто, з якого ви відправляєте, наприклад Йоганнесбург. 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: приховує перевізника, якщо вага кошика нижча за це значення, в кг. 0 означає без обмеження. Не може бути більшим за Maximum weight.

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

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

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

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

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

Додатково

Debug log: записує розрахунки тарифів у logs/vfd_dhla_debug.log.php у папці модуля. Файл не можна відкрити з вебу. Помилки DHL завжди записуються, навіть коли цей параметр вимкнено. Облікові дані та адреси клієнтів ніколи не записуються.

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

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

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

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

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

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

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

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

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

Замовлення

Коли замовлення оформлено, модуль зберігає тариф, розрахований для його кошика. Сторінка замовлення в бек-офісі тоді показує блок 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): ціна у валюті за замовчуванням для вашого магазину.

Пізніші перерахунки кошика, наприклад коли замовлення редагується в бек-офісі, не змінюють ці значення. Тарифи кошиків, які так і не стали замовленнями, видаляються через 30 днів.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox DHL Africa — перший блок на сторінці Modules > Module Manager > VibeFox DHL Africa > Configure, над налаштуваннями. Введіть ключ у License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа і Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: presta-shipping-dhl-africa і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з правом Configure для модуля. Тексти блоку відповідають мові бек-офісу (включено англійську та російську).

Якщо ключ не прийнято, блок вказує причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on з датою. Після зміни адреси магазину або після звільнення слота домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, модуль продовжує працювати з останнім відомим статусом.

Один ключ працює на одному домені: домені основного магазину, також у мультимагазинній конфігурації. Видалення ключа з магазину не звільняє слот домену. Звільніть слот в обліковому записі vibefox.net.

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

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

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

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

Актуальні тарифи не з'являються: перевірте попередження вгорі сторінки модуля (відсутні облікові дані або відправлення). Увімкніть 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, щоб тариф DHL брався без ПДВ DHL, або виберіть No tax, щоб стягувати суму DHL так, як вона котирується.

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

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

Для розробників модуль надає хуки actionVfdDhlaApiUrl, actionVfdDhlaIsDutiable, actionVfdDhlaPackageBox, actionVfdDhlaRestRequest і actionVfdDhlaXmlRequest для зміни адреси API, митної декларації, коробки та запитів до DHL.

Видалення

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

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