VibeFox Chilexpress for WooCommerce — Помощь

Требования

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

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

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

Ключи API Chilexpress (только для актуальных тарифов): создайте учётную запись на портале разработчиков Chilexpress (developers.wschilexpress.com) и подпишитесь на два продукта: Rating (Cotizador) и Coverage (Coberturas / Georreferencia). У каждого продукта свой ключ подписки. Тестовые ключи работают только в тестовой среде; ключи для боевой среды выдаются корпоративным клиентам Chilexpress при наличии клиентского договора. Также нужен код county Chilexpress коммуны, из которой вы отправляете, например STGO. Если вы используете только фиксированные цены, ключи API не нужны.

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

Установка

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

2. Нажмите Activate.

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

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

5. Заполните таблицу цен. Для актуальных тарифов введите оба ключа подписки, код county отправления и, если валюта магазина не CLP, курс обмена CLP, затем выберите источник тарифов (см. раздел «Конфигурация»).

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

Конфигурация

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

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

На странице настроек вверху выводятся проблемы: выбраны тарифы API, но не заполнен ключ, код county отправления или курс обмена CLP, либо в таблице цен нет строки для Чили или для * Default. Каждый раз при сохранении настроек очищаются кешированные тарифы и списки коммун. Числа можно вводить с точкой или запятой; неверное число не сохраняется, и выводится ошибка.

Общие

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

Name: название способа доставки, которое видит покупатель при оформлении заказа. Default: Chilexpress.

Tax status: Taxable добавляет налог WooCommerce к стоимости доставки (если налоги включены), None не добавляет. Тарифы API Chilexpress используются ровно так, как они рассчитаны. Выберите None, если тариф уже включает IVA, а ваш магазин иначе добавил бы налог сверху.

Тарифы

Rate source: откуда берётся цена.

Актуальные тарифы доступны только для адресов в Чили. Для других стран всегда используются фиксированные цены.

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

Calculation type: Per order взимает фиксированную цену один раз. Per item (fixed price x number of items) умножает её на количество товаров в корзине. Тариф API Chilexpress всегда рассчитывается на всю посылку.

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

Test environment: использует тестовую среду Chilexpress (qaservices.wschilexpress.com). Используйте её с тестовыми ключами и выключайте в магазине в боевом режиме.

Rating API key: ключ подписки продукта Rating (Cotizador).

Coverage API key: ключ подписки продукта Coverage (Coberturas / Georreferencia). Он нужен, чтобы найти код county Chilexpress коммуны покупателя (поле «Город» при оформлении заказа).

Origin county code: код county Chilexpress (коммуны), из которой вы отправляете, 2–5 букв, например STGO (Santiago Centro), PROV (Providencia), LCON (Las Condes), VALP (Valparaíso) или CONC (Concepción). Значение, которое не является кодом county, отклоняется с ошибкой.

Service: услуга Chilexpress, которая используется для тарифа. Если она недоступна для адреса назначения, используется самая дешёвая из доступных услуг.

CLP exchange rate: Chilexpress назначает тарифы в чилийских песо. Нужен, только если валюта магазина не CLP: цена 1 CLP в валюте вашего магазина, например 0.001. Без него тарифы API не используются.

Доступность

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

Max weight (kg): метод скрывается при весе корзины выше этого значения. Default: 25. 0 означает без ограничения.

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

Excluded shipping classes: скрывает метод, если какой-либо товар в корзине относится к одному из этих классов доставки WooCommerce.

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

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

Бесплатная доставка

Free shipping: включает порог бесплатной доставки.

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

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

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

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

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

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

Для адреса в Чили и источника тарифов API плагин берёт регион и коммуну из поля «Город» и ищет код county Chilexpress в списке коммун этого региона (Coverage API). Диакритические знаки, пробелы и варианты написания игнорируются, поэтому Ñuñoa и Nunoa совпадают, а Santiago совпадает с Santiago Centro. Код county, введённый в поле «Город», тоже принимается. Затем плагин отправляет в Rating API коды county отправления и назначения, вес корзины (не менее 0,1 кг), размеры посылки (длина и ширина самого большого товара, высоты складываются) и промежуточный итог корзины в CLP как объявленную стоимость. Chilexpress возвращает свои услуги; плагин использует выбранную или самую дешёвую услугу и переводит сумму в песо в валюту вашего магазина. Название услуги сохраняется в строке доставки заказа как Chilexpress service.

Тарифы кешируются на 1 час, списки коммун на 7 дней. Неудачный запрос запоминается на 5 минут, чтобы медленный или недоступный API не замедлял каждое обновление оформления заказа. Таймаут API составляет 10 секунд. Если Chilexpress возвращает ошибку, не возвращает ни одной услуги с ценой или коммуна неизвестна, покупатель не видит никакой ошибки. Метод скрывается в режиме только API или используется фиксированная цена. Причина записывается в журнал WooCommerce.

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

Плагин только рассчитывает тарифы. Он не создаёт отправления и транспортные заказы (OT), не печатает этикетки, не заказывает забор посылок и не отслеживает их; оформляйте отправление в вашем аккаунте Chilexpress. Покупатели не могут выбрать офис Chilexpress, и нет селектора коммуны: покупатель вводит коммуну в стандартное поле «Город». Международные отправления используют фиксированные цены.

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

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

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

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

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

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

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

Актуальный тариф не показан, вместо него используется фиксированная цена: сначала посмотрите предупреждения вверху страницы настроек. Если их нет, включите Debug log, обновите оформление заказа и откройте WooCommerce > Status > Logs, источник vfd-chilexpress. Типичные причины: коммуна, которую Chilexpress не распознаёт (проверьте поле «Город» и регион), ключ от другого продукта или другой среды либо адрес назначения без покрытия Chilexpress.

HTTP 401 или 403 в журнале: ключ подписки неверный, неактивен или относится к другому продукту или среде. Тестовые ключи работают только при включённом Test environment.

Тарифы API не используются в магазине с другой валютой: введите CLP exchange rate.

Тарифы API с IVA или без? Они используются ровно так, как их рассчитал Chilexpress. Если ваш магазин добавляет налог к доставке, а тариф уже включает IVA, установите Tax status в None.

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

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

Удаление

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

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