VibeFox DPD Pickup for OpenCart — Помощь

Требования

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

PHP: 8.0 или новее.

Учётные данные DPD Baltic (Литва, Латвия, Эстония): список пунктов выдачи берётся из веб-сервиса DPD Baltic. Нужны имя пользователя и пароль API, которые DPD выдаёт своим бизнес-клиентам. Уточните их у своего менеджера DPD или в службе поддержки DPD вашей страны. Одна учётная запись выводит пункты выдачи Литвы, Латвии и Эстонии.

DPD Slovakia: публичный поиск паркшопов DPD Slovakia не требует учётных данных.

Весовая категория: веса товаров переводятся в кг. В вашем магазине должна быть весовая категория с единицей измерения kg в разделе System > Localisation > Weight Classes (в OpenCart она есть по умолчанию).

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

Установка

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

OpenCart 3

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

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

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

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

5. Выберите API DPD. Для DPD Литва, Латвия или Эстония введите имя пользователя и пароль API. Проверьте цены по странам, включите Enable/Disable и нажмите Save. Затем нажмите Refresh pickup points, чтобы проверить подключение (см. Настройка).

OpenCart 4

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

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

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

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

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

Настройка

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

Предупреждения вверху страницы сообщают, что имя пользователя или пароль DPD Baltic не заполнены, что цены не заданы (в обоих случаях способ не показывается на оформлении заказа), а также что в магазине нет весовой категории с единицей kg (тогда веса товаров определяются по названию единицы, а неизвестные единицы считаются кг). Некоторые значения не дают сохранить настройки, и тогда ничего не сохраняется: пустое Name или название длиннее 64 символов, Sort order, который не является целым числом, и Min weight (kg), большее Max weight (kg). Значение, которое не является числом или является отрицательным, в поле суммы или веса не сохраняется: поле становится пустым, и предупреждение называет его, а остальные настройки сохраняются. Строки Country prices, не соответствующие формату CC:PRICE, перечисляются в предупреждении и пропускаются.

Общие

Способ предлагается в геозоне, заданной в Availability (все зоны, если ни одна не выбрана), или с Ignore shipping zones в странах, выбранных там.

Enable/Disable: показывает или скрывает DPD Pickup на оформлении заказа. По умолчанию: выключено.

Name: название способа доставки, которое видит покупатель на оформлении заказа. По умолчанию: DPD Pickup Point. Обязательно, не более 64 символов.

Tax class: налоговый класс, применяемый к стоимости доставки, или None (по умолчанию) — без налога.

Sort order: положение способа в списке способов доставки. Целое число.

Список пунктов выдачи DPD

Пункты выдачи загружаются из DPD и кэшируются (см. Как это работает на оформлении заказа).

DPD API: компания DPD, с которой у вас учётная запись. Учётные записи Baltic используют веб-сервис своей страны.

API username (Baltic): имя пользователя для веб-сервиса DPD Baltic. Для DPD Slovakia не нужно. Очистка поля также удаляет сохранённый пароль.

API password (Baltic): пароль для веб-сервиса DPD Baltic. Для DPD Slovakia не нужен. После сохранения поле остаётся пустым и показывает Saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Pickup points: кнопка Refresh pickup points очищает кэш и сразу загружает пункты выдачи из DPD: Литва, Латвия и Эстония для API Baltic и тестовый поиск в Братиславе для DPD Slovakia. Она показывает количество пунктов выдачи или ошибку по каждой стране. Сначала сохраните настройки.

Цены

Стоимость доставки фиксированная для каждой страны, в валюте магазина по умолчанию, без налогов. Тарифы DPD через API не запрашиваются.

Country prices: одна строка на страну: CC:цена, например EE:3.50. Допускается десятичная запятая. По умолчанию: SK:3.50, LT:4.00, LV:4.00, EE:4.00.

Fallback cost: цена для стран, которых нет в Country prices. По умолчанию: 5.00. Оставьте поле пустым, чтобы предлагать способ только в перечисленных странах.

