VibeFox bpost Cubee for OpenCart — Помощь

Требования

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

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

Аккаунт bpost Shipping Platform (только для селектора пунктов выдачи): расширение ищет пункты выдачи через API bpost Shipping Platform. Войдите в свой аккаунт bpost Shipping Platform на plugins.bpost.be и создайте ключи в разделе Settings > Key management. Нужны три значения: Account ID (открытый ключ), Passphrase (закрытый ключ) и App ID (X-APPID). App ID выдаёт bpost для вашей интеграции; обратитесь в службу поддержки e-commerce bpost (eol@bpost.be). Также нужен идентификатор перевозчика по вашему договору (68 = bpost). Без полных ключей способ работает с фиксированными ценами, но покупателя не просят выбрать пункт выдачи.

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

Установка

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

OpenCart 3

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

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

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

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

5. Введите ваши цены, например BE=4.95 и *=9.95, а для селектора пунктов выдачи — API-ключи bpost (см. Настройка). Включите Enable/Disable и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

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

Некоторые ошибки останавливают сохранение, и тогда ничего не сохраняется: Name длиннее 64 символов, Sort Order, который не является целым числом, или неизвестный налоговый класс либо географическая зона. Другие проблемы выводятся как предупреждения, а остальное сохраняется: вес или сумма, которые не являются числом или отрицательны, не сохраняются, и остаётся прежнее значение; если Min weight (kg) больше Max weight (kg), веса не сохраняются; строки Country prices, которые не удалось прочитать, перечисляются и игнорируются; значение Size prices, в котором не распознан ни один размер, отмечается.

Вверху страницы выводится предупреждение, когда что-то тихо скрывает способ или селектор: селектор пунктов выдачи включён, но API-ключи заполнены не полностью; для Бельгии (BE) нет цены и нет цены по умолчанию (*=ЦЕНА); последнее подключение к API bpost не удалось; или в магазине нет класса веса с единицей «kg» (System > Localisation > Weight Classes). В последнем случае веса товаров читаются по названию их единицы (kg, g, lb или oz).

Общие

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

Name: название способа доставки, которое видит покупатель при оформлении заказа. По умолчанию: bpost parcel locker. Если оставить поле пустым, используется значение по умолчанию. Не более 64 символов.

Tax Class: налог этого класса добавляется к вашим ценам. --- None --- (по умолчанию) означает, что цены окончательные.

Sort Order: позиция способа в списке способов доставки.

API bpost (поиск пунктов выдачи) (нужен только для селектора пунктов выдачи)

Account ID (public key): открытый ключ вашего аккаунта bpost Shipping Platform, его можно найти в разделе Key management на plugins.bpost.be. Очистка этого поля также удаляет сохранённую passphrase.

Passphrase (private key): закрытый ключ, которым подписывается каждый запрос (HMAC-SHA256). Он никогда не отправляется в bpost и не записывается в журнал. После сохранения поле остаётся пустым и показывает Saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить.

App ID (X-APPID): идентификатор приложения, выданный bpost для вашей интеграции. Он передаётся в заголовке X-APPID.

Carrier ID: перевозчик по вашему договору bpost Shipping Platform, чьи пункты выдачи и постаматы выводятся. По умолчанию: 68 (bpost). Другие перевозчики, включённые в вашем договоре, имеют собственные ID.

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

Pickup points: показывает селектор пунктов выдачи и постаматов при оформлении заказа. Включено по умолчанию. Селектор появляется, а пункт обязателен, только когда заполнены Account ID, Passphrase и App ID.

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

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

Цены (в основной валюте магазина, без налога; bpost не возвращает цены доставки через этот API)

Price by: способ выбора цены.

Country prices: одна строка на страну в формате CC=ЦЕНА, например BE=4.95. Строка *=ЦЕНА задаёт цену для всех остальных стран, например *=9.95. В качестве десятичного разделителя принимаются и точка, и запятая. Неверные строки игнорируются. Страны без цены (если нет строки *) способ не получают.

Size prices: используется, когда Price by — размер посылки, в формате S=3.50, M=4.50, L=6.00, XL=8.00. Размер определяется по весу корзины: S до 2 кг, M до 5 кг, L до 10 кг, XL свыше.

Calculation: Per order (по умолчанию) взимает цену один раз. Per item (price x number of items) умножает её на количество товаров в корзине.

Цены округляются до знаков после запятой основной валюты магазина, а затем показываются в валюте покупателя.

Условия

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

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

Minimum order amount: показывает способ, только когда промежуточный итог корзины достигает этой суммы. В промежуточный итог входят товары, требующие доставки, после купонов, без налога. Оставьте поле пустым, чтобы показывать способ всегда.

Бесплатная доставка

Free shipping: включает бесплатную доставку от суммы, указанной ниже.

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

Доступность

Обычно способ предлагается в географической зоне, выбранной ниже. При Ignore geo zone он предлагается в странах из списка.

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

Ignore geo zone: предлагает способ в странах из списка независимо от географической зоны.

Countries: страны назначения для этого режима. По умолчанию: Belgium. Оставьте поле пустым, чтобы разрешить все страны. Используется только когда включена опция Ignore geo zone.

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

