VibeFox Balikobot for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Аккаунт Balikobot (для живых тарифов и пунктов выдачи): нужен аккаунт Balikobot с доступом к API. Пользователь API и ключ API находятся в клиентской зоне Balikobot (client.balikobot.cz). Поддержка Balikobot (podpora@balikobot.cz) активирует API для вашего аккаунта и перевозчиков. Живым тарифам нужен перевозчик и услуга, для которых Balikobot поддерживает «transportcosts». Пунктам выдачи нужен перевозчик с поддержкой «branchlocator» (например, Česká pošta, Zásilkovna, PPL, DPD, GLS). Если не уверены, уточните у поддержки Balikobot. Фиксированные цены работают без аккаунта.

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

Установка

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

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Balikobot в списке модулей и нажмите Configure.

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

4. Введите пользователя и ключ API, выберите перевозчика и тип услуги, источник цены и цены по странам (см. Настройки). Для услуг с пунктами выдачи включите Pickup point selection. Нажмите Save.

При установке модуль создаёт перевозчика Balikobot с текстом срока доставки Delivery by Balikobot. Перевозчик назначается зонам Чехии, Словакии и Венгрии и всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Balikobot > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. После сохранения вы увидите Settings saved. Cached rates and pickup points were cleared. В верхней части страницы выводятся предупреждения о настройках, которые скрыли бы перевозчика, живые тарифы или пункты выдачи: живые тарифы или пункты выдачи без пользователя или ключа API, валюта магазина отличается от CZK без Exchange rate, пустая таблица Country prices при фиксированных ценах или резервном режиме, единица веса магазина, которую модуль не распознаёт (веса тогда читаются как кг; используйте kg, g, lb или oz), и удалённый перевозчик. Значение, которое не является числом, не сохраняется, и вы увидите предупреждение с названием поля.

General

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

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

Tax status: None или Taxable с одним из ваших налоговых правил. С налоговым правилом его налог добавляется к стоимости доставки. Выбор сохраняется у перевозчика. Цены Balikobot обычно указаны без НДС. По умолчанию: None.

Аккаунт API Balikobot (нужен для живых тарифов и пунктов выдачи)

API user: ваш пользователь API Balikobot из клиентской зоны.

API key: ваш ключ API Balikobot из клиентской зоны. После сохранения поле остаётся пустым и показывает Saved - leave empty to keep it. Clear the API user to remove the saved key. Вводите новое значение, только если хотите его изменить.

Carrier: перевозчик Balikobot для тарифов и пунктов выдачи: Česká pošta (по умолчанию), Zásilkovna (Packeta), PPL, DPD, GLS, DHL Express, UPS, TNT, FedEx, Geis, InTime, Uloženka, Toptrans, Pošta bez hranic, Slovenská pošta, SPS (Slovak Parcel Service) или Magyar Posta. Он должен быть активирован в вашем аккаунте Balikobot.

Service type: код услуги перевозчика в Balikobot. По умолчанию: NP. Для Česká pošta: NP = посылка в почтовое отделение, NB = посылка в Balíkovna, DR = доставка на дом. Коды других перевозчиков приведены в клиентской зоне Balikobot и в документации API.

Цена (все цены указаны в основной валюте вашего магазина)

Price source: способ расчёта цены.

Country prices: таблица двухбуквенных кодов стран (например, CZ, SK) и цен. Нажмите Add row, чтобы добавить страну, и значок корзины, чтобы удалить её. Используйте * как код страны для всех остальных стран. Дробные числа с точкой или запятой. Используется в фиксированном режиме и как резерв при сбое API. Страна без цены (и без строки с *) не получает фиксированный тариф. Неверные строки удаляются при сохранении, и предупреждение их перечисляет.

Fixed price per: Order берёт цену один раз. Item (price x quantity) умножает её на количество товаров в корзине. Это относится только к фиксированным ценам. Живой тариф Balikobot всегда рассчитывается на всю посылку.

Exchange rate: стоимость 1 единицы валюты цены Balikobot (обычно CZK) в основной валюте вашего магазина, например 0.04. Используется, только если Balikobot возвращает цену в другой валюте. Оставьте поле пустым, чтобы отклонять такие цены, и покупатель никогда не заплатит неверную сумму.

Условия

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

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

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

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

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

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

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

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

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

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

Pickup point selection: покупатель обязан выбрать пункт выдачи. Используйте для услуг с пунктами выдачи, например Česká pošta NP или NB, или Zásilkovna. Нужны пользователь и ключ API.

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

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

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

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

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

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

На шаге доставки PrestaShop запрашивает у модуля цену Balikobot. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в сумму заказа. Модуль сначала проверяет страны (с Ignore shipping zones), вес корзины и Minimum order amount. Если применяется бесплатная доставка, цена равна 0 и запрос в Balikobot не отправляется.

