VibeFox DHL Africa for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

PHP: 8.0 или новее с расширением cURL. Для DHL XML Services также нужно расширение PHP SimpleXML.

Аккаунт DHL Express (только для тарифов в реальном времени): тарифы в реальном времени используют MyDHL API. Вам нужны номер аккаунта DHL Express и учётные данные MyDHL API: API key и API secret. Запросите их на портале разработчиков DHL (MyDHL API, "Get access") или у своего менеджера аккаунта DHL Express. Аккаунты, у которых ещё есть учётные данные DHL XML Services (Site ID и пароль), могут использовать их. Если вы используете только запасные цены, учётные данные DHL не нужны.

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

Установка

Загрузка — один zip-файл с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. В нём есть README.txt, пакет для OpenCart 3 vfd_dhl_africa-oc3-(version).ocmod.zip и пакет для OpenCart 4 vfd_dhl_africa.ocmod.zip. Установите только пакет для вашей версии OpenCart. Лицензионный ключ один и тот же для обеих версий.

OpenCart 3

1. В административной части перейдите в Extensions > Installer, нажмите Upload и выберите файл vfd_dhl_africa-oc3-(version).ocmod.zip. Расширение не добавляет модификации OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload этого пакета в корневую папку вашего магазина.

2. Перейдите в Extensions > Extensions и выберите тип расширения Shipping. Найдите VibeFox DHL Africa и нажмите Install (зелёная кнопка с плюсом).

3. Нажмите Edit (кнопка с карандашом), чтобы открыть страницу настроек.

4. Вставьте лицензионный ключ VibeFox в поле License key в блоке лицензии вверху страницы Edit и нажмите Activate (см. License key).

5. Выберите API DHL, введите API key, API secret и номер вашего аккаунта DHL. Оставьте Test mode включённым, пока используете тестовые учётные данные. Введите адрес Ship from. Если ваш аккаунт DHL выставляется не в основной валюте магазина, задайте DHL quote currency и Exchange rate. При необходимости задайте цены по странам и запасную стоимость (см. Configuration). Включите Enable DHL Express Africa и нажмите Save.

OpenCart 4

1. В административной части перейдите в Extensions > Installer, нажмите Upload и выберите файл vfd_dhl_africa.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на той же странице. Нажмите Install (зелёная кнопка с плюсом) рядом с ним.

3. Перейдите в Extensions > Extensions и выберите тип расширения Shipping. Найдите VibeFox DHL Africa, нажмите Install (зелёная кнопка с плюсом), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ и настройки так же, как в шагах 4 и 5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях.

После установки способ доставки выключен, пока вы не включите Enable DHL Express Africa и не сохраните настройки. Если вы установите расширение повторно после удаления, снова будут использованы сохранённые настройки DHL.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox DHL Africa > Edit. Разделы перечислены слева. Одна кнопка Save сохраняет всю страницу без перезагрузки. Каждое сохранение также очищает кеш котировок DHL. Цены и веса принимают десятичную запятую или точку. Сохранять настройки могут только администраторы с правом изменения для этого расширения.

Предупреждения в верхней части страницы сообщают, когда тарифы в реальном времени отключены: не заполнены API key, API secret или номер аккаунта (либо, при XML Services, Site ID или пароль), не указаны страна или город отправления, выбран XML Services (DHL их отключает), задана валюта котировки без курса обмена, а также когда расширение не знает единицу веса или длины магазина (тогда веса товаров читаются как кг, а размеры — как см; добавьте класс веса с единицей kg в System > Localisation > Weight Classes или класс длины с единицей cm в System > Localisation > Length Classes).

Если значение недопустимо при сохранении (пустое название способа или название длиннее 64 символов, некорректное или отрицательное число, курс обмена 0, минимальный вес больше максимального, неизвестная валюта котировки, страна отправления, налоговый класс или географическая зона, порядок сортировки, который не является целым числом), предупреждение над настройками указывает поле, например Select a valid origin country. It was not saved. Прежнее значение этого поля сохраняется, остальные настройки сохраняются.

Общие

Enable DHL Express Africa: показывает или скрывает DHL Express при оформлении заказа. По умолчанию: выключено.

Method title: название способа доставки, которое видит покупатель при оформлении заказа. По умолчанию: DHL Express. Обязательное поле, не более 64 символов.

Tax class: налоговый класс стоимости доставки или No tax (по умолчанию). При налоговом классе (и включённых в магазине налогах) тариф DHL берётся без налога, который указывает DHL, и OpenCart добавляет свой налог. При No tax тариф DHL взимается как указан, с налогом в составе.