Calculation type: Per order (по умолчанию) — цена взимается один раз. Per item (price x quantity) — цена умножается на количество товаров в корзине.

Free shipping from: доставка бесплатная, когда промежуточная сумма заказа (после скидок, без налогов) достигает этой суммы. Оставьте поле пустым, чтобы отключить.

Доступность

Способ также скрывается, если DPD не возвращает пунктов выдачи для адреса покупателя или API DPD недоступен, потому что заказ нельзя доставить без пункта выдачи.

Min weight (kg): минимальный вес корзины. Веса товаров переводятся из их весовой категории. Пустое значение или 0 означает отсутствие ограничения.

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

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

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

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

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

Выбор пункта выдачи

City order: сначала показывать крупные города (Tallinn, Riga, Vilnius, Bratislava и другие). По умолчанию включено.

City list width: ширина списка городов в CSS, например 100% или 300px. По умолчанию: 100%.

Pickup point list width: ширина списка пунктов выдачи в CSS, например 100% или 400px. По умолчанию: 100%.

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

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

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

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

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

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

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

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

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

Затем расширение загружает пункты выдачи DPD для адреса. Если DPD не возвращает ни одного, недоступен или отсутствуют учётные данные Baltic, способ скрывается. Для DPD Slovakia способ показывается, пока не заполнены город или почтовый индекс, а пункты появляются, когда адрес полный. Цена рассчитывается в валюте магазина по умолчанию и показывается покупателю в его валюте с налогом выбранного Tax class.

Список пунктов выдачи кэшируется на срок до 24 часов, пустой список — до 1 часа, но не дольше срока жизни кэша OpenCart (по умолчанию 1 час). Неудачный запрос запоминается на 5 минут, поэтому сбой DPD никогда не замедляет оформление заказа. Тайм-аут API составляет 15 секунд.

Расширение не запрашивает тарифы DPD, не создаёт отправления DPD, не печатает этикетки, не формирует реестры, не заказывает курьерский забор, не отслеживает посылки и не показывает карту. Поддерживаются только веб-сервис DPD Baltic и поиск паркшопов DPD Slovakia.

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

Когда покупатель выбирает DPD Pickup, под способом доставки появляются список городов и список пунктов выдачи. Город из адреса покупателя выбирается автоматически. Выбор сохраняется сразу, как только покупатель его сделал. Для DPD Slovakia покупатель видит Enter your city and postcode to see the DPD pickup points nearby., пока адрес не заполнен, а затем ближайшие пункты. Если у DPD нет пунктов для адреса, покупатель видит No DPD pickup points are available for this address right now. Please check the address or choose another shipping method.

Пункт выдачи обязателен. Без него покупатель не может продолжить и видит Please select a DPD pickup point. Когда покупатель нажимает Continue, сервер проверяет, что пункт входит в список DPD для адреса покупателя. Поддельный или устаревший выбор отклоняется с сообщением The selected DPD pickup point is not available for this address. Please choose another one. Если список DPD в этот момент не загрузился, принимается пункт, который покупатель уже выбрал, а в заказе вместо названия показывается его ID.

На OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа и выбирает DPD Pickup в окне Shipping method options. Список городов и список пунктов выдачи появляются в этом окне под способом и работают так, как описано выше. Кнопка Continue в окне не пропускает дальше без пункта выдачи, с теми же сообщениями.

Выбранный пункт добавляется к способу доставки заказа, например DPD Pickup Point: name, street, postcode city со стандартным заголовком или My title - DPD pickup point: name, street, postcode city с вашим заголовком (не более 128 символов). Так он отображается в заказе в админ-панели, в истории заказов покупателя, в письмах о заказе и в счёте. Название, сохраняемое в заказе, берётся из DPD, а не из браузера.

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

