VibeFox Balikobot for WooCommerce — Помощь

Требования

WordPress: 5.8 или новее.

WooCommerce: 7.0 или новее, установлен и активен. Без него плагин не активируется.

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

Установка

1. В WordPress перейдите в Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку vfd_balikobot в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Shipping > VibeFox Balikobot или нажмите Settings под названием плагина на странице «Плагины».

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

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

6. Добавьте VibeFox Balikobot в зону доставки (например, Чехия) в WooCommerce > Settings > Shipping > Shipping zones или включите Ignore shipping zones и выберите страны.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Shipping > VibeFox Balikobot. Они действуют во всех зонах доставки. Предупреждения о настройках, которые скрыли бы способ доставки, живые тарифы или пункты выдачи, показываются вверху страницы. При каждом сохранении настроек кэшированные тарифы и пункты выдачи очищаются. При добавлении способа в зону в окне зоны есть только одно поле:

Title (zone): название способа доставки, которое видит покупатель в этой зоне. Оставьте пустым, чтобы использовать общее Name.

Общие

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

Name: название способа доставки, которое видит покупатель. Зона может задать своё Title. По умолчанию: Balikobot.

Tax status: Taxable — WooCommerce добавляет налог на доставку сверх цены, None — не добавляет. Цены Balikobot обычно без НДС.

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

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

API key: ваш ключ API Balikobot из клиентской зоны.

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: фиксированная цена для каждой страны назначения (код из 2 букв, например CZ, SK). Используйте * для всех остальных стран. Десятичные значения с точкой или запятой. Используется в фиксированном режиме и как запасной вариант при сбое API. Страна без цены (и без строки *) фиксированного тарифа не получает.

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

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

Условия

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

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

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

Excluded shipping classes: скрыть способ, если в корзине есть товар из любого из этих классов доставки WooCommerce.

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

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

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

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 и расчёты тарифов в WooCommerce > Status > Logs, источник «vfd-balikobot». Ошибки API записываются всегда. Учётные данные и адреса покупателей никогда не записываются.

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

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

Когда покупатель вводит адрес доставки, плагин проверяет вес корзины, Minimum order amount и Excluded shipping classes. Если применяется бесплатная доставка, тариф равен 0, и запрос в Balikobot не отправляется.

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

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

Способ работает при классическом оформлении заказа и в блоках «Корзина» и «Оформление заказа». Он совместим с WooCommerce High-Performance Order Storage (HPOS).

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

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

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

Выбор обязателен: покупатель видит Please select a pickup point. Сервер также проверяет, что выбранный пункт относится к адресу доставки. После изменения адреса покупателя просят выбрать пункт выдачи заново. Если пункты не удалось загрузить, покупателю предлагается повторить попытку позже или выбрать другой способ доставки.

Выбранный пункт выдачи сохраняется в заказе. На экране заказа в админке он отображается под адресом доставки как Balikobot pickup point с ID отделения Balikobot и перевозчиком — они нужны при создании отправления в Balikobot. Нажмите Change, чтобы выбрать другой пункт рядом с адресом заказа. Покупатель видит пункт как Pickup point на странице заказа и в письмах о заказе (HTML и текстовый вариант). Существующие заказы сохраняют данные своего пункта выдачи.

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

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Shipping > VibeFox Balikobot. Вставьте ключ в поле License key и нажмите Activate. В блоке отображаются статус, например дата окончания действия лицензии, и ваш домен. Используйте Check now, чтобы проверить статус ещё раз, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить его с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

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

Без активного ключа Balikobot не показывается покупателям при оформлении заказа. Авторизованные менеджеры магазина по-прежнему видят его с пометкой (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице «Плагины» и на страницах WooCommerce. Существующие заказы не затрагиваются.

Когда срок лицензии истекает, плагин продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется в фоновом режиме.

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

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

Живые тарифы не появляются: включите Debug log, обновите страницу оформления заказа и откройте WooCommerce > Status > Logs (источник «vfd-balikobot»). В логе указана причина: нет учётных данных API, ещё не введён почтовый индекс, ошибка Balikobot для перевозчика и услуги или цена в другой валюте без Exchange rate. С Live Balikobot rate, fixed price if the API fails покупатели всё равно получат фиксированную цену, пока вы устраняете проблему.

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

НДС включён? Цены Balikobot обычно без НДС. Если Tax status установлен в Taxable, WooCommerce добавляет налог на доставку.

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

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

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите место в аккаунте vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжит работать по последнему известному статусу.

Удаление

Деактивация плагина сохраняет все настройки и только очищает кэш. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина, а также кэшированные тарифы и пункты выдачи удаляются всегда. Настройки и способы доставки в зонах удаляются, только если была включена опция Remove data on uninstall. Иначе они сохраняются для повторной установки. Данные пунктов выдачи, сохранённые в заказах, никогда не удаляются.

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