Sort order: позиция DHL Express среди способов доставки при оформлении заказа. Целое число.

Аккаунт DHL Express (нужен только для тарифов в реальном времени)

DHL API: какой интерфейс DHL используется.

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: показывается только для MyDHL API, когда сохранён ключ или секрет. Включите и нажмите 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. По умолчанию включено. Тестовые учётные данные работают только в тестовой среде, рабочие — только в рабочей. Выключите, когда начнёте работать с реальными заказами.

Адрес отправления

Адрес, с которого DHL забирает посылки. От него зависит тариф. OpenCart хранит адрес магазина как свободный текст, поэтому место отправления всегда указывается здесь. Примечание в этом разделе показывает страну вашего магазина.

Origin country: страна, из которой вы отправляете.

Origin city: город, из которого вы отправляете, например Johannesburg. Его требует 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 (kg): скрывает способ доставки при весе корзины ниже этого значения. 0 означает отсутствие ограничения (по умолчанию). Не может быть больше Maximum weight (kg).

Maximum weight (kg): скрывает способ доставки при весе корзины выше этого значения. По умолчанию: 70 (также используется, если поле пустое). 0 означает отсутствие ограничения.

Minimum subtotal: показывать способ доставки, только если сумма товаров, требующих доставки (после купона, без налога), не меньше этого значения. Оставьте пустым, чтобы показывать всегда.

Доступность

Geo zone: предлагать DHL Express только для адресов в этой географической зоне. All zones (по умолчанию) означает отсутствие ограничения. Географические зоны управляются в System > Localisation > Geo Zones. Не проверяется при Ignore shipping zones.

Ignore shipping zones: предлагать способ доставки для стран ниже (или для всех стран, если список пуст), независимо от выбранной географической зоны.

Countries: страны назначения для этого режима. Используется только вместе с Ignore shipping zones.

Дополнительно

Debug log: записывает расчёты тарифов в storage/logs/vfd_dhla_debug.log.php (в OpenCart 4 — в system/storage/logs/vfd_dhla_debug.log.php). Файл нельзя прочитать из браузера. Ошибки DHL записываются всегда, даже когда опция выключена. Учётные данные, номер аккаунта и адреса покупателей никогда не записываются. Когда файл достигает 5 МБ, он переносится в vfd_dhla_debug.old.log.php, и начинается новый журнал.

Log: показывает размер и последние записи журнала отладки. Нажмите Clear log, чтобы очистить его.

Remove data on uninstall: если включено, при удалении расширения удаляются настройки, кешированные котировки DHL и журнал. Если выключено (по умолчанию), всё сохраняется для повторной установки. Продукты DHL из оформленных заказов всегда сохраняются.

Импорт / Экспорт

Export: нажмите Download JSON, чтобы сохранить настройки в файл JSON. API key, API secret и XML-пароль не экспортируются.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки, например в другом магазине. Значения проверяются так же, как при обычном сохранении. Сохранённые учётные данные остаются.

Как это работает при оформлении заказа

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену DHL Express. Если задана Geo zone (и Ignore shipping zones выключено) и адрес находится вне её, DHL Express не предлагается. Учитываются только товары с Requires Shipping, установленным в Yes: другие товары не добавляют веса и не входят в сумму заказа. Затем расширение проверяет условия: страны из Ignore shipping zones, вес корзины и минимальную сумму заказа. Сумма заказа — это цена товаров, требующих доставки, после скидки по купону и без налога. Подарочные сертификаты, бонусные баллы и кредит магазина не учитываются. Если применяется бесплатная доставка, цена равна 0 и запрос в DHL не отправляется.

В остальных случаях расширение передаёт в DHL отправление и назначение (страна, город, почтовый индекс), вес корзины, переведённый в кг из классов веса товаров (не менее 0,5 кг), и одну коробку, собранную по размерам товаров в см: наибольшая длина, наибольшая ширина и сумма высот при укладке. Товары без размеров не добавляют ничего. Если ни у одного товара нет размеров, используется коробка 10 x 10 x 10 см. Отправления в другую страну декларируются для таможни, а объявленной стоимостью служит сумма корзины. Внутренние отправления не декларируются. Дата забора — сегодня по часовому поясу магазина, а в выходные — понедельник. Тариф в реальном времени запрашивается только после того, как покупатель указал город (для XML Services — город или почтовый индекс). До этого действуют запасные цены.

Самый дешёвый продукт DHL Express показывается одной ценой с названием вашего способа доставки. Покупатель не видит продукт DHL. Цена рассчитывается в основной валюте, округляется до её знаков после запятой и показывается покупателю в его валюте с налогом выбранного Tax class.

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

