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.
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.