VibeFox Instabee for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Учётные данные Budbee API (только для выбора посылочного бокса): API-ключ и API-секрет. Instabee выдаёт их мерчантам с договором на доставку. Уточните у своего контакта в Instabee или используйте мерчант-портал Instabee. Документация API находится на developer.budbee.com. Без учётных данных перевозчик работает с фиксированными ценами, но покупатели не могут выбрать посылочный бокс.

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

Установка

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

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

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

4. Заполните раздел Prices и, для селектора посылочных боксов, ваши API key и API secret Budbee (см. Настройки). Нажмите Save.

При установке модуль создаёт перевозчика Instabee parcel box с текстом срока доставки Delivery to an Instabee parcel box. Перевозчик назначается всем группам клиентов и зонам Швеции, Финляндии, Дании, Нидерландов и Бельгии. Зоны, группы клиентов, срок доставки и логотип можно изменить в Shipping > Carriers. Не задавайте там цены: цена всегда берётся из модуля.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Instabee > Configure. У каждого раздела своя кнопка Save, которая сохраняет всю страницу.

Предупреждения над настройками сообщают, когда введено только одно из двух учётных данных API, когда учётных данных нет, когда не заданы цены по странам и резервная стоимость, когда последний запрос к API Budbee завершился ошибкой (с датой, временем и причиной), когда перевозчик Instabee не найден и когда единица веса магазина не распознана (задайте kg, g, lb или oz в International > Localization, Local units). При каждом сохранении настроек очищаются кешированные списки посылочных боксов и последняя ошибка API. Если название метода или статус налога недопустимы либо Min weight (kg) больше Max weight (kg), ничего не сохраняется и выводится ошибка.

General

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

Method name: название перевозчика, которое покупатель видит при оформлении заказа. По умолчанию: Instabee parcel box. Обязательное поле, не более 64 символов.

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

Селектор посылочных боксов (Budbee API)

При наличии учётных данных API покупатель выбирает посылочный бокс рядом со своим почтовым индексом при оформлении заказа, и бокс сохраняется в заказе. Нужны оба поля. Селектор остаётся выключенным, пока не заполнены оба.

API key: ваш API-ключ Budbee (имя пользователя HTTP Basic).

API secret: ваш API-секрет Budbee (пароль HTTP Basic). В журнал он никогда не записывается.

После сохранения оба поля остаются пустыми и показывают Saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённые учётные данные, отметьте Remove the saved API key and secret и сохраните. Если ничего не сохранено, страница показывает No credentials saved.

Test environment: использует тестовый API Budbee (api.staging.budbee.com). Включайте его только с тестовыми учётными данными от Instabee. Боевые магазины оставляют его выключенным (api.budbee.com). По умолчанию: выключено.

Цены (в заголовке раздела показана валюта магазина по умолчанию)

Все цены указываются в валюте магазина по умолчанию, без налогов. Принимаются как десятичная запятая, так и десятичная точка (49,90 = 49.90). Покупателю цена показывается в валюте корзины.

Calculation type: способ применения цены.

Country prices: таблица с колонками Country, Price, XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg и XL >5 kg. Нажмите Add country, чтобы добавить строку, и значок корзины, чтобы удалить строку. Выберите * Any other country для строки, которая применяется ко всем странам без собственной строки. Пустой диапазон или 0 использует колонку Price. Цена Price, равная 0, означает бесплатную доставку. Если в строке страны нет цены для веса корзины, используется строка *, затем Fallback cost. Значение, которое не является числом, очищается, и предупреждение его перечисляет. Веса пересчитываются из единицы веса магазина в кг.

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

Условия

Min weight (kg): скрывает перевозчика при весе корзины ниже этого значения. По умолчанию: 0 (без ограничения).

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

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

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

Если значение в этих полях или в поле Fallback cost не является числом, оно не сохраняется, остаётся предыдущее значение, и предупреждение называет поле.

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

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

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

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

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

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

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

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

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

На шаге доставки PrestaShop запрашивает у модуля цену Instabee. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в сумму заказа. Модуль проверяет условия: вес корзины и минимальную сумму заказа, а при Ignore shipping zones — разрешённые страны. Если промежуточная сумма корзины достигает Free shipping from, цена равна 0. Иначе цена берётся из строки Country prices страны назначения, строки * или из Fallback cost. Если цены нет, перевозчик скрывается.

