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

Предупреждения в верхней части страницы сообщают, когда ключ DHL API пуст, когда не включён ни один тип пунктов выдачи (в обоих случаях способ доставки не показывается при оформлении заказа), когда записи цен по странам не в формате 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.