VibeFox Packeta for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3), со стандартным оформлением заказа стандартной темы.

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

API-ключ Packeta: его можно найти в разделе клиента Packeta (client.packeta.com) в пункте Client support. Он состоит из 16 букв и цифр. Виджет использует его для открытия при оформлении заказа, поэтому способ доставки показывается покупателям только после ввода API-ключа.

Страны: Чехия, Словакия, Венгрия или Румыния должны быть включёнными странами вашего магазина. Они есть в стандартных данных OpenCart. В Венгрии в OpenCart нет регионов, поэтому поле региона в адресе остаётся пустым; это не важно.

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

Установка

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

OpenCart 3

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

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

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

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

5. Введите API key Packeta и свои цены: как минимум одну строку Country prices (например * Default) или Fallback cost. Включите Enable/Disable и нажмите Save. На странице будет видно, принял ли Packeta ключ.

OpenCart 4

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

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

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

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

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

Настройка

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

Способ предлагается только для стран собственной сети пунктов выдачи Packeta: CZ, SK, HU и RO. Над настройками страница показывает результат проверки API-ключа и предупреждения о проблемах: нет API-ключа, нет цены, выбраны страны вне сети Packeta или единица веса магазина, которую расширение не знает. Предупреждения обновляются после каждого сохранения.

Все цены и ограничения принимают запятую или точку как десятичный разделитель (4,99 или 4.99). Неверное или отрицательное число отклоняется с сообщением, предыдущее значение этого поля сохраняется, остальные поля сохраняются.

Общие

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

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

API key: ваш API-ключ Packeta из client.packeta.com > Client support. Можно также вставить 32-символьный API-пароль: сохраняются только его первые 16 символов, то есть API-ключ. API-ключ публичен: он отправляется в браузер покупателя для открытия виджета. При сохранении нового ключа он проверяется по carrier feed Packeta, и страница показывает Packeta API key verified или сообщает, что Packeta отклонил ключ. Если проверку выполнить невозможно, ключ сохраняется и проверяется снова при следующем сохранении.

Widget language: язык виджета пунктов выдачи. Store / visitor language (по умолчанию) следует языку страницы. Можно также задать фиксированный язык: чешский, словацкий, венгерский, румынский, английский, немецкий, польский или украинский.

Pickup point types: какие пункты Packeta предлагает виджет.

Tax status: налоговый класс OpenCart, применяемый к стоимости доставки, или None (no tax on shipping) (по умолчанию).

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

Цены

Packeta не предоставляет публичного API тарифов. Цены берутся из этой таблицы и вводятся в валюте магазина по умолчанию без учёта налогов. Покупатели, платящие в другой валюте, видят пересчитанную цену.

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

Country prices: цена для каждой страны назначения и веса посылки. Нажмите Add country, чтобы добавить строку, и кнопку × для её удаления. В каждой строке есть Price и весовые колонки: XS до 1 кг, S от 1 до 2 кг, M от 2 до 3 кг, L от 3 до 5 кг и XL свыше 5 кг. Весовая колонка, оставленная в 0, использует колонку Price. Строка * Default используется для стран без собственной строки. Новая строка создаётся как * Default со всеми ценами 0, что означает бесплатную доставку. Выберите страну и введите цены перед сохранением или удалите строку. Если одна и та же страна (или * Default) есть в двух строках, при сохранении остаётся только первая. Если значение в таблице — не число не меньше 0, таблица не сохраняется, а страница показывает неверные значения.

Fallback cost: используется, когда в таблице стран нет строки для страны назначения и строки * Default. Оставьте поле пустым, чтобы не предлагать способ в этих странах.

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

Доступность

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

Maximum weight (kg): скрывает способ, когда корзина весит больше. По умолчанию: 15. Пункты выдачи и Z-BOX Packeta обычно принимают посылки до 15 кг; уточняйте в договоре с Packeta. Пусто или 0 означает отсутствие ограничения. Минимальный вес больше максимального отклоняется при сохранении, и оба предыдущих значения сохраняются.

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

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

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

Countries (ignore zones mode): страны назначения для этого режима. Оставьте пустым, чтобы использовать все страны Packeta. Страны вне сети пунктов выдачи Packeta пропускаются. Это поле используется только при включённом Ignore shipping zones.

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

Debug log: записывает расчёты тарифов и выбор пунктов выдачи в storage/logs/vfd_pckt_debug.log.php. Файл нельзя прочитать из веба. Персональные данные покупателей и API-ключ не записываются. Ошибки и неудачные проверки API-ключа записываются всегда. Выключайте журнал, когда закончите. Когда файл достигает 5 МБ, он переносится в vfd_pckt_debug.old.log.php, и начинается новый журнал.

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

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

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

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

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

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену Packeta. Если задана Geo zone (и выключено Ignore shipping zones) и адрес находится вне неё, Packeta не предлагается. Учитываются только товары с Requires Shipping, равным Yes: остальные товары не добавляют вес и не входят в промежуточный итог. Расширение проверяет условия: страна доставки входит в сеть Packeta, API-ключ, список стран в режиме игнорирования зон, вес корзины и минимальный промежуточный итог корзины. Промежуточный итог — это цена товаров, требующих доставки, после скидки по купону и без налогов. Подарочные сертификаты, бонусные баллы и баланс магазина не учитываются. Если применяется бесплатная доставка, цена равна 0. Иначе цена берётся из таблицы стран, затем из резервной стоимости. Если цены нет, способ скрывается. Цена показывается покупателю в его валюте с налогом по выбранному Tax status.