Расширение только рассчитывает тарифы. Оно не создаёт отправления DHL, не печатает ярлыки и коммерческие инвойсы, не заказывает курьера, не отслеживает посылки, не предлагает пункты обслуживания DHL, не позволяет покупателю выбирать между продуктами DHL, не упаковывает несколько коробок, не добавляет страховку и не рассчитывает пошлины и налоги. Котировка относится только к доставке. Пошлины и импортные налоги оплачивает получатель.

В OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа и выбирает DHL Express в окне Shipping method options. Способ работает так же, как в OpenCart 3.

Заказы

При оформлении заказа расширение сохраняет тариф, рассчитанный для его корзины. Откройте заказ в Sales > Orders: панель 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): цена в основной валюте вашего магазина.

Продукт DHL не показывается покупателю в письмах и на его странице заказа. В заказе отображаются название способа доставки и стоимость доставки, как для любого другого способа доставки OpenCart.

В OpenCart 4 оформление заказа сохраняет один заказ и обновляет его каждый раз, когда покупатель подтверждает заказ снова. Панель тогда показывает последний тариф оформления. Если покупатель переключается на другой способ доставки, панель для этого заказа больше не показывается.

Лицензионный ключ

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox DHL Africa является первым блоком на странице Extensions > Extensions > Shipping > VibeFox DHL Africa > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: opencart-shipping-dhl-africa и ссылка 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 Express не показывается покупателям при оформлении заказа, и тариф не рассчитывается. Администратор, вошедший в админку в том же браузере, всё же видит способ доставки в магазине, помеченный как (unlicensed — visible to admins only), поэтому вы можете настроить и проверить расширение до покупки ключа. В OpenCart 4 этот предпросмотр недоступен: магазин не видит вход администратора, поэтому без активного ключа способ доставки скрыт для всех. После того как вы один раз открыли страницу Edit, на панели Dashboard появляется напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются.

Когда срок лицензии истекает, расширение продолжает работать, но для обновлений и поддержки нужно продление. Статус проверяется снова автоматически, когда вы открываете страницу Dashboard или страницу Edit: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задание не нужно. Удаление расширения всегда удаляет лицензионный ключ и статус лицензии.

Устранение неполадок

DHL Express не появляется при оформлении заказа: проверьте, что лицензия активна и включено Enable DHL Express Africa. Проверьте Geo zone (или включите Ignore shipping zones и проверьте Countries), ограничения по весу и Minimum subtotal. Без тарифа в реальном времени способ доставки появляется, только если задана цена для страны или запасная стоимость. Проверьте, что у товаров установлено Requires Shipping в значение Yes.

Тарифы в реальном времени не появляются: проверьте предупреждения в верхней части страницы расширения (нет учётных данных или места отправления). Включите 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 class, чтобы тариф DHL брался без налога DHL, или выберите No tax, чтобы взимать сумму DHL как указано.

Тарифы выглядят устаревшими после изменения: нажмите Save на странице расширения. Это очистит кешированные котировки DHL.

На странице написано "Warning: You do not have permission to modify VibeFox DHL Africa!": возможно, группа администраторов имеет право только на просмотр настроек. Дайте группе право изменения для extension/shipping/vfd_dhl_africa (OpenCart 3) или extension/vfd_dhl_africa/shipping/vfd_dhl_africa (OpenCart 4) в System > Users > User Groups.

Для разработчиков: расширение вызывает события OpenCart catalog/vfd_dhl_africa/api_url, is_dutiable, package_box, rest_request и xml_request (с тем же префиксом), которые могут менять адрес API, таможенную декларацию, коробку и запросы к DHL.

Удаление

Перейдите в Extensions > Extensions, выберите тип Shipping и нажмите Uninstall (красная кнопка с минусом) рядом с VibeFox DHL Africa. OpenCart всегда сбрасывает Enable DHL Express Africa, Sort order, Tax class и Geo zone. Кешированные котировки DHL и события расширения всегда удаляются. Если Remove data on uninstall включено, удаляются также настройки DHL и журнал отладки. Если выключено, остальные настройки сохраняются и снова используются при повторной установке расширения. Продукты DHL из оформленных заказов никогда не удаляются. Существующие заказы сохраняют свой способ доставки и стоимость.

В OpenCart 4, чтобы удалить также файлы расширения, после удаления перейдите в Extensions > Installer и нажмите Uninstall (оранжевая кнопка с минусом) рядом с VibeFox DHL Africa в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

DHL — товарный знак его владельца. Это расширение не связано с DHL и не одобрено DHL.