VibeFox UPS for WooCommerce — Помощь

Требования

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

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

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

Приложение в UPS Developer Portal (только для тарифов в реальном времени): войдите в UPS Developer Portal (developer.ups.com), создайте приложение с продуктом «Rating», привяжите свою учётную запись UPS и скопируйте Client ID и Client Secret. Плагин использует OAuth 2.0. Access Key, имя пользователя и пароль не нужны. Для согласованных тарифов также нужен 6-символьный номер учётной записи UPS. Без учётных данных используются только фиксированные цены.

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

Установка

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

2. Нажмите Activate.

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

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

5. Введите Client ID и Client Secret, номер учётной записи UPS (для согласованных тарифов) и адрес Ship from: почтовый индекс и для США и Канады двухбуквенный код штата.

6. Если валюта вашей учётной записи UPS отличается от валюты магазина, введите UPS account currency и Exchange rate.

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

8. При необходимости введите фиксированные цены как запасной вариант.

Настройка

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

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

При каждом сохранении настроек очищаются кэшированные токен UPS и тарифы. Также можно нажать Clear cached UPS token and rates в разделе UPS API. Предупреждения над настройками сообщают, когда заполнено только одно из полей Client ID и Client Secret, когда нет ни учётных данных, ни фиксированных цен, когда не указан почтовый индекс или штат отправления, когда выбраны тарифы по учётной записи без её номера или когда не указан курс обмена.

General

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

Name: название способа доставки, которое видит покупатель при оформлении заказа. По умолчанию: UPS.

Tax status: Taxable позволяет WooCommerce добавить налог на доставку сверху, None — не добавляет. Тарифы UPS указаны без налогов, поэтому налог не взимается дважды.

UPS API (тарифы в реальном времени)

Test mode: использовать тестовую среду UPS. Тестовые тарифы не являются реальными ценами. Для тарифов в реальном времени выключите. По умолчанию: выключено.

Client ID: Client ID вашего приложения в UPS Developer Portal.

Client Secret: Client Secret того же приложения.

UPS account number: ваш 6-символьный номер отправителя UPS, например A1B2C3. Нужен для тарифов по учётной записи (согласованных), необязателен для публичных тарифов.

Rates: какие цены UPS используются.

Measurement units: единицы, которые передаются в UPS. Веса и размеры магазина пересчитываются.

Residential delivery: рассчитывать адреса покупателей как жилые, с жилой надбавкой UPS. Выключите, если вы отправляете в основном организациям. По умолчанию: включено.

Box size: необязательные размеры коробки в единицах измерения размеров вашего магазина, например 30x20x15. Тогда UPS применяет объёмный вес. Оставьте поле пустым, чтобы рассчитывать только по весу.

UPS account currency: UPS рассчитывает тарифы в валюте страны учётной записи отправителя, например USD для США, CAD для Канады или EUR для еврозоны. По умолчанию: USD.

Exchange rate: нужен, только если валюта учётной записи UPS отличается от валюты магазина. Введите цену 1 единицы валюты учётной записи в валюте вашего магазина, например 0.92. Без него такие тарифы не используются, и действуют фиксированные цены. Курсы обмена не обновляются автоматически.

Адрес отправления (адрес, с которого UPS забирает посылки или куда вы их сдаёте; используется для тарифов в реальном времени)

Country: страна, из которой вы отправляете. По умолчанию это страна вашего магазина.

State / province code: двухбуквенный код, обязательный для США и Канады, например NY, CA или ON.

City: город, из которого вы отправляете.

ZIP / postal code: почтовый индекс, из которого вы отправляете. Он нужен UPS для расчёта тарифов.

Фиксированные цены (используются, когда не введены учётные данные API, и как запасной вариант, когда UPS не возвращает тариф; если оба пусты, способ в этом случае скрывается)

Country prices: цены в валюте вашего магазина для каждой страны назначения. Нажмите + Add country, чтобы добавить строку, и крестик, чтобы удалить её. Строка * Default применяется ко всем остальным странам. Колонка веса (XS до 1 кг, S 1–2 кг, M 2–3 кг, L 3–5 кг, XL более 5 кг) заменяет Price для этого веса корзины. Пустые ячейки используют Price. 0 означает бесплатную доставку. Строки без цен удаляются при сохранении, а значения, которые не являются числами, отклоняются с сообщением.

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