Debug log: записывает запросы к API и расчёты цен в файл storage/logs/vfd_bpst_debug.log.php. Файл нельзя прочитать через веб. Ошибки API всегда записываются, даже если эта опция выключена. Ключи и токены никогда не записываются в журнал.

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

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

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

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

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

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену bpost. Если задана Geo Zone (и Ignore geo zone выключено) и адрес находится вне её, способ не предлагается. Учитываются только товары с Requires Shipping, установленным в Yes: другие товары не добавляют вес и не входят в сумму заказа. Расширение проверяет условия: страны из Ignore geo zone (если опция включена), вес корзины и минимальную сумму заказа. Затем оно берёт цену из списка стран или по размеру посылки, в режиме за товар умножает её на количество товаров и обнуляет, если применяется бесплатная доставка. Для расчёта цены запрос в bpost не отправляется.

Под опцией bpost покупатель видит поле Postal code or city, кнопку Search и список пунктов выдачи. Когда покупатель выбирает bpost, а список ещё не загружен, автоматически ищется почтовый индекс адреса доставки (или последний поиск покупателя). Покупатель может ввести другой почтовый индекс или название города. Каждый пункт показывается с названием и адресом. Выводится до 50 пунктов. Список запрашивается на нидерландском, если язык магазина — нидерландский, и на французском в остальных случаях.

Покупатель должен выбрать пункт выдачи. Без пункта кнопка Continue на шаге способа доставки показывает Please select a bpost pickup point. Принимается только пункт из списка bpost для данного поиска. Иначе покупатель видит The selected bpost pickup point is not in the list of your search. Please choose another one. Поиск и выбор сохраняются для оформления заказа, поэтому обновление страницы их не теряет. Новый поиск очищает предыдущий выбор.

На OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа и выбирает bpost в окне Shipping method options. Поиск пунктов выдачи и список появляются в этом окне под опцией bpost. Continue в окне без пункта выдачи показывает Please select a bpost pickup point. Остальное работает так же, как в OpenCart 3.

Для вывода пунктов выдачи расширение отправляет в bpost только искомый почтовый индекс или город, страну и ID перевозчика, подписанные вашими ключами. API-токен запрашивается и обновляется автоматически. Если bpost отклоняет токен, новый запрашивается один раз и поиск повторяется. Результаты поиска кэшируются до 6 часов, но не дольше срока жизни кэша OpenCart (по умолчанию 1 час). Если bpost не отвечает, покупатель видит Pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method., а расширение повторяет попытку через 5 минут. Тайм-аут API — 15 секунд.

Расширение использует только фиксированные цены. Оно не получает тарифов в реальном времени от bpost, не создаёт отправления, не печатает этикетки и не отслеживает посылки. Пункты выдачи показываются списком, а не на карте. Создавайте отправления в вашем аккаунте bpost Shipping Platform или Shipping Manager; ID пункта выдачи указан на странице заказа в админке.

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

При оформлении заказа выбранный пункт выдачи добавляется к способу доставки заказа как bpost pickup point: с названием и адресом пункта, например «bpost parcel locker - bpost pickup point: …». Поэтому покупатель видит его в подтверждении заказа, в истории заказов своего аккаунта, в письмах о заказе и в счёте. Полные данные пункта, включая ID, также сохраняются в отдельной таблице расширения. На OpenCart 4 оформление заказа сохраняет один заказ: если покупатель подтверждает заказ повторно, например после выбора другого пункта выдачи, пункт заказа обновляется.

В админке на странице заказа в разделе Sales > Orders показана панель bpost pickup point с пунктом и его ID или надпись No pickup point was selected for this order. Нажмите Change, найдите почтовый индекс или город, выберите другой пункт из списка и нажмите Save. Заказ и текст его способа доставки обновляются сразу, а страница показывает Pickup point updated. Если пункта нет в списке bpost для данного поиска, страница показывает Pickup point not found in the bpost list of this search. Изменение записывается в журнал отладки, если включена опция Debug log. Кнопка Change доступна только когда API-ключи заполнены и администратор может изменять заказы; доступ к настройкам расширения не нужен.

Чтобы предлагать доставку в постамат и доставку на дом вместе, для доставки на дом используйте другой способ доставки. Селектор пунктов выдачи появляется только под опцией bpost.

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

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

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

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

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

bpost не появляется при оформлении заказа: проверьте, что лицензия активна и Enable/Disable включено. Проверьте Geo Zone или то, что Ignore geo zone включено и страна есть в Countries. Проверьте, что для страны есть цена или строка *=ЦЕНА, а также ограничения по весу и Minimum order amount. Проверьте, что у товаров Requires Shipping установлено в Yes. На странице настроек появляется предупреждение, если для Бельгии нет цены.

Селектор пунктов выдачи не появляется при оформлении заказа: проверьте, что Pickup points включено и заполнены Account ID (public key), Passphrase (private key) и App ID (X-APPID). На странице настроек появляется предупреждение, если ключи заполнены не полностью.

Покупатели видят «Pickup points cannot be loaded right now»: bpost не ответил или отклонил ключи. Причина показана вверху страницы настроек и в журнале отладки (поле Log на странице расширения). Расширение автоматически повторяет попытку через 5 минут. Сохранение настроек запускает повтор сразу.

Для этого почтового индекса или города пункты выдачи не найдены: bpost не вернул пунктов для этого поиска. Попросите покупателя указать ближайший почтовый индекс или название города и проверьте Carrier ID.

Цены с запятой не используются: принимаются и 5,50, и 5.50. Строки Country prices, которые не соответствуют формату CC=ЦЕНА, игнорируются; предупреждение после сохранения их перечисляет.

Цены включают налог? Если Tax Class установлен в --- None ---, цены окончательные. С налоговым классом OpenCart добавляет этот налог к вашим ценам.

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

Для разработчиков: адрес API bpost можно заменить настройкой vfd_bpst_api_url (для тестов); на странице настроек для неё нет поля.

Удаление

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

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

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