Под вариантом Packeta на шаге способа доставки есть кнопка Choose pickup point. Она открывает официальный виджет Packeta в браузере покупателя с указанием страны назначения, веса корзины, выбранных типов пунктов и языка виджета. После выбора пункта покупателем его название и адрес показываются под способом, а кнопка меняется на Change pickup point. Пункт сохраняется для сессии оформления и остаётся при перезагрузке страницы. Пункт, выбранный для другой страны, не используется, если адрес доставки меняется на другую страну.

Ваш сервер при оформлении заказа ничего не запрашивает у Packeta. Скрипт виджета загружается с widget.packeta.com только на странице оформления заказа. Если он заблокирован (блокировщиком рекламы или приватности, политикой безопасности контента или сбоем Packeta), покупатель видит сообщение «The Packeta pickup point widget could not be loaded. Please reload the page or choose another shipping method.»

Цены Packeta не запрашиваются в реальном времени; они берутся из вашей таблицы. Расширение не создаёт отправления Packeta, не печатает этикетки и не отслеживает посылки, а также по умолчанию не предлагает доставку до двери или пункты партнёрских перевозчиков. Передайте ID пункта выдачи из заказа в Packeta привычным способом, например импортом в client.packeta.com. Кнопка пункта выдачи работает со стандартным оформлением заказа OpenCart стандартной темы.

В OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа и выбирает Packeta в окне Shipping method options. Кнопка Choose pickup point и выбранный пункт появляются в этом окне, под вариантом Packeta, а виджет Packeta открывается поверх него. Цены такие же, как в OpenCart 3.

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

Пункт выдачи обязателен. Если покупатель нажимает Continue на шаге способа доставки, не выбрав пункт, шаг не завершается и покупатель видит сообщение «Please choose a Packeta pickup point.». Если выбранный пункт находится в другой стране, чем адрес доставки, покупатель видит «The selected Packeta pickup point is not in your shipping country. Please choose a pickup point again.». Расширение не проверяет ID пункта в Packeta; оно только проверяет, что пункт выбран и что его страна совпадает.

Пункт прикрепляется к заказу при его создании:

Способ доставки заказа: название и адрес пункта добавляются к названию способа, например Packeta pickup point: <point> (до 128 символов). Покупатель видит это в истории заказа и в письме о заказе, а также оно печатается в счёте-фактуре. Страница успешного оформления заказа в OpenCart не показывает способ доставки.

Страница заказа в администрировании: откройте заказ в Sales > Orders. Панель Packeta pickup point показывает название и адрес, Pickup point ID и страну. Если в заказе Packeta нет пункта, панель сообщает: «No pickup point was selected for this order.»

На OpenCart 4 кнопка Continue в окне Shipping method options не пропускает дальше без пункта, с теми же сообщениями. OpenCart 4 ведёт один заказ на оформление и обновляет его каждый раз, когда покупатель подтверждает заказ снова; пункт выдачи заказа обновляется вместе с ним. Панель Packeta pickup point на странице заказа в администрировании показывается над разделом History.

Пункт хранится в собственной таблице расширения vfd_pckt_point (сессия оформления, заказ, ID пункта, название и адрес, страна).

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

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

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

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

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

Packeta не появляется при оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включено, что введён API key и что страна доставки — CZ, SK, HU или RO. Проверьте, что для страны задана цена (строка страны, строка * Default или Fallback cost), ограничения по весу и промежуточному итогу, а также Geo zone (или Ignore shipping zones и его страны). Проверьте, что у товаров Requires Shipping равно Yes. Страница настроек вверху показывает проблемы конфигурации. Включите Debug log, чтобы увидеть причину в Log (last lines).

Packeta отклонил API-ключ: скопируйте API-ключ ещё раз из client.packeta.com > Client support и сохраните. До этого виджет не может открыться при оформлении заказа.

Виджет не открывается: скрипт Packeta заблокирован блокировщиком рекламы или приватности, политикой безопасности контента или сбоем Packeta. Разрешите widget.packeta.com в политике безопасности контента.

Доставка бесплатна по ошибке: проверьте Country prices на строки с Price 0, особенно строку * Default, добавленную через Add country и оставленную незаполненной, а также проверьте Free shipping from.

Ограничения по весу или весовые колонки выглядят неверно: если страница предупреждает о единице веса магазина, используйте весовые классы с единицами kg, g, lb или oz и задайте весовой класс по умолчанию в System > Settings, вкладка Local. Другие единицы читаются как килограммы.

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

Для разработчиков: другие расширения могут добавлять страны, передавать виджету параметры, например ID перевозчиков, менять URL скрипта виджета или его язык через события OpenCart vfd_packeta/countries, vfd_packeta/widget_options, vfd_packeta/widget_url и vfd_packeta/widget_language (триггеры с префиксом catalog/, например catalog/vfd_packeta/widget_options).

Удаление

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

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

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