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

Требования

PrestaShop: от 8.0 до 9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

Аккаунт 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 не нужен.

Китайские провинции (только для актуальных цен): актуальная цена требует провинцию адреса доставки. В PrestaShop по умолчанию нет китайских провинций. Модуль может добавить их за вас (см. Chinese provinces ниже).

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

Установка

1. В панели администратора перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox SF Express в списке модулей и нажмите Configure.

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

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

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

При установке модуль создаёт перевозчика SF Express с текстом срока доставки Courier delivery. Перевозчик назначается всем зонам и всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Не задавайте там цены: цена всегда берётся из модуля.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox SF Express > Configure. Они действуют для всех зон перевозчика. У каждого раздела своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает кэш цен SF Express.

При сохранении модуль проверяет числа. Значение, которое не является числом, отрицательная сумма или вес, курс конвертации 0, Min weight больше Max weight или неверная цена в таблице цен отклоняются с сообщением, и ничего не сохраняется, пока вы не исправите ошибку. Предупреждения над настройками сообщают, когда актуальные цены настроены частично (перечисляются недостающие параметры), когда не задан курс конвертации, когда в китайских адресах нет поля провинции или когда модулю не известна единица веса или размеров вашего магазина. Единицы задаются в International > Localization (Local units).

Общие

Enable SF Express: включает или выключает перевозчика. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

Method title: название перевозчика, которое показывается в корзине и при оформлении заказа. По умолчанию: SF Express. Обязательное поле, не более 64 символов.

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

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

Customer code (partnerID): код клиента (顾客编码) вашего приложения FengQiao. Если его очистить, также очищается сохранённый checkword, так что вы можете удалить учётные данные.

Checkword: checkword (校验码) того же окружения. Он используется только для подписи запросов и никогда не отправляется и не записывается в журнал. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Sandbox: использует тестовую среду FengQiao (sfapi-sbox.sf-express.com) с тестовыми учётными данными. Цены в sandbox не настоящие. В работающем магазине выключите. По умолчанию: выключено.

SF Express product: цена какого продукта SF Express показывается.

Cheapest product offered by SF Express: по умолчанию. Используется самая низкая цена, которую вернул SF Express.

SF Express Priority (顺丰特快, code 1): только цена этого продукта.

SF Standard Express (顺丰标快, code 2): только цена этого продукта.

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

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

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

Chinese provinces: показывает, могут ли китайские адреса иметь провинцию. Если нет, нажмите Add Chinese provinces. Кнопка добавляет 32 провинции, автономные районы и муниципалитеты как регионы Китая (коды ISO, например GD и BJ, названия вроде «Guangdong / 广东»), включает «Contains states» для Китая и добавляет поле региона в форму китайского адреса. Уже существующие провинции повторно не добавляются. Без этого нажатия ничего не меняется.

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

Country prices: таблица с базовой ценой для каждой страны. Нажмите Add country, чтобы добавить строку, и значок корзины, чтобы удалить её. Строка * All other countries применяется ко всем странам без собственной строки. Цена весовой категории выше 0 заменяет базовую цену для посылок в этой категории: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg и XL >5 kg. Базовая цена 0 означает бесплатную доставку. Пустая базовая цена означает отсутствие цены для этой страны, и используется запасная стоимость. Принимаются и «9.99», и «9,99». Строка без единой цены не сохраняется.

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

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

Per order (tier by the total cart weight): цена весовой категории, которая соответствует общему весу корзины, взимается один раз.

Per item (every item is priced by its own weight): каждый товар оценивается по своей весовой категории и умножается на количество. Запасная стоимость умножается на количество товаров.

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

Условия

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

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

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

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

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

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

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

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

Debug log: записывает расчёты цен в logs/vfd_sfex_debug.log.php в папке модуля. Файл нельзя открыть из браузера. Ошибки API всегда записываются, даже если эта опция выключена. Checkword и адреса клиентов не записываются.

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

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

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

На шаге доставки PrestaShop запрашивает у модуля цену SF Express. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в промежуточный итог. Модуль сначала проверяет условия: разрешённые страны (с Ignore shipping zones), вес корзины и минимальный промежуточный итог. Если промежуточный итог достигает Free shipping from, цена равна 0 и запрос в SF Express не отправляется.

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

SF Express распознаёт адреса по стандартным китайским названиям. Провинция покупателя берётся из поля региона адреса. Город должен быть написан по-китайски, например 广州市. Для Beijing, Shanghai, Tianjin и Chongqing город заполняется автоматически. Город, написанный латиницей, например «Guangzhou», получает цену из таблицы.

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

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

Если вы редактируете перевозчика в Shipping > Carriers после того, как у него появились заказы, PrestaShop сохраняет его как новую версию перевозчика. Модуль автоматически переходит на новую версию.

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

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox SF Express — это первый блок на странице Modules > Module Manager > VibeFox SF Express > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-shipping-sf-express и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку back office (включены английский и русский).

Если ключ не принят, блок указывает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on и дату. После смены адреса магазина или после освобождения слота домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

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

Без активного ключа перевозчик SF Express не показывается покупателям при оформлении заказа и цена не рассчитывается. Витрина PrestaShop не знает, что вы вошли в back office, поэтому перевозчик скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать при оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются.

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

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

SF Express не появляется при оформлении заказа: проверьте, что лицензия активна и включено Enable SF Express. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя (или включите Ignore shipping zones и проверьте Countries). Проверьте ограничения по весу и Minimum subtotal. Убедитесь, что в таблице или в Fallback cost есть цена для страны. Товары также могут быть ограничены определёнными перевозчиками на странице товара.

Цена берётся из таблицы, а не из SF Express: актуальные цены требуют код клиента и checkword, провинцию и город отправителя, адрес доставки в материковом Китае с провинцией и китайским названием города, а для магазинов не в CNY — курс конвертации. Прочитайте предупреждения вверху страницы модуля, затем включите Debug log, обновите оформление заказа и посмотрите поле Log, чтобы увидеть причину. Неудачный запрос повторяется через 10 минут.

В форме адреса для Китая нет провинции: нажмите Add Chinese provinces в разделе API на странице модуля.

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

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

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

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

Страница сообщает, что перевозчик SF Express не найден: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его снова.

Для разработчиков: хук actionVfdSfExpressQuoteRequest изменяет запрос цены, например, на другой код продукта. actionVfdSfExpressApiUrl изменяет URL шлюза.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox SF Express и выберите Uninstall. Лицензионный ключ и статус лицензии всегда удаляются. Кэшированные цены всегда удаляются. Если Remove data on uninstall включено, перевозчик удаляется (заказы сохраняют историю), а настройки и журнал удаляются. Если выключено, перевозчик только отключается, и все настройки сохраняются. Повторная установка модуля или Reset возвращает перевозчику тот статус, который был раньше. Существующие заказы сохраняют свои строки доставки.

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