Fixed price is: Per order взимает цену один раз. Per item (each item priced by its own weight x quantity) назначает цену каждому товару по его собственному весу (весу по умолчанию, если веса нет) и умножает на количество. Тарифы UPS в реальном времени всегда рассчитываются на общий вес корзины.

Условия

Free shipping from: сумма промежуточного итога корзины, начиная с которой способ бесплатный. Покупатель видит название способа с пометкой «(Free)», и запрос в UPS не отправляется. Оставьте поле пустым, чтобы никогда не предлагать бесплатную доставку.

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

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

Max weight (kg): способ скрывается при весе корзины выше этого значения. По умолчанию: 70, лимит UPS на одно место (70 кг / 150 lbs). 0 означает без ограничения.

Default product weight (kg): вес, который используется для товаров без веса, в тарифах UPS, колонках веса и ограничениях по весу. По умолчанию: 0.5.

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

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

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

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

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

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

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

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

Когда покупатель вводит адрес доставки, WooCommerce запрашивает у плагина тариф. Плагин сначала проверяет условия: вес корзины, минимальную сумму и исключённые классы доставки. Если действует бесплатная доставка, способ показывается как бесплатный и запрос в UPS не отправляется.

Плагин получает токен OAuth от UPS и хранит его до истечения срока. Токен, который UPS отклонил, обновляется автоматически. Затем плагин запрашивает у API Rating от UPS все услуги с вашего адреса отправления до адреса покупателя для корзины как одного места. Для стран с почтовыми индексами запрос ждёт, пока покупатель введёт индекс. Для отправок из США в Канаду или на Пуэрто-Рико передаётся стоимость товаров, как того требует UPS.

Покупатель видит один вариант с самой дешёвой услугой UPS, пересчитанной в валюту вашего магазина. UPS Access Point Economy не рассчитывается, так как плагин не собирает адрес Access Point.

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

Если UPS не возвращает тариф (API недоступен, неверные учётные данные, нет услуги), цена берётся из Country prices, а затем из Fallback cost. Если ни одна не применима, способ скрывается. Покупатель никогда не видит текст ошибок UPS.

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

Плагин только рассчитывает тарифы. Он не предлагает выбор UPS Access Point, не создаёт этикетки доставки и отправления UPS, не заказывает курьера и не отслеживает посылки. Он показывает один вариант, а не несколько услуг UPS. Упаковка по коробкам не выполняется: корзина рассчитывается как одно место. Курсы обмена не обновляются автоматически.

Заказы

Для тарифа в реальном времени строка доставки в заказе сохраняет UPS service, например UPS Ground. Управляющий магазином видит её на экране заказа в админке.

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

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

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

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

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

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

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

Тарифы в реальном времени не появляются: проверьте предупреждения в верхней части страницы настроек. Включите Debug log и откройте WooCommerce > Status > Logs, источник vfd-ups. Там видны ошибки OAuth (проверьте Client ID, Client Secret и Test mode), сообщения об ошибках UPS и проблемы с валютой.

Тариф в USD, а магазин — нет: UPS возвращает тарифы в валюте учётной записи отправителя. Укажите UPS account currency и Exchange rate. Без курса обмена такие тарифы игнорируются и используется фиксированная цена.

«This measurement system is not valid for the selected country»: оставьте Measurement units в положении Automatic или выберите единицы, которые UPS ожидает для вашей страны отправления.

Тарифы выглядят устаревшими после изменения: сохраните страницу настроек или нажмите Clear cached UPS token and rates.

Для разработчиков: фильтры vfd_upsx_allowed_services и vfd_upsx_excluded_services ограничивают услуги UPS, которые могут быть показаны. vfd_upsx_rate_request меняет запрос тарифа, vfd_upsx_api_base_url — адрес API, а vfd_upsx_currency_codes сопоставляет коды валют, которые возвращает UPS.

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

Удаление

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

UPS — торговая марка её владельца. Этот плагин не связан с UPS и не одобрен UPS.