В фиксированном режиме цена берётся из Country prices. В живых режимах модуль передаёт Balikobot перевозчика, тип услуги, страну и почтовый индекс назначения, а также вес корзины в кг. Живой тариф запрашивается только тогда, когда в адресе доставки указан почтовый индекс. Цена в другой валюте пересчитывается по Exchange rate или отклоняется, если курс не задан. Цена рассчитывается в основной валюте магазина, а затем показывается в валюте корзины покупателя.

Живые цены кэшируются на 1 час, поэтому одна и та же корзина не вызывает новый запрос. Неудачный запрос кэшируется на 5 минут, а тайм-аут API составляет 12 секунд, чтобы оформление заказа не ждало Balikobot при каждом обновлении. Ошибки API никогда не показываются покупателю: перевозчик скрывается или в резервном режиме используется фиксированная цена. Подробности попадают в журнал отладки.

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

Модуль не создаёт отправления в Balikobot, не печатает этикетки и не заказывает забор посылок: оформляйте отправку в клиентской зоне Balikobot. Он не отслеживает посылки и не обновляет статусы заказов. Для всех зон используется один перевозчик и один тип услуги. Пункты выдачи показываются в виде выпадающего списка, без карты.

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

Когда Pickup point selection включён, на шаге доставки под перевозчиком Balikobot появляется список пунктов выдачи. Список загружается из «branchlocator» Balikobot для страны, города и почтового индекса адреса доставки. Пока в адресе не указан город, покупатель видит Enter your city to see the pickup points. Список кэшируется на 12 часов.

Выбор сохраняется в корзине сразу, как только покупатель выбирает пункт. Выбор обязателен: Continue на шаге доставки и Place order заблокированы с сообщением Please select a pickup point. Сервер также проверяет, что выбранный пункт относится к адресу доставки. Иначе покупатель увидит The selected pickup point is not available for your shipping address. Please choose a pickup point again. Если пункты не найдены, покупателю предлагается проверить город и почтовый индекс или выбрать другой способ доставки. Если пункты не удалось загрузить, покупателю предлагается повторить попытку позже или выбрать другой способ доставки.

Выбранный пункт выдачи сохраняется в заказе. На странице заказа в панели администратора он показывается в блоке Balikobot pickup point вместе с ID отделения Balikobot и перевозчиком, которые нужны при создании отправления в Balikobot. Нажмите Change, чтобы выбрать другой пункт рядом с адресом заказа, и нажмите Save. Для смены пункта нужно только право редактировать заказы, доступ к страницам модулей не требуется. Если в заказе нет пункта, блок показывает No pickup point was selected for this order.

Покупатель видит пункт как Pickup point: на странице подтверждения заказа и в деталях заказа. В письме с подтверждением заказа и в письме о новом заказе для магазина (модуль Mail alerts) он добавляется после названия перевозчика. Существующие заказы сохраняют данные о пункте выдачи.

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

Модуль работает с лицензионным ключом VibeFox, полученным на vibefox.net. Блок лицензии License — VibeFox Balikobot находится первым на странице Modules > Module Manager > VibeFox Balikobot > Configure, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой лицензия действительна, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-shipping-balikobot и ссылка 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.

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

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

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

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

Живые тарифы не появляются: включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице модуля. Там указана причина: не заданы учётные данные API, ещё нет почтового индекса, ошибка Balikobot для перевозчика и услуги (например, authorization failed — проверьте пользователя и ключ API), или цена в другой валюте без Exchange rate. С Live Balikobot rate, fixed price if the API fails покупатели по-прежнему получают фиксированную цену, пока вы исправляете проблему.

Цены в неправильной валюте: фиксированные цены указаны в основной валюте вашего магазина. Balikobot возвращает живые цены в валюте вашего договора с Balikobot (обычно CZK). Если она отличается от основной валюты, задайте Exchange rate.

НДС включён?: цены Balikobot обычно указаны без НДС. Если в Tax status выбрано налоговое правило, PrestaShop добавляет налог на доставку.

В списке нет пунктов выдачи: проверьте, что заданы пользователь и ключ API, что перевозчик поддерживает «branchlocator» и что в адресе доставки указаны город и почтовый индекс. Посмотрите в журнале ошибку Balikobot.

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

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

Для разработчиков: у модуля есть собственные хуки для изменения адреса API (actionVfdBlkbApiUrl), пакета «transportcosts» (actionVfdBlkbTransportcostsPackage) и количества пунктов выдачи (actionVfdBlkbPickupMaxResults, по умолчанию 30).

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Balikobot и выберите Uninstall. Лицензионный ключ, статус лицензии, кэшированные тарифы и пункты выдачи удаляются всегда. Если Remove data on uninstall включено, перевозчик удаляется (заказы сохраняют свою историю), а настройки, журнал и пункты выдачи корзин без заказа удаляются. Если опция выключена, перевозчик только отключается, и все настройки сохраняются. При повторной установке модуля (или сбросе) сохранённый перевозчик получает статус, который был до удаления: включённый остаётся включённым, выключенный — выключенным. Данные о пункте выдачи, сохранённые в заказах, никогда не удаляются.

Balikobot — торговая марка её владельца. Модуль не связан с Balikobot и не одобрен компанией Balikobot.