VibeFox Canada Post for WooCommerce — Помощь

Требования

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

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

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

Canada Post Developer Program (только для актуальных тарифов): актуальные тарифы используют Rating API Canada Post. Зарегистрируйтесь в Canada Post Developer Program на сайте Canada Post и скопируйте ключ API и номер клиента. Ключ API имеет вид username:password, а Canada Post выдаёт отдельные ключи для среды разработки (sandbox) и для рабочей среды. Также нужен канадский почтовый индекс, с которого вы отправляете. Если вы используете только фиксированные цены, ключи API не нужны.

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

Установка

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

2. Нажмите Activate.

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

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

5. Для актуальных тарифов введите имя пользователя и пароль API, номер клиента и почтовый индекс отправки. Если валюта вашего магазина не CAD, введите курс CAD. Заполните Country prices, если нужны фиксированные цены или запасной вариант (см. раздел Настройка).

6. Добавьте VibeFox Canada Post в зоны доставки: WooCommerce > Settings > Shipping > Shipping zones, или включите Ignore shipping zones и выберите страны.

Настройка

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

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

Каждый раз при сохранении настроек кеш тарифов Canada Post очищается. Страница также показывает ошибку, если настройки не могут работать: заполнено только одно из полей имени пользователя и пароля API, почтовый индекс отправки не является канадским, не указан курс CAD для магазина в другой валюте, или нет ни ключей API, ни фиксированных цен.

Общие

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

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

Tax status: Taxable добавляет налог WooCommerce к стоимости доставки, None — не добавляет.

API Canada Post (актуальные тарифы)

Если заполнены имя пользователя и пароль API, цена берётся из Rating API Canada Post. Если API не возвращает тариф (API недоступен, неверный почтовый индекс, сервис недоступен), используется фиксированная цена из Country prices, или способ скрывается, если её нет.

API username: часть ключа API до двоеточия. Используйте ключ для разработки с Sandbox, а рабочий ключ — в боевом магазине.

API password: часть ключа API после двоеточия. В журнал она никогда не записывается.

Customer number: с номером клиента Canada Post возвращает коммерческие (со скидкой) тарифы вашей учётной записи. Оставьте пустым для розничных (кассовых) тарифов.

Contract number: необязательно, для клиентов с договором. Используется только вместе с номером клиента.

Sandbox: использует среду разработки Canada Post для тестов с ключом разработки. Цены — тестовые данные. Выключите в боевом магазине.

Ship-from postal code: канадский почтовый индекс, с которого отправляются посылки, например K1A 0B1. Для актуальных тарифов он обязателен.

Service in Canada: сервис для адресов в Канаде: Cheapest available, Regular Parcel (по умолчанию), Expedited Parcel, Xpresspost или Priority.

Service to the USA: Cheapest available (по умолчанию), Expedited Parcel USA, Tracked Packet USA, Small Packet USA Air, Xpresspost USA или Priority Worldwide parcel USA.

International service: Cheapest available (по умолчанию), International Parcel Surface, International Parcel Air, Tracked Packet International, Small Packet International Surface, Small Packet International Air, Xpresspost International или Priority Worldwide parcel International.

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

Canadian sales taxes: использует цены Canada Post без GST/HST/PST. Для адресов в Канаде цена Canada Post включает эти налоги. Включайте, когда WooCommerce сам начисляет налог на доставку (Tax status = Taxable), чтобы налог не начислялся дважды.

CAD → store currency rate: в названии поля указана валюта вашего магазина. Цены Canada Post указаны в CAD. Если валюта магазина не CAD, введите, сколько единиц вашей валюты стоит один CAD, например 0.68. Без этого значения актуальные тарифы не используются. Если валюта магазина CAD, оставьте поле пустым. Разделителем дробной части принимаются и точка, и запятая.

Default product weight (kg): передаётся в Canada Post для каждого товара без веса. По умолчанию: 0.5. Веса и размеры товаров пересчитываются из единиц вашего магазина, а корзина рассчитывается как одна посылка.

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

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

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

Условия

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

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

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

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

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

Free shipping from: сумма корзины, начиная с которой доставка бесплатна. В этом случае запрос к API не отправляется.

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

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

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

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

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

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

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

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

С ключами API плагин передаёт в Canada Post почтовый индекс отправки, назначение, вес посылки и, если у всех товаров есть размеры, примерный размер посылки. Для Канады назначением является почтовый индекс, для США — ZIP-код, для остальных стран — только страна. Актуальный тариф запрашивается только тогда, когда у адреса в Канаде или США есть корректный почтовый индекс или ZIP-код. Canada Post возвращает все сервисы для посылки; плагин выбирает выбранный сервис для группы назначения или самый дешёвый, убирает канадские налоги с продаж, если включена опция Canadian sales taxes, и пересчитывает цену в CAD по вашему курсу. Название сервиса сохраняется с заказом и отображается на экране заказа в админке как Canada Post service.

Каждый ответ кешируется на 1 час, поэтому одна и та же корзина и адрес не вызывают новый запрос. Неудачный запрос кешируется на 10 минут, чтобы сбой Canada Post не замедлял каждое обновление оформления заказа. Тайм-аут API — 10 секунд. Посылки тяжелее 30 кг в API не отправляются.

Если API не возвращает тариф, используется фиксированная цена, или способ скрывается, когда фиксированной цены нет. Покупатель никогда не видит подробностей ошибок API; они попадают в журнал WooCommerce.

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

Плагин только рассчитывает тарифы. Он не создаёт отправления, не печатает этикетки, не создаёт манифесты и возвраты и не отслеживает посылки. Покупатели не могут выбрать почтовое отделение или пункт выдачи. Показывается один тариф Canada Post без дат доставки, страховки и опций подписи. Корзина всегда рассчитывается как одна посылка, а курсы валют автоматически не обновляются.

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

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

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

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

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

Решение проблем

Canada Post не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено, а способ добавлен в зону страны покупателя (или включено Ignore shipping zones и страна разрешена). Проверьте ограничения по весу, Minimum order amount и Excluded shipping classes. Тариф должен существовать: с ключами API адрес должен иметь корректный почтовый индекс (Канада) или ZIP-код (США); иначе для страны или для * должна быть фиксированная цена.

Актуальные тарифы не появляются: включите Debug log, обновите оформление заказа и откройте WooCommerce > Status > Logs, источник vfd-canada-post. Там указана причина: не заполнены имя пользователя или пароль API, неверный почтовый индекс отправки или назначения, отсутствует курс CAD, посылка тяжелее 30 кг или сообщение об ошибке Canada Post. Тем временем покупатели получают фиксированную цену, если она есть.

Тариф отличается от сайта Canada Post: с номером клиента вы получаете коммерческие (со скидкой) тарифы своей учётной записи; без номера — розничные (кассовые) тарифы. Для адресов в Канаде цена Canada Post включает GST/HST/PST. Цены конвертируются по вашему курсу CAD.

Налог на доставку начисляется дважды: включите Canadian sales taxes или установите Tax status в None.

Проверка цен в боевом магазине: выключите Sandbox и используйте рабочий ключ API.

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

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

Удаление

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

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