VibeFox Blue Express for WooCommerce — Помощь

Требования

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

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

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

Учётная запись Blue Express (только для тарифов в реальном времени): тарифы в реальном времени требуют учётной записи e-commerce Blue Express и её API-ключа (x-api-key). Запросите его у Blue Express: developers.bluex.cl или gpo.integraciones@bx.cl. Используемая услуга (EX, PY или MD) должна быть подключена в вашем договоре с Blue Express. Если вы используете только фиксированные цены, API-ключ не нужен.

Пункты выдачи: карта Blue Express загружается в браузере покупателя с widget-pudo.blue.cl.

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

Установка

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

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Shipping > VibeFox Blue Express или нажмите Settings под названием плагина на странице Plugins.

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

5. Введите API-ключ, услугу, код района отправления (например, SCL), курс CLP, если валюта вашего магазина не CLP, и фиксированные цены (например, CL=4500). См. раздел «Настройка».

6. Перейдите в WooCommerce > Settings > Shipping > Shipping zones и добавьте VibeFox Blue Express в зону Чили. В настройках метода выберите название и тип доставки (на дом или самовывоз в пункте Blue Express). Добавьте метод дважды, чтобы предлагать оба варианта.

Настройка

Основные настройки находятся в WooCommerce > Settings > Shipping > VibeFox Blue Express. Они действуют для всех зон доставки. Предупреждения о настройках, которые скрыли бы метод или тариф в реальном времени (нет API-ключа, нет курса CLP, пустая таблица фиксированных цен), выводятся вверху страницы. Сохранение настроек очищает кэш.

Окно зоны (при добавлении метода в зону доставки)

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

Delivery type: As in the global settings (по умолчанию), Home delivery или Pickup at a Blue Express point (PUDO). Добавьте метод в зону дважды, чтобы предлагать и доставку на дом, и самовывоз.

Общие

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

Name: название способа доставки, которое показывается при оформлении заказа. Зона может задать собственное название. По умолчанию: Blue Express.

Tax status: цены Blue Express включают IVA. Выберите None, если WooCommerce не должен добавлять налог сверху, или Taxable, если должен.

API Blue Express (нужен для тарифов в реальном времени)

API key: ваш API-ключ Blue Express (заголовок x-api-key). Без него используются только фиксированные цены.

Service: услуга Blue Express для тарифа: Express (EX) (по умолчанию), Prioritario (PY) или SameDay (MD). Она должна быть подключена в вашем договоре с Blue Express.

Origin district code: код района Blue Express того места, откуда вы отправляете, например SCL для Сантьяго (по умолчанию). Если не уверены, уточните у Blue Express.

CLP per 1 (your currency): цены Blue Express указаны в чилийских песо (CLP). Если ваш магазин работает в другой валюте, укажите, сколько CLP стоит одна единица этой валюты, например 1050. Без этого значения тарифы в реальном времени не используются. Игнорируется, если валюта магазина — CLP.

Цена

Rate source: как рассчитывается цена.

Fixed prices: одна строка на страну в формате COUNTRY_CODE=PRICE, в валюте вашего магазина, например CL=4500 для магазина в CLP или CL=4.50 для магазина в EUR. В качестве десятичного разделителя принимаются запятая или точка. Неверные строки выводятся при сохранении. Фиксированные цены можно использовать для любой страны.

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

Условия

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

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

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

Excluded shipping classes: если какой-либо товар в корзине относится к выбранному классу доставки WooCommerce, метод скрывается.

Бесплатная доставка

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

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

Самовывоз в пунктах Blue Express (PUDO)

Pickup point by default: если включено, методы Blue Express доставляют в пункт Blue Express, выбранный покупателем. Это значение по умолчанию для методов зон с Delivery type = As in the global settings. Покупатель должен выбрать пункт, чтобы оформить заказ.

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

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

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

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

Debug log: записывает запросы и решения в WooCommerce > Status > Logs, источник «vfd-blue-express». Ошибки API записываются всегда. Ключ API и адреса покупателей никогда не записываются.

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

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

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

Для тарифа в реальном времени адрес должен быть в Чили, с регионом и городом (коммуной). Плагин сначала просит Blue Express распознать коммуну, затем запрашивает цену для услуги, района отправления, получателя и посылок. Каждый товар передаётся с весом и размерами, переведёнными в кг и см. Товары без веса или размеров передаются как 0,01 кг, 10 x 10 x 10 см. Объявленная стоимость передаётся в CLP. Цена в CLP пересчитывается в валюту вашего магазина.

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

Метод работает в классическом оформлении заказа и в блоках «Корзина» и «Оформление заказа». Он совместим с хранилищем заказов высокой производительности WooCommerce (HPOS).

Плагин не создаёт отправления и накладные в Blue Express, не присваивает номера отслеживания и не показывает статусы отслеживания. Создайте отправление в своей учётной записи Blue Express. Региональных тарифных таблиц по коммунам нет: используйте тариф API Blue Express или одну фиксированную цену за страну. Тарифы в реальном времени работают только для Чили.

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

При типе доставки Pickup at a Blue Express point (PUDO) покупатель видит Choose pickup point под вариантом Blue Express как в классическом оформлении заказа, так и в блочном. Кнопка открывает официальную карту Blue Express, где покупатель выбирает пункт. Выбранный пункт показывается с названием и адресом, а кнопка меняется на Change pickup point. Затем тариф пересчитывается по цене самовывоза Blue Express (PUDO).

Заказ нельзя оформить без пункта: покупатель видит Please choose a Blue Express pickup point. Это проверяется на сервере.

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

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

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

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

Без активного ключа Blue Express не показывается покупателям при оформлении заказа. Менеджеры магазина, вошедшие в систему, по-прежнему его видят, с пометкой (unlicensed — visible to admins only), поэтому вы можете настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице Plugins и на страницах WooCommerce. Существующие заказы не затрагиваются.

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

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

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

Тарифы в реальном времени не появляются: при Blue Express API only метод скрывается, если тарифа нет. Включите Debug log, перезагрузите оформление заказа и откройте WooCommerce > Status > Logs (источник «vfd-blue-express»). Типичные причины: нет API-ключа, валюта магазина не CLP без курса, отсутствует регион или коммуна в адресе, коммуна не распознана Blue Express или ошибка API (например, HTTP 401 или 403, когда API-ключ отклонён). При Blue Express API, fixed price if the API gives no rate покупатели по-прежнему получают фиксированную цену, пока вы устраняете проблему.

Налог добавляется сверху к цене Blue Express: цены Blue Express включают IVA. Установите Tax status в None, если WooCommerce не должен добавлять налог сверху.

Карта не открывается: карта загружается в браузере покупателя с widget-pudo.blue.cl, поэтому этот адрес должен быть доступен и не блокироваться на вашем сайте.

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

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

Удаление

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

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