VibeFox Instabee for OpenCart — Помощь

Требования

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

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

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

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

Установка

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

OpenCart 3

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

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

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

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

5. Заполните раздел Prices и, для селектора бокса для посылок, ваши API key и API secret Budbee (см. раздел «Настройка»). Включите Enable/Disable и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

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

Предупреждения над настройками сообщают, если введены только одни из учетных данных API, если учетных данных API нет, если нет цен по странам и резервной стоимости, если последний запрос к API Budbee завершился ошибкой (с датой, временем и причиной), а также если в магазине нет весовой единицы «kg» и единица класса веса по умолчанию не распознана (тогда веса считаются в килограммах; добавьте весовую единицу kg в разделе System > Localisation > Weight Classes).

Если Method name пустое или слишком длинное, Min weight (kg) больше Max weight (kg), Sort order не является целым числом, или класс налога или геозона не существуют, ничего не сохраняется и показывается ошибка.

Общие

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

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

Tax class: None (the prices are final) (по умолчанию) означает, что цены ниже окончательные. Класс налога добавляет к ценам ниже налог на доставку этого класса.

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

Селектор бокса для посылок (API Budbee)

При наличии учетных данных 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). По умолчанию: off.

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

Все цены указываются в валюте магазина по умолчанию, без налога. Допускаются и десятичная запятая, и десятичная точка (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 для строки, которая применяется ко всем странам, не имеющим собственной строки. Пустая или нулевая категория использует столбец Price. Цена Price, равная 0, означает бесплатную доставку. Если в строке страны нет цены для веса корзины, используется строка *, затем Fallback cost. При сохранении цена, которая не является числом от 0 и выше, очищается, а строка с неизвестной страной удаляется; предупреждение перечисляет их. Веса товаров пересчитываются из их весового класса OpenCart в кг.

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

Условия

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

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

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

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

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

Доступность

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

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

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

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

Debug log: записывает отладочные сообщения в storage/logs/vfd_ibee_debug.log.php (на OpenCart 4 system/storage/logs/vfd_ibee_debug.log.php). Файл нельзя прочитать через веб. Ошибки API и заказы, оформленные без бокса, пока API работал, всегда записываются в журнал, даже если опция выключена. Ключи API и данные покупателей никогда не записываются. Когда файл достигает 5 МБ, он переносится в vfd_ibee_debug.old.log.php, и начинается новый журнал.

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

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

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

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

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

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену Instabee. Если включена опция Ignore shipping zones, Instabee предлагается только для разрешенной страны (геозона не проверяется). В противном случае, если задана Geo zone и адрес находится за ее пределами, Instabee не предлагается. Учитываются только товары с Requires Shipping, установленным в Yes: другие товары не добавляют вес и не входят в сумму заказа. Сумма заказа — это цена товаров, требующих доставки, после скидки по купону и до налога. Расширение проверяет вес корзины и минимальную сумму заказа. Если промежуточный итог достигает Free shipping from, цена равна 0. В противном случае цена берется из строки Country prices страны назначения, строки * или из Fallback cost. Если цены нет, способ доставки скрывается. Цена рассчитывается в валюте магазина по умолчанию, округляется до ее знаков после запятой и показывается покупателю в его валюте с налогом выбранного Tax class.

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

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

В OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа и выбирает Instabee в окне Shipping method options. Блок Parcel box появляется в этом окне под вариантом Instabee и работает так же. Кнопка Continue в этом окне не переходит дальше без бокса из списка, с теми же сообщениями.

Расширение передает 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. Заказ тогда помечается, а бокс вы выбираете при оформлении отправления. Ранее выбранный бокс, который в этот момент невозможно проверить, сохраняется и помечается как непроверенный.

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

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

При создании заказа бокс проверяется еще раз и сохраняется в заказе. С этого момента витрина не может его изменить. В OpenCart 4 для оформления используется один заказ, который обновляется каждый раз, когда покупатель подтверждает его снова, и бокс заказа обновляется вместе с ним. Если покупатель переводит этот заказ на другой способ доставки, его бокс удаляется. Бокс отображается в следующих местах:

Способ доставки заказа: бокс добавляется к названию способа, например Instabee parcel box: (название способа), затем название и адрес бокса. Этот текст появляется на страницах заказа в администраторской части и в кабинете покупателя, в письмах о заказе и в счете.

Страница заказа в администраторской части (Sales > Orders): панель 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. Панель только для чтения и показывается, даже когда способ доставки выключен. В OpenCart 4 она показывается над блоком History.

Письмо о новом заказе магазину: название бокса с его ID или Instabee parcel box: not chosen (Budbee API unavailable at checkout).

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

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

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

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

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

Instabee не появляется при оформлении заказа: проверьте, что лицензия активна и включено Enable/Disable. Проверьте Geo zone или, если включено Ignore shipping zones, что страна разрешена в Countries. Проверьте, что для страны есть цена, или что есть строка * или Fallback cost. Проверьте ограничения по весу и Minimum order amount, а также что у товаров Requires Shipping установлено в Yes. Предупреждение над настройками сообщает, если цена не задана. Включите 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 на странице расширения. Это очистит кэш списков боксов.

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

Удаление

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

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

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