VibeFox Balikobot for OpenCart — Помощь

Требования

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

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

Аккаунт 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. Один ключ работает на одном домене.

Установка

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Balikobot > Edit. Разделы перечислены слева. Одна кнопка Save сохраняет всю страницу без перезагрузки. После сохранения вы увидите Settings saved. Cached rates and pickup points were cleared. Сохранять настройки могут только администраторы с правом изменения этого расширения.

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

Предупреждения о настройках, которые скрыли бы способ, живые тарифы или пункты выдачи, показываются вверху страницы: живые тарифы или пункты выдачи без пользователя или ключа API, валюта магазина, отличная от CZK, без Exchange rate, пустые Country prices при фиксированных ценах или в режиме резерва, а также магазин без весовой единицы kg (тогда веса товаров читаются по названию единицы: kg, g, lb или oz).

Общие

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

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

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

Аккаунт 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: список стран и цен. Нажмите Add row, чтобы добавить строку, и кнопку удаления, чтобы удалить строку. Выберите * All other countries для всех стран без собственной строки. Десятичные значения с точкой или запятой. Используется в фиксированном режиме и как резерв при сбое API. Для страны без цены (и без строки *) фиксированного тарифа нет, поэтому способ для неё скрыт.

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

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

Условия

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

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

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

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

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

Tax Class: налог этого класса добавляется к стоимости доставки. Цены Balikobot обычно без НДС. По умолчанию: --- None ---.

Доступность

Обычно способ предлагается в геозоне, выбранной здесь (All Zones означает везде). Ignore geo zone предлагает его вместо этого в странах из списка.

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

Ignore geo zone: предлагать способ в странах, указанных ниже, независимо от геозоны.

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

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

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

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

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

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

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

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

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

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

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

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену Balikobot. Если задана Geo Zone (и Ignore geo zone выключено) и адрес вне неё, Balikobot не предлагается. При Ignore geo zone решает список Countries. Учитываются только товары с Requires Shipping = Yes: остальные товары не добавляют вес и не входят в сумму заказа. Затем расширение проверяет вес корзины и Minimum order amount. Сумма заказа — это цена товаров, требующих доставки, после скидки по купону и до налога. Если действует бесплатная доставка, цена равна 0 и запрос в Balikobot не отправляется.

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

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

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

В OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа и выбирает Balikobot в окне Shipping method options. Способ работает так же, как в OpenCart 3; список пунктов выдачи описан в разделе Пункты выдачи.

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

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

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

В OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа. Окно Shipping method options показывает список пунктов выдачи под способом Balikobot, с теми же текстами и проверками. Список загружается каждый раз при открытии окна, потому что адрес может измениться на той же странице оформления, и берётся из кэша, когда это возможно. Если покупатель нажимает Continue в окне без допустимого пункта, сообщение появляется вверху страницы оформления, а окно остаётся открытым. OpenCart 4 хранит один заказ для оформления и обновляет его при каждом подтверждении; пункт выдачи заказа обновляется вместе с ним.

Выбранный пункт добавляется к способу доставки заказа в виде - Pickup point:, за которым идут его название и адрес. Покупатель видит его на страницах заказов в своём аккаунте и в письмах о заказе, а также он печатается на счёте-фактуре.

На странице заказа в админке (Sales > Orders, View) панель Balikobot pickup point показывает пункт, его ID Balikobot и перевозчика, которые нужны при создании отправления в Balikobot. Нажмите Change, выберите другой пункт рядом с адресом заказа и нажмите Save. Текст способа доставки заказа тоже обновляется, и вы видите Pickup point updated. Изменение пункта требует только права на изменение заказов, а не доступа к настройкам расширения. Если у заказа нет пункта, панель показывает No pickup point was selected for this order. Панель работает и при выключенном Balikobot: существующие заказы сохраняют данные о пункте выдачи, и пункт можно изменить.

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

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

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

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

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

Balikobot не появляется при оформлении заказа: проверьте, что лицензия активна и Enable/Disable включено. Прочитайте предупреждения вверху страницы расширения. Проверьте Geo Zone (или Ignore geo zone и Countries), ограничения по весу и Minimum order amount. В фиксированном режиме проверьте, что у страны или * All other countries есть цена. Проверьте, что у товаров Requires Shipping = Yes.

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

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

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

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

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

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

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

Удаление

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

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

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