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. В back office перейдите в 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.

На странице заказа в back office блок 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.