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

Требования

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

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 для тестовой и рабочей сред различаются. Если вы используете только таблицу цен, аккаунт SF Express не нужен.

Провинции Китая (только для актуальных цен): для актуальной цены нужна провинция адреса доставки, то есть зона OpenCart (Region / State) этого адреса. В OpenCart есть зоны Китая, но Тибет отсутствует. Расширение может добавить его за вас (см. Chinese provinces ниже).

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

Установка

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

OpenCart 3

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

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

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

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

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

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

7. Включите Enable SF Express и нажмите Save.

OpenCart 4

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

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

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

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

После установки способ доставки отключён, пока вы не включите Enable SF Express и не сохраните настройки. Если вы переустанавливаете расширение после удаления, снова используются сохранённые настройки SF Express.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox SF Express > Edit. Разделы перечислены слева. Они применяются ко всем геозонам. Одна кнопка Save внизу сохраняет всю страницу без перезагрузки. Каждое сохранение также очищает кэш цен SF Express. Сохранять настройки могут только администраторы, имеющие право изменять это расширение.

При сохранении расширение проверяет значения. Не сохраняется, пока вы не исправите их, и выводит сообщение об ошибке, если название способа доставки пустое, длиннее 64 символов или содержит символы < > ; = # { }, если значение не является числом, если сумма или вес отрицательные, если курс конвертации равен 0, если Min weight (kg) больше Max weight (kg), если в таблице цен неверная цена или порядок сортировки не является целым числом. Предупреждения над настройками сообщают, что актуальные цены настроены не полностью (перечисляются недостающие параметры), что курс конвертации не задан, что в магазине нет зон Китая, или что в магазине нет весовой единицы в кг или единицы длины в см, а единица по умолчанию неизвестна расширению.

Общие

Enable SF Express: показывает или скрывает SF Express при оформлении заказа. По умолчанию: выключено.

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

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

Sort order: место 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) для проверки с тестовыми учётными данными. Цены в тестовой среде не настоящие. В работающем магазине отключите эту опцию. По умолчанию: выключено.

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

Sender province: провинция, из которой отправляются посылки, например Guangdong / 广东. Первый вариант использует регион вашего магазина (System > Settings > Store > Local), если магазин находится в Китае. Тогда в списке появится Same as the store region с названием провинции, в противном случае — — Select —.

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

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

Chinese provinces: показывает, сколько из 32 провинций, автономных регионов и муниципалитетов SF Express есть в OpenCart как зоны Китая и каких нет. Адреса в отсутствующей провинции получают табличную цену. Нажмите Add Chinese provinces, чтобы добавить только отсутствующие как зоны Китая (код ISO, название вида "Tibet / 西藏"). Существующие зоны не меняются. Без этого нажатия ничего не меняется. Зоны, добавленные так, остаются в магазине после удаления расширения.

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

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

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 или пустое значение означает отсутствие ограничения.

Geo zone: предлагать SF Express только для адресов в этой геозоне. All zones (по умолчанию) означает отсутствие ограничения. Геозоны настраиваются в System > Localisation > Geo Zones. Не проверяется, когда включена опция Ignore shipping zones.

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

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

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

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

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

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

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

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

Export: нажмите Download JSON, чтобы сохранить настройки в JSON-файл без checkword.

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

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену SF Express. Если задана Geo zone и адрес вне её, SF Express не предлагается (если только не включена Ignore shipping zones). Учитываются только товары с Requires Shipping, установленным в Yes: остальные товары не добавляют вес и не входят в сумму. Сумма — это цена этих товаров после скидки по купону и до налогов. Подарочные сертификаты, бонусные баллы и кредит магазина не учитываются. Затем расширение проверяет условия: разрешённые страны (при Ignore shipping zones), вес корзины и минимальную сумму. Если сумма достигает Free shipping from, цена равна 0 и запрос в SF Express не отправляется.

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

SF Express распознаёт адреса по стандартным китайским названиям. Провинция покупателя берётся из зоны Region / State адреса и сопоставляется по названию. Зона "Hong Kong" не является провинцией материкового Китая и получает табличную цену. Город нужно писать по-китайски, например 广州市. Для Пекина, Шанхая, Тяньцзиня и Чунцина город заполняется автоматически. Город латиницей, например "Guangzhou", получает табличную цену.

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

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

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

На OpenCart 4 покупатель нажимает Choose в блоке способов доставки на странице оформления заказа и выбирает SF Express в окне Shipping method options, где название способа показано вместе с ценой. Способ работает так же, как в OpenCart 3.

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

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

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

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

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

SF Express не появляется при оформлении заказа: проверьте, что лицензия активна и включена опция Enable SF Express. Проверьте Geo zone или включите Ignore shipping zones и проверьте Countries. Проверьте ограничения по весу и Minimum subtotal. Проверьте, что в таблице или в Fallback cost есть цена для страны. Проверьте, что у товаров Requires Shipping установлено в Yes.

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

В журнале ошибка подписи: checkword неверный или относится к другой среде. Проверьте настройку Sandbox. Если SF Express сообщает, что API не разрешён, добавьте API запроса цен в ваше приложение FengQiao.

Адреса в Тибете получают табличную цену: нажмите Add Chinese provinces в разделе API на странице расширения.

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

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

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

Для разработчиков: события OpenCart vfd_sf_express/quote_request и vfd_sf_express/api_url позволяют другому расширению изменить запрос цены (например, на другой код продукта) и URL шлюза.

Удаление

Перейдите в Extensions > Extensions, выберите тип Shipping и нажмите Uninstall (красная кнопка −) рядом с VibeFox SF Express. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда сбрасывает Enable SF Express, Sort order, Tax class и Geo zone. Кэш цен всегда удаляется. Если Remove data on uninstall включено, остальные настройки и журнал также удаляются. Если выключено, они сохраняются и снова используются при повторной установке расширения. Зоны Китая, добавленные через Add Chinese provinces, остаются. Существующие заказы сохраняют свой способ доставки и стоимость.

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

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