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

Требования

PrestaShop: 8.0 — 9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

Аккаунт 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). Также нужен ID перевозчика по вашему договору (68 = bpost). Без полных ключей перевозчик по-прежнему работает с фиксированными ценами, но покупателей не просят выбрать пункт выдачи.

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

Установка

1. В back office перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. По окончании загрузки нажмите Configure или позже найдите VibeFox bpost Cubee в списке модулей и нажмите Configure.

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

4. Введите свои цены и, для выбора пункта выдачи, API-ключи bpost (см. Настройки). Нажмите Save.

При установке модуль создаёт перевозчика bpost parcel locker с текстом срока доставки Pickup point or parcel locker. Перевозчик привязан к зоне Бельгии и ко всем группам клиентов, без налогового правила. Зоны, группы клиентов, текст срока доставки и логотип можно изменить в Shipping > Carriers. Не задавайте там цены: цена всегда берётся из модуля.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox bpost Cubee > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает сохранённый API-токен и кэш списков пунктов выдачи.

Страница показывает предупреждения, когда что-то незаметно скрывает перевозчика или выбор: выбор пункта выдачи включён, но API-ключи заполнены не полностью; нет цены для Бельгии (BE) и цены по умолчанию; последнее подключение к API bpost не удалось; модулю неизвестна единица веса магазина (задайте её в International > Localization, Local units); или перевозчик bpost не найден. При сохранении строки Country prices, которые не удалось прочитать, перечисляются в предупреждении, как и значение Size prices, в котором не распознан ни один размер. Вес или сумма, которые не являются числом или отрицательны, не сохраняются: предупреждение называет поле, а предыдущее значение остаётся. Если Min weight (kg) больше Max weight (kg), вес тоже не сохраняется.

Общие

Enable/Disable: включает или выключает доставку через bpost parcel locker. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

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

Tax status: None означает, что цены окончательные. Taxable с налоговым правилом добавляет налог этого правила к вашим ценам. Выбор сохраняется в перевозчике.

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

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. Для страны всё равно нужна цена, иначе перевозчик не предлагается.

Доступность без зон доставки

Обычно перевозчик предлагается в своих зонах доставки в Shipping > Carriers. При установке это зона Бельгии.

Ignore shipping zones: предлагать перевозчика в странах, указанных ниже, без добавления его в зону. Тогда перевозчик привязывается ко всем активным зонам, в том числе к зонам, которые вы создадите позже. Когда вы снова выключите опцию, перевозчик вернёт свои прежние зоны.

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

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

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

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

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

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

На шаге доставки PrestaShop запрашивает у модуля цену bpost. Учитываются только товары, требующие доставки: виртуальные товары не добавляют вес и не входят в сумму заказа. Модуль проверяет условия: страны из Ignore shipping zones (если включено), вес корзины и минимальную сумму заказа. Затем он берёт цену из списка стран или по размеру посылки, умножает её на количество товаров в режиме за товар и обнуляет, если применяется бесплатная доставка. Запрос в bpost за ценой не отправляется.

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

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

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

Если вы редактируете перевозчика в Shipping > Carriers после того, как у него появились заказы, PrestaShop сохраняет его как новую версию перевозчика. Модуль автоматически следует за новой версией.

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

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

При оформлении заказа выбранный пункт выдачи (название и адрес) и его ID сохраняются вместе с заказом. На странице заказа в back office блок bpost pickup point показывает пункт и его ID или No pickup point was selected for this order. Нажмите Change, найдите почтовый индекс или город, выберите другой пункт из списка и нажмите Save. Заказ обновляется сразу, и страница показывает Pickup point updated. Изменение записывается в журнал отладки, если включён Debug log. Ссылка Change доступна только при заполненных API-ключах. Для сохранения нового пункта нужно право на редактирование заказов; иначе страница показывает Permission denied. Доступ к страницам Modules не нужен.

Если PrestaShop делит одну корзину на несколько заказов, пункт выдачи остаётся у первого заказа. У остальных заказов пункта выдачи нет, а журнал отладки показывает ошибку с названием первого заказа; задайте пункт для этих посылок вручную в bpost.

Покупатели видят пункт выдачи как bpost pickup point: на странице подтверждения заказа и в деталях заказа своего аккаунта. Он также добавляется к названию перевозчика в письме с подтверждением заказа. Письмо о новом заказе для магазина (если вы используете модуль оповещений по e-mail) тоже содержит ID пункта.

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

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox bpost Cubee находится первым на странице Modules > Module Manager > VibeFox bpost Cubee > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой лицензия действительна, и ваш домен) и кнопки Check now, чтобы проверить статус снова, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: presta-shipping-bpost-cubee и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку back office (включены английский и русский).

Если ключ не принят, блок объясняет причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: домене основного магазина, в том числе в мультимагазинной конфигурации. Удаление ключа из магазина не освобождает слот домена. Освободите слот в своём аккаунте vibefox.net.

Без действующего ключа перевозчик bpost не показывается покупателям при оформлении заказа, и тарифы не рассчитываются. Публичная часть PrestaShop не знает, что вы вошли в back office, поэтому перевозчик скрыт и для вас: настроить модуль можно до покупки ключа, но проверить его при оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются.

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

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

bpost не появляется при оформлении заказа: проверьте, что лицензия активна и Enable/Disable включено. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя, или что включено Ignore shipping zones и страна указана в Countries. Проверьте, что у страны есть цена или есть строка *=ЦЕНА, а также ограничения по весу и Minimum order amount. Товары могут быть ограничены определёнными перевозчиками на странице товара. Страница настроек показывает предупреждение, если у Бельгии нет цены.

Нет выбора пункта выдачи при оформлении заказа: проверьте, что 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 status установлен в None, цены окончательные. С налоговым правилом Taxable PrestaShop добавляет этот налог к вашим ценам.

На странице написано, что перевозчик bpost не найден: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его снова.

Для разработчиков: хуки actionVfdBpstApiUrl и actionVfdBpstApiLanguage меняют адрес API bpost и язык списка пунктов выдачи.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox bpost Cubee и выберите Uninstall. Лицензионный ключ и статус лицензии всегда удаляются. Сохранённый API-токен и кэш списков пунктов выдачи всегда удаляются. Если Remove data on uninstall включено, перевозчик удаляется (заказы сохраняют свою историю), а также удаляются настройки, журнал и пункты выдачи незавершённых корзин. Если выключено, перевозчик только отключается, и все настройки сохраняются. Повторная установка модуля возвращает перевозчику статус, который у него был до удаления. Reset в Modules > Module Manager работает так же, поэтому отключённый перевозчик остаётся отключённым. Пункты выдачи, сохранённые в заказах, относятся к истории заказов и никогда не удаляются.

bpost — товарный знак соответствующего правообладателя. Модуль не связан с bpost и не одобрен им.