Когда покупатель выбирает перевозчика Instabee и учётные данные API заданы, под перевозчиком для Швеции, Финляндии, Дании, Нидерландов и Бельгии появляется блок Parcel box. В нём перечислены боксы рядом с почтовым индексом адреса доставки, отсортированные по расстоянию, с названием, адресом и расстоянием. Покупатель может ввести другой почтовый индекс и нажать Search (или Enter). Пока почтовый индекс не введён, блок его запрашивает. Если боксы не найдены, покупателю предлагается попробовать другой почтовый индекс или выбрать другой способ доставки. Для других стран перевозчик предлагается без бокса.

Посылочный бокс обязателен. Выбранный бокс сохраняется в корзине, только если он есть в списке Budbee для этого почтового индекса. Когда покупатель нажимает Continue на шаге доставки, модуль повторно проверяет бокс на сервере. Иначе покупатель видит Please choose an Instabee parcel box. Название бокса берётся из списка Budbee, а не из браузера. Если покупатель меняет страну доставки или почтовый индекс адреса, предыдущий выбор сбрасывается.

Модуль передаёт в Budbee только страну назначения и почтовый индекс, но никогда имена, адреса, e-mail или данные заказа. Списки боксов кешируются на 12 часов для каждого почтового индекса, почтовый индекс без боксов — на 1 час, а неудачный запрос — на 5 минут, чтобы медленный или недоступный API не замедлял каждое обновление оформления заказа. Страница оформления никогда не ждёт Budbee: список загружается в фоне сразу после выбора перевозчика. Тайм-аут API — 10 секунд.

Если API Budbee недоступен, покупатель видит Parcel boxes cannot be loaded right now. You can place the order without choosing a box - the shop will assign one. Заказ тогда помечается, и бокс вы выбираете при бронировании отправления. Ранее выбранный бокс, который в этот момент нельзя проверить, сохраняется и помечается как непроверенный.

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

Модуль не рассчитывает ставки в реальном времени, не оформляет отправления, не печатает этикетки, не выдаёт трек-номера и письма с отслеживанием, не предлагает слоты доставки Budbee Home и не показывает карту. Оформите посылку на выбранный бокс в своих мерчант-инструментах Instabee / Budbee.

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

При создании заказа бокс проверяется ещё раз и сохраняется в заказе. С этого момента витрина не может его изменить. Бокс отображается в следующих местах:

Страница заказа в админ-панели: блок Instabee parcel box с названием бокса, адресом и Box ID. Если бокс не удалось проверить при оформлении, он помечается как not verified (Budbee API was unavailable at checkout). Если бокс не был выбран, потому что API был недоступен, блок содержит Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment.

Страница подтверждения заказа и детали заказа в личном кабинете клиента: Instabee parcel box: с названием и адресом бокса.

Письма о заказе: бокс добавляется к названию перевозчика в письме с подтверждением заказа, отправляемом покупателю. Письмо о новом заказе магазину (из модуля PrestaShop Mail alerts) тоже показывает ID бокса. Если бокс не был выбран, потому что API был недоступен, об этом упоминает только письмо магазину.

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

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

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

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

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

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

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

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

Покупатели не видят список посылочных боксов: список появляется только когда заполнены API key и API secret, для Швеции, Финляндии, Дании, Нидерландов и Бельгии, и после ввода почтового индекса. Последняя ошибка API показывается над настройками. Подробности — в поле Log на странице модуля. Включите Debug log для более подробной информации.

HTTP 401 или 403 в журнале: Budbee отклонил API-ключ или секрет. Проверьте их и убедитесь, что Test environment соответствует вашим учётным данным (тестовые учётные данные только при включённом тестовом окружении).

Нет боксов для почтового индекса: Budbee не обслуживает этот почтовый индекс. Покупатель может ввести другой почтовый индекс или выбрать другой способ доставки.

Покупатель не может продолжить с шага доставки: посылочный бокс нужно выбрать из списка, если только API Budbee не недоступен. Бокс, которого нет в списке для введённого почтового индекса, не сохраняется, и покупатель видит This parcel box is not in the Budbee list for the postal code. Please choose the parcel box again.

Старые списки боксов после изменений: нажмите Save на странице модуля. Это очистит кешированные списки боксов.

На странице сообщается, что перевозчик Instabee не найден: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его заново. То же относится к сообщению The settings were saved, but the carrier could not be updated. Сброс сохраняет статус перевозчика: выключенный перевозчик остаётся выключенным.

Удаление

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

Instabee и Budbee — товарные знаки их владельцев. Этот модуль не связан с Instabee или Budbee и не одобрен ими.