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

Вимоги

PrestaShop: від 8.0 до 9.x. Підтримуються теми Classic і Hummingbird.

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

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

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

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

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

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

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

4. Вставте API-ключ DHL, натисніть Save, а потім Test API key. Оберіть типи пунктів і введіть ціни за країнами (див. Налаштування).

Під час встановлення модуль створює перевізника DHL Packstation з текстом терміну доставки Delivery to a DHL Packstation or post office. Перевізник увімкнений, призначений усім групам клієнтів і зонам Німеччини та Австрії (країнам прайсу за замовчуванням). Зони, групи клієнтів, текст терміну доставки, логотип і обмеження розміру можна змінити в Shipping > Carriers. Ціни там не задавайте: ціна завжди береться з модуля.

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

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox DHL Packstation > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Якщо в полі помилка (некоректне або від'ємне число, Min weight (kg) більше за Max weight (kg), назва довша за 64 символи), нічого не зберігається, а помилка виводиться вгорі. Кожне збереження очищає кеш пунктів.

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

Загальні

Групи клієнтів, зони та обмеження розміру перевізника задаються в Shipping > Carriers. Наведені нижче параметри застосовуються до всіх зон.

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

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

Tax: податкове правило перевізника або No tax. PrestaShop додає цей податок до цін нижче. З No tax ціни остаточні.

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 збереженим ключем і очищає кеш пунктів. Спершу збережіть параметри. Вона показує, скільки пунктів знайдено, чи відхилила 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» для Post Office чи 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: показувати перевізника, лише якщо сума кошика (товари, що потребують доставки, після знижок, до податків) становить щонайменше це значення. Залиште порожнім, щоб показувати завжди.

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

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

Додатково

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

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

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

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

На етапі доставки PrestaShop запитує в модуля ціну DHL Packstation. Враховуються лише фізичні товари: віртуальні товари не додають ваги і не входять до суми кошика. Модуль перевіряє, чи задано API-ключ і принаймні один тип пункту, дозволені країни (за Ignore shipping zones), вагу кошика та мінімальну суму. Далі він бере ціну для країни призначення (або ціну для інших країн) і застосовує безкоштовну доставку, якщо сума достатньо висока. Ціна розраховується в основній валюті магазину й показується у валюті кошика покупця.

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

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

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

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

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

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

Під час оформлення замовлення пункт (ID, тип, номер, назва, адреса) і Postnummer зберігаються разом із замовленням. Якщо Shipping address увімкнено, адреса доставки замовлення замінюється адресою пункту. Пункт показується на сторінці підтвердження замовлення, у розділі Order history and details облікового запису покупця, а також у листі з підтвердженням замовлення та в листі про нове замовлення модуля Mail alerts; до назви перевізника при цьому додаються підписи DHL pickup location і DHL Postnummer.

На сторінці замовлення в бек-офісі блок DHL pickup location показує пункт, його тип і ID, а також Postnummer. Натисніть Change, знайдіть пункт за індексом або містом, оберіть інший пункт, змініть Postnummer і натисніть Save location. Можна змінити й лише Postnummer. Кожна зміна додає до замовлення приватне повідомлення DHL pickup location changed to: …. Якщо Shipping address увімкнено, адреса доставки замовлення також оновлюється. Для зміни пункту потрібне право редагувати замовлення; доступ до сторінок модулів не потрібен. Якщо з одного кошика створено кілька замовлень, пункт належить лише першому замовленню; Change в іншому замовленні цього кошика показує The DHL location of this cart belongs to another order of the same cart - nothing was changed.

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

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

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

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

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

Пункти не показуються: натисніть 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 Packstation не знайдено: перевізника видалено в Shipping > Carriers. Скиньте модуль за допомогою Reset у Modules > Module Manager, щоб створити його знову. Reset зберігає статус увімкнено/вимкнено наявного перевізника.

Видалення

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

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