На странице заказа в админ-панели (Sales > Orders) блок DPD pickup point над историей показывает название пункта, его ID и страну. Нажмите Edit, выберите город и другой пункт, затем нажмите Save. Пункт проверяется по списку DPD для адреса заказа, и блок показывает Pickup point updated. или Pickup point not found for the order address. Текст способа доставки в заказе обновляется, а в истории заказа добавляется примечание (покупателю не отправляется) со старым пунктом, новым пунктом и администратором. Для изменения пункта нужно право изменения заказов, а не доступ к настройкам расширения. Для DPD Slovakia в заказе должны быть город и почтовый индекс доставки, иначе блок показывает Add the shipping city and postcode to change the pickup point. Заказ без пункта показывает No pickup point was selected for this order., и в журнале отладки для него есть ошибка. Блок и Edit работают и после выключения расширения.

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox DPD Pickup — первый блок на странице Extensions > Extensions > Shipping > VibeFox DPD Pickup > Edit, над настройками. Вставьте ключ в License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now, чтобы проверить статус снова, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: opencart-shipping-dpd-pickup и ссылка 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.

Без действующего ключа способ доставки DPD Pickup не показывается покупателям на оформлении заказа, и тариф не рассчитывается. Администратор, вошедший в админ-панель в том же браузере, всё равно видит способ в магазине, отмеченный как (unlicensed — visible to admins only), поэтому вы можете настроить и протестировать расширение до покупки ключа. На OpenCart 4 этот режим предпросмотра недоступен: магазин не видит вход администратора, поэтому без действующего ключа способ скрыт для всех. После того как вы один раз откроете страницу Edit, на Dashboard админ-панели появляется напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются.

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

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

DPD Pickup не появляется на оформлении заказа: проверьте, что лицензия действует и включено Enable/Disable. Проверьте Geo zone (или Ignore shipping zones и Countries), ограничения по весу и сумме, а также наличие цены (или резервной стоимости) для страны. Проверьте предупреждения вверху страницы расширения и нажмите Refresh pickup points. Убедитесь, что у товаров Requires Shipping равно Yes.

Ошибка после Refresh pickup points: результат показывает ошибку DPD по каждой стране. Например, «Login failed» означает, что DPD отклонил учётные данные Baltic, поэтому пункты выдачи загрузить нельзя. Проверьте имя пользователя и пароль API в DPD.

DPD Slovakia не показывает пункты: пункты появляются, когда покупатель ввёл город и почтовый индекс. DPD выводит только пункты в радиусе 50 км от этого адреса.

Поиск причины: включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице расширения. Ошибки API записываются всегда. Имена пользователей и пароли API никогда не записываются в журнал.

Пункты выдачи выглядят устаревшими после изменения: нажмите Save или Refresh pickup points на странице расширения. Обе кнопки очищают кэшированные списки.

Страница показывает «Warning: You do not have permission to modify VibeFox DPD Pickup!»: возможно, ваша группа администраторов может только просматривать настройки. Дайте группе право изменения для extension/shipping/vfd_dpd_pickup (OpenCart 3) или extension/vfd_dpd_pickup/shipping/vfd_dpd_pickup (OpenCart 4) в System > Users > User Groups.

Для разработчиков: радиус поиска DPD Slovakia может изменить другое расширение с помощью события OpenCart vfd_dpd_pickup/sk_search_radius.

Удаление

Перейдите в Extensions > Extensions, выберите тип Shipping и нажмите Uninstall (красная кнопка −) рядом с VibeFox DPD Pickup. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда сбрасывает Enable/Disable, Sort order, Tax class и Geo zone. Расширение всегда удаляет свои события и кэшированные списки пунктов выдачи. Если Remove data on uninstall включено, остальные настройки, журнал отладки и выбор незавершённых оформлений заказа также удаляются. Если выключено, настройки сохраняются и будут использованы при повторной установке расширения. Пункт выдачи, сохранённый в заказах, никогда не удаляется, а существующие заказы сохраняют свой способ доставки и стоимость.

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

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