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

Требования

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

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

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

Аккаунт SF Express (только для актуальных цен): актуальные цены берутся с открытой платформы FengQiao компании SF Express (open.sf-express.com). Нужны ежемесячный аккаунт SF Express и аккаунт разработчика на FengQiao. Зарегистрируйтесь там, создайте приложение, добавьте в него API «Delivery time standard and price query» (EXP_RECE_QUERY_DELIVERTM) и скопируйте код клиента и checkword. Checkword для sandbox и для production различаются. Если вы используете только таблицу цен, аккаунт SF Express не нужен.

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

Установка

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

2. Нажмите Activate.

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

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

5. Заполните таблицу цен и/или запасную стоимость.

6. Для актуальных цен в материковом Китае введите код клиента и checkword, провинцию и город отправки (или укажите китайский адрес магазина) и, если валюта магазина не CNY, курс конвертации. Сначала проверьте работу с Sandbox и тестовыми учётными данными.

7. Добавьте VibeFox SF Express в зону доставки в WooCommerce > Settings > Shipping > Shipping zones или включите Ignore shipping zones и выберите страны.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Shipping > VibeFox SF Express. Они действуют во всех зонах доставки. Когда вы добавляете способ в зону, в окне зоны есть только одно поле:

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

Каждый раз при сохранении настроек кэшированные цены SF Express очищаются. Если актуальные цены настроены не полностью, над настройками появляется предупреждение с перечнем недостающих параметров или недостающим курсом конвертации.

Общие

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

Method title: название способа доставки, которое видно в корзине и при оформлении. Зона может его переопределить. По умолчанию: SF Express.

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

SF Express FengQiao API (актуальные цены) (необязательно, для адресов доставки в материковом Китае)

Customer code (partnerID): код клиента (顾客编码) вашего приложения FengQiao.

Checkword: checkword (校验码) той же среды. Используется только для подписи запросов и никогда не отправляется и не записывается в журнал.

Sandbox: используйте sandbox FengQiao для тестов с тестовыми учётными данными. Цены в sandbox не настоящие. В боевом магазине выключите эту опцию. По умолчанию: off.

SF Express product: цена какого продукта SF Express отображается.

Sender province: провинция, из которой отправляются посылки. Оставьте поле пустым, чтобы использовать провинцию адреса магазина в WooCommerce > Settings > General, если магазин находится в Китае.

Sender city: стандартное китайское название города, например 深圳市. Оставьте поле пустым, чтобы использовать город магазина, если магазин находится в Китае.

Currency conversion rate: цены SF Express указаны в CNY (юанях). Если валюта вашего магазина не CNY, укажите, сколько единиц валюты магазина стоит один CNY. Без курса актуальные цены не используются. Если валюта магазина CNY, цены используются как есть. В качестве десятичного разделителя принимаются и точка, и запятая.

Таблица цен и запасная стоимость (используется для Гонконга, Макао, Тайваня и других стран, когда актуальные цены не настроены или SF Express не вернул цену; цены указаны в валюте вашего магазина)

Country prices: таблица с базовой ценой для каждой страны. Строка * Any other country применяется ко всем странам без собственной строки. Цена весовой категории больше 0 заменяет базовую цену для посылок этой категории: ≤ 1 kg, ≤ 2 kg, ≤ 3 kg, ≤ 5 kg и > 5 kg. Базовая цена 0 означает бесплатную доставку. Пустая базовая цена означает, что для этой страны цены нет и используется запасная стоимость.

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

Table / fallback price is: как взимаются цены по таблице и запасные цены.

Актуальные цены SF Express всегда относятся ко всему заказу.

Условия

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

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

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

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

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

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

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

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

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

Debug log: записывает расчёты цен в журнал WooCommerce: WooCommerce > Status > Logs, источник vfd-sf-express. Ошибки API всегда записываются в журнал, даже если эта опция выключена. Checkword и адреса покупателей не записываются.

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

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

Когда покупатель вводит адрес доставки, WooCommerce запрашивает у плагина цену. Плагин сначала проверяет условия: страну доставки, вес корзины, минимальную сумму заказа и исключённые классы доставки. Если применяется бесплатная доставка и в таблице цен или в Fallback cost есть цена для адреса назначения, способ показывается с ценой 0, и запрос к SF Express не отправляется. В остальных случаях плагин сначала запрашивает у SF Express актуальную цену и показывает способ бесплатным, только если цена вернулась.

Для адреса доставки в материковом Китае при заданных коде клиента и checkword плагин передаёт в SF Express провинцию и город отправки, провинцию и город покупателя, вес корзины и объём корзины (из товаров со всеми тремя размерами). Запрос подписывается вашим checkword. SF Express возвращает цены в CNY, а плагин переводит выбранную цену в валюту вашего магазина.

SF Express распознаёт адреса по стандартным китайским названиям. Провинция покупателя берётся из поля «Регион/область» на странице оформления заказа. Город нужно писать по-китайски, например 广州市. Для Пекина, Шанхая, Тяньцзиня и Чунцина город заполняется автоматически. Город, написанный латиницей, например «Guangzhou», получает цену из таблицы.

Каждая цена кэшируется на час, поэтому одна и та же корзина не вызывает новый запрос. Неудачный запрос кэшируется на 10 минут, чтобы оформление заказа не ждало SF Express при каждом обновлении. Тайм-аут HTTP — 10 секунд.

Если актуальной цены нет, цена берётся из таблицы цен, затем из Fallback cost. Если ни один вариант не подходит, способ скрывается. Покупатель никогда не видит ошибку. Ошибка записывается в журнал.

Способ работает в классическом оформлении заказа и в блоках «Корзина» и «Оформление заказа». Он совместим с WooCommerce High-Performance Order Storage (HPOS). Включены английский и упрощённый китайский переводы.

Плагин только рассчитывает цены. Он не создаёт накладных и этикеток, не создаёт заказы в SF Express, не заказывает забор отправлений, не отменяет и не отслеживает отправления. Создавайте и отслеживайте отправления в своём аккаунте SF Express, как обычно. Покупатели не могут выбрать пункт выдачи или постамат SF. SF Express используется как курьерская доставка «от двери до двери». Актуальные цены доступны только для адресов доставки в материковом Китае. Плагин разработан по документации FengQiao и на основе имитированных ответов, поэтому перед запуском сверьте цены в своём аккаунте SF Express (сначала в sandbox).

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

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

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

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

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

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

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

Цена берётся из таблицы, а не из SF Express: актуальным ценам нужны код клиента и checkword, провинция и город отправки, адрес доставки в материковом Китае с провинцией и китайским названием города, а для магазинов не в CNY — курс конвертации. Откройте WooCommerce > Status > Logs, источник vfd-sf-express, чтобы увидеть причину. Неудачный запрос повторяется через 10 минут.

Ошибка A1006 в журнале: неверная подпись. Checkword неверный или относится к другой среде. Проверьте настройку Sandbox.

Ошибка A1004 в журнале: API запроса цен не добавлен в ваше приложение FengQiao.

Гонконг: работает с таблицей цен и запасной стоимостью. Запрос цен FengQiao предназначен только для адресов в материковом Китае.

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

Для разработчиков: фильтр vfd_sfex_quote_request изменяет запрос цены, например для другого кода продукта. vfd_sfex_api_url меняет URL шлюза.

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

Удаление

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

SF Express — товарный знак его правообладателя. Этот плагин не аффилирован с SF Express и не поддерживается ею.